GreenPolyProducts/cantera
5
0
Fork 0
mirror of https://github.com/Cantera/cantera.git synced 2025-02-25 18:55:29 -06:00
Code Issues Packages Projects Releases Wiki Activity

Migrate compilation docs into Sphinx/MyST

Browse Source
This commit is contained in:
Ray Speth 2023-10-04 16:54:52 -04:00 committed by Ray Speth
parent 3cebba3773
commit a7021138a1
12 changed files with 1269 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.github/workflows/main.yml vendored
View File

@ -338,11 +338,6 @@ jobs:
python3 `which scons` help --options
python3 `which scons` help --list-options
python3 `which scons` help --option=prefix
- name: Parse configuration options from SConstruct as reST
run: |
python3 `which scons` help --restructured-text --dev --output=config-options-dev.rst
mkdir build/doc/scons
mv config-options-dev.rst build/doc/scons/
- name: Create archive for docs output
run: |
cd build/doc

5
SConstruct
View File

@ -937,6 +937,11 @@ for arg in ARGUMENTS:
logger.error(f"Encountered unexpected command line option: {arg!r}")
sys.exit(1)
# Store full config for doc build
if env['sphinx_docs']:
config.add(windows_options)
env['config'] = config
env["cantera_version"] = "3.1.0a1"
# For use where pre-release tags are not permitted (MSI, sonames)
env['cantera_pure_version'] = re.match(r'(\d+\.\d+\.\d+)', env['cantera_version']).group(0)

11
doc/SConscript
View File

@ -1,6 +1,7 @@
from collections import namedtuple
from os.path import join as pjoin
from pathlib import Path
import os
import subprocess
from buildutils import *
@ -162,6 +163,16 @@ if localenv['sphinx_docs']:
localenv.Command(f"#build/doc/samples/clib/{clib_file.name}",
clib_file, Copy("$TARGET", "$SOURCE")))
# Generate documentation for SCons configuration options
def save_config(target, source, env):
Path(str(target[0])).parent.mkdir(parents=True, exist_ok=True)
with open(str(target[0]), "w") as outfile:
outfile.write(env["config"].to_rest())
scons_opts = localenv.Command(
"#build/doc/sphinx/develop/compiling/scons-config-options.rst.inc",
"#SConstruct", save_config)
env.Depends(sphinxdocs, scons_opts)
# Create a list of MATLAB classes to document. This uses the NamedTuple
# structure defined at the top of the file. The @Data and @Utilities
# classes are fake classes for the purposes of documentation only. Each

2
doc/sphinx/conf.py
View File

@ -222,7 +222,7 @@ intersphinx_mapping = {
'pint': ('https://pint.readthedocs.io/en/stable/', None),
}
myst_enable_extensions = ["dollarmath", "amsmath", "deflist"]
myst_enable_extensions = ["dollarmath", "amsmath", "deflist", "colon_fence"]
# Ensure that the primary domain is the Python domain, since we've added the
# MATLAB domain with sphinxcontrib.matlab

565
doc/sphinx/develop/compiling/compilation-reqs.md Normal file
View File

