rdkit/INSTALL

The instructions below are for source distributions from Q3 2008 on. 
= Building on Linux =

== Getting Ready ==
 * Required packages:
   ** The python headers. This probably means that you need to install the python-dev package (or whatever it's called) for your linux distribution.
   ** Blas and lapack. This is also probably just a matter of finding the appropriate package for your linux.
   ** flex and bison. These are frequently already installed if you have the various pieces of the development environment installed
   ** sqlite3. You also need the shared libraries. This may require that you install a sqlite3-dev package.
   ** You need to have numpy (http://www.scipy.org/NumPy) installed. If you do not have python and/or numpy installed in the standard location, you need to edit the Jamroot ($RDBASE/Code/Jamroot) to reflect the location, i.e. replace `<toolset>gcc:<include>/usr/lib/python2.5/site-packages/numpy/core/include` with whatever is appropriate for your python/numpy installation.

== Installing Boost ==
  * download the boost source distribution from [http://www.boost.org the boost web site]
  * extract the source to a _non-temporary_ location on your machine, you're going to need it to build the RDKit as well as boost. (e.g. `/usr/local/src/boost_1_36_0`)
  * build and install the required boost shared libraries: 
    ** `cd $BOOST`
    ** `bjam  --with-thread --with-python release install`
  If you have any problems with this step, check the boost [http://www.boost.org/more/getting_started/unix-variants.html installation instructions].

== Installing the boost numeric bindings ==
  * download the most recent version of the boost numeric bindings from [http://mathema.tician.de/dl/software/boost-bindings http://mathema.tician.de/dl/software/boost-bindings].
  * extract the tar ball to some temporary location.
  * copy the directory `boost-numeric-bindings/boost/numeric/bindings` to `$BOOST/boost/numeric`
  * copy the directory `boost-numeric-bindings/libs/numeric/bindings` to `$BOOST/libs/numeric`


== Building the Code ==
  * follow the Installing Boost instructions above.
  * environment variables:
    ** RDBASE: the root directory of the RDKit distribution (e.g. ~/RDKit)
    ** BOOSTHOME: should be wherever you extracted the boost source (e.g. /usr/local/src/boost_1_34_1)
    ** BOOST_BUILD_PATH: should be the same as $BOOSTHOME
    ** PYTHON_ROOT: wherever python is installed (e.g. /usr)
    ** PYTHON_VERSION: the first two digits of the python version (e.g. 2.5, *not* 2.5.1)
    ** PYTHONPATH: make sure it includes $RDBASE/Python
    ** LD_LIBRARY_PATH: make sure it includes $RDBASE/bin and wherever the boost shared libraries were installed
  * Building: cd to $RDBASE/Code and do `bjam` (`bjam address-model=64` on 64bit systems), this builds all libraries, wrappers, and regression tests. This command will generate a lot of text (mostly compiler warnings), but it should not generate any errors. At the end you should *not* see any messages about failed or skipped targets. 

== Testing the Build (optional, but recommended) ==
  * cd to $RDBASE/Code and do `python $RDBASE/Python/TestRunner.py test_list.py`
  * cd to $RDBASE/Code/GraphMol and do `python $RDBASE/Python/TestRunner.py test_list.py`
  * create the databases used by the Python tests, requires sqlite3 to be installed:
    ** `sqlite3 $RDBASE/Data/RDTests.sqlt < $RDBASE/Python/Dbase/testData/RDTests.sqlite`
    ** `sqlite3 $RDBASE/Data/RDData.sqlt < $RDBASE/Python/Dbase/testData/RDData.sqlite`
  * cd to $RDBASE/Python and do: `find . -name 'test_list.py' -exec python $RDBASE/Python/TestRunner.py \{\} >> pytests.out 2>&1 \;`
  * cd to $RDBASE/Projects and do: `python $RDBASE/Python/TestRunner.py test_list.py`


= Building on Windows =

== Software to Install ==
  * Microsoft Visual C++ : The Express version has everything necessary and can be downloaded for free [http://www.microsoft.com/express/download/ from Microsoft]. This is a big installation and will take a while. The RDKit has been successfully built with all version of visual c++ since 6.0, so the current version of VC++ (2008 as of this writing) should be fine. 
  * flex and bison : these are easily installed as part of a [http://www.cygwin.com cygwin] installation, but one can also find flex and bison binaries for windows elsewhere. Cygwin is not required to build the RDKit, but it's very useful to have (a minimal cygwin installation is fine). *Note* if you install flex and bison without cygwin, be sure to read [http://eli.thegreenplace.net/2007/07/27/bison-looking-for-bisonsimple-on-windows/ this web page] about environment variables and set the BISON_SIMPLE environment variable to the appropriate value.
  * python : [http://www.python.org/download python] should be installed
  * numpy : the [http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103 current version of numpy] should be installed. It's fine to use the binary installer. Note that a directory from the numpy installation needs to be copied to a new location; details are below in the Setup and Preparation section.
  * boost : download a copy of the current versions of the [http://www.boost.org/users/download/ boost source distribution and boost-Jam]. Both are available from the same link, be sure to get the `.ntx86.zip` file for boost-Jam.  Extract the source distribution (to, for example, c:\boost\boost_1_36_0) and copy the bjam.exe executable from the boost jam zip file to the  same directory.
  * boost numeric bindings : download the most recent version from from [http://mathema.tician.de/dl/software/boost-bindings http://mathema.tician.de/dl/software/boost-bindings].
    ** extract the tar ball to some temporary location.
    ** copy the directory `boost-numeric-bindings\boost\numeric\bindings` to `c:\boost\boost_1_36_0\boost\numeric`
    ** copy the directory `boost-numeric-bindings\libs\numeric\bindings` to `c:\boost\boost_1_36_0\libs\numeric`

  * a subversion client : _This is only necessary if you are planning on building development versions of the RDKit_. A command line client for subversion can be installed as part of the cygwin installation, or a very nice graphical client that integrates well with windows explorer can be downloaded from the [http://tortoisesvn.tigris.org/ Tortoise SVN home page].

== Setup and Preparation ==
This section assumes that python is installed in c:\Python25, that the boost libraries have been extracted to c:\boost\boost_1_36_0, and that you will build the RDKit from a directory named c:\RDKit. If any of these conditions is not true, just change the corresponding paths. 

 Notes : 
    # If you install things in paths that have spaces in their names, be sure to use quotes properly in your environment variable definitions.
    # If you have more than one version of visual studio installed, the instructions below may not use the correct compiler. In this case you need to use a different `--toolset` argument to specify the version of the compiler used in all commands. Information for this situation is covered in [http://www.boost.org/doc/libs/1_36_0/more/getting_started/windows.html the boost.build documentation].

  * Make sure that boost builds properly by going to directory c:\boost\boost_1_36_0 and executing the command: `.\bjam.exe --toolset=msvc --with-thread --with-python release install`. This may take a bit, but it should finish without errors. This provides a good test that at least the compiler and bjam are installed properly.
  * If you are planning on using a development version of the RDKit: get a copy of the current RDKit source using subversion. If you're using the command-line client the command is: `svn co http://rdkit.svn.sourceforge.net/svnroot/rdkit/trunk c:\RDKit` 
  * If you are planning on using a released version of the RDKit : get a copy of the most recent release and extract it into the directory c:\RDKit 
  * Set the required environment variables (you can set this in cygwin or in windows. If you set them in windows, be sure to restart your cygwin window):
  ** RDBASE = c:\RDKit
  ** BOOSTHOME = c:\boost\boost_1_36_0
  ** BOOST_BUILD_PATH = c:\boost\boost_1_36_0
  ** If Python is not installed in the standard location, the PYTHONHOME environment variable should point to the root of your Python installation.
  * Make sure that the directory c:\Python25 is in your PATH
  * Make sure that the directory c:\RDKit\bin is in your PATH
  * Make sure that the directory c:\boost\lib is in your PATH
  * Make sure that the directory c:\RDKit\Python is in your PYTHONPATH

== Building the RDKit ==
  * cd to your $RDBASE\Code directory
  * run : `c:\boost\boost_1_36_0\bjam.exe --toolset=msvc`. This will take a while and will generate a lot of text (including many warnings), but it should finish without errors. 

If the last step above completed without errors, you have succeeded in building the RDKit C++ libraries and Python wrappers. Congratulations!

== Testing ==
It's a good idea to test your build to make sure everything is ok. Here's how to do so.

  * cd to your $RDBASE\Code directory
  * run `python c:/RDKit/Python/TestRunner.py test_list.py`. After this completes (less than 30 seconds), you should see a message like this:
{{{
-----------------
        Script: test_list.py.  Passed 14 tests in 9.63 seconds
}}}
  Note that the number of tests passed and time required to run will change as the code itself changes.  The important thing is that no failures are reported.
  * cd to your $RDBASE\Code\GraphMol directory
  * run `python c:/RDKit/Python/TestRunner.py test_list.py`. After this completes (less than 60 seconds), you should see a message like the one above.
  * cd to your $RDBASE\Python\Chem directory
  * run `python c:/RDKit/Python/TestRunner.py test_list.py`. After this completes (less than 60 seconds), you should see a message like the one above.

If these three test suites pass without failures, your RDKit installation is in good shape and you are ready to go.



Please see the file license.txt for details about the "New BSD"
license which covers this software and its associated data and
documents. 

# $Id: README 694 2008-05-24 05:56:39Z glandrum $
# Copyright (C) 2008 Greg Landrum