Environment Variables and Conditional Presets

Now that we have a standard way to find vcpkg on any machine, we can update our preset to use it.

CMake Presets provide a special syntax, $env{VARIABLE_NAME}, to read the value of an environment variable.

Let's refactor our shared _base preset in CMakePresets.json to use this:

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "_base",
5    "hidden": true,
6    "binaryDir": "${sourceDir}/build/${presetName}",
7    "cacheVariables": {
8      "VCPKG_TOOLCHAIN_FILE":
9        "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
10    }
11  } /* Other presets unchanged */]
12}

Any developer, on any machine, can now use a preset than inherits from this and have VCPKG_TOOLCHAIN_FILE automatically set. CMake will read their local VCPKG_ROOT environment variable and construct the correct path to the toolchain file at configure time.

They no longer need to create user presets for this - they just need to set their VCPKG_ROOT environment variable.

Our preset is portable, but what happens if a developer tries to use it without setting the VCPKG_ROOT environment variable? CMake will try to expand $env{VCPKG_ROOT}, find it's empty, and fail because the path is invalid.

The condition key allows you to specify a condition that must be true for the preset to be considered valid and be shown to the user.

The following shows two examples of a condition:

• The windows-only preset uses an equals condition to compare two strings, making the preset only available on Windows
• The mac-or-linux preset uses an inList condition to make the preset only available on Darwin (macOS) or Linux

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "windows-only",
5    "condition": {
6      "type": "equals",
7      "lhs": "${hostSystemName}",
8      "rhs": "Windows"
9    }
10  }, {
11    "name": "mac-or-linux",
12    "condition": {
13      "type": "inList",
14      "string": "${hostSystemName}",
15      "list": ["Darwin", "Linux"]
16    }
17  }]
18}

If we list our available conditions now then, depending on our system, we should see at most one option is available to us:

1cmake --list-presets

1Available configure presets:
2  "mac-or-linux-preset"

Combining Conditions

What if we also need to check for the presence of our VCPKG_ROOT environment variable? The anyOf or allOf condition type can include a conditions array comprising of multiple checks:

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "windows-vcpkg-preset",
5    "condition": {
6      "type": "allOf",
7      "conditions": [{
8        "type": "equals",
9        "lhs": "${hostSystemName}",
10        "rhs": "Windows"
11      }, {
12        "type": "notEquals",
13        "lhs": "$env{VCPKG_ROOT}",
14        "rhs": ""
15      }]
16    }
17  }]
18}

The allOf type acts like a logical AND. This preset will now only be available if all of the nested conditions are true:

• the host system is Windows AND
• the VCPKG_ROOT environment variable is set - that is, it does notEquals an empty string

The official documentation lists a few other conditional types that are available, as well as further variables that can be used similar to how we're using ${hostSystemName} in this example.

While presets are the modern way to handle environment-specific configuration, it's also possible to read environment variables directly from within a CMakeLists.txt file.

The syntax is slightly different: $ENV{VARIABLE_NAME} (note the uppercase ENV).

Practical Example

Our build currently requires a VCPKG_TOOLCHAIN_FILE variable to be defined. That definition is expected to come from the command line, either through a -DVCPKG_TOOLCHAIN_FILE argument or by using a --preset that includes it.

However, if someone doesn't provide that argument, we could still make our build work simply by setting the variable within our CMakeLists.txt file. For example:

1cmake_minimum_required(VERSION 3.21)
2project(Greeter)
3
4# Only set VCPKG_TOOLCHAIN_FILE if the user hasn't already
5if(NOT DEFINED VCPKG_TOOLCHAIN_FILE AND DEFINED ENV{VCPKG_ROOT})
6  set(
7    VCPKG_TOOLCHAIN_FILE
8    "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
9    CACHE FILEPATH "vcpkg toolchain file"
10  )
11  message(STATUS
12    "Using VCPKG_ROOT from environment: $ENV{VCPKG_ROOT}"
13  )
14endif()
15
16add_subdirectory(app)

This script checks if VCPKG_TOOLCHAIN_FILE has already been set. If not, it checks if the VCPKG_ROOT environment variable exists. If it does, it sets the toolchain file itself, caching the result.

Note that the NOT DEFINED VCPKG_TOOLCHAIN_FILE check here is not strictly necessary. As we covered in our earlier lesson on the CMake cache , values provided on the command line will take precedence over our set() commands, unless we add the FORCE argument.

However, including this check anyway makes our intent clearer, and it also ensures our message() only shows when the set() command is effective.

In this final lesson on presets, we've learned how to decouple our build configurations from the specific machines they run on, creating portable and user-friendly workflows.

• Environment Variables: They are the standard way to provide machine-specific information, like paths to tools, to your build system.
• Reading Environment Variables in Presets: Use the $env{VAR_NAME} syntax inside your CMakePresets.json.
• Conditional Presets: Use the "condition" key to control when a preset is available. This is used for creating presets that only appear when the necessary tools or environment variables are present.
• Reading Environment Variables in CMakeLists.txt: For fallbacks or older CMake versions, you can use $ENV{VAR_NAME} directly in your scripts, but the preset approach is generally preferred.