diff --git a/doc/sphinx/compiling.rst b/doc/sphinx/compiling.rst index 07a59b7bd..3091a7dd4 100644 --- a/doc/sphinx/compiling.rst +++ b/doc/sphinx/compiling.rst @@ -533,39 +533,34 @@ Determine configuration options To force SCons to re-run these tests rather than trusting the cached results, run scons with the option ``--config=force``. -Python Module -------------- +General Options +--------------- -The Cantera Python module is implemented using Cython, and as such building the -Cantera Python module requires the Cython package for Python. +The following options control the general compilation procedure. -The Python module is compatible with the following Python versions: 2.7 -and 3.2 - 3.5. +Common Options +^^^^^^^^^^^^^^^ -Building for Python 2 -^^^^^^^^^^^^^^^^^^^^^ +* :ref:`blas_lapack_libs ` -By default, SCons will attempt to build the Cython-based Python module for -Python 2, if both Numpy and Cython are installed. + * On OS X, 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. -Building for Python 3 -^^^^^^^^^^^^^^^^^^^^^ +* :ref:`blas_lapack_dir ` +* :ref:`boost_inc_dir ` +* :ref:`CC ` +* :ref:`cc_flags ` +* :ref:`CXX ` +* :ref:`cxx_flags ` +* :ref:`env_vars ` +* :ref:`extra_inc_dirs ` +* :ref:`extra_lib_dirs ` +* :ref:`prefix ` +* :ref:`VERBOSE ` -If SCons detects a Python 3 interpreter installed in a default location -(i.e. ``python3`` is on the path), it will try to build the Python module -for Python 3. The following SCons options control how the Python 3 module is -built:: - - python3_package=[y|n] - python3_cmd=/path/to/python3/interpreter - python3_array_home=/path/to/numpy - python3_prefix=/path/to/cantera/module - -Note that even when building the Python 3 Cantera module, you should still use -Python 2 with SCons, as SCons does not currently support Python 3. - -Windows (MSVC) --------------- +Windows Only Options +^^^^^^^^^^^^^^^^^^^^ * 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. @@ -586,22 +581,104 @@ Windows (MSVC) This does not apply to paths specified on the command line. Alternatively, you can use forward slashes (``/``) in paths. -Windows (MinGW) ---------------- - -* To compile with MinGW, use the SCons command line option:: +* To compile with MinGW, specify the :ref:`toolchain ` option:: toolchain=mingw -OS X ----- +* :ref:`msvc_version ` +* :ref:`target_arch ` +* :ref:`toolchain ` -* 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. +Less Common Options +^^^^^^^^^^^^^^^^^^^ + +* :ref:`coverage ` +* :ref:`debug ` +* :ref:`debug_flags ` +* :ref:`debug_linker_flags ` +* :ref:`lapack_ftn_string_len_at_end ` +* :ref:`lapack_ftn_trailing_underscore ` +* :ref:`lapack_names ` +* :ref:`layout ` +* :ref:`no_debug_flags ` +* :ref:`no_debug_linker_flags ` +* :ref:`no_optimize_flags ` +* :ref:`optimize ` +* :ref:`optimize_flags ` +* :ref:`renamed_shared_libraries ` +* :ref:`stage_dir ` +* :ref:`sundials_include ` +* :ref:`sundials_libdir ` +* :ref:`system_eigen ` +* :ref:`system_fmt ` +* :ref:`system_googletest ` +* :ref:`system_sundials ` +* :ref:`thread_flags ` +* :ref:`use_pch ` +* :ref:`versioned_shared_library ` +* :ref:`warning_flags ` + +Python Module +------------- + +The Cantera Python module is implemented using Cython, and as such building the +Cantera Python module requires the Cython package for Python. See :ref:`sec-installation-reqs`. + +The Python module is compatible with the following Python versions: 2.7 +and 3.3 - 3.5. + +Building the Python 2 Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, SCons will attempt to build the Cython-based Python module for +Python 2, if both Numpy and Cython are installed. The following options control +how the Python 2 module is built: + +* :ref:`python_array_home ` +* :ref:`python_cmd ` +* :ref:`python_package ` +* :ref:`python_prefix ` + +Building the Python 3 Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If SCons detects a Python 3 interpreter installed in a default location +(i.e., ``python3`` is on the ``PATH`` environment variable) or +``python3_package`` is ``y``, SCons will try to build the Python module +for Python 3. The following SCons options control how the Python 3 module is +built: + +* :ref:`python3_array_home ` +* :ref:`python3_cmd ` +* :ref:`python3_package ` +* :ref:`python3_prefix ` + +Note that even when building the Python 3 Cantera module, you should still use +Python 2 with SCons, as SCons does not currently support Python 3. + +MATLAB Toolbox +-------------- + +Building the MATLAB toolbox requires an installed copy of MATLAB. The following +options control how the MATLAB toolbox is built: + +* :ref:`matlab_path ` +* :ref:`matlab_toolbox ` + +Fortran Module +-------------- + +Building the Fortran module requires a compatible Fortran comiler. 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: + +* :ref:`f90_interface ` +* :ref:`FORTRAN ` +* :ref:`FORTRANFLAGS ` Intel Compilers --------------- + * Before compiling Cantera, you may need to set up the appropriate environment variables for the Intel compiler suite, e.g.:: @@ -622,10 +699,10 @@ Intel Compilers scons build env_vars=all CC=icc CXX=icpc FORTRAN=ifort 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 will not work because ``sudo`` - does not pass the environment variables needed by the Intel compiler. - Instead, you will need to do something like:: +* 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:: scons build ... sudo -s @@ -633,6 +710,11 @@ Intel Compilers scons install exit + Another option is to set the :ref:`prefix ` option to a directory + for which you have write permissions, and specify the ``USER`` value to the + :ref:`python_prefix ` or :ref:`python3_prefix ` + option. + Compile Cantera & Test ======================