diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 594df110a72..f1f7c2bc9e7 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -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 diff --git a/SConstruct b/SConstruct index 1dd2fe121e1..ef504307d26 100644 --- a/SConstruct +++ b/SConstruct @@ -935,6 +935,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) diff --git a/doc/SConscript b/doc/SConscript index ac840025f73..28efacb4ac3 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -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 diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index fc26c9b1c32..6103e6c133e 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -222,7 +222,7 @@ def escape_splats(app, what, name, obj, options, lines): '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 diff --git a/doc/sphinx/develop/compiling/compilation-reqs.md b/doc/sphinx/develop/compiling/compilation-reqs.md new file mode 100644 index 00000000000..50e7184ec8d --- /dev/null +++ b/doc/sphinx/develop/compiling/compilation-reqs.md @@ -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 + , 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 + + - + - 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 + + - + - Be sure to choose the appropriate architecture for your system - either + 32-bit or 64-bit + + - One of the following supported compilers + + - Microsoft compilers + + - + - 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 + + - + - + - Known to work with Mingw-w64 12.2. + + - The Boost headers + + - + - 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 + + - + + - 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 +``` diff --git a/doc/sphinx/develop/compiling/config-options.rst b/doc/sphinx/develop/compiling/config-options.rst new file mode 100644 index 00000000000..8e9b08d13a1 --- /dev/null +++ b/doc/sphinx/develop/compiling/config-options.rst @@ -0,0 +1,37 @@ +.. _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 diff --git a/doc/sphinx/develop/compiling/configure-build.md b/doc/sphinx/develop/compiling/configure-build.md new file mode 100644 index 00000000000..21c77c5e94c --- /dev/null +++ b/doc/sphinx/develop/compiling/configure-build.md @@ -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 dump` + : Dump the state of the SCons environment to the + screen instead of doing ``, 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 +``` diff --git a/doc/sphinx/develop/compiling/dependencies.md b/doc/sphinx/develop/compiling/dependencies.md new file mode 100644 index 00000000000..fea05c075fd --- /dev/null +++ b/doc/sphinx/develop/compiling/dependencies.md @@ -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) + + - (64-bit) + - (64-bit) + - Known to work with Mingw-w64 12.2. + +## Other Required Software + +- SCons: + + - + - Works with versions >= 3.0.0 + - On Windows, more recent SCons versions are required to support each new version of + the MSVC compiler. + +- Python: + + - + - Works with versions >= 3.8. + +- Boost + + - + - 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. + - + - 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 ` + +- 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. + - + - 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. + - + - 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. + - + - 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 diff --git a/doc/sphinx/develop/compiling/source-code.md b/doc/sphinx/develop/compiling/source-code.md new file mode 100644 index 00000000000..aa3a9ad6845 --- /dev/null +++ b/doc/sphinx/develop/compiling/source-code.md @@ -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 +``` diff --git a/doc/sphinx/develop/compiling/special-cases.md b/doc/sphinx/develop/compiling/special-cases.md new file mode 100644 index 00000000000..0b166184a4f --- /dev/null +++ b/doc/sphinx/develop/compiling/special-cases.md @@ -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 +- 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. diff --git a/doc/sphinx/develop/index.md b/doc/sphinx/develop/index.md index a46aff043b5..0216f6a18af 100644 --- a/doc/sphinx/develop/index.md +++ b/doc/sphinx/develop/index.md @@ -5,6 +5,34 @@ This page is a work in progress. For compilation instructions for Cantera 3.0, p see this page. ``` -- 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 diff --git a/site_scons/buildutils.py b/site_scons/buildutils.py index 7244309ad8b..20b4c74f59f 100644 --- a/site_scons/buildutils.py +++ b/site_scons/buildutils.py @@ -248,7 +248,7 @@ def decorate(key: str, tick: bool = True) -> str: 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"