How to define the option() command in CMake

The option() command is used to define an option variable that can be toggled by the user when configuring the project. It provides a way to enable or disable certain features or behaviors of the project based on the user's preference.

Here is a list of features or behaviors of the options() command in CMake:

  • User-configurable options: The primary purpose of the options() command is to provide a way for users to customize the behavior of the project by enabling or disabling specific options.

  • CMakeCache.txt Entries: When an option() command is defined, it creates an entry in the CMakeCache.txt file, allowing users to modify the value of the option without reconfiguring the project from scratch.

  • Cache variables: For each option defined using the options() command, a corresponding cache variable is created. This variable can be accessed and modified by developers in their CMakeLists.txt files.

  • Default values: Using the option(<option_name> "option description" [default_value]) syntax, we can specify a default value for each option. If no default value is provided, the option will default to OFF.

  • User interaction: When users run the CMake configuration step, the options() command prompts them to enable or disable the options defined using a user-friendly interface.

  • CMake GUI support: The options() command is particularly useful when using the CMake GUI tools because they provide checkboxes that users can toggle to enable or disable options.

  • Conditional compilation: The values of options can be used to conditionally include or exclude certain parts of the project's build process or source code, enabling fine-grained customization.

  • Control over build configuration: By allowing users to choose options during configuration, the options() command gives control over the build configuration without the need to edit CMake files.

widget

Syntax

The syntax for the option() command is as follows:

option(<variable> "help string" [initial_value])

Parameters

Here’s what each parameter represents:

  • <variable>: This is the name of the option variable. This variable is created and can be used throughout the CMakeLists.txt file to control the project’s behavior conditionally.

  • "help string": This is a brief description of the option. This string is displayed to users when they run CMake and configure the project.

  • [initial_value]: This optional initial value is assigned to the option variable. By default, the initial value is OFF. If the user doesn’t specify the value, the option variable will have this initial value.

After defining an option using the option() command, we can check its value using an if() statement to conditionally enable or disable certain project parts based on the user’s choice.

Example

Here’s an example option.cmake file that demonstrates the usage of the option() command. Click the “Run” button and execute the cmake -P option.cmake command in the following terminal:

cmake_minimum_required(VERSION 3.25.1)

message("BUILD_TESTS before: ${BUILD_TESTS}")

option(BUILD_TESTS "Build tests" ON)

message("BUILD_TESTS After: ${BUILD_TESTS}")
Playground for the option() command

Explanation

  • Line 1: The CMake script establishes the minimum required version as 3.25.1.

  • Line 3: We print the value of the BUILD_TESTS variable before it is defined as an option. The value will be printed if the variable has been previously set or initialized.

  • Line 5: We define the BUILD_TESTS variable as an option. The help string "Build tests" will be displayed to the user during configuration, providing information about the option. The initial value of the option is set to ON, meaning the tests will be built by default.

  • Line 7: We print the value of the BUILD_TESTS variable after it has been defined as an option. The updated value, which the user may have changed during configuration, will be displayed.

widget

Overall, this code establishes an option called BUILD_TESTS that enables users to control whether tests should be built. It shows the value of this option both before and after defining it, offering insights into the variable’s state.

Free Resources

HowDev By Educative. Copyright ©2025 Educative, Inc. All rights reserved