Build customisation and options

OpenCMISS comes with a default build behaviour that is intended be sufficient for most cases of api-users. However, if you need to make (well-informed!) changes to the default build configuration, here is what we offer.

Caution

Due to the way CMake is designed, one cannot change the compiler once the configuration phase is run (without a big fuss or deleting the directory contents). Moreover, changing the MPI implementation turned out to be very error-prone as well. Hence, we decided to exclude those settings from those you can “easily” change. For information on toolchain/mpi configuration see Building for multiple architectures/configurations.

The OpenCMISS default configuration is set by the <manage>/Config/OpenCMISSDefaultConfig file. Any value defined there can be overridden by re-definition in local configuration files, which are created (from a template at <manage>/Templates/OpenCMISSLocalConfig.template.cmake) within your top-level binary dir as OpenCMISSLocalConfig.cmake.

Yes, you have a separate local configuration file for each toolchain/mpi combination!

For example, in the default setting this file is located at

<OPENCMISS_ROOT>/manage/build/OpenCMISSLocalConfig.cmake

The local config file will be automatically read by CMake upon configuration stage. Any subsequent changes to that file trigger an automatic re-run of cmake to propagate the changes to the current build.

Building only Iron or Zinc

In many cases you might only want to build Iron or Zinc. You can easily achieve that by setting the following variables in your OpenCMISSLocalConfig (terminal) or CMake GUI environment:

  • Building only Iron: Set OC_USE_ZINC to NO
  • Building only Zinc: Set OC_USE_IRON to NO, set MPI to none

OpenCMISS configuration options

These are the options available within the OpenCMISSLocalConfig.cmake file.

OpenCMISS inter-component configuration

Some OpenCMISS components depend on or can use each other. Therefore, the build system provides flags of the type A_USE_B or A_WITH_B to control component connectivity.

Note

These flags only apply if the corresponding package is build by the OpenCMISS Dependencies system. The packages themselves will then search for the appropriate consumed packages. No checks are performed on whether the consumed packages will also be build by us or not, as they might be provided externally.

Caution

Take care to also enable the appropriate OC_USE_<COMP> flags. For example, if you wanted to use MUMPS with SCOTCH, also set OC_USE_SCOTCH=YES so that the build system ensures that SCOTCH will be available.

The full list of available inter-component connection flags is as follows (defaults added):

CELLML_WITH_CSIM
: NO
Load CellML models through CSim
FIELDML-API_WITH_HDF5
: NO
Enable FieldML HDF5 support
FIELDML-API_WITH_JAVA_BINDINGS
: NO
Build Java bindings for FieldML
FIELDML-API_WITH_FORTRAN_BINDINGS
: YES
Build Fortran bindings for FieldML
HDF5_WITH_MPI
: YES
Build HDF5 with MPI support
HDF5_WITH_SZIP
: YES
Have HDF5 use szip
HDF5_WITH_ZLIB
: YES
Have HDF5 use zlib
HDF5_BUILD_FORTRAN
: NO
Build Fortran interface for HDF5
IRON_WITH_CELLML
: YES
Have Iron use CellML
IRON_WITH_FIELDML
: YES
Have Iron use FieldML
IRON_WITH_HYPRE
: YES
Have Iron use Hypre
IRON_WITH_SUNDIALS
: YES
Have Iron use Sundials
IRON_WITH_MUMPS
: YES
Have Sundials use LAPACK
IRON_WITH_SCALAPACK
: YES
Have Iron use ScaLAPACK
IRON_WITH_PETSC
: YES
Have Iron use PetSC
IRON_WITH_C_BINDINGS
: YES
Build Iron-C bindings
IRON_WITH_Python_BINDINGS
: YES if Python bindings prerequisites are given, NO otherwise
Build Iron-Python bindings. This setting is automatically enabled if the build system finds local Python(-libraries) and Swig.
LIBXML2_WITH_ZLIB
: YES
Build LibXML2 with zLib compression support
MUMPS_WITH_SCOTCH
: NO
Have MUMPS use Scotch.
MUMPS_WITH_PTSCOTCH
: YES
Have MUMPS use PT-Scotch.
MUMPS_WITH_METIS
: NO
Have MUMPS use Metis.
MUMPS_WITH_PARMETIS
Have MUMPS use Parmetis.
OPTPP_WITH_BLAS
: NO
Have Opt++ use external BLAS routines. Use only when system BLAS is available or you have a Fortran compiler and build your own BLAS/LAPACK.
PASTIX_USE_THREADS
: YES
Have Sundials use LAPACK
PASTIX_USE_METIS
: YES
Have PASTIX use Metis
PASTIX_USE_PTSCOTCH
: YES
Have PASTIX use PT-Scotch
PETSC_WITH_HYPRE
: YES
Have PetSC use HYPRE
PETSC_WITH_MUMPS
: YES
Have PetSC use MUMPS
PETSC_WITH_PARMETIS
: YES
Have PetSC use PARMETIS
PETSC_WITH_PASTIX
: YES
Have PetSC use PASTIX. Defaults to NO for Visual Studio.
PETSC_WITH_PTSCOTCH
: YES
Have PetSC use PTSCOTCH
PETSC_WITH_SCALAPACK
: YES
Have PetSC use SCALAPACK
PETSC_WITH_SUITESPARSE
: YES
Have PetSC use SUITESPARSE
PETSC_WITH_SUNDIALS
: YES
Have PetSC use SUNDIALS
PETSC_WITH_SUPERLU
: YES
Have PetSC use SUPERLU
PETSC_WITH_SUPERLU_DIST
: YES
Have PetSC use SUPERLU_DIST
SCOTCH_USE_THREADS
: YES
Enable use of threading for Scotch/PT-Scotch
SCOTCH_WITH_ZLIB
: YES
Have Scotch/PT-Scotch use zlib
SCOTCH_WITH_BZIP2
: YES
Have Scotch/PT-Scotch use bzip2
SUNDIALS_WITH_LAPACK
: YES
Have Sundials use LAPACK
SUPERLU_DIST_WITH_PARMETIS
: YES
Enable Parmetis support for SuperLU-Dist
ZINC_WITH_Python_BINDINGS
: YES if Python bindings prerequisites are given, NO otherwise
Build Python bindings for ZINC. This setting is automatically enabled if the build system finds local Python(-libraries) and Swig

OpenCMISS developer options

For OpenCMISS developers, there are a range of extra options that can be set. The corresponding file is located at the root directory: <manage>/OpenCMISSDeveloper.cmake.

In principal, all the configuration options above can also be set in the developer config file. However, this file is included in all top-level build tree configurations for all architectures - hence those setting are global in a sense.

Caution

The OpenCMISSDeveloper file is included after any OpenCMISSLocalConfig file. Hence, all settings specified in the developer config take precedence over any local setting.

As OpenCMISS-Developers will mainly work only on a selection of components, the extra configuration file is intended to tell the build system which those components are and have the setup checkout the correct Git repos etc.