diff --git a/doc/doxygen/build.dox b/doc/doxygen/build.dox index 4c6574752..2e6b8a52c 100644 --- a/doc/doxygen/build.dox +++ b/doc/doxygen/build.dox @@ -1,8 +1,8 @@ /** -\page cantera-build Cantera Compilation Guide +\page cantera-build %Cantera Compilation Guide -This guide contains instructions for compiling Cantera on the following operating systems: +This guide contains instructions for compiling %Cantera on the following operating systems: - Linux - Ubuntu 10.04 LTS (Lucid Lynx) or newer @@ -10,7 +10,7 @@ This guide contains instructions for compiling Cantera on the following operatin - 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 +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. @@ -46,7 +46,7 @@ build and what architecture (32-bit or 64-bit) you want to use. 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 + 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 @@ -64,12 +64,12 @@ build and what architecture (32-bit or 64-bit) you want to use. - 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 +- %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: +- 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 @@ -79,7 +79,7 @@ build and what architecture (32-bit or 64-bit) you want to use. \verbatim python setup.py install --user \endverbatim -\section download-cantera Download the Cantera source code +\section download-cantera Download the %Cantera source code \subsection download-posix Linux / OS X @@ -100,7 +100,7 @@ build and what architecture (32-bit or 64-bit) you want to use. \subsection config-general General - run \verbatim scons help \endverbatim to see a list all - configuration options for Cantera. + 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 @@ -108,17 +108,27 @@ build and what architecture (32-bit or 64-bit) you want to use. \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: +- If you want to build the Matlab toolbox, you will need to specify the path + to the Matlab installation, e.g. \verbatim - matlab_toolbox=y - matlab_cmd=/path/to/matlab \endverbatim + 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 + 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". @@ -127,12 +137,6 @@ build and what architecture (32-bit or 64-bit) you want to use. 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: @@ -140,12 +144,10 @@ build and what architecture (32-bit or 64-bit) you want to use. 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 +- 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 @@ -159,22 +161,39 @@ build and what architecture (32-bit or 64-bit) you want to use. \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 +\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: + 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 +- %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. @@ -197,10 +216,10 @@ build and what architecture (32-bit or 64-bit) you want to use. #include_next #endif \endverbatim -\section software-sources Sources and versions of software used by Cantera: +\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 +system. A Fortran compiler is required only if you plan to use %Cantera from a Fortran program. - GNU compilers (C/C++/Fortran) @@ -209,7 +228,7 @@ from a Fortran program. - 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 + - 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. @@ -237,18 +256,18 @@ from a Fortran program. \subsection software-optional Optional Programs - Numpy - - Required to build the Cantera Python module. + - 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. + - 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 + - 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 diff --git a/doc/doxygen/scons-options.txt b/doc/doxygen/scons-options.txt index 29383e49f..4cb647446 100644 --- a/doc/doxygen/scons-options.txt +++ b/doc/doxygen/scons-options.txt @@ -20,6 +20,20 @@ of this file is: ************************************************** +* msvc_version: [ string ] + Version of Visual Studio to use. The default is the same version + that was used to compile the installed version of Python. + - default: '9.0' + +* target_arch: [ string ] + Target architecture. The default is the same architecture as the + installed version of Python + - default: 'amd64' + +* toolchain: [ msvc | mingw | intel ] + The preferred compiler toolchain. + - default: 'msvc' + * CXX: [ string ] The C++ compiler to use. - default: 'g++' @@ -32,7 +46,6 @@ of this file is: * prefix: [ /path/to/prefix ] Set this to the directory where Cantera should be installed. - default: '/usr/local' - - actual: '/opt/cantera-dev' * python_package: [ full | minimal | none | default ] If you plan to work in Python, or you want to use the graphical @@ -72,17 +85,18 @@ of this file is: * matlab_toolbox: [ y | n | default ] This variable controls whether the Matlab toolbox will be built. If - it is set to 'default', the Matlab toolbox will be built if Matlab - can be found in the $PATH. Note that you may need to run 'mex - -setup' within Matlab to configure it for your C++ compiler before - building Cantera. + set to 'y', you will also need to set the value of the 'matlab_path' + variable. If set to 'default', the Matlab toolbox will be built if + 'matlab_path' is set. - default: 'default' - - actual: 'n' -* matlab_cmd: [ /path/to/matlab_cmd ] - Path to the Matlab executable. In Windows, this is probably - something like "C:/Program Files/MATLAB/R2009a/bin/win64/MATLAB.exe" - - default: 'matlab' +* matlab_path: [ /path/to/matlab_path ] + Path to the Matlab install directory. This should be the directory + containing the 'extern', 'bin', etc. subdirectories. Typical values + are: "C:/Program Files/MATLAB/R2011a" on Windows, + "/Applications/MATLAB_R2011a.app" on OS X, or "/opt/MATLAB/R2011a" + on Linux. + - default: '' * f90_interface: [ y | n | default ] This variable controls whether the Fortran 90/95 interface will be @@ -90,7 +104,6 @@ of this file is: Fortran compiler in the $PATH, and compile the Fortran 90 interface if one is found. - default: 'default' - - actual: 'n' * F90: [ /path/to/F90 ] The Fortran 90 compiler. If unspecified, the builder will look for a @@ -101,8 +114,9 @@ of this file is: Compilation options for the Fortran 90 compiler. - default: '-O3' -* debug: [ yes | no ] - Enable extra printing code to aid in debugging. +* debug_verbose: [ yes | no ] + Enable extra printing to aid in debugging. This code is marked by + the preprocessor macros DEBUG_MODE and DEBUG_MODE_ENABLED. - default: 'no' * coverage: [ yes | no ] @@ -113,7 +127,6 @@ of this file is: * build_docs: [ yes | no ] Build HTML documentation using Doxygen - default: 'no' - - actual: 'yes' * with_lattice_solid: [ yes | no ] Include thermodynamic model for lattice solids in the Cantera @@ -270,33 +283,63 @@ of this file is: * lapack_ftn_string_len_at_end: [ yes | no ] - default: 'yes' +* env_vars: [ string ] + Environment variables to propagate through to SCons. Either the + string "all" or a comma separated list of variable names, e.g. + 'LD_LIBRARY_PATH,HOME' + - default: '' + * cxx_flags: [ string ] Compiler flags passed to the C++ compiler only. - default: '-ftemplate-depth-128' - - actual: '-fbounds-check' * cc_flags: [ string ] Compiler flags passed to both the C and C++ compilers, regardless of optimization level - - default: '-Wall -g' + - default: '-Wall -Wno-deprecated-declarations' + +* thread_flags: [ string ] + Compiler and linker flags for POSIX multithreading support + - default: '-pthread' * optimize: [ yes | no ] - Enable extra compiler optimizations specified by the "release_flags" - variable, instead of the flags specified by the "debug_flags" - variable + Enable extra compiler optimizations specified by the + "optimize_flags" variable, instead of the flags specified by the + "debug_flags" variable - default: 'yes' - - actual: 'no' -* release_flags: [ string ] +* optimize_flags: [ string ] Additional compiler flags passed to the C/C++ compiler when optimize=yes. - - default: '-O3 -finline-functions -Wno-inline -DNDEBUG' + - default: '-O3 -DNDEBUG -finline-functions -Wno-inline' -* debug_flags: [ string ] +* no_optimize_flags: [ string ] Additional compiler flags passed to the C/C++ compiler when optimize=no. - default: '-O0 -fno-inline' +* debug: [ yes | no ] + Enable compiler debugging symbols. + - default: 'yes' + +* debug_flags: [ string ] + Additional compiler flags passed to the C/C++ compiler when + debug=yes. + - default: '-g' + +* no_debug_flags: [ string ] + Additional compiler flags passed to the C/C++ compiler when + debug=no. + - default: '' + +* debug_linker_flags: [ string ] + Additional options passed to the linker when debug=yes + - default: '' + +* no_debug_linker_flags: [ string ] + Additional options passed to the linker when debug=yes + - default: '' + * build_thread_safe: [ yes | no ] Cantera can be built so that it is thread safe. Doing so requires using procedures from the Boost library, so if you want thread @@ -341,7 +384,11 @@ of this file is: 'scons install' will install files to 'stage_dir/prefix/...' instead of installing into the local filesystem. - default: '' - - actual: 'stage' + +* legacy_headers: [ yes | no ] + Create symbolic links for headers that were installed to the + 'kernel' subdirectory in previous versions of Cantera. + - default: 'no' * graphvisdir: [ /path/to/graphvisdir ] The directory location of the graphviz program, dot. dot is used for