Compiling Cantera C++ Programs

Compiling Cantera C++ Programs¶

This guide shows you how to build C++ programs that use Cantera's features

Build Systems¶

In general, it should be possible to use Cantera with any build system by specifying the appropriate header and library paths, and specifying the required libraries when linking. It is also necessary to specify the paths for libraries used by Cantera, such as Sundials, BLAS, and LAPACK.

Instructions below assume a Linux operating system where Cantera's libraries are installed in a standard location such as /usr/lib or /usr/local/lib. If Cantera is installed to a custom location, environment variables LD_LIBRARY_PATH and PKG_CONFIG_PATH need to be specified. If they are not already set elsewhere, they can be set from the command line as:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lib
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/lib/pkgconfig

where /path/to/lib should be replaced by Cantera's library installation path.

pkg-config¶

On systems where the pkg-config program is installed, it can be used to determine the correct compiler and linker flags for use with Cantera. For example:

g++ myProgram.cpp -o myProgram $(pkg-config --cflags --libs cantera)

It can also be used to populate variables in a Makefile:

CFLAGS += $(shell pkg-config --cflags cantera)
LIBS += $(shell pkg-config --libs cantera)

Or in an SConstruct file:

env.ParseConfig("pkg-config --cflags --libs cantera")

Note that pkg-config will work only if it can find the cantera.pc file. If Cantera's libraries are not installed in a standard location such as /usr/lib or /usr/local/lib, you may need to set the PKG_CONFIG_PATH environment variable appropriately before using pkg-config.

SCons¶

SCons is a multi-platform, Python-based build system. It is the build system used to compile Cantera. The description of how to build a project is contained in a file named SConstruct. The SConstruct file is actually a Python script, which makes it very straightforward to add functionality to a SCons-based build system.

A typical SConstruct file for compiling a program that uses Cantera might look like this:

env = Environment()

env.Append(CCFLAGS='-g',
           CPPPATH=['/usr/local/cantera/include',
                    '/usr/local/sundials/include'],
           LIBS=['cantera', 'sundials_cvodes', 'sundials_ida',
                 'sundials_nvecserial', 'lapack', 'blas', 'fmt', 'yaml-cpp'],
           LIBPATH=['/usr/local/cantera/lib',
                    '/usr/local/sundials/lib'],
           LINKFLAGS=['-g', '-pthread'])

sample = env.Program('sample', 'sample.cpp')
Default(sample)

This script establishes what SCons refers to as a "construction environment" named env, and sets the header (CPPPATH) and library (LIBPATH) paths to include the directories containing the Cantera headers and libraries, as well as libraries that Cantera depends on, such as Sundials, BLAS, and LAPACK. Then, a program named sample is compiled using the single source file sample.cpp.

Several other example SConstruct files are included with the C++ examples contained in the samples subdirectory of the Cantera installation directory.

For more information on SCons, see the SCons Wiki and the SCons homepage.

CMake¶

CMake is a multi-platform build system that uses a high-level project description to generate platform-specific build scripts (for example, on Linux, CMake will generate Makefiles). The configuration file for a CMake project is called CMakeLists.txt. A typical CMakeLists.txt file for compiling a program that uses Cantera might look like this:

cmake_minimum_required(VERSION 3.1)
project (sample)

set(CMAKE_VERBOSE_MAKEFILE ON)
set(CMAKE_CXX_STANDARD 11)

find_package(Threads REQUIRED)

include_directories("/opt/cantera/include" "/opt/sundials-2.7.0/include")
link_directories("/opt/cantera/lib" "/opt/sundials-2.7.0/lib")

add_executable(sample sample.cpp)
target_link_libraries(sample cantera sundials_cvodes sundials_ida sundials_nvecserial fmt Threads::Threads)

Several example CMakeLists.txt files are included with the C++ examples contained in the samples subdirectory of the Cantera installation directory, which have the paths and lists of libraries correctly configured for the system on which they are installed.

Make¶

Cantera is distributed with an "include Makefile" that can be used with Make-based build systems. This file Cantera.mak is located in the samples subdirectory of the Cantera installation directory. To use it, add a line referencing this file to the top of your Makefile:

include path/to/Cantera.mak

The path specified should be the relative path from the Makefile to Cantera.mak. This file defines several variables which can be used in your Makefile. The following is an example Makefile that uses the definitions contained in Cantera.mak:

include ../../Cantera.mak

CC=gcc
CXX=g++
RM=rm -f
CCFLAGS=-g
CPPFLAGS=$(CANTERA_INCLUDES)
LDFLAGS=
LDLIBS=$(CANTERA_LIBS)

SRCS=sample.cpp
OBJS=$(subst .cpp,.o,$(SRCS))

all: sample

kinetics1: $(OBJS)
             $(CXX) $(LDFLAGS) -o sample $(OBJS) $(LDLIBS)

clean:
             $(RM) $(OBJS)

dist-clean: clean
             $(RM) *~

Return: C++ Interface Tutorial

Next: C++ Header Files