This page discusses the internals of the build system: how it works, how the different pieces fit together, and the various ways it can be configured. This page is intended for those who would like to understand how the build system works and how it can be modified or extended.
- Build third-party libraries (TPLs)
- Build Quinoa
Both stages consist of the following two steps
- Use cmake to configure the build
- Perform the build
As the section on non-recursive clones discusses, 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.
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/
- 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_
- 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.
Whether a dynamically or statically linked build is performed is decided in cmake/
BuildSharedS.cmake. This can be configured by the cmake variable
BUILD_SHARED_LIBS(on/off). The default is off, yielding a dynamic build (except on Crays, where the default is static).
- 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_PREFIXcmake variable. For a non-recursive clone the default is
quinoa/external/install/clang-x86_64/. If a custom location is set, the subsequent Quinoa build can be told by setting the
TPL_DIRcmake variable to the path used as
CMAKE_INSTALL_PREFIXfor 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_COUNTand 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_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
- 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>.cmakefiles 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.
In the Quinoa repository the main entry point of the Quinoa-build is src/
- 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.
- Whether a dynamically or statically linked build is performed is decided. The default is dynamic linking. 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_PREFIXin 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
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 compiler flags can be set by the cmake variables,
- 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