@ -0,0 +1,565 @@
(sec-compilation-reqs)=
# Compilation Requirements
Click the buttons below to see the required software that you must install to
compile Cantera on your operating system.
`````{grid} auto
````{grid-item}
```{button-ref} sec-conda
:color: primary
:shadow:
```
````
````{grid-item}
```{button-ref} sec-ubuntu-debian-reqs
:color: primary
:shadow:
```
````
````{grid-item}
```{button-ref} sec-opensuse-reqs
:color: primary
:shadow:
OpenSUSE & SLE
```
````
````{grid-item}
```{button-ref} sec-fedora-reqs
:color: primary
:shadow:
Fedora & RHEL
```
````
````{grid-item}
```{button-ref} sec-macos
:color: primary
:shadow:
```
````
````{grid-item}
```{button-ref} sec-windows
:color: primary
:shadow:
```
````
`````
(sec-conda)=
## Conda & Anaconda
### General Notes
- These instructions will set you up to build Cantera with the dependencies installed in
a Conda environment
- You will need to install compilers for your system by following the instructions in
the sections below to install the compiler for your operating system.
- By default, Cantera is installed into the active conda environment, where the layout
of the directory structure corresponds to the [configuration option](configure-build)
`layout=conda`.
(sec-conda-reqs)=
### Conda Requirements
- Install [Anaconda](https://www.anaconda.com/download/),
[Miniconda](https://conda.io/miniconda.html), or
[Miniforge](https://github.com/conda-forge/miniforge).
- Launch the command line interface:
- On macOS and Linux, the installer should add the appropriate activation mechanism
for your normal terminal by default. You can test this by running
```bash
conda --version
```
in the terminal. If there is no output or an error appears, locate your Conda
installation and run the following code in the terminal:
```bash
/path/to/conda/install/folder/bin/conda init --all
```
Then restart your terminal or shell.
- On Windows, use the Anaconda PowerShell to run the build process (available from
the Start Menu). When using MSVC compilers, you also need to set environment
variables for x64-native tools (see [Developer command file locations](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_file_locations))
by running
```bash
. "C:\path\to\MSVC\Auxiliary\Build\vcvars64.bat"
```
(note that the period `'.'` is part of the command). The path can be found as
follows: locate the **x64 Native Tools Command Prompt** in the Start Menu,
right-click, select **More > Open File Location**, right-click on the shortcut,
select **Properties** and copy the **Target** command.
- Create an environment `ct-build` with the dependencies to build Cantera. Create a
file called `environment.yaml` with the following content
```yaml
name: ct-build
channels:
- conda-forge
dependencies:
- python # Cantera supports Python 3.8 and up
- scons # build system
- boost-cpp # C++ dependency
- hdf5 # optional C++ dependency
# - highfive # C++ dependency; uncomment to override Cantera default
# - sundials # uncomment to override Cantera default
# - fmt # uncomment to override Cantera default
# - eigen # uncomment to override Cantera default
# - yaml-cpp # uncomment to override Cantera default
# - libgomp # optional (OpenMP implementation when using GCC)
- cython # needed to build Python package
- numpy # needed to build Python package
- pip # needed to build Python package
- wheel # needed to build Python package
- setuptools # needed to build Python package
- pytest # needed for the Python test suite
# - pytest-cov # optional (needed if running with test coverage enabled)
- ruamel.yaml # needed for converter scripts
# - pandas # optional (needed for pandas interface)
# - scipy # optional (needed for some examples)
# - matplotlib # optional (needed for plots)
# - python-graphviz # optional (needed for reaction path diagrams)
- ipython # optional (needed for nicer interactive command line)
# - jupyter # optional (needed for Jupyter Notebook)
# - sphinx # optional (needed for documentation)
# - pydata-sphinx-theme # optional (needed for documentation)
# - sphinx-argparse # optional (needed for documentation)
# - doxygen # optional (needed for documentation)
# - graphviz # optional (needed for documentation)
# - texlive-core # optional (needed for documentation)
# - perl # optional (needed for documentation)
# - pip: # optional (list of PyPI managed packages)
# - sphinxcontrib-matlabdomain # optional (needed for documentation)
# - sphinxcontrib-doxylink # optional (needed for documentation)
```
The environment is then created and activated using
```bash
conda env create -f environment.yaml
conda activate ct-build
```
After creating the environment, it can be updated from within `ct-build` using
```bash
conda env update -f environment.yaml --prune
```
- (Optional) If you want to override external libraries packaged with Cantera
(`sundials`, `fmt`, `eigen`, `yaml-cpp`), simply uncomment corresponding lines in the
file `environment.yaml` above. Note that specific versions can be forced by providing
version numbers (example: replace `sundials` by `sundials=5.8` to install version
`5.8`).
- (Optional) If you want to build the documentation, make sure to uncomment lines for
`pip`, `sphinx`, `doxygen`, and any other lines marked as "needed for documentation"
in the `environment.yaml` sample above.
- (Cantera \< 2.6 only) On previous Cantera versions, the build process required
configuration options `boost_inc_dir` and `prefix` (see [configuration
options](configure-build)); starting with Cantera 2.6, these settings are detected
automatically.
:::{note}
As the compiled code is based on the conda environment `ct-build`, it is only
usable from within that environment. This means that in order to use the compiled
Cantera package, you have to activate your `ct-build` environment first.
:::
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```
(sec-linux)=
## Linux
### General Notes
- To download the source code, installing `git` is highly recommended in addition
to the requirements listed below.
- The following instructions use the system-installed versions of Python, but alternate
installations such as the Anaconda distribution of Python can be used as well.
- Cython is only required to be installed for the version of Python that also has SCons
installed; following the instructions below will install Cython for the version of
Python installed in the system directories. The minimum compatible Cython version is
0.29.31. If your distribution does not contain a suitable version, you may be able to
install a more recent version using Pip.
- Users of other distributions should install the equivalent packages, which may have
slightly different names.
- In addition to the operating systems below, Cantera should work on any Unix-like
system where the necessary prerequisites are available, but some additional
configuration may be required.
(sec-ubuntu-debian-reqs)=
### Ubuntu & Debian
- Ubuntu 20.04 LTS (Focal Fossa) or newer
- Debian 11.0 (Bullseye) or newer
- The following packages must be installed to build any of the Cantera modules using
your choice of package manager:
```
g++ python3 scons libboost-dev libhdf5-dev
```
- The HDF5 headers and libraries are not installed to directories on the compiler's
default search path. When building Cantera, these paths need to be specified as
options to `scons`, for example `extra_inc_dirs=/usr/include/hdf5/serial` and
`extra_lib_dirs=/usr/lib/x86_64-linux-gnu/hdf5/serial`.
- If you want to use system system packages to provide the following dependencies,
instead of the versions bundled with Cantera, you should also install:
```
libsundials-dev libeigen3-dev libyaml-cpp-dev libfmt-dev
```
- In addition to the general packages, building the Python 3 module also requires:
```
cython3 python3-setuptools python3-wheel python3-numpy python3-ruamel.yaml python3-pytest
```
- Debian 12.0 (Bookworm) and Ubuntu 23.04 (Lunar Lobster) provide compatible Cython
versions. For older releases, install Cython using Pip.
- In addition to the general packages, building the Fortran module also requires:
```
gfortran
```
- In addition to the general packages, building the MATLAB toolbox also requires:
- MATLAB version later than 2009a
- Typically installed to:
```
/opt/MATLAB/R20YYn
```
where `YY` is a two digit year and `n` is either `a` or `b`
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```
(sec-fedora-reqs)=
### Fedora & RHEL
- The following packages must be installed to build any of the Cantera modules using
your choice of package manager:
```
gcc-c++ python3 scons boost-devel hdf5-devel
```
- If you want to use system system packages to provide the following dependencies,
instead of the versions bundled with Cantera, you should also install:
> sundials-devel eigen3-devel yaml-cpp-devel fmt-devel highfive-devel
- In addition to the general packages, building the Python 3 module also requires:
```
python3-devel Cython python3-numpy python3-ruamel-yaml python3-pytest
```
- In addition to the general packages, building the Fortran module also requires:
```
gcc-gfortran
```
- In addition to the general packages, building the MATLAB toolbox also requires:
- MATLAB version later than 2009a
- Typically installed to:
```
/opt/MATLAB/R20YYn
```
where `YY` is a two digit year and `n` is either `a` or `b`
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```
(sec-opensuse-reqs)=
### OpenSUSE & SUSE Linux Enterprise
- OpenSUSE Leap 15.5 or newer recommended
- The following packages must be installed to build any of the Cantera modules using
your choice of package manager:
```
gcc11-c++ python311 libboost_headers1_75_0-devel hdf5-devel python311-pip
```
You can specify other version numbers for GCC, Python, and Boost, as long as they meet
Cantera's minimum requirements.
- You will also need to install `scons` using the Pip version installed above.
- In addition to the general packages, building the Python module also requires:
```
python3-devel
```
as well as the following packages installed using Pip:
> numpy wheel cython ruamel.yaml pytest
- In addition to the general packages, building the Fortran module also requires:
```
gcc11-fortran
```
- In addition to the general packages, building the MATLAB toolbox also requires:
- MATLAB version later than 2009a
- Typically installed to:
```
/opt/MATLAB/R20YYn
```
where `YY` is a two digit year and `n` is either `a` or `b`
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```
(sec-windows)=
## Windows
### General Notes
- 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.
- The following instructions use the versions of Python downloaded from
<https://www.python.org/downloads/>, but alternate installations such as the Anaconda
distribution of Python can be used as well.
- 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.
- It is generally helpful to have SCons and Python in your `PATH` environment variable.
This can be done by checking the appropriate box during the installation of Python or
can be accomplished by adding the top-level Python directory and the `Scripts`
subdirectory (for example, `C:\Python311;C:\Python311\Scripts`) to your `PATH`. The
dialog to change the `PATH` is accessible from:
```
Control Panel > System and Security > System > Advanced System Settings > Environment Variables
```
Make sure that the installation of Python that has SCons comes first on your `PATH`.
- In order to use SCons to install Cantera to a system folder (for example,
`C:\Program Files\Cantera`) you must run the `scons install` command in a
command prompt that has been launched by selecting the *Run as Administrator*
option.
(sec-windows-reqs)=
### Windows Requirements
- Windows 7 or later; either 32-bit or 64-bit
- To build any of the Cantera modules, you will need to install
- Python
- <https://www.python.org/downloads/>
- Cantera supports Python 3.8 and higher
- Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
- When installing, make sure to choose the option to add to your `PATH`
- SCons
- <https://pypi.org/project/SCons/>
- Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
- One of the following supported compilers
- Microsoft compilers
- <https://visualstudio.microsoft.com/downloads/>
- Known to work with Visual Studio 2017 (MSVC 14.1), Visual Studio 2019
(MSVC 14.2), and Visual Studio 2022 (MSVC 14.3).
- MinGW compilers
- <http://mingw-w64.org/>
- <http://tdm-gcc.tdragon.net/>
- Known to work with Mingw-w64 12.2.
- The Boost headers
- <https://www.boost.org/doc/libs/1_82_0/more/getting_started/windows.html#get-boost>
- It is not necessary to compile the Boost libraries since Cantera only uses
the headers from Boost
- In addition to the general software, building the Python module also requires
several Python packages: Cython, NumPy, setuptools, wheel, ruamel.yaml, and pytest.
All of these can be installed using `pip`:
```bash
py -m pip install setuptools wheel cython numpy ruamel.yaml pytest
```
- In addition to the general software, building the MATLAB toolbox also requires:
- MATLAB version later than 2009a
- Typically installed to:
```
C:\Program Files\MATLAB\R20YYn
```
where `YY` is a two digit year and `n` is either `a` or `b`
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```
(sec-macos)=
## macOS
### General Notes
- Cantera 2.5.0 and higher do not support Python 2, which may be installed by default
on your computer. You must install Python 3 from another source to be able to build
Cantera. The instructions below use Homebrew.
(sec-mac-os-reqs)=
### macOS Requirements
- macOS 10.15 (Catalina) is required; Homebrew requires 11.0 or newer.
- To build any of the Cantera interfaces, you will need to install
- Xcode
- Download and install from the App Store
- From a Terminal, run:
```bash
sudo xcode-select --install
```
and agree to the Xcode license agreement
- Homebrew
- <https://brew.sh>
- From a Terminal, run:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
- Once Homebrew is installed, the rest of the dependencies can be installed with:
```bash
brew install python scons boost git hdf5 libomp
```
Note that brew installs Python 3 by default, but does not over-write the existing
system Python. When you want to use the brew-installed Python, check to make sure
that `python3` and `pip3` refer to the Homebrew installation by running:
```bash
which python3
which pip3
```
If these commands do not include the Homebrew path, you can run the correct ones as
`$(brew --prefix)/bin/python3` and `$(brew --prefix)/bin/pip3`.
- In addition to the general software, building the Python module also requires:
```bash
$(brew --prefix)/bin/pip3 install cython numpy wheel setuptools ruamel.yaml pytest
```
- In addition to the general software, building the Fortran module also requires:
```bash
brew install gcc
```
- In addition to the general software, building the MATLAB toolbox also requires:
- MATLAB version later than 2009a
- Typically installed to:
```
/Applications/MATLAB_R20YYn.app
```
where `YY` is a two digit year and `n` is either `a` or `b`
- The Homebrew header and library directories will not be on the path for the system
compiler (Xcode), so when compiling Cantera, you will need to provide the command line
options `extra_inc_dirs=$(brew --prefix)/include` and
`extra_lib_dirs=$(brew --prefix)/lib`.
```{button-ref} source-code
:color: primary
:shadow:
:align: right
Next: Download the Source Code
```

38
doc/sphinx/develop/compiling/config-options.rst Normal file
View File

@ -0,0 +1,38 @@
.. _scons-config:
Configuration Options
=====================
This document lists the options available for compiling Cantera with
SCons.
The default values are operating-system dependent. To see the defaults for your current
operating system, run the command:
.. code:: bash
scons help
from the command prompt.
The following options can be passed to SCons to customize the Cantera
build process. They should be given in the form:
.. code:: bash
scons build option1=value1 option2=value2
Variables set in this way will be stored in the ``cantera.conf`` file and reused
automatically on subsequent invocations of SCons. Alternatively, the
configuration options can be entered directly into ``cantera.conf`` before
running ``scons build``. The format of this file is:
.. code:: python
option1 = 'value1'
option2 = 'value2'
..
The options list is generated by SCons during the build process
.. include:: scons-config-options.rst.inc

258
doc/sphinx/develop/compiling/configure-build.md Normal file
View File

@ -0,0 +1,258 @@
# Configure and Build Cantera
(sec-determine-config)=
## Determine configuration options
- Run `scons help --options` to see a list of all of the configuration options for
Cantera, or see all of the options on the [Configuration Options](scons-config)
page.
- Configuration options are specified as additional arguments to the `scons`
command. For example:
```bash
scons command option_name=value
```
where `scons` is the program that manages the build steps, and `command`
is most commonly one of
- `build`
- `test`
- `clean`
Other commands are explained in the [Build Commands](sec-build-commands) section.
- SCons saves configuration options specified on the command line in the file
`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:
```bash
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 `--config=force`.
- 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](scons-config) page.
### Common Options
- [`debug`](sconsopt-debug)
- [`optimize`](sconsopt-optimize)
- [`prefix`](sconsopt-prefix)
### Specifying Paths for Cantera's Dependencies
- [`blas_lapack_libs`](sconsopt-blas-lapack-libs)
- On macOS, the Accelerate framework is automatically used to provide optimized
versions of BLAS and LAPACK, so the `blas_lapack_libs` option should generally be
left unspecified.
- [`blas_lapack_dir`](sconsopt-blas-lapack-dir)
- [`boost_inc_dir`](sconsopt-boost-inc-dir)
- [`sundials_include`](sconsopt-sundials-include)
- [`sundials_libdir`](sconsopt-sundials-libdir)
- [`hdf_include`](sconsopt-hdf-include)
- [`hdf_libdir`](sconsopt-hdf-libdir)
- [`extra_inc_dirs`](sconsopt-extra-inc-dirs)
- [`extra_lib_dirs`](sconsopt-extra-lib-dirs)
### Python Module Options
Compiling the Cantera Python module requires that NumPy and Cython are installed
for the target installation of Python. The following SCons options control how
the Python module is built:
- [`python_package`](sconsopt-python-package)
- [`python_cmd`](sconsopt-python-cmd)
- By default, SCons will try to build the full Python interface for copy of
Python that is running SCons. Use this option if you wish to build Cantera
for a different Python installation.
- [`python_prefix`](sconsopt-python-prefix)
### Windows Only Options
:::{note}
The `cantera.conf` file uses the backslash character `\` as an escape
character. When modifying this file, backslashes in paths need to be escaped
like this: `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
`"C:\Program Files"`.
- 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 `target_arch` and `msvc_toolset_version`.
- To compile with MinGW, specify the [`toolchain`](sconsopt-toolchain) option:
```
toolchain=mingw
```
- [`msvc_toolset_version`](sconsopt-msvc-toolset-version)
- [`msvc_version`](sconsopt-msvc-version)
- [`target_arch`](sconsopt-target-arch)
- [`toolchain`](sconsopt-toolchain)
### 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:
- [`matlab_toolbox`](sconsopt-matlab-toolbox)
- [`matlab_path`](sconsopt-matlab-path)
### Fortran Module Options
Building the Fortran module requires a compatible Fortran compiler. SCons will
attempt to find a compatible compiler by default in the `PATH` environment
variable. The following options control how the Fortran module is built:
- [`f90_interface`](sconsopt-f90-interface)
- [`FORTRAN`](sconsopt-fortran)
### Documentation Options
The following options control if the documentation is built:
- [`doxygen_docs`](sconsopt-doxygen-docs)
- [`sphinx_docs`](sconsopt-sphinx-docs)
### Less Common Options
- [`CC`](sconsopt-cc)
- [`CXX`](sconsopt-cxx)
- [`env_vars`](sconsopt-env-vars)
- [`layout`](sconsopt-layout)
- [`logging`](sconsopt-logging)
- [`gtest_flags`](sconsopt-gtest-flags)
(sec-build-commands)=
## Build Commands
The following *commands* are possible as arguments to SCons:
```bash
scons command
```
- `scons help`
: Print a list of available SCons commands.
- `scons help --options`
: Print a description of user-specifiable options.
- `scons build`
: Compile Cantera and the language interfaces using
default options.
- `scons clean`
: Delete files created while building Cantera.
- `scons install`
: Install Cantera.
- `scons uninstall`
: Uninstall Cantera.
- `scons test`
: Run all tests which did not previously pass or for which the
results may have changed.
- `scons test-reset`
: Reset the passing status of all tests.
- `scons test-clean`
: Delete files created while running the tests.
- `scons test-help`
: List available tests.
- `scons test-NAME`
: Run the test named `NAME`.
- `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.
- `scons samples`
: Compile the C++ and Fortran samples.
- `scons msi`
: Build a Windows installer (.msi) for Cantera.
- `scons sphinx`
: Build the Sphinx documentation
- `scons doxygen`
: Build the Doxygen documentation
## Compile Cantera & Test
- Run SCons with the list of desired configuration options:
```bash
scons build ...
```
- If Cantera compiles successfully, you should see a message that looks like:
```
*******************************************************
Compilation completed successfully.
- To run the test suite, type 'scons test'.
- To list available tests, type 'scons test-help'.
- To install, type 'scons install'.
*******************************************************
```
- If you do not see this message, check the output for errors to see what went
wrong. You may also need to examine the contents of `config.log`.
- Cantera has a series of tests that can be run with the command:
```bash
scons test
```
- 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
### Building Documentation
To build the Cantera HTML documentation, run the commands:
```bash
scons doxygen
scons sphinx
```
or append the options `sphinx_docs=y` and `doxygen_docs=y` to the build
command:
```bash
scons build doxygen_docs=y sphinx_docs=y
```

181
doc/sphinx/develop/compiling/dependencies.md Normal file
View File

@ -0,0 +1,181 @@
(sec-dependencies)=
# 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 build the Fortran module.
- GNU compilers (C/C++/Fortran)
- Known to work with versions 9.4 and 11.4. Expected to work with version >= 9.0.
- Clang/LLVM (C/C++)
- Known to work with versions 10 and 12. Expected to work with version >= 5.0
- Works with the versions included in Xcode 13.0 and 14.3.1.
- Intel compilers (C/C++/Fortran)
- Known to work with the Intel OneAPI Compilers (version 2022.0.2).
- Some earlier versions of the Intel compiler (including the 2017 version) are
**NOT RECOMMENDED** because of a bug in the C compiler.
- Microsoft compilers (C/C++)
- Known to work with Visual Studio 2017 (MSVC 14.1), Visual Studio 2019 (MSVC 14.2)
and Visual Studio 2022 (MSVC 14.3).
- MinGW (C/C++/Fortran)
- <http://mingw-w64.org/doku.php> (64-bit)
- <http://tdm-gcc.tdragon.net/> (64-bit)
- Known to work with Mingw-w64 12.2.
## Other Required Software
- SCons:
- <http://scons.org/tag/releases.html>
- Works with versions >= 3.0.0
- On Windows, more recent SCons versions are required to support each new version of
the MSVC compiler.
- Python:
- <https://python.org/downloads/>
- Works with versions >= 3.8.
- Boost
- <https://www.boost.org/users/download/>
- Known to work with versions 1.71, 1.74, and 1.82; Expected to work with versions >=
1.70
- Only the "header-only" portions of Boost are required. Cantera does not currently
depend on any of the compiled Boost libraries.
- SUNDIALS
- If SUNDIALS is not installed and you have checked out the Cantera source code using
Git, SUNDIALS will be automatically downloaded and the necessary portions will be
compiled and installed with Cantera.
- <https://computing.llnl.gov/projects/sundials>
- Known to work with versions >= 3.0. Expected to work with versions \<= 7.0.
- To use SUNDIALS with Cantera on a Linux/Unix system, it must be compiled
with the `-fPIC` flag. You can specify this flag when configuring SUNDIALS as
`cmake -DCMAKE_C_FLAGS=-fPIC <other command-line options>`
- Eigen
- If Eigen is not installed and you have checked out the Cantera source code using
Git, Eigen will be automatically downloaded and installed with Cantera.
- <https://eigen.tuxfamily.org/index.php?title=Main_Page>
- Known to work with version 3.4.0.
- fmt
- If fmt (previously known as cppformat) is not installed and you have checked out the
Cantera source code using Git, fmt will be automatically downloaded and the
necessary portions will be compiled and installed with Cantera.
- <https://fmt.dev/latest/index.html>
- Known to work with version 9.1.0.
- yaml-cpp
- If yaml-cpp is not installed and you have checked out the Cantera source code using
Git, it will be automatically downloaded and the necessary portions will be compiled
and installed with Cantera.
- <https://github.com/jbeder/yaml-cpp>
- Known to work with version 0.7.0. Version 0.6.0 or newer is required.
## Optional Dependencies
- [Numpy](https://www.numpy.org/)
- Required to build the Cantera Python module, and to run significant portions
of the test suite.
- Expected to work with versions >= 1.12.0. 1.16.0 or newer is recommended.
- [Cython](https://cython.org/)
- Required version >=0.29.31 to build the Python module.
- [Pip](https://pip.pypa.io/en/stable/installing/) (Python)
- Required to build the Cantera Python module.
- Provides the `pip` command which can be used to install most of
the other Python dependencies.
- [wheel](https://pypi.org/project/wheel/) (Python)
- Required to build the Cantera Python module.
- [setuptools](https://pypi.org/project/setuptools/) (Python)
- Required to build the Cantera Python module.
- [Ruamel.yaml](https://pypi.org/project/ruamel.yaml/) (Python)
- Required to convert input files from Chemkin, CTI, and XML to the YAML
format
- Known to work with versions 0.15.42, 0.15.87, and 0.16.5
- Expected to work with versions >= 0.15.0
- [libhdf5](https://www.hdfgroup.org/solutions/hdf5/)
- Required to read and write data files in the HDF5 format
- Known to work with versions 1.12 and 1.14.
- [HighFive](https://github.com/BlueBrain/HighFive)
- Required to read and write data files in the HDF5 format
- If HighFive is not installed and you have checked out the Cantera source code
using Git, HighFive will be automatically downloaded and the necessary portions will
be compiled as part of the Cantera build process.
- Version 2.5.0 or newer is required.
- [Google Test](https://github.com/google/googletest)
- If Google Test is not installed and you have checked out the Cantera source code
using Git, Google Test will be automatically downloaded and the necessary portions
will be compiled as part of the Cantera build process.
- Required to run significant portions of the test suite.
- Known to work with version 1.11.0.
- [pytest](https://pytest.org)
- Required to run the Python test suite.
- Known to work with version 7.2.0
- Matlab
- Required to build the Cantera Matlab toolbox.
- Known to work with 2022a. Expected to work with versions >= 2009a.
- [Windows Installer XML (WiX) toolset](http://wixtoolset.org/)
- Required to build MSI installers on Windows.
- Known to work with versions 3.5 and 3.8.
- Packages required for building Sphinx documentation
- [Sphinx](http://www.sphinx-doc.org/en/stable/)
- [PyData Sphinx theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/)
- [Pygments](http://pygments.org/)
- [pyparsing](https://sourceforge.net/projects/pyparsing/)
- [sphinx-argparse](https://sphinx-argparse.readthedocs.io/en/latest/)
- [doxylink](https://pythonhosted.org/sphinxcontrib-doxylink/)
- [matlabdomain](https://pypi.org/project/sphinxcontrib-matlabdomain)
- [Doxygen](http://doxygen.nl/)
- Required for building the C++ API Documentation
- Version 1.8 or newer is recommended.
- [Graphviz](https://www.graphviz.org/)
- Required to build the dependency graph images in the C++ API Documentation
- Known to work with version 2.40.1, expected to work with versions >=2.40.1

118
doc/sphinx/develop/compiling/source-code.md Normal file
View File

@ -0,0 +1,118 @@
(sec-source-code)=
# Downloading the Cantera source code
## Stable Release
- **Option 1**: Check out the code using Git (recommended):
```bash
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
```
Then, check out the tag of the most recent stable version:
```bash
git checkout tags/v3.0.0
git submodule update
```
A list of all the tags can be shown by:
```bash
git tag --list
```
- **Option 2**: Download the most recent source `.tar.gz` or `.zip` file from
[GitHub](https://github.com/Cantera/cantera/releases) and extract the contents. In
this case, several dependencies that are linked to the Cantera Git repository will not
be available and will need to be installed elsewhere on your system.
```{button-ref} configure-build
:color: primary
:shadow:
:align: right
Next: Configure & Build Cantera
```
## Beta Release
- Check out the code using Git:
```bash
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
```
Then pick either **Option 1** or **Option 2** below.
- **Option 1**: Check out the tag with the most recent beta release:
```bash
git checkout tags/v3.0.0b1
git submodule update
```
Note that the most recent beta version might be older than the most recent stable
release. A list of all the tags, including stable and beta versions can be shown by:
```bash
git tag --list
```
- **Option 2**: Check out the branch with all the bug fixes leading to the next minor
release of the stable version:
```bash
git checkout 3.0
git submodule update
```
This branch has all the work on the 3.0.x version of the software.
If you've already checked out the 3.0 branch, you can get the latest updates from the
main Cantera repository and synchronize your local repository by running:
```bash
git checkout 3.0
git fetch --all
git pull --ff-only
```
```{button-ref} configure-build
:color: primary
:shadow:
:align: right
Next: Configure & Build Cantera
```
## Development Version
Check out the code using Git:
```bash
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
```
Note that by default, the `main` branch is checked out, containing all of the feature
updates and bug fixes to the code since the previous stable release. The main branch is
usually an alpha release, corresponding to the `a` in the version number, and does not
usually get a tag.
If you've previously checked out the repository, and haven't made any changes locally,
you can get the latest updates from the main Cantera repository and synchronize your
local repository by running:
```bash
git checkout main
git fetch --all
git pull --ff-only
```
```{button-ref} configure-build
:color: primary
:shadow:
:align: right
Next: Configure & Build Cantera
```

60
doc/sphinx/develop/compiling/special-cases.md Normal file
View File

@ -0,0 +1,60 @@
(sec-special-compiling-cases)=
# Special Compiling Cases
This guide explains some of the less common ways to build Cantera.
(conda-build)=
## Building the Conda Package
- The recipe for the Cantera Conda package is located at <https://github.com/Cantera/conda-recipes>
- See the `README.md` in that repository for instructions.
(sec-intel-compilers)=
## Intel Compilers
- The following instructions refer to the [Intel OneAPI Toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/toolkits.html).
- Before compiling Cantera, you may need to set up the appropriate environment
variables for the Intel compiler suite. For example:
```bash
source /opt/intel/oneapi/setvars.sh
```
- For the Intel compiler to work with SCons, these environment variables need
to be passed through SCons by using the command line option:
```bash
env_vars=all
```
- If you want to use the Intel MKL versions of BLAS and LAPACK, you will need
to provide additional options. The following are typically correct on
64-bit Linux systems:
```bash
blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64
```
Your final SCons call might then look something like:
```bash
scons build env_vars=all CC=icx CXX=icpx FORTRAN=ifx blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64
```
- When installing Cantera after building with the Intel compiler, the normal
method of using `sudo` to install Cantera to the system default directories
will not work because `sudo` does not pass the environment variables needed
by the Intel compiler. Instead, you will need to do something like:
```bash
scons build ...
sudo -s
source /path/to/setvars.sh
scons install
exit
```
Another option is to set the [`prefix`](sconsopt-prefix) option to a directory
for which you have write permissions, and specify the `USER` value to the
[`python_prefix`](sconsopt-python-prefix) option.

34
doc/sphinx/develop/index.md
View File

@ -5,6 +5,34 @@ This page is a work in progress. For compilation instructions for Cantera 3.0, p
see <a href="/install/compiling-install.html">this page</a>.
```
- Compilation instructions
- Explanations of how the code works
- Guides to introducing new models
## Compiling Cantera from Source
If you're interested in contributing new features to Cantera, or you want to try the
latest and development version, you will need to compile Cantera from source. The first
step is to make sure you have all the [](compiling/compilation-reqs) installed. Then,
you can [download the Cantera source code](compiling/source-code). Finally, you can
determine the appropriate configuration options and [compile
Cantera](compiling/configure-build) on your computer.
The following additional references may also be useful:
- [](compiling/dependencies.md)
- [](compiling/config-options)
- [](compiling/special-cases)
```{toctree}
:caption: Compiling Cantera from Source
:hidden:
:maxdepth: 1
compiling/compilation-reqs
compiling/source-code
compiling/configure-build
compiling/dependencies
compiling/config-options
compiling/special-cases
```
## How Cantera Works
## Adding New Models to Cantera

2
site_scons/buildutils.py
View File

@ -248,7 +248,7 @@ class Option:
def to_rest(self, dev: bool = False, indent: int = 3) -> str:
"""Convert description of option to restructured text (reST)"""
# assemble output
tag = self.name.replace("_", "-").lower()
tag = "sconsopt-" + self.name.replace("_", "-").lower()
if dev:
tag += "-dev"
out = f".. _{tag}:\n\n"