Configure & Build Cantera¶
These directions are for the current release of Cantera, version 2.4. For the development version, see these instructions.
Determine configuration options¶
scons helpto see a list of all of the configuration options for Cantera, or see all of the options on the Configuration Options page.
Configuration options are specified as additional arguments to the
sconscommand. For example:
scons command option_name=value
sconsis the program that manages the build steps, and
commandis most commonly one of
Other commands are possible, and are explained in the Build Commands section.
SCons saves configuration options specified on the command line in the file
cantera.confin 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.confor use the syntax:
scons command option_name=
Sometimes, changes in your environment can cause SCons’s configuration tests (for example, checking for libraries or compiler capabilities) to unexpectedly fail. To force SCons to re-run these tests rather than trusting the cached results, run scons with the option
The following lists of options are not complete, they show only some commonly used options. The entire list of options can be found on the Configuration options page.
General Python Module Options¶
By default, SCons will try to build the full Python interface for whichever version of Python is running SCons. This requires that NumPy is installed for that version of Python, and that Cython is installed for whichever Python is running SCons. The following SCons options control how the Python module is built:
Note that these general options should not be used at the same time as the Python-version specific options discussed below. If SCons detects that it is being run with Python 2, and the python2_package option is set, the build will raise an error and exit; or if SCons detects that it is being run with Python 3, and the python3_package option is set, the build will raise an error and exit.
If a user wishes to build multiple Python interfaces, or a Python
interface for the version of Python that is not running SCons, they
should use the version-specific options below, and set the
python_package option to
Python 2 Module Options¶
By default, if SCons detects a Python 2 interpreter installed in a
default location (that is, if
python2 is on the
full, SCons will try to build
the Python module for Python 2. The following SCons options control how
the Python 2 module is built:
Python 3 Module Options¶
By default, if SCons detects a Python 3 interpreter installed in a
default location (that is, if
python3 is on the
full, SCons will try to build
the Python module for Python 3. The following SCons options control how
the Python 3 module is built:
Windows Only Options¶
cantera.conf file uses the backslash character
\ as an escape
character. When modifying this file, backslashes in paths need to be escaped
boost_inc_dir = 'C:\\Program Files (x86)\\boost\\include'
This does not apply to paths specified on the command line. Alternatively,
you can use forward slashes (
/) in paths.
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, such as
By default, SCons attempts to use the same architecture as the copy of Python that is running SCons, and the most recent installed version of the Visual Studio compiler. If you aren’t building the Python module, you can override this with the configuration options
To compile with MinGW, specify the toolchain option:
MATLAB Toolbox Options¶
Building the MATLAB toolbox requires an installed copy of MATLAB, and the path to the directory where MATLAB is installed must be specified using the following option:
Fortran Module Options¶
Building the Fortran module requires a compatible Fortran comiler. SCons will
attempt to find a compatible compiler by default in the
variable. The following options control how the Fortran module is built:
The following options control if the documentation is built:
The following options are possible as commands to SCons (that is, the first
Print a description of user-specifiable options.
Compile Cantera and the language interfaces using default options.
Delete files created while building Cantera.
[sudo] scons install
[sudo] scons uninstall
Run all tests which did not previously pass or for which the results may have changed.
Reset the passing status of all tests.
Delete files created while running the tests.
List available tests.
Run the test named
scons <command> dump
Dump the state of the SCons environment to the screen instead of doing
<command>, for example,
scons build dump. For debugging purposes.
Compile the C++ and Fortran samples.
Build a Windows installer (.msi) for Cantera.
Build the Sphinx documentation
Build the Doxygen documentation
Compile Cantera & Test¶
Run SCons with the list of desired configuration options:
scons build ...
If you are compiling with a version of SCons installed by Homebrew on macOS, the appropriate way to perform any commands with SCons is
python3 /usr/local/bin/scons command ...
This ensures that the dependencies are chosen from the correct version of Python.
If Cantera compiles successfully, you should see a message that looks like:
******************************************************* Compilation completed successfully. - To run the test suite, type 'scons test'. - To install, type '[sudo] scons install'. *******************************************************
If you do not see this message, check the output for errors to see what went wrong.
Cantera has a series of tests that can be run with the command:
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
Output files generated by the tests