In order to build Molekel from source you need the following tools

  • Subversion client - to get the code from the repository, optional if you download the source code archive
  • CMake ( http://www.cmake.org ) - makefile generation tool
  • A C++ compiler such as gcc (MacOS X, Unix), MinGW (Windows) or Visual C++ (Windows, recommended, free version available at http://www.microsoft.com/express/vc)
  • wget (optional but useful to automate the build process as done in the Molekel build scripts)
  • unix2dos and dos2unix (both optional) to convert EOL separators

and libraries:

After all the dependencies are installed and you have downloaded the source code you need to generate the makefiles with CMake; three options available:

  • (RECOMMENDED) get one of the run_<environment>_cmake.sh/bat files from the build directory of the source distribution and change the paths to suit your environment then execute the script OR
  • run ccmake (Unix/Mac OS X) or CMakeSetup.exe (Windows) and specify the include and library path through an interactive interface then execute make/nmake OR
  • run cmake on the command line specifying the path to the CMakeLists.txt configuration file and the include/library paths on the command line then execute make/nmake

Detailed instructions

I Dependencies

  1. Install Qt (http://www.trolltech.com/products/qt); Qt has to be installed before VTK because VTK needs some Qt libraries.
  2. Install VTK 5.x (http://www.vtk.org)
    • build VTK from source and 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 OpenBabel 2.x libraries (http://openbabel.sourceforge.net)
    • If you are building on Windows with MinGW check out the OpenBabel OS specific issues below.
  4. 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 Coin3D) you also have to have in the PATH the directory where the coin-config file 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/VC++ make sure you set the OIV_DIR environment variable to the installation directory 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 installed 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 platforms.

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

II Build

These build instruction are useful only if you want to run CMake yourself instead of using one of the scripts available in the build directory.

  1. Uncompress the Molekel source archive, cd to the top level distribution dir and create a cmakebuild folder:
    • mkdir cmakebuild
    • cd to the 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" )
  1. Run ccmake (Linux, Mac OS) or CMakeSetup.exe (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.exe (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.<dll|so> file is.
      • IV_INCLUDE_DIR: OpenInventor (Coin3D) include dir; where the Inventor include dir resides. Not required on Mac if Coin is installed as a framework.
      • IV_LINK_DIR: OpenInventor (Coin3D) lib dir. Not required on Mac if Coin is 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
  2. Generate the makefiles with ccmake or CMakeSetup.exe (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.
  3. Run make or nmake.

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

  • 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

All the required dlls must be in directories listed in the PATH environment variable or in the same directory as the executable.

Linux

You can make all the required shared objects accessible by adding the directories where the libraries reside to the LD_LIBRARY_PATH environment variable. To find the list of used dlls run: ldd dist/bin/Molekel from within the build directory.

MacOS

You should not have to do anything to run the program; if for whatever reason the program cannot find some dynamic libraries you can add the directories where the dynamic libraries reside to the DYLD_LIBRARY_PATH environment variable. To find the list of dynamic libraries and frameworks used run otool -L dist/bundle/Molekel.app/Contents/MacOS/Molekel from the build directory.
All the resources in the resource directory (including the toolbar dir) must be copied into Molekel.app/Contents/Resources.

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.