Internals

Overview

As section build_defaults describes, Quinoa is built in two stages:

1. Build third-party libraries (TPLs)
2. Build Quinoa

Both stages consist of the following two steps

• Use cmake to configure the build
• Perform the build

Some of the cmake code is abstracted away into its own git repository so that it can be effectively shared between the two repositories: quinoa and quinoa-tpl. For more details, see also the page on modules.

Third-party-libraries build

In a default build the main entry point of the TPL-build is /CMakeLists.txt. The TPL-build uses cmake's external project functionality to build the third-party libraries.

The following main steps are taken by the TPL-cmake script to configure the build of the third-party libraries:

• In-source builds are disallowed in cmake/DisallowInSourceBuilds.cmake.
• The default build type is set in cmake/BuildType.cmake. This can be configured by the cmake variable CMAKE_BUILD_TYPE. The default is Release. Other valid options are described at https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html.
• The operating system is detected in cmake/DetectOS.cmake. This is mostly used for working around some quirks for some specific operating systems, e.g., Alpine Linux.
• The target build architecture is detected and configured in cmake/TargetArch.cmake. This is used for setting the correct architecture-specific configuration for, e.g., the runtime system, Charm++.
• The install directory in which to install all third-party libraries is configured by the CMAKE_INSTALL_PREFIX cmake variable. The default is quinoa-tpl/install/<compiler>-<architecture>/, e.g., quinoa-tpl/install/clang-x86_64/. If a custom location is set, the subsequent Quinoa build can be told by setting the TPL_DIR cmake variable to the path used as CMAKE_INSTALL_PREFIX for the TPL build.
• Next the TPL cmake run detects the number of CPUs available on the build machine. This is stored in the cmake variable PROCESSOR_COUNT and is used to configure longer-running regression tests that need more than a few CPUs, e.g., the whole build machine.

• Next we set a number of cmake boolean variables, named as ENABLE_<SOME_TPL>, e.g., ENABLE_CHARM, ENABLE_HDF5, etc. These are then selectively set to true if a requested executable requires them. This enables configuring the build system to only build (and only build third-partly libraries for) selected executables. On how to build only a single executable, see Build specific executables only.

• After this we configure the Charm++ build: architecture, communication sub-system, SMP mode, etc.

• Next the compilers are configured. At this time, the TPL build requires Fortran, C, and a C++ compiler. Also required is MPI, e.g., OpenMPI. The Quinoa build only requires C and C++ compilers. The cmake build echoes a detailed output to screen about the MPI wrappers and the underlying compilers configured/found. Also echoed are extra Charm++ arguments, which can be provided on top of the default ones by the cmake variable CHARM_EXTRA_ARGS.

• Next are compiler-specific configuration blocks: default standard library, default compiler flags, etc. This section is also a good place to look for to find out what compiler we test, tested or at least tried to use in past.
• This is followed by multiple configuration blocks that are specific to individual third-party libraries if enabled. In each of these block, first we try to find the library on the system by invoking cmake code reused between the TPL and the Quinoa builds. These are given in the Find_<TPL>.cmake files that live under [cmake/BuildType.cmake](https://github.com/quinoacomputing/cmake-modules].
• After these TPL-specific configuration blocks, there are the calls to cmake's ExternalProject_Add() functions, parameterized to the given TPL. These are the sections to look at to see how an individual TPL is built, e.g., whether it uses autotools or cmake, or what it takes to install a given TPL to make suitable for Quinoa. These are also the sections that potentially apply patches that are not (yet) communicated upstream to the given TPL.

Quinoa build

In the Quinoa repository the main entry point of the Quinoa-build is src/CMakeLists.txt. The following main steps are taken by the Quinoa-cmake script to configure the build. Many of the steps are the same (or very similar) to configuring the TPL build. See the Third-party-libraries build for more details.

• In-source builds are disallowed. See the Third-party-libraries build for more details.
• The default build type is set. This can be configured by the cmake variable CMAKE_BUILD_TYPE. The default is Release. See the Third-party-libraries build for more details.
• The operating system is detected. See the Third-party-libraries build for more details.
• The target build architecture is detected and configured. See the Third-party-libraries build for more details.
• The default TPL directory, in the cmake variable TPL_DIR, is set to the install directory that is the default in the cmake variable CMAKE_INSTALL_PREFIX in the TPL build. See the Third-party-libraries build for more details.
• There is an option to disable tests. The default is to enable both unit-, and regression tests. This is controlled by the cmake variable ENABLE_TESTS.

• We then detect all TPLs and enable all executable targets for which TPLs are found.

• Similar to the TPL-cmake configuration, there is a detailed information to screen on the compilers: MPI wrappers and their underlying compilers.
• There is way to pass extra arguments to the linker, configured by the cmake variable EXTRA_LINK_ARGS.

• Extra compiler flags can be set by the cmake variables, CMAKE_C_FLAGS and CMAKE_CXX_FLAGS.

• This is followed by compiler-specific settings and flags, e.g., enabling and disabling certain warnings for all of Quinoa. Some warnings are only locally disabled under directory src/NoWarning/.

Related pages

• Quickstart on how to build
• Third-party libraries and cmake code
• A list of all required and optional third-party libraries
• Build system internals