OrangesBuildConfigs

This module provides functions for working with build configurations.

Add a build configuration

add_build_config

:

add_build_config (<name>

[DEBUG] [IPO] [DEFAULT] [POSTFIX <postfix>]

[FRAMEWORK_MULTI_CONFIG_POSTFIX <postfix>] [<LANG>_FLAGS <flags…>] [SHARED_LINKER_FLAGS <flags…>] [MODULE_LINKER_FLAGS <flags…>] [RUNTIME_LINKER_FLAGS <flags…>] [STATIC_LIB_AR_FLAGS <flags…>] [LIBRARY_OUTPUT_DIR <dir>] [RUNTIME_OUTPUT_DIR <dir>] [PDB_OUTPUT_DIR <dir>] [COMPILE_PDB_OUTPUT_DIR <dir>])

Adds a new build configuration <name> to the list of build configurations known to this CMake project.

Options:

DEBUG

When present, indicates that this build configuration is for debugging purposes. This function will add this configuration name to the list stored in the global property DEBUG_CONFIGURATIONS. If the DEBUG option is not present, it is assumed this is a release configuration.

IPO

When present, indicates that interprocedural optimization should be enabled in this build configuration by default.

DEFAULT

When present, indicates that this configuration should be made the default. This will set CMAKE_DEFAULT_BUILD_TYPE to the name of this new build configuration.

POSTFIX

A string postfix that will be appended to the names of all output artefacts produced by this configuration. This can be used to allow installing artefacts from multiple build configurations into the same package without name collisions – for example, a library may install someLib.a (the release build) and someLib-d.a (the debug build). In this case, the postfix for the debug configuration is -d.

FRAMEWORK_MULTI_CONFIG_POSTFIX

Similar to POSTFIX, except applies to frameworks when building with a multi-config generator.

<LANG>_FLAGS

Default compiler flags to be used in this build configuration. <LANG> may be any of: ASM, ASM-ATT, ASM-MASM, ASM-NASM, C, CSharp, CUDA, CXX, Fortran, HIP, ISPC, Java, OBJC, OBJCXX, RC, Swift.

SHARED_LINKER_FLAGS

Linker flags to be used when linking shared libraries in this build configuration.

MODULE_LINKER_FLAGS

Linker flags to be used when linking module libraries in this build configuration.

RUNTIME_LINKER_FLAGS

Linker flags to be used when linking executables in this build configuration.

STATIC_LIB_AR_FLAGS

Flags to be passed to ar when archiving static libraries in this build configuration.

LIBRARY_OUTPUT_DIR

Output directory in which to put library artefacts for this build configuration. This value may use generator expressions.

RUNTIME_OUTPUT_DIR

Output directory in which to put runtime artefacts for this build configuration. This value may use generator expressions.

PDB_OUTPUT_DIR

Output directory for MSVC’s .pdb files when building with this configuration. This applies to linker-generated .pdb files for executables and shared libraries.

COMPILE_PDB_OUTPUT_DIR

Output directory for MSVC’s .pdb files when building with this configuration. This applies to .pdb files generated by the compiler while building source files.

Set default build configurations

set_default_build_configs

:

set_default_build_configs ([DEFAULT <config>] [DEFAULTS <all | <configs…>>]

[CROSS <all | <configs…>>])

Use this command to set default build configurations, as well as cross-configurations for the Ninja Multi-Config generator.

Options:

DEFAULT

Specify the default configuration to build if none is explicitly chosen when using the Ninja Multi-Config generator. This option will set the value of the CMAKE_DEFAULT_BUILD_TYPE variable.

DEFAULTS

Specify default configurations to build if none is explicitly chosen when using the Ninja Multi-Config generator. This option may either be the literal string all or a list of build configuration names. This option will set the variable CMAKE_DEFAULT_CONFIGS. The configuration(s) given to DEFAULTS must either be the same as CMAKE_DEFAULT_BUILD_TYPE (the configuration passed to DEFAULT), or be a subset of CMAKE_CROSS_CONFIGS (the configurations passed to CROSS). This option must not be specified unless both CMAKE_DEFAULT_BUILD_TYPE (DEFAULT) and CMAKE_CROSS_CONFIGS (CROSS) are specified.

CROSS

Specify build configurations available from any configuration-specific build-<Config>.ninja file. This option will set the variable CMAKE_CROSS_CONFIGS, activating the Ninja Multi-Config generator’s cross-config mode. This option may be eiher the literal string all or a list of build configuration names.

List known build configurations

build_config_list

:

build_config_list (<outVar> [DEBUG|RELEASE])

This command sets <outVar> to a list of build configuration names. If either DEBUG or RELEASE is specified, then the returned list will contain only names of debug or release configurations, respectively. If neither is specified, the list will contain all known build configurations. Passing both DEBUG and RELEASE will result in an error.

Create build configuration generator expressions

build_config_genex

:

build_config_genex (<outVar> <DEBUG|RELEASE>)

This command sets <outVar> to a generator expression that evaluates to true if its context is a debug or release build, depending on if DEBUG or RELEASE was passed to this command. The resulting generator expression is suitable for composing larger generator expressions.

For example:

add_library (Foo)

build_config_genex (config_is_debug DEBUG) build_config_genex (config_is_release RELEASE)

target_compile_definitions (Foo PRIVATE $<${config_is_debug}:DEBUG_BUILD> $<${config_is_release}:RELEASE_BUILD> )

With the above CMake code, the Foo library will have the DEBUG_BUILD symbol defined when building any debug configuration, and the RELEASE_BUILD symbol defined when building any release configuration.