258 lines
10 KiB
Text
258 lines
10 KiB
Text
/**
|
||
|
||
\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 and the Matlab executable is
|
||
not on your PATH, you should specify:
|
||
\verbatim
|
||
matlab_toolbox=y
|
||
matlab_cmd=/path/to/matlab \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.
|
||
- If you’re building the Matlab toolbox, you need to specify the path
|
||
to the architecture-dependent Matlab executable. For example, if
|
||
you’re building the 64-bit toolbox, the correct option will be
|
||
something like:
|
||
\verbatim
|
||
matlab_cmd="C:/Program Files/MATLAB/R2009a/bin/win64/MATLAB.exe" \endverbatim
|
||
|
||
\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.
|
||
- MinGW cannot be used to build the Matlab toolbox because the "mex -setup"
|
||
command does not recognize MinGW.
|
||
|
||
\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
|
||
|
||
|
||
\section compile-test Compile Cantera & Test
|
||
- Run scons with the list of desired configuration options, e.g.:
|
||
\verbatim
|
||
scons build debug=y optimize=n 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
|
||
- 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 <float.h>
|
||
#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; 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
|
||
<b>-fPIC</b> flag. You can specify this flag when configuring Sundials:
|
||
\verbatim
|
||
configure --with-cflags=-fPIC \endverbatim
|
||
|
||
\see \ref cxx-ctnew
|
||
|
||
*/
|