diff --git a/doc/doxygen/build.dox b/doc/doxygen/build.dox deleted file mode 100644 index 2e6b8a52c..000000000 --- a/doc/doxygen/build.dox +++ /dev/null @@ -1,277 +0,0 @@ -/** - -\page cantera-build %Cantera Compilation Guide - -This guide contains instructions for compiling %Cantera on the following operating systems: - -- Linux - - Ubuntu 10.04 LTS (Lucid Lynx) or newer - - Debian 5.0 (Lenny) or newer -- Windows Vista or Windows 7 (32-bit or 64-bit versions) -- OS X 10.6 (Snow Leopard) or newer - -In addition to the above operating systems, %Cantera should work on any -Unix-like system where the necessary prerequisites are available, but some -additional configuration may be required. - -\section prereqs Installation Prerequisites - -\subsection Linux -- For Ubuntu or Debian users, the following packages should be - installed using your choice of package manager: - \verbatim - g++ python scons libboost-all-dev libsundials-serial-dev subversion \endverbatim -- Building the python module also requires: - \verbatim - python-dev python-numpy python-numpy-dev \endverbatim -- Building the Fortran interface also requires gfortran or another - supported Fortran compiler. -- Users of other distributions should install the equivalent - packages, which may have slightly different names. - -\subsection Windows - -There are a number of requirements for the versions of software to -install depending on which interfaces (Python, Matlab) you want to -build and what architecture (32-bit or 64-bit) you want to use. - -- If you want to build the Python module, you must use the same - version of the Microsoft compiler as was used to compile Python. For - current versions of Python (2.6 and 2.7) this means that you must - use Visual Studio 2008 or the equivalent version of the Windows SDK - (see link below). -- The build process will produce a Python module compatible with the - version of Python used for the compilation. To generate different - modules for other versions of Python, you will need to install those - versions of Python and recompile. -- If you want to build the Matlab toolbox and you have a 64-bit copy - of Windows, by default you will be using a 64-bit copy of Matlab, - and therefore you need to compile %Cantera in 64-bit mode. For - simplicity, it is highly recommended that you use a 64-bit version - of Python to handle this automatically. -- There is no 64-bit installer for SCons under Windows, so you will - need to download the ZIP version. After extracting it, start a - command prompt in the unzipped folder and run: - \verbatim - python setup.py install \endverbatim -- It is generally helpful to have SCons and Python in your PATH. This - can usually be accomplished by adding the top-level Python directory - (e.g. C:\Python27) to your PATH. This is accessible from: - \verbatim - Control Panel > System and Security > System > Advanced System Settings > Environment Variables \endverbatim - -\subsection osx OS X -- Download and install Xcode from the Apple Developer site: - \verbatim - https://developer.apple.com/xcode/index.php \endverbatim -- %Cantera can be compiled with the command line tools that ship with either - Xcode 3.x or Xcode 4.x. -- If you don't have numpy version >= 1.3, you can install a recent version with: - \verbatim - sudo easy_install -U numpy \endverbatim -- If you want to build %Cantera with Fortran 90 support, download gfortran from: - \verbatim - http://gcc.gnu.org/wiki/GFortranBinaries#MacOS \endverbatim -- Download scons-2.1.0.tar.gz from scons.org and extract the contents. Install with either - \verbatim - sudo python setup.py install \endverbatim - to install for all users, or - \verbatim - python setup.py install --user \endverbatim - -\section download-cantera Download the %Cantera source code - -\subsection download-posix Linux / OS X - -- Option 1: Check out the code using Subversion: - \verbatim - svn checkout http://cantera.googlecode.com/svn/cantera/trunk/ cantera \endverbatim - -- Option 2: Check out the code using Git: - \verbatim - git svn clone --std-layout http://cantera.googlecode.com/svn/cantera cantera \endverbatim - -\subsection download-win Windows - Use your Subversion client to check out the code from: - \verbatim - http://cantera.googlecode.com/svn/cantera/trunk/ \endverbatim - -\section cantera-config Determine configuration options - -\subsection config-general General -- run \verbatim scons help \endverbatim to see a list all - configuration options for %Cantera. -- If the prerequisites are installed in standard locations, the - default values should work. -- If you installed Sundials to a non-standard location (e.g. the - libraries aren’t in /usr/lib), you will need to specify the options: - \verbatim - sundials_include=/path/to/sundials/include - sundials_libdir=/path/to/sundials/lib \endverbatim -- If you want to build the Matlab toolbox, you will need to specify the path - to the Matlab installation, e.g. - \verbatim - matlab_path=/opt/MATLAB/R2011a - matlab_path="C:\Program Files\MATLAB/R2011a" - matlab_path=/Applications/MATLAB_R2011a.app \endverbatim - The above paths are typical defaults on Linux, Windows, and OS X, - respectively. -- SCons saves configuration options specified on the command line in the file - \b cantera.conf in the root directory of the source tree, so generally it is - not necessary to respecify configuration options when rebuilding %Cantera. - To unset a previously set configuration option, either remove the - corresponding line from cantera.conf or use the syntax - \verbatim - option_name= \endverbatim - -\see \ref configCantera - -\subsection Windows (MSVC) -- In Windows there aren’t any proper default locations for many of the - packages that %Cantera depends on, so you will need to specify these - paths explicitly. -- Remember to put double quotes around any paths with spaces in them, - e.g. "C:\Program Files". -- By default, SCons attempts to use the same architecture and version - of the Microsoft compiler as was used to compile Python, typically - Visual Studio 2008 or the equivalent version of the Windows SDK. If - you aren’t building the Python module, you can override this with - the configuration options target_arch and msvc_version. - -\subsection Windows (MinGW) -- To compile with MinGW, use the SCons command line option: - \verbatim - toolchain=mingw \endverbatim -- The version of MinGW from www.mingw.org is 32-bit only, and therefore - cannot be used to build a 64-bit Python module. - -\subsection config-osx OS X - -- The available compilers to compile %Cantera will depend on the version - of Xcode that is installed. - - If Xcode 3 is installed, you can use either GCC by leaving the - \b CC and \b CXX options unspecified, or setting them to - \verbatim - CC=gcc CXX=g++ \endverbatim - You can also use LLVM with the GCC frontend by specifying - \verbatim - CC=llvm-gcc CXX=llvm-g++ \endverbatim - - If Xcode 4 is installed, then you can either use LLVM-GCC as above - or Clang by specifying: - \verbatim - CC=clang CXX=clang++ \endverbatim - -\subsection Intel Compilers -- Before compiling %Cantera, you may need to set up the appropriate environment - variables for the Intel compiler suite, e.g.: - \verbatim - source /opt/intel/bin/compilervars.sh intel64 \endverbatim -- For the Intel compiler to work with SCons, these environment variables need - to be passed through SCons by using the command line option - \verbatim - env_vars=all \endverbatim - Your final SCons call might then look something like - \verbatim - scons build env_vars=all CC=icc CXX=icpc F90=ifort F77=ifort \endverbatim - -\section compile-test Compile %Cantera & Test -- Run scons with the list of desired configuration options, e.g.: - \verbatim - scons build optimize=n blas_lapack_libs=blas,lapack prefix=/opt/cantera \endverbatim -- If %Cantera compiles successfully, you should see the message: - \verbatim - ************************************************************** - Compilation complete. Type '[sudo] scons install' to install. - ************************************************************** \endverbatim -- If you do not see this message, check the output for errors to see - what went wrong. -- %Cantera has a series of regression tests that can be run with the - command: - \verbatim - scons test \endverbatim -- In addition, a series of unit tests for the C++, Python, and Matlab - interfaces can be run with the command: - \verbatim - scons newtest \endverbatim - -- When the tests finish, you should see a summary indicating the - number of tests that passed and failed. - -- If you have tests that fail, try looking at the following to - determine the source of the error: - - Messages printed to the console while running scons test - - Output files generated by the tests - -\subsection compile-mingw MinGW Compilation problems - -- If you get a compiler error while compiling some of the "f2c" code, then - your version of MinGW has a problem with the order of its internal include - paths, such that it sees the GCC float.h before its own special version. To - fix this problem edit the GCC float.h located at (roughly): - \verbatim - c:\MinGW\lib\gcc\mingw32\4.6.1\include\float.h \endverbatim - and add the following just before the end (before the final #endif): - \verbatim -#ifndef _MINGW_FLOAT_H_ -#include_next -#endif \endverbatim - -\section software-sources Sources and versions of software used by %Cantera: - -You must have one of the following C++ compilers installed on your -system. A Fortran compiler is required only if you plan to use %Cantera -from a Fortran program. - -- GNU compilers (C/C++/Fortran) - - Known to work with version 4.6; Expected to work with version >= 4.3 -- Clang/LLVM (C/C++) - - Known to work with version 2.9 - - This is the version included with Apple Xcode 4.x -- Intel compilers (C/C++/Fortran) - - Known to work with version 11.0 and 12.1; Expected to work with versions >= 11.0 -- Microsoft compilers (C/C++) - - Windows SDK: http://www.microsoft.com/download/en/details.aspx?id=3138 - This is equivalent to Visual Studio 2008. It is a free download. - - Known to work with version 9.0 (Visual Studio 2008) and version 10.0 (Visual Studio 2010). -- MinGW (C/C++/Fortran) - - http://www.mingw.org - - Known to work with version 4.6. - - Supported versions of MinGW should be the same as the supported versions of GCC - -\subsection software-other Other Required software: - -- Subversion - - For Windows: http://tortoisesvn.net/downloads.html - - Known to work with versions >= 1.6 -- SCons: - - http://www.scons.org/download.php - - Known to work with SCons 2.1.0; Expected to work with versions >= 1.0.0 -- Python: http://python.org/download/ - - Known to work with 2.6 and 2.7; Expected to work with versions >= 2.5 - - Does not yet work with 3.x -- Boost - - http://www.boost.org/users/download/ - - Known to work with version 1.46; Expected to work with versions >= 1.40 - -\subsection software-optional Optional Programs - -- Numpy - - Required to build the %Cantera Python module. - - http://sourceforge.net/projects/numpy/ - - Known to work with versions 1.3 and 1.5; Expected to work with version >= 1.1 - - Test suite requires version >= 1.3 -- Matlab - - Required to build the %Cantera Matlab toolbox. - - Known to work with 2009a, 2010a, and 2011b. Expected to work with versions >= 2009a. -- Sundials - - Required to enable some features such as sensitivity analysis. - - https://computation.llnl.gov/casc/sundials/download/download.html - - Known to work with version 2.4; Support for versions 2.3 and 2.2 is deprecated. - - To use Sundials with %Cantera, you may need to compile it with the - -fPIC flag. You can specify this flag when configuring Sundials: - \verbatim - configure --with-cflags=-fPIC \endverbatim - -\see \ref cxx-ctnew - -*/ diff --git a/doc/doxygen/configuring.txt b/doc/doxygen/configuring.txt deleted file mode 100644 index bd766ef8d..000000000 --- a/doc/doxygen/configuring.txt +++ /dev/null @@ -1,14 +0,0 @@ -/** - -\page configCantera Configuring Cantera - -This document lists the options available for compiling Cantera with SCons. - -These options may be seen by running the command -\verbatim -scons help \endverbatim -from the command prompt. - -\include scons-options.txt - -*/ diff --git a/doc/sphinx/compiling.rst b/doc/sphinx/compiling.rst new file mode 100644 index 000000000..94afaaf31 --- /dev/null +++ b/doc/sphinx/compiling.rst @@ -0,0 +1,356 @@ +************************* +Cantera Compilation Guide +************************* + +.. toctree:: + :hidden: + + SCons Configuration Options + +This guide contains instructions for compiling Cantera on the following +operating systems: + +* Linux + + * Ubuntu 10.04 LTS (Lucid Lynx) or newer + * Debian 5.0 (Lenny) or newer + +* Windows Vista or Windows 7 (32-bit or 64-bit versions) +* OS X 10.6 (Snow Leopard) or newer + +In addition to the above operating systems, Cantera should work on any +Unix-like system where the necessary prerequisites are available, but some +additional configuration may be required. + +Installation Prerequisites +========================== + +Linux +----- + +* For Ubuntu or Debian users, the following packages should be installed using + your choice of package manager:: + + g++ python scons libboost-all-dev libsundials-serial-dev subversion + +* Building the python module also requires:: + + python-dev python-numpy python-numpy-dev + +* Building the Fortran interface also requires gfortran or another supported + Fortran compiler. +* Users of other distributions should install the equivalent packages, which + may have slightly different names. + +Windows +------- + +There are a number of requirements for the versions of software to install +depending on which interfaces (Python, Matlab) you want to build and what +architecture (32-bit or 64-bit) you want to use. + +* If you want to build the Python module, you must use the same version of the + Microsoft compiler as was used to compile Python. For current versions of + Python (2.6 and 2.7) this means that you must use Visual Studio 2008 or the + equivalent version of the Windows SDK (see link below). +* The build process will produce a Python module compatible with the version of + Python used for the compilation. To generate different modules for other + versions of Python, you will need to install those versions of Python and + recompile. +* If you want to build the Matlab toolbox and you have a 64-bit copy of + Windows, by default you will be using a 64-bit copy of Matlab, and therefore + you need to compile Cantera in 64-bit mode. For simplicity, it is highly + recommended that you use a 64-bit version of Python to handle this + automatically. +* There is no 64-bit installer for SCons under Windows, so you will need to + download the ZIP version. After extracting it, start a command prompt in the + unzipped folder and run:: + + python setup.py install + +* It is generally helpful to have SCons and Python in your PATH. This can + usually be accomplished by adding the top-level Python directory + (e.g. C:\Python27) to your PATH. This is accessible from:: + + Control Panel > System and Security > System > Advanced System Settings > Environment Variables + +OS X +---- + +* Download and install Xcode from the + `Apple Developer site `_ +* Cantera can be compiled with the command line tools that ship with either + Xcode 3.x or Xcode 4.x. +* If you don't have numpy version >= 1.3, you can install a recent version with:: + + sudo easy_install -U numpy + +* If you want to build Cantera with Fortran 90 support, download gfortran from:: + + http://gcc.gnu.org/wiki/GFortranBinaries#MacOS + +* Download scons-2.1.0.tar.gz from scons.org and extract the contents. Install with either:: + + sudo python setup.py install + + to install for all users, or:: + + python setup.py install --user + +Downloading the Cantera source code +=================================== + +Linux / OS X +------------ + +* Option 1: Check out the code using Subversion:: + + svn checkout http://cantera.googlecode.com/svn/cantera/trunk/ cantera + +* Option 2: Check out the code using Git:: + + git svn clone --std-layout http://cantera.googlecode.com/svn/cantera cantera + +Windows +------- + +Use your Subversion client to check out the code from:: + + http://cantera.googlecode.com/svn/cantera/trunk/ + +Determine configuration options +=============================== + +General +------- + +* run ``scons help`` to see a list all configuration options for Cantera, or + see :ref:`scons-config`. +* If the prerequisites are installed in standard locations, the default values + should work. +* If you installed Sundials to a non-standard location (e.g. the libraries + aren’t in /usr/lib), you will need to specify the options:: + + sundials_include=/path/to/sundials/include + sundials_libdir=/path/to/sundials/lib + +* If you want to build the Matlab toolbox, you will need to specify the path + to the Matlab installation, e.g.:: + + matlab_path=/opt/MATLAB/R2011a + matlab_path="C:\Program Files\MATLAB/R2011a" + matlab_path=/Applications/MATLAB_R2011a.app + + The above paths are typical defaults on Linux, Windows, and OS X, + respectively. +* SCons saves configuration options specified on the command line in the file + \b cantera.conf in the root directory of the source tree, so generally it is + not necessary to respecify configuration options when rebuilding Cantera. To + unset a previously set configuration option, either remove the corresponding + line from cantera.conf or use the syntax:: + + option_name= + + +Windows (MSVC) +-------------- + +* In Windows there aren’t any proper default locations for many of the packages + that Cantera depends on, so you will need to specify these paths explicitly. +* Remember to put double quotes around any paths with spaces in them, e.g. + "C:\Program Files". +* By default, SCons attempts to use the same architecture and version of the + Microsoft compiler as was used to compile Python, typically Visual Studio + 2008 or the equivalent version of the Windows SDK. If you aren’t building the + Python module, you can override this with the configuration options + ``target_arch`` and ``msvc_version``. + +Windows (MinGW) +--------------- + +* To compile with MinGW, use the SCons command line option:: + + toolchain=mingw + +* The version of MinGW from www.mingw.org is 32-bit only, and therefore cannot + be used to build a 64-bit Python module. + +OS X +---- + +* The available compilers to compile Cantera will depend on the version of + Xcode that is installed. + + * If Xcode 3 is installed, you can use either GCC by leaving the ``CC`` and + ``CXX`` options unspecified, or setting them to:: + + CC=gcc CXX=g++ + + You can also use LLVM with the GCC frontend by specifying:: + + CC=llvm-gcc CXX=llvm-g++ + + * If Xcode 4 is installed, then you can either use LLVM-GCC as above or + Clang by specifying:: + + CC=clang CXX=clang++ + +Intel Compilers +--------------- +* Before compiling Cantera, you may need to set up the appropriate environment + variables for the Intel compiler suite, e.g.:: + + source /opt/intel/bin/compilervars.sh intel64 + +* For the Intel compiler to work with SCons, these environment variables need + to be passed through SCons by using the command line option:: + + env_vars=all + + Your final SCons call might then look something like:: + + scons build env_vars=all CC=icc CXX=icpc F90=ifort F77=ifort + +Compile Cantera & Test +====================== + +* Run scons with the list of desired configuration options, e.g.:: + + scons build optimize=n blas_lapack_libs=blas,lapack prefix=/opt/cantera + +* If Cantera compiles successfully, you should see the message:: + + ************************************************************** + Compilation complete. Type '[sudo] scons install' to install. + ************************************************************** + +* If you do not see this message, check the output for errors to see what went + wrong. +* Cantera has a series of regression tests that can be run with the command:: + + scons test + +* In addition, a series of unit tests for the C++, Python, and Matlab + interfaces can be run with the command:: + + scons newtest + +* When the tests finish, you should see a summary indicating the number of + tests that passed and failed. + +* If you have tests that fail, try looking at the following to determine the + source of the error: + + * Messages printed to the console while running scons test + * Output files generated by the tests + +MinGW Compilation problems +-------------------------- + +* If you get a compiler error while compiling some of the "f2c" code, then your + version of MinGW has a problem with the order of its internal include paths, + such that it sees the GCC float.h before its own special version. To fix this + problem edit the GCC float.h located at (roughly):: + + c:\MinGW\lib\gcc\mingw32\4.6.1\include\float.h + + and add the following just before the end (before the final #endif) + + .. code-block:: c++ + + #ifndef _MINGW_FLOAT_H_ + #include_next + #endif + +Software used by Cantera +======================== + +This section lists the versions of third-party software that are required to +build and use Cantera. + +Compilers +--------- + +You must have one of the following C++ compilers installed on your system. A +Fortran compiler is required only if you plan to use Cantera from a Fortran +program. + +* GNU compilers (C/C++/Fortran) + + * Known to work with version 4.6; Expected to work with version >= 4.3 + +* Clang/LLVM (C/C++) + + * Known to work with version 2.9 + * This is the version included with Apple Xcode 4.x + +* Intel compilers (C/C++/Fortran) + + * Known to work with version 11.0 and 12.1; Expected to work with + versions >= 11.0 + +* Microsoft compilers (C/C++) + + * Windows SDK: http://www.microsoft.com/download/en/details.aspx?id=3138 + This is equivalent to Visual Studio 2008. It is a free download. + * Known to work with version 9.0 (Visual Studio 2008) and version 10.0 + (Visual Studio 2010). + +* MinGW (C/C++/Fortran) + + * http://www.mingw.org + * Known to work with version 4.6. + * Supported versions of MinGW should be the same as the supported versions of + GCC. + +Other Required Software +----------------------- + +* Subversion + + * For Windows: http://tortoisesvn.net/downloads.html + * Known to work with versions >= 1.6 + +* SCons: + + * http://www.scons.org/download.php + * Known to work with SCons 2.1.0; Expected to work with versions >= 1.0.0 + +* Python: + + * http://python.org/download/ + * Known to work with 2.6 and 2.7; Expected to work with versions >= 2.5 + * Does not yet work with 3.x + +* Boost + + * http://www.boost.org/users/download/ + * Known to work with version 1.46; Expected to work with versions >= 1.40 + +Optional Programs +----------------- + +* Numpy + + * Required to build the Cantera Python module. + * http://sourceforge.net/projects/numpy/ + * Known to work with versions 1.3 and 1.5; Expected to work with version >= 1.1 + * Test suite requires version >= 1.3 + +* Matlab + + * Required to build the Cantera Matlab toolbox. + * Known to work with 2009a, 2010a, and 2011b. Expected to work with + versions >= 2009a. + +* Sundials + + * Required to enable some features such as sensitivity analysis. + * https://computation.llnl.gov/casc/sundials/download/download.html + * Known to work with version 2.4; Support for versions 2.3 and 2.2 is deprecated. + * To use Sundials with Cantera, you may need to compile it with the + ``-fPIC`` flag. You can specify this flag when configuring Sundials:: + + configure --with-cflags=-fPIC + +.. \see \ref cxx-ctnew diff --git a/doc/sphinx/configuring.rst b/doc/sphinx/configuring.rst new file mode 100644 index 000000000..6b657c3c0 --- /dev/null +++ b/doc/sphinx/configuring.rst @@ -0,0 +1,15 @@ +.. _scons-config: + +******************* +Configuring Cantera +******************* + +This document lists the options available for compiling Cantera with SCons. + +These options may be seen by running the command:: + + scons help + +from the command prompt. + +.. literalinclude:: scons-options.txt diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index e17d4bafe..826ef2159 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -1,17 +1,20 @@ .. Cantera documentation master file, created by sphinx-quickstart on Mon Mar 12 11:43:09 2012. +********************* Cantera Documentation -===================== +********************* Contents ======== .. toctree:: :maxdepth: 2 + Compiliation Instructions python/index C++ API Documentation Cantera Development Homepage + Indexes ======= diff --git a/doc/doxygen/scons-options.txt b/doc/sphinx/scons-options.txt similarity index 100% rename from doc/doxygen/scons-options.txt rename to doc/sphinx/scons-options.txt