Build Instructions

This setcion describes the procedure to follow when building Molekel on Linux (gcc), Windows (MinGW) and Mac OS X (gcc).

Molekel is built with CMake and Make and some libraries need to be installed before you can build the executable.

Some shell scripts found in the build and install directories are available to automate the build process, these are useful to build redistributable archives but can also be used to e.g. check out the required components from the source code repository and invoke CMake with the proper configuration parameters. If you need to build Molekel on Windows you might want to check out the mingw scripts since they will take care of checking out the code, downloading all the dependencies except Qt and build everything, provided you have the following tools/toolkits already installed:

• MinGW
• MSYS
• SVN
• CMake
• wget (used only to get the dependency archive through ftp; can be done manually)
• unix2dos (optional - used to convert all text files in the distribution to win format)

It is recommended that you get the libraries from the following sites:

• Qt 4.2: http://www.trolltech.com/products/qt
• VTK 5.x: http://www.vtk.org
• Coin3D: http://www.coin3d.org
• OpenMOIV: http://www.tecn.upf.es/openMOIV
• OpenBabel: http://openbabel.sourceforge.net

We do have pre-built and source distributions of the above libraries on our ftp site at this address: ftp://ftp.cscs.ch/out/molekel/molekel_5.3/dep.

Building the above lbraries (when needed) on Mac OS, and Linux is straightforward, it takes some time but you should not encounter any issues; building everything except OpenBabel with MinGW is fairly easy too.

Steps

I Dependencies

1. Install CMake (http://www.cmake.org)
2. Install VTK 5.x (http://www.vtk.org)
   • if you build from source make sure the following parameters are set to ON
     • VTK_USE_GUISUPPORT
     • VTK_USE_QVTK
     • VTK_USE_GL2PS
   • Check out OS specific information below.
3. Install the Open Source verion of Qt 4.2 (http://www.trolltech.com/products/qt)
4. Install OpenBabel 2.x libraries (http://openbabel.sourceforge.net)
   • If you are building on Windows with MinGW check out the OpenBabel OS specific issues below.
5. Install OpenInventor and Molecular Inventor

• Any implementation of OpenInventor 2.x will work; you can get an open source version here (Coin3D): http://www.coin3d.org
  • Note that in case you want to build OpenMOIV (or any program requiring coin) you also have to have in the PATH the directory where coin-config resides. In case Coin3D is installed as a framework on Mac OS this is not required.
• An open source implementation of Molecular Inventor(OpenMOIV) can be downloaded here: http://www.tecn.upf.es/openMOIV
• When building OpenMOIV on Linux/MinGW make sure you set the OIV_DIR environment variable to the installation dir of Coin3D (where the include and lib dirs are) e.g. export OIV_DIR=/usr/local You do not need to do this on Mac OS X if you installe Coin3D as a framework (which is the default).
• Make sure you read the build information for OpenMOIV to undestand how to deal with fonts on different platform.

On MinGW you need to make sure that the gettimeofday function is available (check in include/sys/time.h); in case it's not then download the latest mingw-runtime environment or have a look at the OpenBabel build page.

II Build

1. Uncompress the molekel source archive, cd to the top level distribution dir and create a cmakebuild folder:
   • mkdir cmakebuild
   • cd to cmakebuild folder
2. Modify the PATH variable so that the correct binary Qt dir is found: Cmake finds Qt looking for the qmake executable so you need to have the right qmake executable as the first one in the path.
3. Create a text file version_info.cmake in the build directory; this file is included by the main CMakeLists.txt file to set version information. Open version_info.cmake and add something like (use whatever version numbers you want).

   SET( MOLEKEL_VERSION_MAJOR 5 )
   SET( MOLEKEL_VERSION_MINOR 0 )
   SET( MOLEKEL_VERSION_PATCH 0 )
   SET( MOLEKEL_VERSION_BUILD 0 )
   SET( MOLEKEL_VERSION_TYPE "development" )
   

4. Run ccmake (Linux, Mac OS) or CMakeSetup(Windows) and make sure that all the parameters are correct.
   • ccmake ../src
   • IV_DYNAMIC and MOIV_DYNAMIC should be set to ON in case dynamic libraries are used; to OFF otherwise. Note that this only seems to be required on MINGW.
   • The following parameters need to be set (make sure you also read the OS specific section) from within ccmake(Linux, Mac) or CMakeSetup(Windows):
     • OPENBABEL_INCLUDE_DIR: OpenBabel include dir; where the openbabel include dir is e.g. /usr/local/include/openbabel-2.0
     • OPENBABEL_LINK_DIR: OpenBabel library dir; where the libopenbabel file is.
     • IV_INCLUDE_DIR: OpenInventor(Coin3D) include dir; where the Inventor include dir resides. Not required on Mac if Coin installed as a framework.
     • IV_LINK_DIR: OpenInventor(Coin3D) lib dir. Not required on Mac if Coin installed as a framework.
     • MOIV_INCLUDE_DIR: Molecular Inventor include dir; where the ChemKit2 include directory is.
     • MOIV_LINK_DIR: Molecular Inventor lib dir;
     • VTK_DIR: VTK dir e.g. /usr/local/lib/vtk-5.0
5. Generate the makefiles with ccmake or ''CMakeSetup (configure then generate):
   1. Check that all the parameters are set to the proper values.
   2. Press [c](Mac, Linux) or Configure(Windows) to configure then [g](Mac, Linux) or Ok(Windows) to generate the makefiles.
   • Whenever you change one or more parameter values in ccmake or CMakeSetup you'll have to configure before you can generate.
6. Run make.

The build process will generate the following tree in the build dir:

• dist - release notes, license, readme
  • bin OR bundle - binary or Mac bundle
  • resources - images, configuration files...
    • toolbar - toolbar icons
  • doc - user documentation

Note: with MinGW 3.4.5 compilation of MolekelData.cpp can be very slow; to speed up build time during development #define MOLEKEL_USE_COMMON_FILE_FORMATS

III Run

In order to launch Molekel you need to make sure that all the required dynamic libraries are accessible from the executable.

Windows

Linux

MacOS

Rendering issues

Molekel versions 5.3 or above use some advanced multi-pass rendering techniques to enhance visual quality; these techniques may generate visual artifacts on transparent surfaces on some specific graphic cards. We have experienced problems on SuSE 10.3 x86-32/NVIDIA 8800 Ultra and Windows XP 32bit/NVIDIA 8800 Ultra system; on Windows problems can be fixed by selecting Let the 3D application decide (which should be the default) in the Image Settings page of the NVIDIA Control Panel.

In general, in case you have rendering problems, get messages about errors in Coin or the program crashes when loading files without reporting any error, you can set the value of two environment variables as follows:

• COIN_FULL_INDIRECT_RENDERING=0
• COIN_FORCE_GL1_0_ONLY=1

before launching Molekel to disable the use of advanced OpenGL features.

To set the environment variables permanently on Windows XP right-click on My Computer then select the Advanced tab and click on the Environment Variables button.

You can also set the COIN_DEBUG_GLGLUE environment variable to 1 before starting Molekel in a console window to print OpenGL debug information. To enable printing on standard output on Mac you'll have to invoke the actual executable in the Molekel.app folder i.e. Molekel.app/Contents/MacOS/Molekel.