research/cantera
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Moved compilation guide to Sphinx

Browse source
This commit is contained in:
Ray Speth 2012-03-30 23:46:42 +00:00
parent 4ef4c79be9
commit ed261a2d68
6 changed files with 375 additions and 292 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

277
doc/doxygen/build.dox
View file

@ -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 <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 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
<b>-fPIC</b> flag. You can specify this flag when configuring Sundials:
\verbatim
configure --with-cflags=-fPIC \endverbatim
\see \ref cxx-ctnew
*/

14
doc/doxygen/configuring.txt
View file

@ -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
*/

356
doc/sphinx/compiling.rst Normal file
View file

@ -0,0 +1,356 @@
*************************
Cantera Compilation Guide
*************************
.. toctree::
:hidden:
SCons Configuration Options <configuring>
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 <https://developer.apple.com/xcode/index.php>`_
* 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 <float.h>
#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

15
doc/sphinx/configuring.rst Normal file
View file

@ -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

5
doc/sphinx/index.rst
View file

@ -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 <compiling>
python/index
C++ API Documentation <http://cantera.github.com/docs/index.html>
Cantera Development Homepage <http://cantera.googlecode.com>
Indexes
=======

0
doc/doxygen/scons-options.txt → doc/sphinx/scons-options.txt
View file