     unknown

   Generated by Sphinx 3.3.1.

CMake
*****

     CMake 3.19.2, Jan 01, 1970

     unknown

     Copyright © 2000-1970 Kitware, Inc.  and Contributors

CMake is a tool to manage building of source code.  Originally, CMake
was designed as a generator for various dialects of ‘Makefile’, today
CMake generates modern buildsystems such as ‘Ninja’ as well as project
files for IDEs such as Visual Studio and Xcode.

CMake is widely used for the C and C++ languages, but it may be used to
build source code of other languages too.

People encountering CMake for the first time may have different initial
goals.  To learn how to build a source code package downloaded from the
internet, start with the User Interaction Guide.  This will
detail the steps needed to run the cmake(1) or
cmake-gui(1) executable and how to choose a generator, and how to
complete the build.

The Using Dependencies Guide is aimed at developers wishing to
get started using a third-party library.

For developers starting a project using CMake, the CMake Tutorial
is a suitable starting point.  The cmake-buildsystem(7).
manual is aimed at developers expanding their knowledge of maintaining a
buildsystem and becoming familiar with the build targets that can be
represented in CMake.  The cmake-packages(7) manual explains
how to create packages which can easily be consumed by third-party
CMake-based buildsystems.

 — The Detailed Node Listing —

Command-Line Tools

cmake(1)

Generate a Project Buildsystem

Run a Command-Line Tool

ctest(1)

Dashboard Client

Dashboard Client Configuration

Resource Allocation

cpack(1)

Interactive Dialogs

cmake-gui(1)

ccmake(1)

Reference Manuals

cmake-buildsystem(7)

Binary Targets

Binary Library Types

Normal Libraries

Build Specification and Usage Requirements

Build Specification with Generator Expressions

Output Artifacts

Pseudo Targets

cmake-commands(7)

Scripting Commands

cmake_language

Deferring Calls

cmake_minimum_required

cmake_policy

configure_file

file

find_package

function

if

list

macro

message

set

string

Search and Replace

unset

Project Commands

add_compile_options

add_custom_command

add_executable

add_library

install

project

target_compile_options

target_include_directories

target_link_libraries

target_precompile_headers

try_compile

try_run

CTest Commands

ctest_submit

Deprecated Commands

cmake-compile-features(7)

Compile Feature Requirements

cmake-developer(7)

Find Modules

cmake-env-variables(7)

Environment Variables that Change Behavior

Environment Variables that Control the Build

Environment Variables for Languages

Environment Variables for CTest

Environment Variables for the CMake curses interface

cmake-file-api(7)

API v1

v1 Reply Index File

Object Kinds

Object Kind “codemodel”

Object Kind “cache”

Object Kind “cmakeFiles”

cmake-generator-expressions(7)

Boolean Generator Expressions

String-Valued Generator Expressions

cmake-generators(7)

CMake Generators

Command-Line Build Tool Generators

Makefile Generators

Ninja Generators

Ninja

IDE Build Tool Generators

Visual Studio Generators

Visual Studio 9 2008

Visual Studio 10 2010

Visual Studio 11 2012

Visual Studio 12 2013

Visual Studio 14 2015

Visual Studio 15 2017

Visual Studio 16 2019

Other Generators

Xcode

Extra Generators

cmake-language(7)

Organization

Syntax

Command Arguments

Comments

Control Structures

cmake-modules(7)

Utility Modules

AndroidTestUtilities

CheckIPOSupported

CheckPIESupported

CMakeGraphVizOptions

CMakePackageConfigHelpers

CPack

CPackComponent

Commands

CPackIFW

CPackIFWConfigureFile

CSharpUtilities

ExternalData

Referencing Files

ExternalProject

Commands

FeatureSummary

FetchContent

Commands

FortranCInterface

GNUInstallDirs

UseJava

Creating And Installing JARs

WriteCompilerDetectionHeader

Find Modules

FindALSA

FindBLAS

FindBoost

FindBZip2

FindCUDAToolkit

Imported targets

FindCups

FindCURL

FindCurses

FindDCMTK

FindDoxygen

FindEnvModules

FindEXPAT

FindFLTK

FindFontconfig

FindFreetype

FindGDAL

FindGIF

FindGLEW

FindGLUT

FindGnuTLS

FindGSL

FindGTest

FindGTK2

FindHDF5

FindJNI

FindJPEG

FindLAPACK

FindLibinput

FindLibLZMA

FindLibXml2

FindLibXslt

FindLTTngUST

FindMatlab

Variables defined by the module

FindMPI

FindODBC

FindOpenACC

FindOpenAL

FindOpenCL

FindOpenGL

FindOpenMP

FindOpenSSL

FindPkgConfig

FindPNG

FindPostgreSQL

FindPython

FindPython2

FindPython3

FindQt4

FindRuby

FindSDL

FindSQLite3

FindThreads

FindTIFF

FindVulkan

FindXalanC

FindXCTest

FindXercesC

FindZLIB

Deprecated Modules

Deprecated Utility Modules

Deprecated Find Modules

FindCUDA

Legacy CPack Modules

cmake-packages(7)

Using Packages

Package Layout

Creating Packages

Creating a Package Configuration File

Package Registry

cmake-policies(7)

Policies Introduced by CMake 3.19

Policies Introduced by CMake 3.18

CMP0104

Policies Introduced by CMake 3.17

Policies Introduced by CMake 3.16

Policies Introduced by CMake 3.15

Policies Introduced by CMake 3.14

CMP0083

Policies Introduced by CMake 3.13

Policies Introduced by CMake 3.12

Policies Introduced by CMake 3.11

Policies Introduced by CMake 3.10

Policies Introduced by CMake 3.9

CMP0069

Policies Introduced by CMake 3.8

Policies Introduced by CMake 3.7

Policies Introduced by CMake 3.4

Policies Introduced by CMake 3.3

Policies Introduced by CMake 3.2

Policies Introduced by CMake 3.1

Policies Introduced by CMake 3.0

Policies Introduced by CMake 2.8

Policies Introduced by CMake 2.6

cmake-presets(7)

cmake-properties(7)

Properties of Global Scope

CMAKE_CXX_KNOWN_FEATURES

Low level individual compile features

Properties on Directories

Properties on Targets

AUTOGEN_ORIGIN_DEPENDS

AUTOGEN_TARGET_DEPENDS

AUTOMOC

Source file processing

Output file location

AUTOMOC_DEPEND_FILTERS

AUTOMOC_MACRO_NAMES

AUTOMOC_PATH_PREFIX

AUTORCC

AUTORCC_OPTIONS

AUTOUIC

AUTOUIC_OPTIONS

CUDA_ARCHITECTURES

INTERFACE_INCLUDE_DIRECTORIES

INTERFACE_LINK_LIBRARIES

ISPC_INSTRUCTION_SETS

LINK_INTERFACE_LIBRARIES

LINK_INTERFACE_LIBRARIES_<CONFIG>

MAP_IMPORTED_CONFIG_<CONFIG>

SOVERSION

UNITY_BUILD

VERSION

VS_NO_SOLUTION_DEPLOY

VS_SOLUTION_DEPLOY

Properties on Tests

DEPENDS

REQUIRED_FILES

TIMEOUT_AFTER_MATCH

Properties on Source Files

AUTORCC_OPTIONS

AUTOUIC_OPTIONS

SKIP_AUTOGEN

SKIP_AUTOMOC

SKIP_AUTORCC

SKIP_AUTOUIC

Properties on Cache Entries

Properties on Installed Files

Deprecated Properties on Directories

Deprecated Properties on Targets

Deprecated Properties on Source Files

cmake-qt(7)

Qt Build Tools

cmake-server(7)

Protocol API

General Message Layout

Specific Signals

Specific Message Types

cmake-toolchains(7)

Cross Compiling

Cross Compiling for Android

Cross Compiling for iOS, tvOS, or watchOS

cmake-variables(7)

Variables that Provide Information

CMAKE_GENERATOR_PLATFORM

CMAKE_GENERATOR_TOOLSET

Variables that Change Behavior

Variables that Describe the System

CMAKE_HOST_SYSTEM_PROCESSOR

CMAKE_SYSTEM_NAME

CMAKE_SYSTEM_VERSION

Variables that Control the Build

CMAKE_AUTOMOC_MACRO_NAMES

CMAKE_AUTORCC_OPTIONS

CMAKE_AUTOUIC_OPTIONS

CMAKE_GLOBAL_AUTOGEN_TARGET

Variables for Languages

CMAKE_<LANG>_COMPILER

Variables for CTest

CTEST_COVERAGE_COMMAND

Variables for CPack

Variable Expansion Operators

Internal Variables

cpack-generators(7)

Generators

CPack Archive Generator

CPack Bundle Generator

CPack Cygwin Generator

CPack DEB Generator

CPack DragNDrop Generator

CPack External Generator

JSON Format

CPack FreeBSD Generator

CPack IFW Generator

Variables

Other Settings

CPack NSIS Generator

CPack NuGet Generator

CPack PackageMaker Generator

CPack productbuild Generator

CPack RPM Generator

CPack WIX Generator

Guides

CMake Tutorial

A Basic Starting Point (Step 1)

Installing and Testing (Step 4)

Adding System Introspection (Step 5)

User Interaction Guide

Introduction

Generating a Buildsystem

Setting Build Variables

Presets

Invoking the Buildsystem

Using Dependencies Guide

Imported Targets from Packages

Importing and Exporting Guide

Importing Targets

Exporting Targets

Creating Packages

IDE Integration Guide

Command-Line Tools
******************

1 cmake(1)
**********

1.1 Synopsis
============

     See Generate a Project Buildsystem.
      cmake [<options>] <path-to-source>
      cmake [<options>] <path-to-existing-build>
      cmake [<options>] -S <path-to-source> -B <path-to-build>

     See Build a Project.
      cmake --build <dir> [<options>] [-- <build-tool-options>]

     See Install a Project.
      cmake --install <dir> [<options>]

     See Open a Project.
      cmake --open <dir>

     See Run a Script.
      cmake [{-D <var>=<value>}...] -P <cmake-script-file>

     See Run a Command-Line Tool.
      cmake -E <command> [<options>]

     See Run the Find-Package Tool.
      cmake --find-package [<options>]

     See View Help.
      cmake --help[-<topic>]

1.2 Description
===============

The `cmake' executable is the command-line interface of the
cross-platform buildsystem generator CMake.  The above Synopsis
lists various actions the tool can perform as described in sections
below.

To build a software project with CMake, see Generate a Project Buildsystem.
Optionally use `cmake' to Build a Project,
Install a Project or just run the corresponding build tool
(e.g.  ‘make’) directly.  `cmake' can also be used to View Help.

The other actions are meant for use by software developers writing
scripts in the CMake language to support their builds.

For graphical user interfaces that may be used in place of `cmake', see
ccmake and cmake-gui.  For command-line interfaces
to the CMake testing and packaging facilities, see ctest and
cpack.

For more information on CMake at large, see see also the links at
the end of this manual.

1.3 Introduction to CMake Buildsystems
======================================

A `buildsystem' describes how to build a project’s executables and
libraries from its source code using a `build tool' to automate the
process.  For example, a buildsystem may be a ‘Makefile’ for use with a
command-line ‘make’ tool or a project file for an Integrated Development
Environment (IDE). In order to avoid maintaining multiple such
buildsystems, a project may specify its buildsystem abstractly using
files written in the CMake language.  From these files CMake
generates a preferred buildsystem locally for each user through a
backend called a `generator'.

To generate a buildsystem with CMake, the following must be selected:

Source Tree

     The top-level directory containing source files provided by the
     project.  The project specifies its buildsystem using files as
     described in the cmake-language(7) manual, starting with
     a top-level file named ‘CMakeLists.txt’.  These files specify build
     targets and their dependencies as described in the
     cmake-buildsystem(7) manual.

Build Tree

     The top-level directory in which buildsystem files and build output
     artifacts (e.g.  executables and libraries) are to be stored.
     CMake will write a ‘CMakeCache.txt’ file to identify the directory
     as a build tree and store persistent information such as
     buildsystem configuration options.

     To maintain a pristine source tree, perform an `out-of-source'
     build by using a separate dedicated build tree.  An `in-source'
     build in which the build tree is placed in the same directory as
     the source tree is also supported, but discouraged.

Generator

     This chooses the kind of buildsystem to generate.  See the
     cmake-generators(7) manual for documentation of all
     generators.  Run ‘cmake --help’ to see a list of generators
     available locally.  Optionally use the ‘-G’ option below to specify
     a generator, or simply accept the default CMake chooses for the
     current platform.

     When using one of the Command-Line Build Tool Generators.
     CMake expects that the environment needed by the compiler toolchain
     is already configured in the shell.  When using one of the
     IDE Build Tool Generators, no particular environment is needed.

1.4 Generate a Project Buildsystem
==================================

Run CMake with one of the following command signatures to specify the
source and build trees and generate a buildsystem:

‘cmake [<options>] <path-to-source>’

     Uses the current working directory as the build tree, and
     ‘<path-to-source>’ as the source tree.  The specified path may be
     absolute or relative to the current working directory.  The source
     tree must contain a ‘CMakeLists.txt’ file and must `not' contain a
     ‘CMakeCache.txt’ file because the latter identifies an existing
     build tree.  For example:

          $ mkdir build ; cd build
          $ cmake ../src

‘cmake [<options>] <path-to-existing-build>’

     Uses ‘<path-to-existing-build>’ as the build tree, and loads the
     path to the source tree from its ‘CMakeCache.txt’ file, which must
     have already been generated by a previous run of CMake.  The
     specified path may be absolute or relative to the current working
     directory.  For example:

          $ cd build
          $ cmake .

‘cmake [<options>] -S <path-to-source> -B <path-to-build>’

     Uses ‘<path-to-build>’ as the build tree and ‘<path-to-source>’ as
     the source tree.  The specified paths may be absolute or relative
     to the current working directory.  The source tree must contain a
     ‘CMakeLists.txt’ file.  The build tree will be created
     automatically if it does not already exist.  For example:

          $ cmake -S src -B build

In all cases the ‘<options>’ may be zero or more of the Options
below.

After generating a buildsystem one may use the corresponding native
build tool to build the project.  For example, after using the
Unix Makefiles generator one may run ‘make’ directly:

          $ make
          $ make install

Alternatively, one may use `cmake' to Build a Project by
automatically choosing and invoking the appropriate native build tool.

1.4.1 Options
-------------

‘-S <path-to-source>’

     Path to root directory of the CMake project to build.

‘-B <path-to-build>’

     Path to directory which CMake will use as the root of build
     directory.

     If the directory doesn’t already exist CMake will make it.

‘-C <initial-cache>’

     Pre-load a script to populate the cache.

     When CMake is first run in an empty build tree, it creates a
     ‘CMakeCache.txt’ file and populates it with customizable settings
     for the project.  This option may be used to specify a file from
     which to load cache entries before the first pass through the
     project’s CMake listfiles.  The loaded entries take priority over
     the project’s default values.  The given file should be a CMake
     script containing set() commands that use the ‘CACHE’
     option, not a cache-format file.

     References to CMAKE_SOURCE_DIR and
     CMAKE_BINARY_DIR within the script evaluate to the top-level
     source and build tree.

‘-D <var>:<type>=<value>, -D <var>=<value>’

     Create or update a CMake ‘CACHE’ entry.

     When CMake is first run in an empty build tree, it creates a
     ‘CMakeCache.txt’ file and populates it with customizable settings
     for the project.  This option may be used to specify a setting that
     takes priority over the project’s default value.  The option may be
     repeated for as many ‘CACHE’ entries as desired.

     If the ‘:<type>’ portion is given it must be one of the types
     specified by the set() command documentation for its
     ‘CACHE’ signature.  If the ‘:<type>’ portion is omitted the entry
     will be created with no type if it does not exist with a type
     already.  If a command in the project sets the type to ‘PATH’ or
     ‘FILEPATH’ then the ‘<value>’ will be converted to an absolute
     path.

     This option may also be given as a single argument:
     ‘-D<var>:<type>=<value>’ or ‘-D<var>=<value>’.

‘-U <globbing_expr>’

     Remove matching entries from CMake ‘CACHE’.

     This option may be used to remove one or more variables from the
     ‘CMakeCache.txt’ file, globbing expressions using ‘*’ and ‘?’ are
     supported.  The option may be repeated for as many ‘CACHE’ entries
     as desired.

     Use with care, you can make your ‘CMakeCache.txt’ non-working.

‘-G <generator-name>’

     Specify a build system generator.

     CMake may support multiple native build systems on certain
     platforms.  A generator is responsible for generating a particular
     build system.  Possible generator names are specified in the
     cmake-generators(7) manual.

     If not specified, CMake checks the CMAKE_GENERATOR.
     environment variable and otherwise falls back to a builtin default
     selection.

‘-T <toolset-spec>’

     Toolset specification for the generator, if supported.

     Some CMake generators support a toolset specification to tell the
     native build system how to choose a compiler.  See the
     CMAKE_GENERATOR_TOOLSET variable for details.

‘-A <platform-name>’

     Specify platform name if supported by generator.

     Some CMake generators support a platform name to be given to the
     native build system to choose a compiler or SDK. See the
     CMAKE_GENERATOR_PLATFORM variable for details.

‘-Wno-dev’

     Suppress developer warnings.

     Suppress warnings that are meant for the author of the
     ‘CMakeLists.txt’ files.  By default this will also turn off
     deprecation warnings.

‘-Wdev’

     Enable developer warnings.

     Enable warnings that are meant for the author of the
     ‘CMakeLists.txt’ files.  By default this will also turn on
     deprecation warnings.

‘-Werror=dev’

     Make developer warnings errors.

     Make warnings that are meant for the author of the ‘CMakeLists.txt’
     files errors.  By default this will also turn on deprecated
     warnings as errors.

‘-Wno-error=dev’

     Make developer warnings not errors.

     Make warnings that are meant for the author of the ‘CMakeLists.txt’
     files not errors.  By default this will also turn off deprecated
     warnings as errors.

‘-Wdeprecated’

     Enable deprecated functionality warnings.

     Enable warnings for usage of deprecated functionality, that are
     meant for the author of the ‘CMakeLists.txt’ files.

‘-Wno-deprecated’

     Suppress deprecated functionality warnings.

     Suppress warnings for usage of deprecated functionality, that are
     meant for the author of the ‘CMakeLists.txt’ files.

‘-Werror=deprecated’

     Make deprecated macro and function warnings errors.

     Make warnings for usage of deprecated macros and functions, that
     are meant for the author of the ‘CMakeLists.txt’ files, errors.

‘-Wno-error=deprecated’

     Make deprecated macro and function warnings not errors.

     Make warnings for usage of deprecated macros and functions, that
     are meant for the author of the ‘CMakeLists.txt’ files, not errors.

‘-L[A][H]’

     List non-advanced cached variables.

     List ‘CACHE’ variables will run CMake and list all the variables
     from the CMake ‘CACHE’ that are not marked as ‘INTERNAL’ or
     ADVANCED.  This will effectively display current CMake
     settings, which can then be changed with ‘-D’ option.  Changing
     some of the variables may result in more variables being created.
     If ‘A’ is specified, then it will display also advanced variables.
     If ‘H’ is specified, it will also display help for each variable.

‘-N’

     View mode only.

     Only load the cache.  Do not actually run configure and generate
     steps.

‘--graphviz=[file]’

     Generate graphviz of dependencies, see CMakeGraphVizOptions
     for more.

     Generate a graphviz input file that will contain all the library
     and executable dependencies in the project.  See the documentation
     for CMakeGraphVizOptions for more details.

‘--system-information [file]’

     Dump information about this system.

     Dump a wide range of information about the current system.  If run
     from the top of a binary tree for a CMake project it will dump
     additional information such as the cache, log files etc.

‘--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>’

     Set the log level.

     The message() command will only output messages of the
     specified log level or higher.  The default log level is ‘STATUS’.

     To make a log level persist between CMake runs, set
     CMAKE_MESSAGE_LOG_LEVEL as a cache variable instead.  If both
     the command line option and the variable are given, the command
     line option takes precedence.

     For backward compatibility reasons, ‘--loglevel’ is also accepted
     as a synonym for this option.

‘--log-context’

     Enable the message() command outputting context attached
     to each message.

     This option turns on showing context for the current CMake run
     only.  To make showing the context persistent for all subsequent
     CMake runs, set CMAKE_MESSAGE_CONTEXT_SHOW as a cache
     variable instead.  When this command line option is given, see
     CMAKE_MESSAGE_CONTEXT_SHOW is ignored.

‘--debug-trycompile’

     Do not delete the try_compile() build tree.  Only useful
     on one try_compile() at a time.

     Do not delete the files and directories created for
     try_compile() calls.  This is useful in debugging failed
     try_compiles.  It may however change the results of the
     try-compiles as old junk from a previous try-compile may cause a
     different test to either pass or fail incorrectly.  This option is
     best used for one try-compile at a time, and only when debugging.

‘--debug-output’

     Put cmake in a debug mode.

     Print extra information during the cmake run like stack traces with
     message(SEND_ERROR) calls.

‘--debug-find’

     Put cmake find commands in a debug mode.

     Print extra find call information during the cmake run to standard
     error.  Output is designed for human consumption and not for
     parsing.  See also the CMAKE_FIND_DEBUG_MODE variable
     for debugging a more local part of the project.

‘--trace’

     Put cmake in trace mode.

     Print a trace of all calls made and from where.

‘--trace-expand’

     Put cmake in trace mode.

     Like ‘--trace’, but with variables expanded.

‘--trace-format=<format>’

     Put cmake in trace mode and sets the trace output format.

     ‘<format>’ can be one of the following values.

          ‘human’

               Prints each trace line in a human-readable format.  This
               is the default format.

          ‘json-v1’

               Prints each line as a separate JSON document.  Each
               document is separated by a newline ( ‘\n’ ).  It is
               guaranteed that no newline characters will be present
               inside a JSON document.

               JSON trace format:

                    {
                      "file": "/full/path/to/the/CMake/file.txt",
                      "line": 0,
                      "cmd": "add_executable",
                      "args": ["foo", "bar"],
                      "time": 1579512535.9687231,
                      "frame": 2
                    }

               The members are:

               ‘file’

                    The full path to the CMake source file where the
                    function was called.

               ‘line’

                    The line in ‘file’ of the function call.

               ‘defer’

                    Optional member that is present when the function
                    call was deferred by cmake_language(DEFER).
                    If present, its value is a string containing
                    the deferred call ‘<id>’.

               ‘cmd’

                    The name of the function that was called.

               ‘args’

                    A string list of all function parameters.

               ‘time’

                    Timestamp (seconds since epoch) of the function
                    call.

               ‘frame’

                    Stack frame depth of the function that was called.

               Additionally, the first JSON document outputted contains
               the ‘version’ key for the current major and minor version
               of the

               JSON trace format:

                    {
                      "version": {
                        "major": 1,
                        "minor": 1
                      }
                    }

               The members are:

               ‘version’

                    Indicates the version of the JSON format.  The
                    version has a major and minor components following
                    semantic version conventions.

‘--trace-source=<file>’

     Put cmake in trace mode, but output only lines of a specified file.

     Multiple options are allowed.

‘--trace-redirect=<file>’

     Put cmake in trace mode and redirect trace output to a file instead
     of stderr.

‘--warn-uninitialized’

     Warn about uninitialized values.

     Print a warning when an uninitialized variable is used.

‘--warn-unused-vars’

     Does nothing.  In CMake versions 3.2 and below this enabled
     warnings about unused variables.  In CMake versions 3.3 through
     3.18 the option was broken.  In CMake 3.19 and above the option has
     been removed.

‘--no-warn-unused-cli’

     Don’t warn about command line options.

     Don’t find variables that are declared on the command line, but not
     used.

‘--check-system-vars’

     Find problems with variable usage in system files.

     Normally, unused and uninitialized variables are searched for only
     in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR.
     This flag tells CMake to warn about other files as well.

‘--profiling-output=<path>’

     Used in conjunction with ‘--profiling-format’ to output to a given
     path.

‘--profiling-format=<file>’

     Enable the output of profiling data of CMake script in the given
     format.

     This can aid performance analysis of CMake scripts executed.  Third
     party applications should be used to process the output into human
     readable format.

     Currently supported values are: ‘google-trace’ Outputs in Google
     Trace Format, which can be parsed by the ‘about:tracing’ tab of
     Google Chrome or using a plugin for a tool like Trace Compass.

‘--preset=<preset>’

     Reads a preset from ‘<path-to-source>/CMakePresets.json’
     and ‘<path-to-source>/CMakeUserPresets.json’.  The preset specifies
     the generator and the build directory, and optionally a list of
     variables and other arguments to pass to CMake.  The CMake GUI
     can also recognize ‘CMakePresets.json’ and
     ‘CMakeUserPresets.json’ files.  For full details on these files,
     see cmake-presets(7).

     The presets are read before all other command line options.  The
     options specified by the preset (variables, generator, etc.)  can
     all be overridden by manually specifying them on the command line.
     For example, if the preset sets a variable called ‘MYVAR’ to ‘1’,
     but the user sets it to ‘2’ with a ‘-D’ argument, the value ‘2’ is
     preferred.

1.5 Build a Project
===================

CMake provides a command-line signature to build an already-generated
project binary tree:

     cmake --build <dir> [<options>] [-- <build-tool-options>]

This abstracts a native build tool’s command-line interface with the
following options:

‘--build <dir>’

     Project binary directory to be built.  This is required and must be
     first.

‘--parallel [<jobs>], -j [<jobs>]’

     The maximum number of concurrent processes to use when building.
     If ‘<jobs>’ is omitted the native build tool’s default number is
     used.

     The CMAKE_BUILD_PARALLEL_LEVEL environment variable, if
     set, specifies a default parallel level when this option is not
     given.

     Some native build tools always build in parallel.  The use of
     ‘<jobs>’ value of ‘1’ can be used to limit to a single job.

‘--target <tgt>..., -t <tgt>...’

     Build ‘<tgt>’ instead of the default target.  Multiple targets may
     be given, separated by spaces.

‘--config <cfg>’

     For multi-configuration tools, choose configuration ‘<cfg>’.

‘--clean-first’

     Build target ‘clean’ first, then build.  (To clean only, use
     ‘--target clean’.)

‘--use-stderr’

     Ignored.  Behavior is default in CMake >= 3.0.

‘--verbose, -v’

     Enable verbose output - if supported - including the build commands
     to be executed.

     This option can be omitted if VERBOSE environment
     variable or CMAKE_VERBOSE_MAKEFILE cached variable is
     set.

‘--’

     Pass remaining options to the native tool.

Run ‘cmake --build’ with no options for quick help.

1.6 Install a Project
=====================

CMake provides a command-line signature to install an already-generated
project binary tree:

     cmake --install <dir> [<options>]

This may be used after building a project to run installation without
using the generated build system or the native build tool.  The options
are:

‘--install <dir>’

     Project binary directory to install.  This is required and must be
     first.

‘--config <cfg>’

     For multi-configuration generators, choose configuration ‘<cfg>’.

‘--component <comp>’

     Component-based install.  Only install component ‘<comp>’.

‘--default-directory-permissions <permissions>’

     Default directory install permissions.  Permissions in format
     ‘<u=rwx,g=rx,o=rx>’.

‘--prefix <prefix>’

     Override the installation prefix, see CMAKE_INSTALL_PREFIX.

‘--strip’

     Strip before installing.

‘-v, --verbose’

     Enable verbose output.

     This option can be omitted if VERBOSE environment
     variable is set.

Run ‘cmake --install’ with no options for quick help.

1.7 Open a Project
==================

     cmake --open <dir>

Open the generated project in the associated application.  This is only
supported by some generators.

1.8 Run a Script
================

     cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...]

Process the given cmake file as a script written in the CMake language.
No configure or generate step is performed and the cache is not
modified.  If variables are defined using ‘-D’, this must be done before
the ‘-P’ argument.

Any options after ‘--’ are not parsed by CMake, but they are still
included in the set of CMAKE_ARGV<n> variables passed to the
script (including the ‘--’ itself).

1.9 Run a Command-Line Tool
===========================

CMake provides builtin command-line tools through the signature

     cmake -E <command> [<options>]

Run ‘cmake -E’ or ‘cmake -E help’ for a summary of commands.  Available
commands are:

‘capabilities’

     Report cmake capabilities in JSON format.  The output is a JSON
     object with the following keys:

     ‘version’

          A JSON object with version information.  Keys are:

          ‘string’

               The full version string as displayed by cmake
               ‘--version’.

          ‘major’

               The major version number in integer form.

          ‘minor’

               The minor version number in integer form.

          ‘patch’

               The patch level in integer form.

          ‘suffix’

               The cmake version suffix string.

          ‘isDirty’

               A bool that is set if the cmake build is from a dirty
               tree.

     ‘generators’

          A list available generators.  Each generator is a JSON object
          with the following keys:

          ‘name’

               A string containing the name of the generator.

          ‘toolsetSupport’

               ‘true’ if the generator supports toolsets and ‘false’
               otherwise.

          ‘platformSupport’

               ‘true’ if the generator supports platforms and ‘false’
               otherwise.

          ‘extraGenerators’

               A list of strings with all the extra generators
               compatible with the generator.

     ‘fileApi’

          Optional member that is present when the
          cmake-file-api(7) is available.  The value is a JSON
          object with one member:

          ‘requests’

               A JSON array containing zero or more supported file-api
               requests.  Each request is a JSON object with members:

               ‘kind’

                    Specifies one of the supported Object Kinds.

               ‘version’

                    A JSON array whose elements are each a JSON object
                    containing ‘major’ and ‘minor’ members specifying
                    non-negative integer version components.

     ‘serverMode’

          ‘true’ if cmake supports server-mode and ‘false’ otherwise.

‘cat <files>...’

     Concatenate files and print on the standard output.

‘chdir <dir> <cmd> [<arg>...]’

     Change the current working directory and run a command.

‘compare_files [--ignore-eol] <file1> <file2>’

     Check if ‘<file1>’ is same as ‘<file2>’.  If files are the same,
     then returns ‘0’, if not it returns ‘1’.  In case of invalid
     arguments, it returns 2.  The ‘--ignore-eol’ option implies
     line-wise comparison and ignores LF/CRLF differences.

‘copy <file>... <destination>’

     Copy files to ‘<destination>’ (either file or directory).  If
     multiple files are specified, the ‘<destination>’ must be directory
     and it must exist.  Wildcards are not supported.  ‘copy’ does
     follow symlinks.  That means it does not copy symlinks, but the
     files or directories it point to.

‘copy_directory <dir>... <destination>’

     Copy content of ‘<dir>...’ directories to ‘<destination>’
     directory.  If ‘<destination>’ directory does not exist it will be
     created.  ‘copy_directory’ does follow symlinks.

‘copy_if_different <file>... <destination>’

     Copy files to ‘<destination>’ (either file or directory) if they
     have changed.  If multiple files are specified, the ‘<destination>’
     must be directory and it must exist.  ‘copy_if_different’ does
     follow symlinks.

‘create_symlink <old> <new>’

     Create a symbolic link ‘<new>’ naming ‘<old>’.

          Note: Path to where ‘<new>’ symbolic link will be created has
          to exist beforehand.

‘create_hardlink <old> <new>’

     Create a hard link ‘<new>’ naming ‘<old>’.

          Note: Path to where ‘<new>’ hard link will be created has to
          exist beforehand.  ‘<old>’ has to exist beforehand.

‘echo [<string>...]’

     Displays arguments as text.

‘echo_append [<string>...]’

     Displays arguments as text but no new line.

‘env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...’

     Run command in a modified environment.

‘environment’

     Display the current environment variables.

‘false’

     Do nothing, with an exit code of 1.

‘make_directory <dir>...’

     Create ‘<dir>’ directories.  If necessary, create parent
     directories too.  If a directory already exists it will be silently
     ignored.

‘md5sum <file>...’

     Create MD5 checksum of files in ‘md5sum’ compatible format:

          351abe79cd3800b38cdfb25d45015a15  file1.txt
          052f86c15bbde68af55c7f7b340ab639  file2.txt

‘sha1sum <file>...’

     Create SHA1 checksum of files in ‘sha1sum’ compatible format:

          4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
          1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

‘sha224sum <file>...’

     Create SHA224 checksum of files in ‘sha224sum’ compatible format:

          b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
          6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

‘sha256sum <file>...’

     Create SHA256 checksum of files in ‘sha256sum’ compatible format:

          76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
          15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

‘sha384sum <file>...’

     Create SHA384 checksum of files in ‘sha384sum’ compatible format:

          acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
          668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

‘sha512sum <file>...’

     Create SHA512 checksum of files in ‘sha512sum’ compatible format:

          2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
          7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

‘remove [-f] <file>...’

     Deprecated since version 3.17.

     Remove the file(s).  The planned behaviour was that if any of the
     listed files already do not exist, the command returns a non-zero
     exit code, but no message is logged.  The ‘-f’ option changes the
     behavior to return a zero exit code (i.e.  success) in such
     situations instead.  ‘remove’ does not follow symlinks.  That means
     it remove only symlinks and not files it point to.

     The implementation was buggy and always returned 0.  It cannot be
     fixed without breaking backwards compatibility.  Use ‘rm’ instead.

‘remove_directory <dir>...’

     Deprecated since version 3.17.

     Remove ‘<dir>’ directories and their contents.  If a directory does
     not exist it will be silently ignored.  If ‘<dir>’ is a symlink to
     a directory, just the symlink will be removed.  Use ‘rm’ instead.

‘rename <oldname> <newname>’

     Rename a file or directory (on one volume).  If file with the
     ‘<newname>’ name already exists, then it will be silently replaced.

‘rm [-rRf] <file> <dir>...’

     Remove the files ‘<file>’ or directories ‘dir’.  Use ‘-r’ or ‘-R’
     to remove directories and their contents recursively.  If any of
     the listed files/directories do not exist, the command returns a
     non-zero exit code, but no message is logged.  The ‘-f’ option
     changes the behavior to return a zero exit code (i.e.  success) in
     such situations instead.

‘server’

     Launch cmake-server(7) mode.

‘sleep <number>...’

     Sleep for given number of seconds.

‘tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]’

     Create or extract a tar or zip archive.  Options are:

     ‘c’

          Create a new archive containing the specified files.  If used,
          the ‘<pathname>...’ argument is mandatory.

     ‘x’

          Extract to disk from the archive.  The ‘<pathname>...’
          argument could be used to extract only selected files or
          directories.  When extracting selected files or directories,
          you must provide their exact names including the path, as
          printed by list (‘-t’).

     ‘t’

          List archive contents.  The ‘<pathname>...’ argument could be
          used to list only selected files or directories.

     ‘v’

          Produce verbose output.

     ‘z’

          Compress the resulting archive with gzip.

     ‘j’

          Compress the resulting archive with bzip2.

     ‘J’

          Compress the resulting archive with XZ.

     ‘--zstd’

          Compress the resulting archive with Zstandard.

     ‘--files-from=<file>’

          Read file names from the given file, one per line.  Blank
          lines are ignored.  Lines may not start in ‘-’ except for
          ‘--add-file=<name>’ to add files whose names start in ‘-’.

     ‘--format=<format>’

          Specify the format of the archive to be created.  Supported
          formats are: ‘7zip’, ‘gnutar’, ‘pax’, ‘paxr’ (restricted pax,
          default), and ‘zip’.

     ‘--mtime=<date>’

          Specify modification time recorded in tarball entries.

     ‘--’

          Stop interpreting options and treat all remaining arguments as
          file names, even if they start with ‘-’.

‘time <command> [<args>...]’

     Run command and display elapsed time.

‘touch <file>...’

     Creates ‘<file>’ if file do not exist.  If ‘<file>’ exists, it is
     changing ‘<file>’ access and modification times.

‘touch_nocreate <file>...’

     Touch a file if it exists but do not create it.  If a file does not
     exist it will be silently ignored.

‘true’

     Do nothing, with an exit code of 0.

1.9.1 Windows-specific Command-Line Tools
-----------------------------------------

The following ‘cmake -E’ commands are available only on Windows:

‘delete_regv <key>’

     Delete Windows registry value.

‘env_vs8_wince <sdkname>’

     Displays a batch file which sets the environment for the provided
     Windows CE SDK installed in VS2005.

‘env_vs9_wince <sdkname>’

     Displays a batch file which sets the environment for the provided
     Windows CE SDK installed in VS2008.

‘write_regv <key> <value>’

     Write Windows registry value.

1.10 Run the Find-Package Tool
==============================

CMake provides a pkg-config like helper for Makefile-based projects:

     cmake --find-package [<options>]

It searches a package using find_package() and prints the
resulting flags to stdout.  This can be used instead of pkg-config to
find installed libraries in plain Makefile-based projects or in
autoconf-based projects (via ‘share/aclocal/cmake.m4’).

     Note: This mode is not well-supported due to some technical
     limitations.  It is kept for compatibility but should not be used
     in new projects.

1.11 View Help
==============

To print selected pages from the CMake documentation, use

     cmake --help[-<topic>]

with one of the following options:

‘--help,-help,-usage,-h,-H,/?’

     Print usage information and exit.

     Usage describes the basic command line interface and its options.

‘--version,-version,/V [<f>]’

     Show program name/version banner and exit.

     If a file is specified, the version is written into it.  The help
     is printed to a named <f>ile if given.

‘--help-full [<f>]’

     Print all help manuals and exit.

     All manuals are printed in a human-readable text format.  The help
     is printed to a named <f>ile if given.

‘--help-manual <man> [<f>]’

     Print one help manual and exit.

     The specified manual is printed in a human-readable text format.
     The help is printed to a named <f>ile if given.

‘--help-manual-list [<f>]’

     List help manuals available and exit.

     The list contains all manuals for which help may be obtained by
     using the ‘--help-manual’ option followed by a manual name.  The
     help is printed to a named <f>ile if given.

‘--help-command <cmd> [<f>]’

     Print help for one command and exit.

     The cmake-commands(7) manual entry for ‘<cmd>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-command-list [<f>]’

     List commands with help available and exit.

     The list contains all commands for which help may be obtained by
     using the ‘--help-command’ option followed by a command name.  The
     help is printed to a named <f>ile if given.

‘--help-commands [<f>]’

     Print cmake-commands manual and exit.

     The cmake-commands(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-module <mod> [<f>]’

     Print help for one module and exit.

     The cmake-modules(7) manual entry for ‘<mod>’ is printed
     in a human-readable text format.  The help is printed to a named
     <f>ile if given.

‘--help-module-list [<f>]’

     List modules with help available and exit.

     The list contains all modules for which help may be obtained by
     using the ‘--help-module’ option followed by a module name.  The
     help is printed to a named <f>ile if given.

‘--help-modules [<f>]’

     Print cmake-modules manual and exit.

     The cmake-modules(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-policy <cmp> [<f>]’

     Print help for one policy and exit.

     The cmake-policies(7) manual entry for ‘<cmp>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-policy-list [<f>]’

     List policies with help available and exit.

     The list contains all policies for which help may be obtained by
     using the ‘--help-policy’ option followed by a policy name.  The
     help is printed to a named <f>ile if given.

‘--help-policies [<f>]’

     Print cmake-policies manual and exit.

     The cmake-policies(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-property <prop> [<f>]’

     Print help for one property and exit.

     The cmake-properties(7) manual entries for ‘<prop>’ are
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-property-list [<f>]’

     List properties with help available and exit.

     The list contains all properties for which help may be obtained by
     using the ‘--help-property’ option followed by a property name.
     The help is printed to a named <f>ile if given.

‘--help-properties [<f>]’

     Print cmake-properties manual and exit.

     The cmake-properties(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-variable <var> [<f>]’

     Print help for one variable and exit.

     The cmake-variables(7) manual entry for ‘<var>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-variable-list [<f>]’

     List variables with help available and exit.

     The list contains all variables for which help may be obtained by
     using the ‘--help-variable’ option followed by a variable name.
     The help is printed to a named <f>ile if given.

‘--help-variables [<f>]’

     Print cmake-variables manual and exit.

     The cmake-variables(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

To view the presets available for a project, use

     cmake <source-dir> --list-presets

1.12 See Also
=============

The following resources are available to get help using CMake:

Home Page

     ‘https://cmake.org’

     The primary starting point for learning about CMake.

Online Documentation and Community Resources

     ‘https://cmake.org/documentation’

     Links to available documentation and community resources may be
     found on this web page.

Discourse Forum

     ‘https://discourse.cmake.org’

     The Discourse Forum hosts discussion and questions about CMake.

2 ctest(1)
**********

2.1 Synopsis
============

     ctest [<options>]
     ctest --build-and-test <path-to-source> <path-to-build>
           --build-generator <generator> [<options>...]
           [--build-options <opts>...] [--test-command <command> [<args>...]]
     ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
           [-- <dashboard-options>...]

2.2 Description
===============

The `ctest' executable is the CMake test driver program.
CMake-generated build trees created for projects that use the
enable_testing() and add_test() commands have testing
support.  This program will run the tests and report results.

2.3 Options
===========

‘-C <cfg>, --build-config <cfg>’

     Choose configuration to test.

     Some CMake-generated build trees can have multiple build
     configurations in the same tree.  This option can be used to
     specify which one should be tested.  Example configurations are
     ‘Debug’ and ‘Release’.

‘--progress’

     Enable short progress output from tests.

     When the output of `ctest' is being sent directly to a terminal,
     the progress through the set of tests is reported by updating the
     same line rather than printing start and end messages for each test
     on new lines.  This can significantly reduce the verbosity of the
     test output.  Test completion messages are still output on their
     own line for failed tests and the final test summary will also
     still be logged.

     This option can also be enabled by setting the environment variable
     CTEST_PROGRESS_OUTPUT.

‘-V,--verbose’

     Enable verbose output from tests.

     Test output is normally suppressed and only summary information is
     displayed.  This option will show all test output.

‘-VV,--extra-verbose’

     Enable more verbose output from tests.

     Test output is normally suppressed and only summary information is
     displayed.  This option will show even more test output.

‘--debug’

     Displaying more verbose internals of CTest.

     This feature will result in a large number of output that is mostly
     useful for debugging dashboard problems.

‘--output-on-failure’

     Output anything outputted by the test program if the test should
     fail.  This option can also be enabled by setting the
     CTEST_OUTPUT_ON_FAILURE environment variable

‘--stop-on-failure’

     Stop running the tests when the first failure happens.

‘-F’

     Enable failover.

     This option allows CTest to resume a test set execution that was
     previously interrupted.  If no interruption occurred, the ‘-F’
     option will have no effect.

‘-j <jobs>, --parallel <jobs>’

     Run the tests in parallel using the given number of jobs.

     This option tells CTest to run the tests in parallel using given
     number of jobs.  This option can also be set by setting the
     CTEST_PARALLEL_LEVEL environment variable.

     This option can be used with the PROCESSORS test
     property.

     See Label and Subproject Summary.

‘--resource-spec-file <file>’

     Run CTest with resource allocation enabled, using the
     resource specification file specified in ‘<file>’.

     When ‘ctest’ is run as a Dashboard Client this sets the
     ‘ResourceSpecFile’ option of the CTest Test Step.

‘--test-load <level>’

     While running tests in parallel (e.g.  with ‘-j’), try not to start
     tests when they may cause the CPU load to pass above a given
     threshold.

     When ‘ctest’ is run as a Dashboard Client this sets the
     ‘TestLoad’ option of the CTest Test Step.

‘-Q,--quiet’

     Make CTest quiet.

     This option will suppress all the output.  The output log file will
     still be generated if the ‘--output-log’ is specified.  Options
     such as ‘--verbose’, ‘--extra-verbose’, and ‘--debug’ are ignored
     if ‘--quiet’ is specified.

‘-O <file>, --output-log <file>’

     Output to log file.

     This option tells CTest to write all its output to a ‘<file>’ log
     file.

‘-N,--show-only[=<format>]’

     Disable actual execution of tests.

     This option tells CTest to list the tests that would be run but not
     actually run them.  Useful in conjunction with the ‘-R’ and ‘-E’
     options.

     ‘<format>’ can be one of the following values.

          ‘human’

               Human-friendly output.  This is not guaranteed to be
               stable.  This is the default.

          ‘json-v1’

               Dump the test information in JSON format.  See Show as JSON Object Model.

‘-L <regex>, --label-regex <regex>’

     Run tests with labels matching regular expression.

     This option tells CTest to run only the tests whose labels match
     the given regular expression.

‘-R <regex>, --tests-regex <regex>’

     Run tests matching regular expression.

     This option tells CTest to run only the tests whose names match the
     given regular expression.

‘-E <regex>, --exclude-regex <regex>’

     Exclude tests matching regular expression.

     This option tells CTest to NOT run the tests whose names match the
     given regular expression.

‘-LE <regex>, --label-exclude <regex>’

     Exclude tests with labels matching regular expression.

     This option tells CTest to NOT run the tests whose labels match the
     given regular expression.

‘-FA <regex>, --fixture-exclude-any <regex>’

     Exclude fixtures matching ‘<regex>’ from automatically adding any
     tests to the test set.

     If a test in the set of tests to be executed requires a particular
     fixture, that fixture’s setup and cleanup tests would normally be
     added to the test set automatically.  This option prevents adding
     setup or cleanup tests for fixtures matching the ‘<regex>’.  Note
     that all other fixture behavior is retained, including test
     dependencies and skipping tests that have fixture setup tests that
     fail.

‘-FS <regex>, --fixture-exclude-setup <regex>’

     Same as ‘-FA’ except only matching setup tests are excluded.

‘-FC <regex>, --fixture-exclude-cleanup <regex>’

     Same as ‘-FA’ except only matching cleanup tests are excluded.

‘-D <dashboard>, --dashboard <dashboard>’

     Execute dashboard test.

     This option tells CTest to act as a CDash client and perform a
     dashboard test.  All tests are ‘<Mode><Test>’, where ‘<Mode>’ can
     be ‘Experimental’, ‘Nightly’, and ‘Continuous’, and ‘<Test>’ can be
     ‘Start’, ‘Update’, ‘Configure’, ‘Build’, ‘Test’, ‘Coverage’, and
     ‘Submit’.

     See Dashboard Client.

‘-D <var>:<type>=<value>’

     Define a variable for script mode.

     Pass in variable values on the command line.  Use in conjunction
     with ‘-S’ to pass variable values to a dashboard script.  Parsing
     ‘-D’ arguments as variable values is only attempted if the value
     following ‘-D’ does not match any of the known dashboard types.

‘-M <model>, --test-model <model>’

     Sets the model for a dashboard.

     This option tells CTest to act as a CDash client where the
     ‘<model>’ can be ‘Experimental’, ‘Nightly’, and ‘Continuous’.
     Combining ‘-M’ and ‘-T’ is similar to ‘-D’.

     See Dashboard Client.

‘-T <action>, --test-action <action>’

     Sets the dashboard action to perform.

     This option tells CTest to act as a CDash client and perform some
     action such as ‘start’, ‘build’, ‘test’ etc.  See Dashboard Client Steps
     for the full list of actions.  Combining ‘-M’ and
     ‘-T’ is similar to ‘-D’.

     See Dashboard Client.

‘-S <script>, --script <script>’

     Execute a dashboard for a configuration.

     This option tells CTest to load in a configuration script which
     sets a number of parameters such as the binary and source
     directories.  Then CTest will do what is required to create and run
     a dashboard.  This option basically sets up a dashboard and then
     runs ‘ctest -D’ with the appropriate options.

     See Dashboard Client.

‘-SP <script>, --script-new-process <script>’

     Execute a dashboard for a configuration.

     This option does the same operations as ‘-S’ but it will do them in
     a separate process.  This is primarily useful in cases where the
     script may modify the environment and you do not want the modified
     environment to impact other ‘-S’ scripts.

     See Dashboard Client.

‘-I [Start,End,Stride,test#,test#|Test file], --tests-information’

     Run a specific number of tests by number.

     This option causes CTest to run tests starting at number ‘Start’,
     ending at number ‘End’, and incrementing by ‘Stride’.  Any
     additional numbers after ‘Stride’ are considered individual test
     numbers.  ‘Start’, ‘End’, or ‘Stride’ can be empty.  Optionally a
     file can be given that contains the same syntax as the command
     line.

‘-U, --union’

     Take the Union of ‘-I’ and ‘-R’.

     When both ‘-R’ and ‘-I’ are specified by default the intersection
     of tests are run.  By specifying ‘-U’ the union of tests is run
     instead.

‘--rerun-failed’

     Run only the tests that failed previously.

     This option tells CTest to perform only the tests that failed
     during its previous run.  When this option is specified, CTest
     ignores all other options intended to modify the list of tests to
     run (‘-L’, ‘-R’, ‘-E’, ‘-LE’, ‘-I’, etc).  In the event that CTest
     runs and no tests fail, subsequent calls to CTest with the
     ‘--rerun-failed’ option will run the set of tests that most
     recently failed (if any).

‘--repeat <mode>:<n>’

     Run tests repeatedly based on the given ‘<mode>’ up to ‘<n>’ times.
     The modes are:

     ‘until-fail’

          Require each test to run ‘<n>’ times without failing in order
          to pass.  This is useful in finding sporadic failures in test
          cases.

     ‘until-pass’

          Allow each test to run up to ‘<n>’ times in order to pass.
          Repeats tests if they fail for any reason.  This is useful in
          tolerating sporadic failures in test cases.

     ‘after-timeout’

          Allow each test to run up to ‘<n>’ times in order to pass.
          Repeats tests only if they timeout.  This is useful in
          tolerating sporadic timeouts in test cases on busy machines.

‘--repeat-until-fail <n>’

     Equivalent to ‘--repeat until-fail:<n>’.

‘--max-width <width>’

     Set the max width for a test name to output.

     Set the maximum width for each test name to show in the output.
     This allows the user to widen the output to avoid clipping the test
     name which can be very annoying.

‘--interactive-debug-mode [0|1]’

     Set the interactive mode to ‘0’ or ‘1’.

     This option causes CTest to run tests in either an interactive mode
     or a non-interactive mode.  On Windows this means that in
     non-interactive mode, all system debug pop up windows are blocked.
     In dashboard mode (‘Experimental’, ‘Nightly’, ‘Continuous’), the
     default is non-interactive.  When just running tests not for a
     dashboard the default is to allow popups and interactive debugging.

‘--no-label-summary’

     Disable timing summary information for labels.

     This option tells CTest not to print summary information for each
     label associated with the tests run.  If there are no labels on the
     tests, nothing extra is printed.

     See Label and Subproject Summary.

‘--no-subproject-summary’

     Disable timing summary information for subprojects.

     This option tells CTest not to print summary information for each
     subproject associated with the tests run.  If there are no
     subprojects on the tests, nothing extra is printed.

     See Label and Subproject Summary.

‘--build-and-test’ See Build and Test Mode.

‘--test-output-size-passed <size>’

     Limit the output for passed tests to ‘<size>’ bytes.

‘--test-output-size-failed <size>’

     Limit the output for failed tests to ‘<size>’ bytes.

‘--overwrite’

     Overwrite CTest configuration option.

     By default CTest uses configuration options from configuration
     file.  This option will overwrite the configuration option.

‘--force-new-ctest-process’

     Run child CTest instances as new processes.

     By default CTest will run child CTest instances within the same
     process.  If this behavior is not desired, this argument will
     enforce new processes for child CTest processes.

‘--schedule-random’

     Use a random order for scheduling tests.

     This option will run the tests in a random order.  It is commonly
     used to detect implicit dependencies in a test suite.

‘--submit-index’

     Legacy option for old Dart2 dashboard server feature.  Do not use.

‘--timeout <seconds>’

     Set the default test timeout.

     This option effectively sets a timeout on all tests that do not
     already have a timeout set on them via the TIMEOUT.
     property.

‘--stop-time <time>’

     Set a time at which all tests should stop running.

     Set a real time of day at which all tests should timeout.  Example:
     ‘7:00:00 -0400’.  Any time format understood by the curl date
     parser is accepted.  Local time is assumed if no timezone is
     specified.

‘--print-labels’

     Print all available test labels.

     This option will not run any tests, it will simply print the list
     of all labels associated with the test set.

‘--no-tests=<[error|ignore]>’

     Regard no tests found either as error or ignore it.

     If no tests were found, the default behavior of CTest is to always
     log an error message but to return an error code in script mode
     only.  This option unifies the behavior of CTest by either
     returning an error code if no tests were found or by ignoring it.

‘--help,-help,-usage,-h,-H,/?’

     Print usage information and exit.

     Usage describes the basic command line interface and its options.

‘--version,-version,/V [<f>]’

     Show program name/version banner and exit.

     If a file is specified, the version is written into it.  The help
     is printed to a named <f>ile if given.

‘--help-full [<f>]’

     Print all help manuals and exit.

     All manuals are printed in a human-readable text format.  The help
     is printed to a named <f>ile if given.

‘--help-manual <man> [<f>]’

     Print one help manual and exit.

     The specified manual is printed in a human-readable text format.
     The help is printed to a named <f>ile if given.

‘--help-manual-list [<f>]’

     List help manuals available and exit.

     The list contains all manuals for which help may be obtained by
     using the ‘--help-manual’ option followed by a manual name.  The
     help is printed to a named <f>ile if given.

‘--help-command <cmd> [<f>]’

     Print help for one command and exit.

     The cmake-commands(7) manual entry for ‘<cmd>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-command-list [<f>]’

     List commands with help available and exit.

     The list contains all commands for which help may be obtained by
     using the ‘--help-command’ option followed by a command name.  The
     help is printed to a named <f>ile if given.

‘--help-commands [<f>]’

     Print cmake-commands manual and exit.

     The cmake-commands(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-module <mod> [<f>]’

     Print help for one module and exit.

     The cmake-modules(7) manual entry for ‘<mod>’ is printed
     in a human-readable text format.  The help is printed to a named
     <f>ile if given.

‘--help-module-list [<f>]’

     List modules with help available and exit.

     The list contains all modules for which help may be obtained by
     using the ‘--help-module’ option followed by a module name.  The
     help is printed to a named <f>ile if given.

‘--help-modules [<f>]’

     Print cmake-modules manual and exit.

     The cmake-modules(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-policy <cmp> [<f>]’

     Print help for one policy and exit.

     The cmake-policies(7) manual entry for ‘<cmp>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-policy-list [<f>]’

     List policies with help available and exit.

     The list contains all policies for which help may be obtained by
     using the ‘--help-policy’ option followed by a policy name.  The
     help is printed to a named <f>ile if given.

‘--help-policies [<f>]’

     Print cmake-policies manual and exit.

     The cmake-policies(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-property <prop> [<f>]’

     Print help for one property and exit.

     The cmake-properties(7) manual entries for ‘<prop>’ are
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-property-list [<f>]’

     List properties with help available and exit.

     The list contains all properties for which help may be obtained by
     using the ‘--help-property’ option followed by a property name.
     The help is printed to a named <f>ile if given.

‘--help-properties [<f>]’

     Print cmake-properties manual and exit.

     The cmake-properties(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-variable <var> [<f>]’

     Print help for one variable and exit.

     The cmake-variables(7) manual entry for ‘<var>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-variable-list [<f>]’

     List variables with help available and exit.

     The list contains all variables for which help may be obtained by
     using the ‘--help-variable’ option followed by a variable name.
     The help is printed to a named <f>ile if given.

‘--help-variables [<f>]’

     Print cmake-variables manual and exit.

     The cmake-variables(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

2.4 Label and Subproject Summary
================================

CTest prints timing summary information for each ‘LABEL’ and subproject
associated with the tests run.  The label time summary will not include
labels that are mapped to subprojects.

When the PROCESSORS test property is set, CTest will display
a weighted test timing result in label and subproject summaries.  The
time is reported with ‘sec*proc’ instead of just ‘sec’.

The weighted time summary reported for each label or subproject ‘j’ is
computed as:

     Weighted Time Summary for Label/Subproject j =
         sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

     for labels/subprojects j=1...total

where:

   * ‘raw_test_time[j,i]’: Wall-clock time for the ‘i’ test for the ‘j’
     label or subproject

   * ‘num_processors[j,i]’: Value of the CTest PROCESSORS.
     property for the ‘i’ test for the ‘j’ label or subproject

   * ‘num_tests[j]’: Number of tests associated with the ‘j’ label or
     subproject

   * ‘total’: Total number of labels or subprojects that have at least
     one test run

Therefore, the weighted time summary for each label or subproject
represents the amount of time that CTest gave to run the tests for each
label or subproject and gives a good representation of the total expense
of the tests for each label or subproject when compared to other labels
or subprojects.

For example, if ‘SubprojectA’ showed ‘100 sec*proc’ and ‘SubprojectB’
showed ‘10 sec*proc’, then CTest allocated approximately 10 times the
CPU/core time to run the tests for ‘SubprojectA’ than for ‘SubprojectB’
(e.g.  so if effort is going to be expended to reduce the cost of the
test suite for the whole project, then reducing the cost of the test
suite for ‘SubprojectA’ would likely have a larger impact than effort to
reduce the cost of the test suite for ‘SubprojectB’).

2.5 Build and Test Mode
=======================

CTest provides a command-line signature to configure (i.e.  run cmake
on), build, and/or execute a test:

     ctest --build-and-test <path-to-source> <path-to-build>
           --build-generator <generator>
           [<options>...]
           [--build-options <opts>...]
           [--test-command <command> [<args>...]]

The configure and test steps are optional.  The arguments to this
command line are the source and binary directories.  The
‘--build-generator’ option `must' be provided to use ‘--build-and-test’.
If ‘--test-command’ is specified then that will be run after the build
is complete.  Other options that affect this mode include:

‘--build-target’

     Specify a specific target to build.

     If left out the ‘all’ target is built.

‘--build-nocmake’

     Run the build without running cmake first.

     Skip the cmake step.

‘--build-run-dir’

     Specify directory to run programs from.

     Directory where programs will be after it has been compiled.

‘--build-two-config’

     Run CMake twice.

‘--build-exe-dir’

     Specify the directory for the executable.

‘--build-generator’

     Specify the generator to use.  See the cmake-generators(7)
     manual.

‘--build-generator-platform’

     Specify the generator-specific platform.

‘--build-generator-toolset’

     Specify the generator-specific toolset.

‘--build-project’

     Specify the name of the project to build.

‘--build-makeprogram’

     Specify the explicit make program to be used by CMake when
     configuring and building the project.  Only applicable for Make and
     Ninja based generators.

‘--build-noclean’

     Skip the make clean step.

‘--build-config-sample’

     A sample executable to use to determine the configuration that
     should be used.  e.g.  ‘Debug’, ‘Release’ etc.

‘--build-options’

     Additional options for configuring the build (i.e.  for CMake, not
     for the build tool).  Note that if this is specified, the
     ‘--build-options’ keyword and its arguments must be the last option
     given on the command line, with the possible exception of
     ‘--test-command’.

‘--test-command’

     The command to run as the test step with the ‘--build-and-test’
     option.  All arguments following this keyword will be assumed to be
     part of the test command line, so it must be the last option given.

‘--test-timeout’

     The time limit in seconds

2.6 Dashboard Client
====================

CTest can operate as a client for the CDash(1) software quality
dashboard application.  As a dashboard client, CTest performs a sequence
of steps to configure, build, and test software, and then submits the
results to a CDash(2) server.  The command-line signature used to submit
to CDash(3) is:

     ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
           [-- <dashboard-options>...]

Options for Dashboard Client include:

‘--group <group>’

     Specify what group you’d like to submit results to

     Submit dashboard to specified group instead of default one.  By
     default, the dashboard is submitted to Nightly, Experimental, or
     Continuous group, but by specifying this option, the group can be
     arbitrary.

     This replaces the deprecated option ‘--track’.  Despite the name
     change its behavior is unchanged.

‘-A <file>, --add-notes <file>’

     Add a notes file with submission.

     This option tells CTest to include a notes file when submitting
     dashboard.

‘--tomorrow-tag’

     ‘Nightly’ or ‘Experimental’ starts with next day tag.

     This is useful if the build will not finish in one day.

‘--extra-submit <file>[;<file>]’

     Submit extra files to the dashboard.

     This option will submit extra files to the dashboard.

‘--http1.0’

     Submit using ‘HTTP 1.0’.

     This option will force CTest to use ‘HTTP 1.0’ to submit files to
     the dashboard, instead of ‘HTTP 1.1’.

‘--no-compress-output’

     Do not compress test output when submitting.

     This flag will turn off automatic compression of test output.  Use
     this to maintain compatibility with an older version of CDash which
     doesn’t support compressed test output.

   ---------- Footnotes ----------

   (1) http://cdash.org/

   (2) http://cdash.org/

   (3) http://cdash.org/

2.6.1 Dashboard Client Steps
----------------------------

CTest defines an ordered list of testing steps of which some or all may
be run as a dashboard client:

‘Start’

     Start a new dashboard submission to be composed of results recorded
     by the following steps.  See the CTest Start Step.
     section below.

‘Update’

     Update the source tree from its version control repository.  Record
     the old and new versions and the list of updated source files.  See
     the CTest Update Step section below.

‘Configure’

     Configure the software by running a command in the build tree.
     Record the configuration output log.  See the CTest Configure Step
     section below.

‘Build’

     Build the software by running a command in the build tree.  Record
     the build output log and detect warnings and errors.  See the
     CTest Build Step section below.

‘Test’

     Test the software by loading a ‘CTestTestfile.cmake’ from the build
     tree and executing the defined tests.  Record the output and result
     of each test.  See the CTest Test Step section below.

‘Coverage’

     Compute coverage of the source code by running a coverage analysis
     tool and recording its output.  See the CTest Coverage Step
     section below.

‘MemCheck’

     Run the software test suite through a memory check tool.  Record
     the test output, results, and issues reported by the tool.  See the
     CTest MemCheck Step section below.

‘Submit’

     Submit results recorded from other testing steps to the software
     quality dashboard server.  See the CTest Submit Step.
     section below.

2.6.2 Dashboard Client Modes
----------------------------

CTest defines three modes of operation as a dashboard client:

‘Nightly’

     This mode is intended to be invoked once per day, typically at
     night.  It enables the ‘Start’, ‘Update’, ‘Configure’, ‘Build’,
     ‘Test’, ‘Coverage’, and ‘Submit’ steps by default.  Selected steps
     run even if the ‘Update’ step reports no changes to the source
     tree.

‘Continuous’

     This mode is intended to be invoked repeatedly throughout the day.
     It enables the ‘Start’, ‘Update’, ‘Configure’, ‘Build’, ‘Test’,
     ‘Coverage’, and ‘Submit’ steps by default, but exits after the
     ‘Update’ step if it reports no changes to the source tree.

‘Experimental’

     This mode is intended to be invoked by a developer to test local
     changes.  It enables the ‘Start’, ‘Configure’, ‘Build’, ‘Test’,
     ‘Coverage’, and ‘Submit’ steps by default.

2.6.3 Dashboard Client via CTest Command-Line
---------------------------------------------

CTest can perform testing on an already-generated build tree.  Run the
‘ctest’ command with the current working directory set to the build tree
and use one of these signatures:

     ctest -D <mode>[<step>]
     ctest -M <mode> [ -T <step> ]...

The ‘<mode>’ must be one of the above Dashboard Client Modes,
and each ‘<step>’ must be one of the above Dashboard Client Steps.

CTest reads the Dashboard Client Configuration settings from
a file in the build tree called either ‘CTestConfiguration.ini’ or
‘DartConfiguration.tcl’ (the names are historical).  The format of the
file is:

     # Lines starting in '#' are comments.
     # Other non-blank lines are key-value pairs.
     <setting>: <value>

where ‘<setting>’ is the setting name and ‘<value>’ is the setting
value.

In build trees generated by CMake, this configuration file is generated
by the CTest module if included by the project.  The module
uses variables to obtain a value for each setting as documented with the
settings below.

2.6.4 Dashboard Client via CTest Script
---------------------------------------

CTest can perform testing driven by a cmake-language(7).
script that creates and maintains the source and build tree as well as
performing the testing steps.  Run the ‘ctest’ command with the current
working directory set outside of any build tree and use one of these
signatures:

     ctest -S <script>
     ctest -SP <script>

The ‘<script>’ file must call CTest Commands commands to run
testing steps explicitly as documented below.  The commands obtain
Dashboard Client Configuration settings from their arguments or
from variables set in the script.

2.7 Dashboard Client Configuration
==================================

The Dashboard Client Steps may be configured by named
settings as documented in the following sections.

2.7.1 CTest Start Step
----------------------

Start a new dashboard submission to be composed of results recorded by
the following steps.

In a CTest Script, the ctest_start() command runs
this step.  Arguments to the command may specify some of the step
settings.  The command first runs the command-line specified by the
‘CTEST_CHECKOUT_COMMAND’ variable, if set, to initialize the source
directory.

Configuration settings include:

‘BuildDirectory’

     The full path to the project build tree.

        * CTest Script variable:
          CTEST_BINARY_DIRECTORY.

        * CTest module variable: PROJECT_BINARY_DIR.

‘SourceDirectory’

     The full path to the project source tree.

        * CTest Script variable:
          CTEST_SOURCE_DIRECTORY.

        * CTest module variable: PROJECT_SOURCE_DIR.

2.7.2 CTest Update Step
-----------------------

In a CTest Script, the ctest_update() command runs
this step.  Arguments to the command may specify some of the step
settings.

Configuration settings to specify the version control tool include:

‘BZRCommand’

     ‘bzr’ command-line tool to use if source tree is managed by Bazaar.

        * CTest Script variable: CTEST_BZR_COMMAND.

        * CTest module variable: none

‘BZRUpdateOptions’

     Command-line options to the ‘BZRCommand’ when updating the source.

        * CTest Script variable:
          CTEST_BZR_UPDATE_OPTIONS.

        * CTest module variable: none

‘CVSCommand’

     ‘cvs’ command-line tool to use if source tree is managed by CVS.

        * CTest Script variable: CTEST_CVS_COMMAND.

        * CTest module variable: ‘CVSCOMMAND’

‘CVSUpdateOptions’

     Command-line options to the ‘CVSCommand’ when updating the source.

        * CTest Script variable:
          CTEST_CVS_UPDATE_OPTIONS.

        * CTest module variable: ‘CVS_UPDATE_OPTIONS’

‘GITCommand’

     ‘git’ command-line tool to use if source tree is managed by Git.

        * CTest Script variable: CTEST_GIT_COMMAND.

        * CTest module variable: ‘GITCOMMAND’

     The source tree is updated by ‘git fetch’ followed by ‘git reset
     --hard’ to the ‘FETCH_HEAD’.  The result is the same as ‘git pull’
     except that any local modifications are overwritten.  Use
     ‘GITUpdateCustom’ to specify a different approach.

‘GITInitSubmodules’

     If set, CTest will update the repository’s submodules before
     updating.

        * CTest Script variable:
          CTEST_GIT_INIT_SUBMODULES.

        * CTest module variable: ‘CTEST_GIT_INIT_SUBMODULES’

‘GITUpdateCustom’

     Specify a custom command line (as a semicolon-separated list) to
     run in the source tree (Git work tree) to update it instead of
     running the ‘GITCommand’.

        * CTest Script variable:
          CTEST_GIT_UPDATE_CUSTOM.

        * CTest module variable: ‘CTEST_GIT_UPDATE_CUSTOM’

‘GITUpdateOptions’

     Command-line options to the ‘GITCommand’ when updating the source.

        * CTest Script variable:
          CTEST_GIT_UPDATE_OPTIONS.

        * CTest module variable: ‘GIT_UPDATE_OPTIONS’

‘HGCommand’

     ‘hg’ command-line tool to use if source tree is managed by
     Mercurial.

        * CTest Script variable: CTEST_HG_COMMAND.

        * CTest module variable: none

‘HGUpdateOptions’

     Command-line options to the ‘HGCommand’ when updating the source.

        * CTest Script variable:
          CTEST_HG_UPDATE_OPTIONS.

        * CTest module variable: none

‘P4Client’

     Value of the ‘-c’ option to the ‘P4Command’.

        * CTest Script variable: CTEST_P4_CLIENT.

        * CTest module variable: ‘CTEST_P4_CLIENT’

‘P4Command’

     ‘p4’ command-line tool to use if source tree is managed by
     Perforce.

        * CTest Script variable: CTEST_P4_COMMAND.

        * CTest module variable: ‘P4COMMAND’

‘P4Options’

     Command-line options to the ‘P4Command’ for all invocations.

        * CTest Script variable: CTEST_P4_OPTIONS.

        * CTest module variable: ‘CTEST_P4_OPTIONS’

‘P4UpdateCustom’

     Specify a custom command line (as a semicolon-separated list) to
     run in the source tree (Perforce tree) to update it instead of
     running the ‘P4Command’.

        * CTest Script variable: none

        * CTest module variable: ‘CTEST_P4_UPDATE_CUSTOM’

‘P4UpdateOptions’

     Command-line options to the ‘P4Command’ when updating the source.

        * CTest Script variable:
          CTEST_P4_UPDATE_OPTIONS.

        * CTest module variable: ‘CTEST_P4_UPDATE_OPTIONS’

‘SVNCommand’

     ‘svn’ command-line tool to use if source tree is managed by
     Subversion.

        * CTest Script variable: CTEST_SVN_COMMAND.

        * CTest module variable: ‘SVNCOMMAND’

‘SVNOptions’

     Command-line options to the ‘SVNCommand’ for all invocations.

        * CTest Script variable: CTEST_SVN_OPTIONS.

        * CTest module variable: ‘CTEST_SVN_OPTIONS’

‘SVNUpdateOptions’

     Command-line options to the ‘SVNCommand’ when updating the source.

        * CTest Script variable:
          CTEST_SVN_UPDATE_OPTIONS.

        * CTest module variable: ‘SVN_UPDATE_OPTIONS’

‘UpdateCommand’

     Specify the version-control command-line tool to use without
     detecting the VCS that manages the source tree.

        * CTest Script variable: CTEST_UPDATE_COMMAND.

        * CTest module variable: ‘<VCS>COMMAND’ when
          ‘UPDATE_TYPE’ is ‘<vcs>’, else ‘UPDATE_COMMAND’

‘UpdateOptions’

     Command-line options to the ‘UpdateCommand’.

        * CTest Script variable: CTEST_UPDATE_OPTIONS.

        * CTest module variable: ‘<VCS>_UPDATE_OPTIONS’ when
          ‘UPDATE_TYPE’ is ‘<vcs>’, else ‘UPDATE_OPTIONS’

‘UpdateType’

     Specify the version-control system that manages the source tree if
     it cannot be detected automatically.  The value may be ‘bzr’,
     ‘cvs’, ‘git’, ‘hg’, ‘p4’, or ‘svn’.

        * CTest Script variable: none, detected from source
          tree

        * CTest module variable: ‘UPDATE_TYPE’ if set, else
          ‘CTEST_UPDATE_TYPE’

‘UpdateVersionOnly’

     Specify that you want the version control update command to only
     discover the current version that is checked out, and not to update
     to a different version.

        * CTest Script variable:
          CTEST_UPDATE_VERSION_ONLY.

‘UpdateVersionOverride’

     Specify the current version of your source tree.

     When this variable is set to a non-empty string, CTest will report
     the value you specified rather than using the update command to
     discover the current version that is checked out.  Use of this
     variable supersedes ‘UpdateVersionOnly’.  Like ‘UpdateVersionOnly’,
     using this variable tells CTest not to update the source tree to a
     different version.

        * CTest Script variable:
          CTEST_UPDATE_VERSION_OVERRIDE.

Additional configuration settings include:

‘NightlyStartTime’

     In the ‘Nightly’ dashboard mode, specify the “nightly start time”.
     With centralized version control systems (‘cvs’ and ‘svn’), the
     ‘Update’ step checks out the version of the software as of this
     time so that multiple clients choose a common version to test.
     This is not well-defined in distributed version-control systems so
     the setting is ignored.

        * CTest Script variable:
          CTEST_NIGHTLY_START_TIME.

        * CTest module variable: ‘NIGHTLY_START_TIME’ if set,
          else ‘CTEST_NIGHTLY_START_TIME’

2.7.3 CTest Configure Step
--------------------------

In a CTest Script, the ctest_configure() command
runs this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘ConfigureCommand’

     Command-line to launch the software configuration process.  It will
     be executed in the location specified by the ‘BuildDirectory’
     setting.

        * CTest Script variable:
          CTEST_CONFIGURE_COMMAND.

        * CTest module variable: CMAKE_COMMAND.
          followed by PROJECT_SOURCE_DIR.

‘LabelsForSubprojects’

     Specify a semicolon-separated list of labels that will be treated
     as subprojects.  This mapping will be passed on to CDash when
     configure, test or build results are submitted.

        * CTest Script variable:
          CTEST_LABELS_FOR_SUBPROJECTS.

        * CTest module variable:
          ‘CTEST_LABELS_FOR_SUBPROJECTS’

     See Label and Subproject Summary.

2.7.4 CTest Build Step
----------------------

In a CTest Script, the ctest_build() command runs
this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘DefaultCTestConfigurationType’

     When the build system to be launched allows build-time selection of
     the configuration (e.g.  ‘Debug’, ‘Release’), this specifies the
     default configuration to be built when no ‘-C’ option is given to
     the ‘ctest’ command.  The value will be substituted into the value
     of ‘MakeCommand’ to replace the literal string
     ‘${CTEST_CONFIGURATION_TYPE}’ if it appears.

        * CTest Script variable:
          CTEST_CONFIGURATION_TYPE.

        * CTest module variable:
          ‘DEFAULT_CTEST_CONFIGURATION_TYPE’, initialized by the
          CMAKE_CONFIG_TYPE environment variable

‘LabelsForSubprojects’

     Specify a semicolon-separated list of labels that will be treated
     as subprojects.  This mapping will be passed on to CDash when
     configure, test or build results are submitted.

        * CTest Script variable:
          CTEST_LABELS_FOR_SUBPROJECTS.

        * CTest module variable:
          ‘CTEST_LABELS_FOR_SUBPROJECTS’

     See Label and Subproject Summary.

‘MakeCommand’

     Command-line to launch the software build process.  It will be
     executed in the location specified by the ‘BuildDirectory’ setting.

        * CTest Script variable: CTEST_BUILD_COMMAND.

        * CTest module variable: ‘MAKECOMMAND’, initialized
          by the build_command() command

‘UseLaunchers’

     For build trees generated by CMake using one of the Makefile Generators
     or the Ninja generator, specify whether
     the ‘CTEST_USE_LAUNCHERS’ feature is enabled by the
     CTestUseLaunchers module (also included by the CTest
     module).  When enabled, the generated build system wraps each
     invocation of the compiler, linker, or custom command line with a
     “launcher” that communicates with CTest via environment variables
     and files to report granular build warning and error information.
     Otherwise, CTest must “scrape” the build output log for
     diagnostics.

        * CTest Script variable: CTEST_USE_LAUNCHERS.

        * CTest module variable: ‘CTEST_USE_LAUNCHERS’

2.7.5 CTest Test Step
---------------------

In a CTest Script, the ctest_test() command runs
this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘ResourceSpecFile’

     Specify a resource specification file.

        * CTest Script variable:
          CTEST_RESOURCE_SPEC_FILE.

        * CTest module variable: ‘CTEST_RESOURCE_SPEC_FILE’

     See Resource Allocation for more information.

‘LabelsForSubprojects’

     Specify a semicolon-separated list of labels that will be treated
     as subprojects.  This mapping will be passed on to CDash when
     configure, test or build results are submitted.

        * CTest Script variable:
          CTEST_LABELS_FOR_SUBPROJECTS.

        * CTest module variable:
          ‘CTEST_LABELS_FOR_SUBPROJECTS’

     See Label and Subproject Summary.

‘TestLoad’

     While running tests in parallel (e.g.  with ‘-j’), try not to start
     tests when they may cause the CPU load to pass above a given
     threshold.

        * CTest Script variable: CTEST_TEST_LOAD.

        * CTest module variable: ‘CTEST_TEST_LOAD’

‘TimeOut’

     The default timeout for each test if not specified by the
     TIMEOUT test property.

        * CTest Script variable: CTEST_TEST_TIMEOUT.

        * CTest module variable: ‘DART_TESTING_TIMEOUT’

2.7.6 CTest Coverage Step
-------------------------

In a CTest Script, the ctest_coverage() command
runs this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘CoverageCommand’

     Command-line tool to perform software coverage analysis.  It will
     be executed in the location specified by the ‘BuildDirectory’
     setting.

        * CTest Script variable:
          CTEST_COVERAGE_COMMAND.

        * CTest module variable: ‘COVERAGE_COMMAND’

‘CoverageExtraFlags’

     Specify command-line options to the ‘CoverageCommand’ tool.

        * CTest Script variable:
          CTEST_COVERAGE_EXTRA_FLAGS.

        * CTest module variable: ‘COVERAGE_EXTRA_FLAGS’

     These options are the first arguments passed to ‘CoverageCommand’.

2.7.7 CTest MemCheck Step
-------------------------

In a CTest Script, the ctest_memcheck() command
runs this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘MemoryCheckCommand’

     Command-line tool to perform dynamic analysis.  Test command lines
     will be launched through this tool.

        * CTest Script variable:
          CTEST_MEMORYCHECK_COMMAND.

        * CTest module variable: ‘MEMORYCHECK_COMMAND’

‘MemoryCheckCommandOptions’

     Specify command-line options to the ‘MemoryCheckCommand’ tool.
     They will be placed prior to the test command line.

        * CTest Script variable:
          CTEST_MEMORYCHECK_COMMAND_OPTIONS.

        * CTest module variable:
          ‘MEMORYCHECK_COMMAND_OPTIONS’

‘MemoryCheckType’

     Specify the type of memory checking to perform.

        * CTest Script variable:
          CTEST_MEMORYCHECK_TYPE.

        * CTest module variable: ‘MEMORYCHECK_TYPE’

‘MemoryCheckSanitizerOptions’

     Specify options to sanitizers when running with a sanitize-enabled
     build.

        * CTest Script variable:
          CTEST_MEMORYCHECK_SANITIZER_OPTIONS.

        * CTest module variable:
          ‘MEMORYCHECK_SANITIZER_OPTIONS’

‘MemoryCheckSuppressionFile’

     Specify a file containing suppression rules for the
     ‘MemoryCheckCommand’ tool.  It will be passed with options
     appropriate to the tool.

        * CTest Script variable:
          CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.

        * CTest module variable:
          ‘MEMORYCHECK_SUPPRESSIONS_FILE’

Additional configuration settings include:

‘BoundsCheckerCommand’

     Specify a ‘MemoryCheckCommand’ that is known to be command-line
     compatible with Bounds Checker.

        * CTest Script variable: none

        * CTest module variable: none

‘PurifyCommand’

     Specify a ‘MemoryCheckCommand’ that is known to be command-line
     compatible with Purify.

        * CTest Script variable: none

        * CTest module variable: ‘PURIFYCOMMAND’

‘ValgrindCommand’

     Specify a ‘MemoryCheckCommand’ that is known to be command-line
     compatible with Valgrind.

        * CTest Script variable: none

        * CTest module variable: ‘VALGRIND_COMMAND’

‘ValgrindCommandOptions’

     Specify command-line options to the ‘ValgrindCommand’ tool.  They
     will be placed prior to the test command line.

        * CTest Script variable: none

        * CTest module variable: ‘VALGRIND_COMMAND_OPTIONS’

‘DrMemoryCommand’

     Specify a ‘MemoryCheckCommand’ that is known to be a command-line
     compatible with DrMemory.

        * CTest Script variable: none

        * CTest module variable: ‘DRMEMORY_COMMAND’

‘DrMemoryCommandOptions’

     Specify command-line options to the ‘DrMemoryCommand’ tool.  They
     will be placed prior to the test command line.

        * CTest Script variable: none

        * CTest module variable: ‘DRMEMORY_COMMAND_OPTIONS’

‘CudaSanitizerCommand’

     Specify a ‘MemoryCheckCommand’ that is known to be a command-line
     compatible with cuda-memcheck or compute-sanitizer.

        * CTest Script variable: none

        * CTest module variable: ‘CUDA_SANITIZER_COMMAND’

‘CudaSanitizerCommandOptions’

     Specify command-line options to the ‘CudaSanitizerCommand’ tool.
     They will be placed prior to the test command line.

        * CTest Script variable: none

        * CTest module variable:
          ‘CUDA_SANITIZER_COMMAND_OPTIONS’

2.7.8 CTest Submit Step
-----------------------

In a CTest Script, the ctest_submit() command runs
this step.  Arguments to the command may specify some of the step
settings.

Configuration settings include:

‘BuildName’

     Describe the dashboard client platform with a short string.
     (Operating system, compiler, etc.)

        * CTest Script variable: CTEST_BUILD_NAME.

        * CTest module variable: ‘BUILDNAME’

‘CDashVersion’

     Legacy option.  Not used.

        * CTest Script variable: none, detected from server

        * CTest module variable: ‘CTEST_CDASH_VERSION’

‘CTestSubmitRetryCount’

     Specify a number of attempts to retry submission on network
     failure.

        * CTest Script variable: none, use the
          ctest_submit(). ‘RETRY_COUNT’ option.

        * CTest module variable: ‘CTEST_SUBMIT_RETRY_COUNT’

‘CTestSubmitRetryDelay’

     Specify a delay before retrying submission on network failure.

        * CTest Script variable: none, use the
          ctest_submit(). ‘RETRY_DELAY’ option.

        * CTest module variable: ‘CTEST_SUBMIT_RETRY_DELAY’

‘CurlOptions’

     Specify a semicolon-separated list of options to control the Curl
     library that CTest uses internally to connect to the server.
     Possible options are ‘CURLOPT_SSL_VERIFYPEER_OFF’ and
     ‘CURLOPT_SSL_VERIFYHOST_OFF’.

        * CTest Script variable: CTEST_CURL_OPTIONS.

        * CTest module variable: ‘CTEST_CURL_OPTIONS’

‘DropLocation’

     Legacy option.  When ‘SubmitURL’ is not set, it is constructed from
     ‘DropMethod’, ‘DropSiteUser’, ‘DropSitePassword’, ‘DropSite’, and
     ‘DropLocation’.

        * CTest Script variable: CTEST_DROP_LOCATION.

        * CTest module variable: ‘DROP_LOCATION’ if set, else
          ‘CTEST_DROP_LOCATION’

‘DropMethod’

     Legacy option.  When ‘SubmitURL’ is not set, it is constructed from
     ‘DropMethod’, ‘DropSiteUser’, ‘DropSitePassword’, ‘DropSite’, and
     ‘DropLocation’.

        * CTest Script variable: CTEST_DROP_METHOD.

        * CTest module variable: ‘DROP_METHOD’ if set, else
          ‘CTEST_DROP_METHOD’

‘DropSite’

     Legacy option.  When ‘SubmitURL’ is not set, it is constructed from
     ‘DropMethod’, ‘DropSiteUser’, ‘DropSitePassword’, ‘DropSite’, and
     ‘DropLocation’.

        * CTest Script variable: CTEST_DROP_SITE.

        * CTest module variable: ‘DROP_SITE’ if set, else
          ‘CTEST_DROP_SITE’

‘DropSitePassword’

     Legacy option.  When ‘SubmitURL’ is not set, it is constructed from
     ‘DropMethod’, ‘DropSiteUser’, ‘DropSitePassword’, ‘DropSite’, and
     ‘DropLocation’.

        * CTest Script variable:
          CTEST_DROP_SITE_PASSWORD.

        * CTest module variable: ‘DROP_SITE_PASSWORD’ if set,
          else ‘CTEST_DROP_SITE_PASWORD’

‘DropSiteUser’

     Legacy option.  When ‘SubmitURL’ is not set, it is constructed from
     ‘DropMethod’, ‘DropSiteUser’, ‘DropSitePassword’, ‘DropSite’, and
     ‘DropLocation’.

        * CTest Script variable: CTEST_DROP_SITE_USER.

        * CTest module variable: ‘DROP_SITE_USER’ if set,
          else ‘CTEST_DROP_SITE_USER’

‘IsCDash’

     Legacy option.  Not used.

        * CTest Script variable: CTEST_DROP_SITE_CDASH.

        * CTest module variable: ‘CTEST_DROP_SITE_CDASH’

‘ScpCommand’

     Legacy option.  Not used.

        * CTest Script variable: CTEST_SCP_COMMAND.

        * CTest module variable: ‘SCPCOMMAND’

‘Site’

     Describe the dashboard client host site with a short string.
     (Hostname, domain, etc.)

        * CTest Script variable: CTEST_SITE.

        * CTest module variable: ‘SITE’, initialized by the
          site_name() command

‘SubmitURL’

     The ‘http’ or ‘https’ URL of the dashboard server to send the
     submission to.

        * CTest Script variable: CTEST_SUBMIT_URL.

        * CTest module variable: ‘SUBMIT_URL’ if set, else
          ‘CTEST_SUBMIT_URL’

‘TriggerSite’

     Legacy option.  Not used.

        * CTest Script variable: CTEST_TRIGGER_SITE.

        * CTest module variable: ‘TRIGGER_SITE’ if set, else
          ‘CTEST_TRIGGER_SITE’

2.8 Show as JSON Object Model
=============================

When the ‘--show-only=json-v1’ command line option is given, the test
information is output in JSON format.  Version 1.0 of the JSON object
model is defined as follows:

‘kind’

     The string “ctestInfo”.

‘version’

     A JSON object specifying the version components.  Its members are

     ‘major’

          A non-negative integer specifying the major version component.

     ‘minor’

          A non-negative integer specifying the minor version component.

‘backtraceGraph’

     JSON object representing backtrace information with the following
     members:

     ‘commands’

          List of command names.

     ‘files’

          List of file names.

     ‘nodes’

          List of node JSON objects with members:

          ‘command’

               Index into the ‘commands’ member of the ‘backtraceGraph’.

          ‘file’

               Index into the ‘files’ member of the ‘backtraceGraph’.

          ‘line’

               Line number in the file where the backtrace was added.

          ‘parent’

               Index into the ‘nodes’ member of the ‘backtraceGraph’
               representing the parent in the graph.

‘tests’

     A JSON array listing information about each test.  Each entry is a
     JSON object with members:

     ‘name’

          Test name.

     ‘config’

          Configuration that the test can run on.  Empty string means
          any config.

     ‘command’

          List where the first element is the test command and the
          remaining elements are the command arguments.

     ‘backtrace’

          Index into the ‘nodes’ member of the ‘backtraceGraph’.

     ‘properties’

          Test properties.  Can contain keys for each of the supported
          test properties.

2.9 Resource Allocation
=======================

CTest provides a mechanism for tests to specify the resources that they
need in a fine-grained way, and for users to specify the resources
available on the running machine.  This allows CTest to internally keep
track of which resources are in use and which are free, scheduling tests
in a way that prevents them from trying to claim resources that are not
available.

When the resource allocation feature is used, CTest will not
oversubscribe resources.  For example, if a resource has 8 slots, CTest
will not run tests that collectively use more than 8 slots at a time.
This has the effect of limiting how many tests can run at any given
time, even if a high ‘-j’ argument is used, if those tests all use some
slots from the same resource.  In addition, it means that a single test
that uses more of a resource than is available on a machine will not run
at all (and will be reported as ‘Not Run’).

A common use case for this feature is for tests that require the use of
a GPU. Multiple tests can simultaneously allocate memory from a GPU, but
if too many tests try to do this at once, some of them will fail to
allocate, resulting in a failed test, even though the test would have
succeeded if it had the memory it needed.  By using the resource
allocation feature, each test can specify how much memory it requires
from a GPU, allowing CTest to schedule tests in a way that running
several of these tests at once does not exhaust the GPU’s memory pool.

Please note that CTest has no concept of what a GPU is or how much
memory it has, nor does it have any way of communicating with a GPU to
retrieve this information or perform any memory management.  CTest
simply keeps track of a list of abstract resource types, each of which
has a certain number of slots available for tests to use.  Each test
specifies the number of slots that it requires from a certain resource,
and CTest then schedules them in a way that prevents the total number of
slots in use from exceeding the listed capacity.  When a test is
executed, and slots from a resource are allocated to that test, tests
may assume that they have exclusive use of those slots for the duration
of the test’s process.

The CTest resource allocation feature consists of two inputs:

   * The resource specification file, described below, which
     describes the resources available on the system.

   * The RESOURCE_GROUPS property of tests, which describes
     the resources required by the test.

When CTest runs a test, the resources allocated to that test are passed
in the form of a set of environment variables as described
below.  Using this information to decide which resource to connect to is
left to the test writer.

The ‘RESOURCE_GROUPS’ property tells CTest what resources a test expects
to use grouped in a way meaningful to the test.  The test itself must
read the environment variables to determine which resources
have been allocated to each group.  For example, each group may
correspond to a process the test will spawn when executed.

Note that even if a test specifies a ‘RESOURCE_GROUPS’ property, it is
still possible for that to test to run without any resource allocation
(and without the corresponding environment variables) if the
user does not pass a resource specification file.  Passing this file,
either through the ‘--resource-spec-file’ command-line argument or the
‘RESOURCE_SPEC_FILE’ argument to ctest_test(), is what
activates the resource allocation feature.  Tests should check the
‘CTEST_RESOURCE_GROUP_COUNT’ environment variable to find out whether or
not resource allocation is activated.  This variable will always (and
only) be defined if resource allocation is activated.  If resource
allocation is not activated, then the ‘CTEST_RESOURCE_GROUP_COUNT’
variable will not exist, even if it exists for the parent ‘ctest’
process.  If a test absolutely must have resource allocation, then it
can return a failing exit code or use the SKIP_RETURN_CODE or
SKIP_REGULAR_EXPRESSION properties to indicate a skipped
test.

2.9.1 Resource Specification File
---------------------------------

The resource specification file is a JSON file which is passed to CTest,
either on the ctest(1) command line as
‘--resource-spec-file’, or as the ‘RESOURCE_SPEC_FILE’ argument of
ctest_test().  If a dashboard script is used and
‘RESOURCE_SPEC_FILE’ is not specified, the value of
CTEST_RESOURCE_SPEC_FILE in the dashboard script is used instead.
If ‘--resource-spec-file’, ‘RESOURCE_SPEC_FILE’, and
CTEST_RESOURCE_SPEC_FILE in the dashboard script are not specified,
the value of CTEST_RESOURCE_SPEC_FILE in the CMake build is
used instead.  If none of these are specified, no resource spec file is
used.

The resource specification file must be a JSON object.  All examples in
this document assume the following resource specification file:

     {
       "version": {
         "major": 1,
         "minor": 0
       },
       "local": [
         {
           "gpus": [
             {
               "id": "0",
               "slots": 2
             },
             {
               "id": "1",
               "slots": 4
             },
             {
               "id": "2",
               "slots": 2
             },
             {
               "id": "3"
             }
           ],
           "crypto_chips": [
             {
               "id": "card0",
               "slots": 4
             }
           ]
         }
       ]
     }

The members are:

‘version’

     An object containing a ‘major’ integer field and a ‘minor’ integer
     field.  Currently, the only supported version is major ‘1’, minor
     ‘0’.  Any other value is an error.

‘local’

     A JSON array of resource sets present on the system.  Currently,
     this array is restricted to being of size 1.

     Each array element is a JSON object with members whose names are
     equal to the desired resource types, such as ‘gpus’.  These names
     must start with a lowercase letter or an underscore, and subsequent
     characters can be a lowercase letter, a digit, or an underscore.
     Uppercase letters are not allowed, because certain platforms have
     case-insensitive environment variables.  See the Environment Variables
     section below for more information.  It is
     recommended that the resource type name be the plural of a noun,
     such as ‘gpus’ or ‘crypto_chips’ (and not ‘gpu’ or ‘crypto_chip’.)

     Please note that the names ‘gpus’ and ‘crypto_chips’ are just
     examples, and CTest does not interpret them in any way.  You are
     free to make up any resource type you want to meet your own
     requirements.

     The value for each resource type is a JSON array consisting of JSON
     objects, each of which describe a specific instance of the
     specified resource.  These objects have the following members:

     ‘id’

          A string consisting of an identifier for the resource.  Each
          character in the identifier can be a lowercase letter, a
          digit, or an underscore.  Uppercase letters are not allowed.

          Identifiers must be unique within a resource type.  However,
          they do not have to be unique across resource types.  For
          example, it is valid to have a ‘gpus’ resource named ‘0’ and a
          ‘crypto_chips’ resource named ‘0’, but not two ‘gpus’
          resources both named ‘0’.

          Please note that the IDs ‘0’, ‘1’, ‘2’, ‘3’, and ‘card0’ are
          just examples, and CTest does not interpret them in any way.
          You are free to make up any IDs you want to meet your own
          requirements.

     ‘slots’

          An optional unsigned number specifying the number of slots
          available on the resource.  For example, this could be
          megabytes of RAM on a GPU, or cryptography units available on
          a cryptography chip.  If ‘slots’ is not specified, a default
          value of ‘1’ is assumed.

In the example file above, there are four GPUs with ID’s 0 through 3.
GPU 0 has 2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of
1 slot.  There is also one cryptography chip with 4 slots.

2.9.2 ‘RESOURCE_GROUPS’ Property
--------------------------------

See RESOURCE_GROUPS for a description of this property.

2.9.3 Environment Variables
---------------------------

Once CTest has decided which resources to allocate to a test, it passes
this information to the test executable as a series of environment
variables.  For each example below, we will assume that the test in
question has a RESOURCE_GROUPS property of
‘2,gpus:2;gpus:4,gpus:1,crypto_chips:2’.

The following variables are passed to the test process:

 -- Envvar: CTEST_RESOURCE_GROUP_COUNT

     The total number of groups specified by the RESOURCE_GROUPS
     property.  For example:

        * ‘CTEST_RESOURCE_GROUP_COUNT=3’

     This variable will only be defined if ctest(1) has been
     given a ‘--resource-spec-file’, or if ctest_test() has
     been given a ‘RESOURCE_SPEC_FILE’.  If no resource specification
     file has been given, this variable will not be defined.

 -- Envvar: CTEST_RESOURCE_GROUP_<num>

     The list of resource types allocated to each group, with each item
     separated by a comma.  ‘<num>’ is a number from zero to
     ‘CTEST_RESOURCE_GROUP_COUNT’ minus one.
     ‘CTEST_RESOURCE_GROUP_<num>’ is defined for each ‘<num>’ in this
     range.  For example:

        * ‘CTEST_RESOURCE_GROUP_0=gpus’

        * ‘CTEST_RESOURCE_GROUP_1=gpus’

        * ‘CTEST_RESOURCE_GROUP_2=crypto_chips,gpus’

 -- Envvar: CTEST_RESOURCE_GROUP_<num>_<resource-type>

     The list of resource IDs and number of slots from each ID allocated
     to each group for a given resource type.  This variable consists of
     a series of pairs, each pair separated by a semicolon, and with the
     two items in the pair separated by a comma.  The first item in each
     pair is ‘id:’ followed by the ID of a resource of type
     ‘<resource-type>’, and the second item is ‘slots:’ followed by the
     number of slots from that resource allocated to the given group.
     For example:

        * ‘CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2’

        * ‘CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2’

        * ‘CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1’

        * ‘CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2’

     In this example, group 0 gets 2 slots from GPU ‘0’, group 1 gets 2
     slots from GPU ‘2’, and group 2 gets 4 slots from GPU ‘1’, 1 slot
     from GPU ‘3’, and 2 slots from cryptography chip ‘card0’.

     ‘<num>’ is a number from zero to ‘CTEST_RESOURCE_GROUP_COUNT’ minus
     one.  ‘<resource-type>’ is the name of a resource type, converted
     to uppercase.  ‘CTEST_RESOURCE_GROUP_<num>_<resource-type>’ is
     defined for the product of each ‘<num>’ in the range listed above
     and each resource type listed in ‘CTEST_RESOURCE_GROUP_<num>’.

     Because some platforms have case-insensitive names for environment
     variables, the names of resource types may not clash in a
     case-insensitive environment.  Because of this, for the sake of
     simplicity, all resource types must be listed in all lowercase in
     the resource specification file and in the
     RESOURCE_GROUPS property, and they are converted to all
     uppercase in the ‘CTEST_RESOURCE_GROUP_<num>_<resource-type>’
     environment variable.

2.10 See Also
=============

The following resources are available to get help using CMake:

Home Page

     ‘https://cmake.org’

     The primary starting point for learning about CMake.

Online Documentation and Community Resources

     ‘https://cmake.org/documentation’

     Links to available documentation and community resources may be
     found on this web page.

Discourse Forum

     ‘https://discourse.cmake.org’

     The Discourse Forum hosts discussion and questions about CMake.

3 cpack(1)
**********

3.1 Synopsis
============

     cpack [<options>]

3.2 Description
===============

The `cpack' executable is the CMake packaging program.  It generates
installers and source packages in a variety of formats.

For each installer or package format, `cpack' has a specific backend,
called “generator”.  A generator is responsible for generating the
required inputs and invoking the specific package creation tools.  These
installer or package generators are not to be confused with the makefile
generators of the cmake command.

All supported generators are specified in the cpack-generators
manual.  The command ‘cpack --help’ prints a list of generators
supported for the target platform.  Which of them are to be used can be
selected through the CPACK_GENERATOR variable or through the
command-line option ‘-G’.

The `cpack' program is steered by a configuration file written in the
CMake language.  Unless chosen differently through the
command-line option ‘--config’, the file ‘CPackConfig.cmake’ in the
current directory is used.

In the standard CMake workflow, the file ‘CPackConfig.cmake’ is
generated by the cmake executable, provided the CPack
module is included by the project’s ‘CMakeLists.txt’ file.

3.3 Options
===========

‘-G <generators>’

     ‘<generators>’ is a semicolon-separated list of
     generator names.  ‘cpack’ will iterate through this list and
     produce package(s) in that generator’s format according to the
     details provided in the ‘CPackConfig.cmake’ configuration file.  If
     this option is not given, the CPACK_GENERATOR variable
     determines the default set of generators that will be used.

‘-C <configs>’

     Specify the project configuration(s) to be packaged (e.g.  ‘Debug’,
     ‘Release’, etc.), where ‘<configs>’ is a semicolon-separated list.
     When the CMake project uses a multi-configuration
     generator such as Xcode or Visual Studio, this option is needed to
     tell ‘cpack’ which built executables to include in the package.
     The user is responsible for ensuring that the configuration(s)
     listed have already been built before invoking ‘cpack’.

‘-D <var>=<value>’

     Set a CPack variable.  This will override any value set for ‘<var>’
     in the input file read by ‘cpack’.

‘--config <configFile>’

     Specify the configuration file read by ‘cpack’ to provide the
     packaging details.  By default, ‘CPackConfig.cmake’ in the current
     directory will be used.

‘--verbose, -V’

     Run ‘cpack’ with verbose output.  This can be used to show more
     details from the package generation tools and is suitable for
     project developers.

‘--debug’

     Run ‘cpack’ with debug output.  This option is intended mainly for
     the developers of ‘cpack’ itself and is not normally needed by
     project developers.

‘--trace’

     Put the underlying cmake scripts in trace mode.

‘--trace-expand’

     Put the underlying cmake scripts in expanded trace mode.

‘-P <packageName>’

     Override/define the value of the CPACK_PACKAGE_NAME.
     variable used for packaging.  Any value set for this variable in
     the ‘CPackConfig.cmake’ file will then be ignored.

‘-R <packageVersion>’

     Override/define the value of the CPACK_PACKAGE_VERSION.
     variable used for packaging.  It will override a value set in the
     ‘CPackConfig.cmake’ file or one automatically computed from
     CPACK_PACKAGE_VERSION_MAJOR, CPACK_PACKAGE_VERSION_MINOR
     and CPACK_PACKAGE_VERSION_PATCH.

‘-B <packageDirectory>’

     Override/define CPACK_PACKAGE_DIRECTORY, which controls
     the directory where CPack will perform its packaging work.  The
     resultant package(s) will be created at this location by default
     and a ‘_CPack_Packages’ subdirectory will also be created below
     this directory to use as a working area during package creation.

‘--vendor <vendorName>’

     Override/define CPACK_PACKAGE_VENDOR.

‘--help,-help,-usage,-h,-H,/?’

     Print usage information and exit.

     Usage describes the basic command line interface and its options.

‘--version,-version,/V [<f>]’

     Show program name/version banner and exit.

     If a file is specified, the version is written into it.  The help
     is printed to a named <f>ile if given.

‘--help-full [<f>]’

     Print all help manuals and exit.

     All manuals are printed in a human-readable text format.  The help
     is printed to a named <f>ile if given.

‘--help-manual <man> [<f>]’

     Print one help manual and exit.

     The specified manual is printed in a human-readable text format.
     The help is printed to a named <f>ile if given.

‘--help-manual-list [<f>]’

     List help manuals available and exit.

     The list contains all manuals for which help may be obtained by
     using the ‘--help-manual’ option followed by a manual name.  The
     help is printed to a named <f>ile if given.

‘--help-command <cmd> [<f>]’

     Print help for one command and exit.

     The cmake-commands(7) manual entry for ‘<cmd>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-command-list [<f>]’

     List commands with help available and exit.

     The list contains all commands for which help may be obtained by
     using the ‘--help-command’ option followed by a command name.  The
     help is printed to a named <f>ile if given.

‘--help-commands [<f>]’

     Print cmake-commands manual and exit.

     The cmake-commands(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-module <mod> [<f>]’

     Print help for one module and exit.

     The cmake-modules(7) manual entry for ‘<mod>’ is printed
     in a human-readable text format.  The help is printed to a named
     <f>ile if given.

‘--help-module-list [<f>]’

     List modules with help available and exit.

     The list contains all modules for which help may be obtained by
     using the ‘--help-module’ option followed by a module name.  The
     help is printed to a named <f>ile if given.

‘--help-modules [<f>]’

     Print cmake-modules manual and exit.

     The cmake-modules(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-policy <cmp> [<f>]’

     Print help for one policy and exit.

     The cmake-policies(7) manual entry for ‘<cmp>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-policy-list [<f>]’

     List policies with help available and exit.

     The list contains all policies for which help may be obtained by
     using the ‘--help-policy’ option followed by a policy name.  The
     help is printed to a named <f>ile if given.

‘--help-policies [<f>]’

     Print cmake-policies manual and exit.

     The cmake-policies(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-property <prop> [<f>]’

     Print help for one property and exit.

     The cmake-properties(7) manual entries for ‘<prop>’ are
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-property-list [<f>]’

     List properties with help available and exit.

     The list contains all properties for which help may be obtained by
     using the ‘--help-property’ option followed by a property name.
     The help is printed to a named <f>ile if given.

‘--help-properties [<f>]’

     Print cmake-properties manual and exit.

     The cmake-properties(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-variable <var> [<f>]’

     Print help for one variable and exit.

     The cmake-variables(7) manual entry for ‘<var>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-variable-list [<f>]’

     List variables with help available and exit.

     The list contains all variables for which help may be obtained by
     using the ‘--help-variable’ option followed by a variable name.
     The help is printed to a named <f>ile if given.

‘--help-variables [<f>]’

     Print cmake-variables manual and exit.

     The cmake-variables(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

3.4 See Also
============

The following resources are available to get help using CMake:

Home Page

     ‘https://cmake.org’

     The primary starting point for learning about CMake.

Online Documentation and Community Resources

     ‘https://cmake.org/documentation’

     Links to available documentation and community resources may be
     found on this web page.

Discourse Forum

     ‘https://discourse.cmake.org’

     The Discourse Forum hosts discussion and questions about CMake.

Interactive Dialogs
*******************

4 cmake-gui(1)
**************

4.1 Synopsis
============

     cmake-gui [<options>]
     cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>}
     cmake-gui [<options>] -S <path-to-source> -B <path-to-build>
     cmake-gui [<options>] --browse-manual

4.2 Description
===============

The `cmake-gui' executable is the CMake GUI. Project configuration
settings may be specified interactively.  Brief instructions are
provided at the bottom of the window when the program is running.

CMake is a cross-platform build system generator.  Projects specify
their build process with platform-independent CMake listfiles included
in each directory of a source tree with the name ‘CMakeLists.txt’.
Users build a project by using CMake to generate a build system for a
native tool on their platform.

4.3 Options
===========

‘-S <path-to-source>’

     Path to root directory of the CMake project to build.

‘-B <path-to-build>’

     Path to directory which CMake will use as the root of build
     directory.

     If the directory doesn’t already exist CMake will make it.

‘--preset=<preset-name>’

     Name of the preset to use from the project’s presets.
     files, if it has them.

‘--browse-manual’

     Open the CMake reference manual in a browser and immediately exit.

‘--help,-help,-usage,-h,-H,/?’

     Print usage information and exit.

     Usage describes the basic command line interface and its options.

‘--version,-version,/V [<f>]’

     Show program name/version banner and exit.

     If a file is specified, the version is written into it.  The help
     is printed to a named <f>ile if given.

‘--help-full [<f>]’

     Print all help manuals and exit.

     All manuals are printed in a human-readable text format.  The help
     is printed to a named <f>ile if given.

‘--help-manual <man> [<f>]’

     Print one help manual and exit.

     The specified manual is printed in a human-readable text format.
     The help is printed to a named <f>ile if given.

‘--help-manual-list [<f>]’

     List help manuals available and exit.

     The list contains all manuals for which help may be obtained by
     using the ‘--help-manual’ option followed by a manual name.  The
     help is printed to a named <f>ile if given.

‘--help-command <cmd> [<f>]’

     Print help for one command and exit.

     The cmake-commands(7) manual entry for ‘<cmd>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-command-list [<f>]’

     List commands with help available and exit.

     The list contains all commands for which help may be obtained by
     using the ‘--help-command’ option followed by a command name.  The
     help is printed to a named <f>ile if given.

‘--help-commands [<f>]’

     Print cmake-commands manual and exit.

     The cmake-commands(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-module <mod> [<f>]’

     Print help for one module and exit.

     The cmake-modules(7) manual entry for ‘<mod>’ is printed
     in a human-readable text format.  The help is printed to a named
     <f>ile if given.

‘--help-module-list [<f>]’

     List modules with help available and exit.

     The list contains all modules for which help may be obtained by
     using the ‘--help-module’ option followed by a module name.  The
     help is printed to a named <f>ile if given.

‘--help-modules [<f>]’

     Print cmake-modules manual and exit.

     The cmake-modules(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-policy <cmp> [<f>]’

     Print help for one policy and exit.

     The cmake-policies(7) manual entry for ‘<cmp>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-policy-list [<f>]’

     List policies with help available and exit.

     The list contains all policies for which help may be obtained by
     using the ‘--help-policy’ option followed by a policy name.  The
     help is printed to a named <f>ile if given.

‘--help-policies [<f>]’

     Print cmake-policies manual and exit.

     The cmake-policies(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-property <prop> [<f>]’

     Print help for one property and exit.

     The cmake-properties(7) manual entries for ‘<prop>’ are
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-property-list [<f>]’

     List properties with help available and exit.

     The list contains all properties for which help may be obtained by
     using the ‘--help-property’ option followed by a property name.
     The help is printed to a named <f>ile if given.

‘--help-properties [<f>]’

     Print cmake-properties manual and exit.

     The cmake-properties(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-variable <var> [<f>]’

     Print help for one variable and exit.

     The cmake-variables(7) manual entry for ‘<var>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-variable-list [<f>]’

     List variables with help available and exit.

     The list contains all variables for which help may be obtained by
     using the ‘--help-variable’ option followed by a variable name.
     The help is printed to a named <f>ile if given.

‘--help-variables [<f>]’

     Print cmake-variables manual and exit.

     The cmake-variables(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

4.4 See Also
============

The following resources are available to get help using CMake:

Home Page

     ‘https://cmake.org’

     The primary starting point for learning about CMake.

Online Documentation and Community Resources

     ‘https://cmake.org/documentation’

     Links to available documentation and community resources may be
     found on this web page.

Discourse Forum

     ‘https://discourse.cmake.org’

     The Discourse Forum hosts discussion and questions about CMake.

5 ccmake(1)
***********

5.1 Synopsis
============

     ccmake [<options>] {<path-to-source> | <path-to-existing-build>}

5.2 Description
===============

The `ccmake' executable is the CMake curses interface.  Project
configuration settings may be specified interactively through this GUI.
Brief instructions are provided at the bottom of the terminal when the
program is running.

CMake is a cross-platform build system generator.  Projects specify
their build process with platform-independent CMake listfiles included
in each directory of a source tree with the name ‘CMakeLists.txt’.
Users build a project by using CMake to generate a build system for a
native tool on their platform.

5.3 Options
===========

‘-S <path-to-source>’

     Path to root directory of the CMake project to build.

‘-B <path-to-build>’

     Path to directory which CMake will use as the root of build
     directory.

     If the directory doesn’t already exist CMake will make it.

‘-C <initial-cache>’

     Pre-load a script to populate the cache.

     When CMake is first run in an empty build tree, it creates a
     ‘CMakeCache.txt’ file and populates it with customizable settings
     for the project.  This option may be used to specify a file from
     which to load cache entries before the first pass through the
     project’s CMake listfiles.  The loaded entries take priority over
     the project’s default values.  The given file should be a CMake
     script containing set() commands that use the ‘CACHE’
     option, not a cache-format file.

     References to CMAKE_SOURCE_DIR and
     CMAKE_BINARY_DIR within the script evaluate to the top-level
     source and build tree.

‘-D <var>:<type>=<value>, -D <var>=<value>’

     Create or update a CMake ‘CACHE’ entry.

     When CMake is first run in an empty build tree, it creates a
     ‘CMakeCache.txt’ file and populates it with customizable settings
     for the project.  This option may be used to specify a setting that
     takes priority over the project’s default value.  The option may be
     repeated for as many ‘CACHE’ entries as desired.

     If the ‘:<type>’ portion is given it must be one of the types
     specified by the set() command documentation for its
     ‘CACHE’ signature.  If the ‘:<type>’ portion is omitted the entry
     will be created with no type if it does not exist with a type
     already.  If a command in the project sets the type to ‘PATH’ or
     ‘FILEPATH’ then the ‘<value>’ will be converted to an absolute
     path.

     This option may also be given as a single argument:
     ‘-D<var>:<type>=<value>’ or ‘-D<var>=<value>’.

‘-U <globbing_expr>’

     Remove matching entries from CMake ‘CACHE’.

     This option may be used to remove one or more variables from the
     ‘CMakeCache.txt’ file, globbing expressions using ‘*’ and ‘?’ are
     supported.  The option may be repeated for as many ‘CACHE’ entries
     as desired.

     Use with care, you can make your ‘CMakeCache.txt’ non-working.

‘-G <generator-name>’

     Specify a build system generator.

     CMake may support multiple native build systems on certain
     platforms.  A generator is responsible for generating a particular
     build system.  Possible generator names are specified in the
     cmake-generators(7) manual.

     If not specified, CMake checks the CMAKE_GENERATOR.
     environment variable and otherwise falls back to a builtin default
     selection.

‘-T <toolset-spec>’

     Toolset specification for the generator, if supported.

     Some CMake generators support a toolset specification to tell the
     native build system how to choose a compiler.  See the
     CMAKE_GENERATOR_TOOLSET variable for details.

‘-A <platform-name>’

     Specify platform name if supported by generator.

     Some CMake generators support a platform name to be given to the
     native build system to choose a compiler or SDK. See the
     CMAKE_GENERATOR_PLATFORM variable for details.

‘-Wno-dev’

     Suppress developer warnings.

     Suppress warnings that are meant for the author of the
     ‘CMakeLists.txt’ files.  By default this will also turn off
     deprecation warnings.

‘-Wdev’

     Enable developer warnings.

     Enable warnings that are meant for the author of the
     ‘CMakeLists.txt’ files.  By default this will also turn on
     deprecation warnings.

‘-Werror=dev’

     Make developer warnings errors.

     Make warnings that are meant for the author of the ‘CMakeLists.txt’
     files errors.  By default this will also turn on deprecated
     warnings as errors.

‘-Wno-error=dev’

     Make developer warnings not errors.

     Make warnings that are meant for the author of the ‘CMakeLists.txt’
     files not errors.  By default this will also turn off deprecated
     warnings as errors.

‘-Wdeprecated’

     Enable deprecated functionality warnings.

     Enable warnings for usage of deprecated functionality, that are
     meant for the author of the ‘CMakeLists.txt’ files.

‘-Wno-deprecated’

     Suppress deprecated functionality warnings.

     Suppress warnings for usage of deprecated functionality, that are
     meant for the author of the ‘CMakeLists.txt’ files.

‘-Werror=deprecated’

     Make deprecated macro and function warnings errors.

     Make warnings for usage of deprecated macros and functions, that
     are meant for the author of the ‘CMakeLists.txt’ files, errors.

‘-Wno-error=deprecated’

     Make deprecated macro and function warnings not errors.

     Make warnings for usage of deprecated macros and functions, that
     are meant for the author of the ‘CMakeLists.txt’ files, not errors.

‘--help,-help,-usage,-h,-H,/?’

     Print usage information and exit.

     Usage describes the basic command line interface and its options.

‘--version,-version,/V [<f>]’

     Show program name/version banner and exit.

     If a file is specified, the version is written into it.  The help
     is printed to a named <f>ile if given.

‘--help-full [<f>]’

     Print all help manuals and exit.

     All manuals are printed in a human-readable text format.  The help
     is printed to a named <f>ile if given.

‘--help-manual <man> [<f>]’

     Print one help manual and exit.

     The specified manual is printed in a human-readable text format.
     The help is printed to a named <f>ile if given.

‘--help-manual-list [<f>]’

     List help manuals available and exit.

     The list contains all manuals for which help may be obtained by
     using the ‘--help-manual’ option followed by a manual name.  The
     help is printed to a named <f>ile if given.

‘--help-command <cmd> [<f>]’

     Print help for one command and exit.

     The cmake-commands(7) manual entry for ‘<cmd>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-command-list [<f>]’

     List commands with help available and exit.

     The list contains all commands for which help may be obtained by
     using the ‘--help-command’ option followed by a command name.  The
     help is printed to a named <f>ile if given.

‘--help-commands [<f>]’

     Print cmake-commands manual and exit.

     The cmake-commands(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-module <mod> [<f>]’

     Print help for one module and exit.

     The cmake-modules(7) manual entry for ‘<mod>’ is printed
     in a human-readable text format.  The help is printed to a named
     <f>ile if given.

‘--help-module-list [<f>]’

     List modules with help available and exit.

     The list contains all modules for which help may be obtained by
     using the ‘--help-module’ option followed by a module name.  The
     help is printed to a named <f>ile if given.

‘--help-modules [<f>]’

     Print cmake-modules manual and exit.

     The cmake-modules(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-policy <cmp> [<f>]’

     Print help for one policy and exit.

     The cmake-policies(7) manual entry for ‘<cmp>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-policy-list [<f>]’

     List policies with help available and exit.

     The list contains all policies for which help may be obtained by
     using the ‘--help-policy’ option followed by a policy name.  The
     help is printed to a named <f>ile if given.

‘--help-policies [<f>]’

     Print cmake-policies manual and exit.

     The cmake-policies(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-property <prop> [<f>]’

     Print help for one property and exit.

     The cmake-properties(7) manual entries for ‘<prop>’ are
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-property-list [<f>]’

     List properties with help available and exit.

     The list contains all properties for which help may be obtained by
     using the ‘--help-property’ option followed by a property name.
     The help is printed to a named <f>ile if given.

‘--help-properties [<f>]’

     Print cmake-properties manual and exit.

     The cmake-properties(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

‘--help-variable <var> [<f>]’

     Print help for one variable and exit.

     The cmake-variables(7) manual entry for ‘<var>’ is
     printed in a human-readable text format.  The help is printed to a
     named <f>ile if given.

‘--help-variable-list [<f>]’

     List variables with help available and exit.

     The list contains all variables for which help may be obtained by
     using the ‘--help-variable’ option followed by a variable name.
     The help is printed to a named <f>ile if given.

‘--help-variables [<f>]’

     Print cmake-variables manual and exit.

     The cmake-variables(7) manual is printed in a
     human-readable text format.  The help is printed to a named <f>ile
     if given.

5.4 See Also
============

The following resources are available to get help using CMake:

Home Page

     ‘https://cmake.org’

     The primary starting point for learning about CMake.

Online Documentation and Community Resources

     ‘https://cmake.org/documentation’

     Links to available documentation and community resources may be
     found on this web page.

Discourse Forum

     ‘https://discourse.cmake.org’

     The Discourse Forum hosts discussion and questions about CMake.

Reference Manuals
*****************

6 cmake-buildsystem(7)
**********************

6.1 Introduction
================

A CMake-based buildsystem is organized as a set of high-level logical
targets.  Each target corresponds to an executable or library, or is a
custom target containing custom commands.  Dependencies between the
targets are expressed in the buildsystem to determine the build order
and the rules for regeneration in response to change.

6.2 Binary Targets
==================

Executables and libraries are defined using the add_executable()
and add_library() commands.  The resulting binary files
have appropriate PREFIX, SUFFIX and extensions for
the platform targeted.  Dependencies between binary targets are
expressed using the target_link_libraries() command:

     add_library(archive archive.cpp zip.cpp lzma.cpp)
     add_executable(zipapp zipapp.cpp)
     target_link_libraries(zipapp archive)

‘archive’ is defined as a ‘STATIC’ library – an archive containing
objects compiled from ‘archive.cpp’, ‘zip.cpp’, and ‘lzma.cpp’.
‘zipapp’ is defined as an executable formed by compiling and linking
‘zipapp.cpp’.  When linking the ‘zipapp’ executable, the ‘archive’
static library is linked in.

6.2.1 Binary Executables
------------------------

The add_executable() command defines an executable target:

     add_executable(mytool mytool.cpp)

Commands such as add_custom_command(), which generates rules
to be run at build time can transparently use an EXECUTABLE.
target as a ‘COMMAND’ executable.  The buildsystem rules will ensure
that the executable is built before attempting to run the command.

6.2.2 Binary Library Types
--------------------------

6.2.2.1 Normal Libraries
........................

By default, the add_library() command defines a ‘STATIC’
library, unless a type is specified.  A type may be specified when using
the command:

     add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)

     add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)

The BUILD_SHARED_LIBS variable may be enabled to change the
behavior of add_library() to build shared libraries by
default.

In the context of the buildsystem definition as a whole, it is largely
irrelevant whether particular libraries are ‘SHARED’ or ‘STATIC’ – the
commands, dependency specifications and other APIs work similarly
regardless of the library type.  The ‘MODULE’ library type is dissimilar
in that it is generally not linked to – it is not used in the
right-hand-side of the target_link_libraries() command.  It
is a type which is loaded as a plugin using runtime techniques.  If the
library does not export any unmanaged symbols (e.g.  Windows resource
DLL, C++/CLI DLL), it is required that the library not be a ‘SHARED’
library because CMake expects ‘SHARED’ libraries to export at least one
symbol.

     add_library(archive MODULE 7z.cpp)

6.2.2.2 Apple Frameworks
........................

A ‘SHARED’ library may be marked with the FRAMEWORK target
property to create an macOS or iOS Framework Bundle.  A library with the
‘FRAMEWORK’ target property should also set the FRAMEWORK_VERSION
target property.  This property is typically set to the value of “A”
by macOS conventions.  The ‘MACOSX_FRAMEWORK_IDENTIFIER’ sets
‘CFBundleIdentifier’ key and it uniquely identifies the bundle.

     add_library(MyFramework SHARED MyFramework.cpp)
     set_target_properties(MyFramework PROPERTIES
       FRAMEWORK TRUE
       FRAMEWORK_VERSION A # Version "A" is macOS convention
       MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
     )

6.2.2.3 Object Libraries
........................

The ‘OBJECT’ library type defines a non-archival collection of object
files resulting from compiling the given source files.  The object files
collection may be used as source inputs to other targets by using the
syntax ‘$<TARGET_OBJECTS:name>’.  This is a generator expression
that can be used to supply the ‘OBJECT’ library content to other
targets:

     add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

     add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)

     add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)

The link (or archiving) step of those other targets will use the object
files collection in addition to those from their own sources.

Alternatively, object libraries may be linked into other targets:

     add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

     add_library(archiveExtras STATIC extras.cpp)
     target_link_libraries(archiveExtras PUBLIC archive)

     add_executable(test_exe test.cpp)
     target_link_libraries(test_exe archive)

The link (or archiving) step of those other targets will use the object
files from ‘OBJECT’ libraries that are `directly' linked.  Additionally,
usage requirements of the ‘OBJECT’ libraries will be honored when
compiling sources in those other targets.  Furthermore, those usage
requirements will propagate transitively to dependents of those other
targets.

Object libraries may not be used as the ‘TARGET’ in a use of the
add_custom_command(TARGET) command signature.  However, the list of
objects can be used by add_custom_command(OUTPUT) or
file(GENERATE) by using ‘$<TARGET_OBJECTS:objlib>’.

6.3 Build Specification and Usage Requirements
==============================================

The target_include_directories(),
target_compile_definitions() and target_compile_options()
commands specify the build specifications and the usage requirements
of binary targets.  The commands populate the INCLUDE_DIRECTORIES,
see COMPILE_DEFINITIONS and COMPILE_OPTIONS.
target properties respectively, and/or the
INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS
and INTERFACE_COMPILE_OPTIONS target properties.

Each of the commands has a ‘PRIVATE’, ‘PUBLIC’ and ‘INTERFACE’ mode.
The ‘PRIVATE’ mode populates only the non-‘INTERFACE_’ variant of the
target property and the ‘INTERFACE’ mode populates only the ‘INTERFACE_’
variants.  The ‘PUBLIC’ mode populates both variants of the respective
target property.  Each command may be invoked with multiple uses of each
keyword:

     target_compile_definitions(archive
       PRIVATE BUILDING_WITH_LZMA
       INTERFACE USING_ARCHIVE_LIB
     )

Note that usage requirements are not designed as a way to make
downstreams use particular COMPILE_OPTIONS or
COMPILE_DEFINITIONS etc for convenience only.  The contents of the
properties must be `requirements', not merely recommendations or
convenience.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

6.3.1 Target Properties
-----------------------

The contents of the INCLUDE_DIRECTORIES,
COMPILE_DEFINITIONS and COMPILE_OPTIONS target
properties are used appropriately when compiling the source files of a
binary target.

Entries in the INCLUDE_DIRECTORIES are added to the compile
line with ‘-I’ or ‘-isystem’ prefixes and in the order of appearance in
the property value.

Entries in the COMPILE_DEFINITIONS are prefixed with ‘-D’ or
‘/D’ and added to the compile line in an unspecified order.  The
DEFINE_SYMBOL target property is also added as a compile
definition as a special convenience case for ‘SHARED’ and ‘MODULE’
library targets.

Entries in the COMPILE_OPTIONS are escaped for the shell and
added in the order of appearance in the property value.  Several compile
options have special separate handling, such as
POSITION_INDEPENDENT_CODE.

The contents of the INTERFACE_INCLUDE_DIRECTORIES,
INTERFACE_COMPILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS
target properties are `Usage Requirements' – they specify content
which consumers must use to correctly compile and link with the target
they appear on.  For any binary target, the contents of each
‘INTERFACE_’ property on each target specified in a
target_link_libraries() command is consumed:

     set(srcs archive.cpp zip.cpp)
     if (LZMA_FOUND)
       list(APPEND srcs lzma.cpp)
     endif()
     add_library(archive SHARED ${srcs})
     if (LZMA_FOUND)
       # The archive library sources are compiled with -DBUILDING_WITH_LZMA
       target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
     endif()
     target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

     add_executable(consumer)
     # Link consumer to archive and consume its usage requirements. The consumer
     # executable sources are compiled with -DUSING_ARCHIVE_LIB.
     target_link_libraries(consumer archive)

Because it is common to require that the source directory and
corresponding build directory are added to the
INCLUDE_DIRECTORIES, the CMAKE_INCLUDE_CURRENT_DIR.
variable can be enabled to conveniently add the corresponding
directories to the INCLUDE_DIRECTORIES of all targets.  The
variable CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be
enabled to add the corresponding directories to the
INTERFACE_INCLUDE_DIRECTORIES of all targets.  This makes use of
targets in multiple different directories convenient through use of the
target_link_libraries() command.

6.3.2 Transitive Usage Requirements
-----------------------------------

The usage requirements of a target can transitively propagate to
dependents.  The target_link_libraries() command has
‘PRIVATE’, ‘INTERFACE’ and ‘PUBLIC’ keywords to control the propagation.

     add_library(archive archive.cpp)
     target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

     add_library(serialization serialization.cpp)
     target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)

     add_library(archiveExtras extras.cpp)
     target_link_libraries(archiveExtras PUBLIC archive)
     target_link_libraries(archiveExtras PRIVATE serialization)
     # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
     # and -DUSING_SERIALIZATION_LIB

     add_executable(consumer consumer.cpp)
     # consumer is compiled with -DUSING_ARCHIVE_LIB
     target_link_libraries(consumer archiveExtras)

Because ‘archive’ is a ‘PUBLIC’ dependency of ‘archiveExtras’, the usage
requirements of it are propagated to ‘consumer’ too.  Because
‘serialization’ is a ‘PRIVATE’ dependency of ‘archiveExtras’, the usage
requirements of it are not propagated to ‘consumer’.

Generally, a dependency should be specified in a use of
target_link_libraries() with the ‘PRIVATE’ keyword if it is used by
only the implementation of a library, and not in the header files.  If a
dependency is additionally used in the header files of a library (e.g.
for class inheritance), then it should be specified as a ‘PUBLIC’
dependency.  A dependency which is not used by the implementation of a
library, but only by its headers should be specified as an ‘INTERFACE’
dependency.  The target_link_libraries() command may be
invoked with multiple uses of each keyword:

     target_link_libraries(archiveExtras
       PUBLIC archive
       PRIVATE serialization
     )

Usage requirements are propagated by reading the ‘INTERFACE_’ variants
of target properties from dependencies and appending the values to the
non-‘INTERFACE_’ variants of the operand.  For example, the
INTERFACE_INCLUDE_DIRECTORIES of dependencies is read and appended
to the INCLUDE_DIRECTORIES of the operand.  In cases where
order is relevant and maintained, and the order resulting from the
target_link_libraries() calls does not allow correct compilation,
use of an appropriate command to set the property directly may update
the order.

For example, if the linked libraries for a target must be specified in
the order ‘lib1’ ‘lib2’ ‘lib3’ , but the include directories must be
specified in the order ‘lib3’ ‘lib1’ ‘lib2’:

     target_link_libraries(myExe lib1 lib2 lib3)
     target_include_directories(myExe
       PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)

Note that care must be taken when specifying usage requirements for
targets which will be exported for installation using the
install(EXPORT) command.  See Creating Packages for
more.

6.3.3 Compatible Interface Properties
-------------------------------------

Some target properties are required to be compatible between a target
and the interface of each dependency.  For example, the
POSITION_INDEPENDENT_CODE target property may specify a boolean
value of whether a target should be compiled as
position-independent-code, which has platform-specific consequences.  A
target may also specify the usage requirement
INTERFACE_POSITION_INDEPENDENT_CODE to communicate that consumers
must be compiled as position-independent-code.

     add_executable(exe1 exe1.cpp)
     set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)

     add_library(lib1 SHARED lib1.cpp)
     set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

     add_executable(exe2 exe2.cpp)
     target_link_libraries(exe2 lib1)

Here, both ‘exe1’ and ‘exe2’ will be compiled as
position-independent-code.  ‘lib1’ will also be compiled as
position-independent-code because that is the default setting for
‘SHARED’ libraries.  If dependencies have conflicting, non-compatible
requirements cmake(1) issues a diagnostic:

     add_library(lib1 SHARED lib1.cpp)
     set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

     add_library(lib2 SHARED lib2.cpp)
     set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1)
     set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)

     add_executable(exe2 exe2.cpp)
     target_link_libraries(exe2 lib1 lib2)

The ‘lib1’ requirement ‘INTERFACE_POSITION_INDEPENDENT_CODE’ is not
“compatible” with the POSITION_INDEPENDENT_CODE property of
the ‘exe1’ target.  The library requires that consumers are built as
position-independent-code, while the executable specifies to not built
as position-independent-code, so a diagnostic is issued.

The ‘lib1’ and ‘lib2’ requirements are not “compatible”.  One of them
requires that consumers are built as position-independent-code, while
the other requires that consumers are not built as
position-independent-code.  Because ‘exe2’ links to both and they are in
conflict, a CMake error message is issued:

     CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
     not agree with the value of POSITION_INDEPENDENT_CODE already determined
     for "exe2".

To be “compatible”, the POSITION_INDEPENDENT_CODE property,
if set must be either the same, in a boolean sense, as the
INTERFACE_POSITION_INDEPENDENT_CODE property of all transitively
specified dependencies on which that property is set.

This property of “compatible interface requirement” may be extended to
other properties by specifying the property in the content of the
COMPATIBLE_INTERFACE_BOOL target property.  Each specified
property must be compatible between the consuming target and the
corresponding property with an ‘INTERFACE_’ prefix from each dependency:

     add_library(lib1Version2 SHARED lib1_v2.cpp)
     set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
     set_property(TARGET lib1Version2 APPEND PROPERTY
       COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
     )

     add_library(lib1Version3 SHARED lib1_v3.cpp)
     set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON

     add_executable(exe2 exe2.cpp)
     target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

Non-boolean properties may also participate in “compatible interface”
computations.  Properties specified in the
COMPATIBLE_INTERFACE_STRING property must be either unspecified or
compare to the same string among all transitively specified
dependencies.  This can be useful to ensure that multiple incompatible
versions of a library are not linked together through transitive
requirements of a target:

     add_library(lib1Version2 SHARED lib1_v2.cpp)
     set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
     set_property(TARGET lib1Version2 APPEND PROPERTY
       COMPATIBLE_INTERFACE_STRING LIB_VERSION
     )

     add_library(lib1Version3 SHARED lib1_v3.cpp)
     set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"

     add_executable(exe2 exe2.cpp)
     target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

The COMPATIBLE_INTERFACE_NUMBER_MAX target property
specifies that content will be evaluated numerically and the maximum
number among all specified will be calculated:

     add_library(lib1Version2 SHARED lib1_v2.cpp)
     set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
     set_property(TARGET lib1Version2 APPEND PROPERTY
       COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
     )

     add_library(lib1Version3 SHARED lib1_v3.cpp)
     set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)

     add_executable(exe1 exe1.cpp)
     # CONTAINER_SIZE_REQUIRED will be "200"
     target_link_libraries(exe1 lib1Version2)

     add_executable(exe2 exe2.cpp)
     # CONTAINER_SIZE_REQUIRED will be "1000"
     target_link_libraries(exe2 lib1Version2 lib1Version3)

Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used
to calculate the numeric minimum value for a property from dependencies.

Each calculated “compatible” property value may be read in the consumer
at generate-time using generator expressions.

Note that for each dependee, the set of properties specified in each
compatible interface property must not intersect with the set specified
in any of the other properties.

6.3.4 Property Origin Debugging
-------------------------------

Because build specifications can be determined by dependencies, the lack
of locality of code which creates a target and code which is responsible
for setting build specifications may make the code more difficult to
reason about.  cmake(1) provides a debugging facility to print
the origin of the contents of properties which may be determined by
dependencies.  The properties which can be debugged are listed in the
CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:

     set(CMAKE_DEBUG_TARGET_PROPERTIES
       INCLUDE_DIRECTORIES
       COMPILE_DEFINITIONS
       POSITION_INDEPENDENT_CODE
       CONTAINER_SIZE_REQUIRED
       LIB_VERSION
     )
     add_executable(exe1 exe1.cpp)

In the case of properties listed in COMPATIBLE_INTERFACE_BOOL
or COMPATIBLE_INTERFACE_STRING, the debug output shows
which target was responsible for setting the property, and which other
dependencies also defined the property.  In the case of
COMPATIBLE_INTERFACE_NUMBER_MAX and
COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value
of the property from each dependency, and whether the value determines
the new extreme.

6.3.5 Build Specification with Generator Expressions
----------------------------------------------------

Build specifications may use generator expressions containing
content which may be conditional or known only at generate-time.  For
example, the calculated “compatible” value of a property may be read
with the ‘TARGET_PROPERTY’ expression:

     add_library(lib1Version2 SHARED lib1_v2.cpp)
     set_property(TARGET lib1Version2 PROPERTY
       INTERFACE_CONTAINER_SIZE_REQUIRED 200)
     set_property(TARGET lib1Version2 APPEND PROPERTY
       COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
     )

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1Version2)
     target_compile_definitions(exe1 PRIVATE
         CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
     )

In this case, the ‘exe1’ source files will be compiled with
‘-DCONTAINER_SIZE=200’.

Configuration determined build specifications may be conveniently set
using the ‘CONFIG’ generator expression.

     target_compile_definitions(exe1 PRIVATE
         $<$<CONFIG:Debug>:DEBUG_BUILD>
     )

The ‘CONFIG’ parameter is compared case-insensitively with the
configuration being built.  In the presence of IMPORTED.
targets, the content of MAP_IMPORTED_CONFIG_DEBUG is also
accounted for by this expression.

Some buildsystems generated by cmake(1) have a predetermined
build-configuration set in the CMAKE_BUILD_TYPE variable.
The buildsystem for the IDEs such as Visual Studio and Xcode are
generated independent of the build-configuration, and the actual build
configuration is not known until build-time.  Therefore, code such as

     string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
     if (_type STREQUAL debug)
       target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
     endif()

may appear to work for Makefile Generators and Ninja
generators, but is not portable to IDE generators.  Additionally,
the IMPORTED configuration-mappings are not accounted for
with code like this, so it should be avoided.

The unary ‘TARGET_PROPERTY’ generator expression and the ‘TARGET_POLICY’
generator expression are evaluated with the consuming target context.
This means that a usage requirement specification may be evaluated
differently based on the consumer:

     add_library(lib1 lib1.cpp)
     target_compile_definitions(lib1 INTERFACE
       $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
       $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
       $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
     )

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1)

     cmake_policy(SET CMP0041 NEW)

     add_library(shared_lib shared_lib.cpp)
     target_link_libraries(shared_lib lib1)

The ‘exe1’ executable will be compiled with ‘-DLIB1_WITH_EXE’, while the
‘shared_lib’ shared library will be compiled with
‘-DLIB1_WITH_SHARED_LIB’ and ‘-DCONSUMER_CMP0041_NEW’, because policy
CMP0041 is ‘NEW’ at the point where the ‘shared_lib’ target
is created.

The ‘BUILD_INTERFACE’ expression wraps requirements which are only used
when consumed from a target in the same buildsystem, or when consumed
from a target exported to the build directory using the export()
command.  The ‘INSTALL_INTERFACE’ expression wraps requirements
which are only used when consumed from a target which has been installed
and exported with the install(EXPORT) command:

     add_library(ClimbingStats climbingstats.cpp)
     target_compile_definitions(ClimbingStats INTERFACE
       $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
       $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
     )
     install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
     install(EXPORT libExport NAMESPACE Upstream::
             DESTINATION lib/cmake/ClimbingStats)
     export(EXPORT libExport NAMESPACE Upstream::)

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 ClimbingStats)

In this case, the ‘exe1’ executable will be compiled with
‘-DClimbingStats_FROM_BUILD_LOCATION’.  The exporting commands generate
IMPORTED targets with either the ‘INSTALL_INTERFACE’ or the
‘BUILD_INTERFACE’ omitted, and the ‘*_INTERFACE’ marker stripped away.
A separate project consuming the ‘ClimbingStats’ package would contain:

     find_package(ClimbingStats REQUIRED)

     add_executable(Downstream main.cpp)
     target_link_libraries(Downstream Upstream::ClimbingStats)

Depending on whether the ‘ClimbingStats’ package was used from the build
location or the install location, the ‘Downstream’ target would be
compiled with either ‘-DClimbingStats_FROM_BUILD_LOCATION’ or
‘-DClimbingStats_FROM_INSTALL_LOCATION’.  For more about packages and
exporting see the cmake-packages(7) manual.

6.3.5.1 Include Directories and Usage Requirements
..................................................

Include directories require some special consideration when specified as
usage requirements and when used with generator expressions.  The
target_include_directories() command accepts both relative and
absolute include directories:

     add_library(lib1 lib1.cpp)
     target_include_directories(lib1 PRIVATE
       /absolute/path
       relative/path
     )

Relative paths are interpreted relative to the source directory where
the command appears.  Relative paths are not allowed in the
INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets.

In cases where a non-trivial generator expression is used, the
‘INSTALL_PREFIX’ expression may be used within the argument of an
‘INSTALL_INTERFACE’ expression.  It is a replacement marker which
expands to the installation prefix when imported by a consuming project.

Include directories usage requirements commonly differ between the
build-tree and the install-tree.  The ‘BUILD_INTERFACE’ and
‘INSTALL_INTERFACE’ generator expressions can be used to describe
separate usage requirements based on the usage location.  Relative paths
are allowed within the ‘INSTALL_INTERFACE’ expression and are
interpreted relative to the installation prefix.  For example:

     add_library(ClimbingStats climbingstats.cpp)
     target_include_directories(ClimbingStats INTERFACE
       $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
       $<INSTALL_INTERFACE:/absolute/path>
       $<INSTALL_INTERFACE:relative/path>
       $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
     )

Two convenience APIs are provided relating to include directories usage
requirements.  The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.
variable may be enabled, with an equivalent effect to:

     set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
     )

for each target affected.  The convenience for installed targets is an
‘INCLUDES DESTINATION’ component with the install(TARGETS).
command:

     install(TARGETS foo bar bat EXPORT tgts ${dest_args}
       INCLUDES DESTINATION include
     )
     install(EXPORT tgts ${other_args})
     install(FILES ${headers} DESTINATION include)

This is equivalent to appending ‘${CMAKE_INSTALL_PREFIX}/include’ to the
INTERFACE_INCLUDE_DIRECTORIES of each of the installed
IMPORTED targets when generated by install(EXPORT).

When the INTERFACE_INCLUDE_DIRECTORIES of an imported target
is consumed, the entries in the property are treated as
‘SYSTEM’ include directories, as if they were listed in the
INTERFACE_SYSTEM_INCLUDE_DIRECTORIES of the dependency.  This can
result in omission of compiler warnings for headers found in those
directories.  This behavior for Imported Targets may be
controlled by setting the NO_SYSTEM_FROM_IMPORTED target
property on the `consumers' of imported targets.

If a binary target is linked transitively to a macOS FRAMEWORK,
the ‘Headers’ directory of the framework is also treated as a usage
requirement.  This has the same effect as passing the framework
directory as an include directory.

6.3.6 Link Libraries and Generator Expressions
----------------------------------------------

Like build specifications, see link libraries may be specified
with generator expression conditions.  However, as consumption of usage
requirements is based on collection from linked dependencies, there is
an additional limitation that the link dependencies must form a
“directed acyclic graph”.  That is, if linking to a target is dependent
on the value of a target property, that target property may not be
dependent on the linked dependencies:

     add_library(lib1 lib1.cpp)
     add_library(lib2 lib2.cpp)
     target_link_libraries(lib1 PUBLIC
       $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
     )
     add_library(lib3 lib3.cpp)
     set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 lib1 lib3)

As the value of the POSITION_INDEPENDENT_CODE property of
the ‘exe1’ target is dependent on the linked libraries (‘lib3’), and the
edge of linking ‘exe1’ is determined by the same
POSITION_INDEPENDENT_CODE property, the dependency graph above
contains a cycle.  cmake(1) issues an error message.

6.3.7 Output Artifacts
----------------------

The buildsystem targets created by the add_library() and
add_executable() commands create rules to create binary
outputs.  The exact output location of the binaries can only be
determined at generate-time because it can depend on the
build-configuration and the link-language of linked dependencies etc.
‘TARGET_FILE’, ‘TARGET_LINKER_FILE’ and related expressions can be used
to access the name and location of generated binaries.  These
expressions do not work for ‘OBJECT’ libraries however, as there is no
single file generated by such libraries which is relevant to the
expressions.

There are three kinds of output artifacts that may be build by targets
as detailed in the following sections.  Their classification differs
between DLL platforms and non-DLL platforms.  All Windows-based systems
including Cygwin are DLL platforms.

6.3.7.1 Runtime Output Artifacts
................................

A `runtime' output artifact of a buildsystem target may be:

   * The executable file (e.g.  ‘.exe’) of an executable target created
     by the add_executable() command.

   * On DLL platforms: the executable file (e.g.  ‘.dll’) of a shared
     library target created by the add_library() command with
     the ‘SHARED’ option.

The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME
target properties may be used to control runtime output artifact
locations and names in the build tree.

6.3.7.2 Library Output Artifacts
................................

A `library' output artifact of a buildsystem target may be:

   * The loadable module file (e.g.  ‘.dll’ or ‘.so’) of a module
     library target created by the add_library() command with
     the ‘MODULE’ option.

   * On non-DLL platforms: the shared library file (e.g.  ‘.so’ or
     ‘.dylib’) of a shared library target created by the
     add_library() command with the ‘SHARED’ option.

The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME
target properties may be used to control library output artifact
locations and names in the build tree.

6.3.7.3 Archive Output Artifacts
................................

An `archive' output artifact of a buildsystem target may be:

   * The static library file (e.g.  ‘.lib’ or ‘.a’) of a static library
     target created by the add_library() command with the
     ‘STATIC’ option.

   * On DLL platforms: the import library file (e.g.  ‘.lib’) of a
     shared library target created by the add_library().
     command with the ‘SHARED’ option.  This file is only guaranteed to
     exist if the library exports at least one unmanaged symbol.

   * On DLL platforms: the import library file (e.g.  ‘.lib’) of an
     executable target created by the add_executable().
     command when its ENABLE_EXPORTS target property is set.

   * On AIX: the linker import file (e.g.  ‘.imp’) of an executable
     target created by the add_executable() command when its
     ENABLE_EXPORTS target property is set.

The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME
target properties may be used to control archive output artifact
locations and names in the build tree.

6.3.8 Directory-Scoped Commands
-------------------------------

The target_include_directories(),
target_compile_definitions() and target_compile_options()
commands have an effect on only one target at a time.  The commands
add_compile_definitions(), add_compile_options().
and include_directories() have a similar function, but
operate at directory scope instead of target scope for convenience.

6.4 Pseudo Targets
==================

Some target types do not represent outputs of the buildsystem, but only
inputs such as external dependencies, aliases or other non-build
artifacts.  Pseudo targets are not represented in the generated
buildsystem.

6.4.1 Imported Targets
----------------------

An IMPORTED target represents a pre-existing dependency.
Usually such targets are defined by an upstream package and should be
treated as immutable.  After declaring an IMPORTED target
one can adjust its target properties by using the customary commands
such as target_compile_definitions(),
target_include_directories(), target_compile_options() or
target_link_libraries() just like with any other regular
target.

IMPORTED targets may have the same usage requirement
properties populated as binary targets, such as
INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS,
see INTERFACE_COMPILE_OPTIONS,
INTERFACE_LINK_LIBRARIES, and
INTERFACE_POSITION_INDEPENDENT_CODE.

The LOCATION may also be read from an IMPORTED target,
though there is rarely reason to do so.  Commands such as
add_custom_command() can transparently use an IMPORTED.
EXECUTABLE target as a ‘COMMAND’ executable.

The scope of the definition of an IMPORTED target is the
directory where it was defined.  It may be accessed and used from
subdirectories, but not from parent directories or sibling directories.
The scope is similar to the scope of a cmake variable.

It is also possible to define a ‘GLOBAL’ IMPORTED target
which is accessible globally in the buildsystem.

See the cmake-packages(7) manual for more on creating packages
with IMPORTED targets.

6.4.2 Alias Targets
-------------------

An ‘ALIAS’ target is a name which may be used interchangeably with a
binary target name in read-only contexts.  A primary use-case for
‘ALIAS’ targets is for example or unit test executables accompanying a
library, which may be part of the same buildsystem or built separately
based on user configuration.

     add_library(lib1 lib1.cpp)
     install(TARGETS lib1 EXPORT lib1Export ${dest_args})
     install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})

     add_library(Upstream::lib1 ALIAS lib1)

In another directory, we can link unconditionally to the
‘Upstream::lib1’ target, which may be an IMPORTED target
from a package, or an ‘ALIAS’ target if built as part of the same
buildsystem.

     if (NOT TARGET Upstream::lib1)
       find_package(lib1 REQUIRED)
     endif()
     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 Upstream::lib1)

‘ALIAS’ targets are not mutable, installable or exportable.  They are
entirely local to the buildsystem description.  A name can be tested for
whether it is an ‘ALIAS’ name by reading the ALIASED_TARGET.
property from it:

     get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
     if(_aliased)
       message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
     endif()

6.4.3 Interface Libraries
-------------------------

An ‘INTERFACE’ library target does not compile sources and does not
produce a library artifact on disk, so it has no LOCATION.

It may specify usage requirements such as
INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS,
see INTERFACE_COMPILE_OPTIONS,
INTERFACE_LINK_LIBRARIES, INTERFACE_SOURCES, and
INTERFACE_POSITION_INDEPENDENT_CODE.  Only the ‘INTERFACE’ modes of
the target_include_directories(),
target_compile_definitions(), target_compile_options(),
target_sources(), and target_link_libraries().
commands may be used with ‘INTERFACE’ libraries.

Since CMake 3.19, an ‘INTERFACE’ library target may optionally contain
source files.  An interface library that contains source files will be
included as a build target in the generated buildsystem.  It does not
compile sources, but may contain custom commands to generate other
sources.  Additionally, IDEs will show the source files as part of the
target for interactive reading and editing.

A primary use-case for ‘INTERFACE’ libraries is header-only libraries.

     add_library(Eigen INTERFACE
       src/eigen.h
       src/vector.h
       src/matrix.h
       )
     target_include_directories(Eigen INTERFACE
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
       $<INSTALL_INTERFACE:include/Eigen>
     )

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 Eigen)

Here, the usage requirements from the ‘Eigen’ target are consumed and
used when compiling, but it has no effect on linking.

Another use-case is to employ an entirely target-focussed design for
usage requirements:

     add_library(pic_on INTERFACE)
     set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
     add_library(pic_off INTERFACE)
     set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

     add_library(enable_rtti INTERFACE)
     target_compile_options(enable_rtti INTERFACE
       $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
     )

     add_executable(exe1 exe1.cpp)
     target_link_libraries(exe1 pic_on enable_rtti)

This way, the build specification of ‘exe1’ is expressed entirely as
linked targets, and the complexity of compiler-specific flags is
encapsulated in an ‘INTERFACE’ library target.

‘INTERFACE’ libraries may be installed and exported.  Any content they
refer to must be installed separately:

     set(Eigen_headers
       src/eigen.h
       src/vector.h
       src/matrix.h
       )
     add_library(Eigen INTERFACE ${Eigen_headers})
     target_include_directories(Eigen INTERFACE
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
       $<INSTALL_INTERFACE:include/Eigen>
     )

     install(TARGETS Eigen EXPORT eigenExport)
     install(EXPORT eigenExport NAMESPACE Upstream::
       DESTINATION lib/cmake/Eigen
     )
     install(FILES ${Eigen_headers}
       DESTINATION include/Eigen
     )

7 cmake-commands(7)
*******************

7.1 Scripting Commands
======================

These commands are always available.

7.1.1 break
-----------

Break from an enclosing foreach or while loop.

     break()

Breaks from an enclosing foreach() or while().
loop.

See also the continue() command.

7.1.2 cmake_host_system_information
-----------------------------------

Query host system specific information.

     cmake_host_system_information(RESULT <variable> QUERY <key> ...)

Queries system information of the host system on which cmake runs.  One
or more ‘<key>’ can be provided to select the information to be queried.
The list of queried values is stored in ‘<variable>’.

‘<key>’ can be one of the following values:

Key                               Description

---------------------------------------------------------------------------------------

‘NUMBER_OF_LOGICAL_CORES’         Number of logical cores

‘NUMBER_OF_PHYSICAL_CORES’        Number of physical cores

‘HOSTNAME’                        Hostname

‘FQDN’                            Fully qualified domain name

‘TOTAL_VIRTUAL_MEMORY’            Total virtual memory in MiB (1)

‘AVAILABLE_VIRTUAL_MEMORY’        Available virtual memory in MiB (2)

‘TOTAL_PHYSICAL_MEMORY’           Total physical memory in MiB (3)

‘AVAILABLE_PHYSICAL_MEMORY’       Available physical memory in MiB (4)

‘IS_64BIT’                        One if processor is 64Bit

‘HAS_FPU’                         One if processor has floating point unit

‘HAS_MMX’                         One if processor supports MMX instructions

‘HAS_MMX_PLUS’                    One if processor supports Ext.  MMX instructions

‘HAS_SSE’                         One if processor supports SSE instructions

‘HAS_SSE2’                        One if processor supports SSE2 instructions

‘HAS_SSE_FP’                      One if processor supports SSE FP instructions

‘HAS_SSE_MMX’                     One if processor supports SSE MMX instructions

‘HAS_AMD_3DNOW’                   One if processor supports 3DNow instructions

‘HAS_AMD_3DNOW_PLUS’              One if processor supports 3DNow+ instructions

‘HAS_IA64’                        One if IA64 processor emulating x86

‘HAS_SERIAL_NUMBER’               One if processor has serial number

‘PROCESSOR_SERIAL_NUMBER’         Processor serial number

‘PROCESSOR_NAME’                  Human readable processor name

‘PROCESSOR_DESCRIPTION’           Human readable full processor description

‘OS_NAME’                         See CMAKE_HOST_SYSTEM_NAME.

‘OS_RELEASE’                      The OS sub-type e.g.  on Windows ‘Professional’

‘OS_VERSION’                      The OS build ID

‘OS_PLATFORM’                     See CMAKE_HOST_SYSTEM_PROCESSOR.

   ---------- Footnotes ----------

   (1) (1) One MiB (mebibyte) is equal to 1024x1024 bytes.

   (2) (1) One MiB (mebibyte) is equal to 1024x1024 bytes.

   (3) (1) One MiB (mebibyte) is equal to 1024x1024 bytes.

   (4) (1) One MiB (mebibyte) is equal to 1024x1024 bytes.

7.1.3 cmake_language
--------------------

New in version 3.18.

Call meta-operations on CMake commands.

7.1.3.1 Synopsis
................

     cmake_language(see CALL. <command> [<arg>...])
     cmake_language(see EVAL. CODE <code>...)
     cmake_language(see DEFER. <options>... CALL <command> [<arg>...])

7.1.3.2 Introduction
....................

This command will call meta-operations on built-in CMake commands or
those created via the macro() or function().
commands.

‘cmake_language’ does not introduce a new variable or policy scope.

7.1.3.3 Calling Commands
........................

     cmake_language(CALL <command> [<arg>...])

Calls the named ‘<command>’ with the given arguments (if any).  For
example, the code:

     set(message_command "message")
     cmake_language(CALL ${message_command} STATUS "Hello World!")

is equivalent to

     message(STATUS "Hello World!")

     Note: To ensure consistency of the code, the following commands are
     not allowed:

        * ‘if’ / ‘elseif’ / ‘else’ / ‘endif’

        * ‘while’ / ‘endwhile’

        * ‘foreach’ / ‘endforeach’

        * ‘function’ / ‘endfunction’

        * ‘macro’ / ‘endmacro’

7.1.3.4 Evaluating Code
.......................

     cmake_language(EVAL CODE <code>...)

Evaluates the ‘<code>...’ as CMake code.

For example, the code:

     set(A TRUE)
     set(B TRUE)
     set(C TRUE)
     set(condition "(A AND B) OR C")

     cmake_language(EVAL CODE "
       if (${condition})
         message(STATUS TRUE)
       else()
         message(STATUS FALSE)
       endif()"
     )

is equivalent to

     set(A TRUE)
     set(B TRUE)
     set(C TRUE)
     set(condition "(A AND B) OR C")

     file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
       if (${condition})
         message(STATUS TRUE)
       else()
         message(STATUS FALSE)
       endif()"
     )

     include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

7.1.3.5 Deferring Calls
.......................

New in version 3.19.

     cmake_language(DEFER <options>... CALL <command> [<arg>...])

Schedules a call to the named ‘<command>’ with the given arguments (if
any) to occur at a later time.  By default, deferred calls are executed
as if written at the end of the current directory’s ‘CMakeLists.txt’
file, except that they run even after a return() call.
Variable references in arguments are evaluated at the time the deferred
call is executed.

The options are:

‘DIRECTORY <dir>’

     Schedule the call for the end of the given directory instead of the
     current directory.  The ‘<dir>’ may reference either a source
     directory or its corresponding binary directory.  Relative paths
     are treated as relative to the current source directory.

     The given directory must be known to CMake, being either the
     top-level directory or one added by add_subdirectory().
     Furthermore, the given directory must not yet be finished
     processing.  This means it can be the current directory or one of
     its ancestors.

‘ID <id>’

     Specify an identification for the deferred call.  The ‘<id>’ may
     not be empty and may not begin with a capital letter ‘A-Z’.  The
     ‘<id>’ may begin with an underscore (‘_’) only if it was generated
     automatically by an earlier call that used ‘ID_VAR’ to get the id.

‘ID_VAR <var>’

     Specify a variable in which to store the identification for the
     deferred call.  If ‘ID <id>’ is not given, a new identification
     will be generated and the generated id will start with an
     underscore (‘_’).

The currently scheduled list of deferred calls may be retrieved:

     cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)

This will store in ‘<var>’ a semicolon-separated list of
deferred call ids.  The ids are for the directory scope in which the
calls have been deferred to (i.e.  where they will be executed), which
can be different to the scope in which they were created.  The
‘DIRECTORY’ option can be used to specify the scope for which to
retrieve the call ids.  If that option is not given, the call ids for
the current directory scope will be returned.

Details of a specific call may be retrieved from its id:

     cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)

This will store in ‘<var>’ a semicolon-separated list in
which the first element is the name of the command to be called, and the
remaining elements are its unevaluated arguments (any contained ‘;’
characters are included literally and cannot be distinguished from
multiple arguments).  If multiple calls are scheduled with the same id,
this retrieves the first one.  If no call is scheduled with the given id
in the specified ‘DIRECTORY’ scope (or the current directory scope if no
‘DIRECTORY’ option is given), this stores an empty string in the
variable.

Deferred calls may be canceled by their id:

     cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)

This cancels all deferred calls matching any of the given ids in the
specified ‘DIRECTORY’ scope (or the current directory scope if no
‘DIRECTORY’ option is given).  Unknown ids are silently ignored.

7.1.3.6 Deferred Call Examples
..............................

For example, the code:

     cmake_language(DEFER CALL message "${deferred_message}")
     cmake_language(DEFER ID_VAR id CALL message "Cancelled Message")
     cmake_language(DEFER CANCEL_CALL ${id})
     message("Immediate Message")
     set(deferred_message "Deferred Message")

prints:

     Immediate Message
     Deferred Message

The ‘Cancelled Message’ is never printed because its command is
cancelled.  The ‘deferred_message’ variable reference is not evaluated
until the call site, so it can be set after the deferred call is
scheduled.

In order to evaluate variable references immediately when scheduling a
deferred call, wrap it using ‘cmake_language(EVAL)’.  However, note that
arguments will be re-evaluated in the deferred call, though that can be
avoided by using bracket arguments.  For example:

     set(deferred_message "Deferred Message 1")
     set(re_evaluated [[${deferred_message}]])
     cmake_language(EVAL CODE "
       cmake_language(DEFER CALL message [[${deferred_message}]])
       cmake_language(DEFER CALL message \"${re_evaluated}\")
     ")
     message("Immediate Message")
     set(deferred_message "Deferred Message 2")

also prints:

     Immediate Message
     Deferred Message 1
     Deferred Message 2

7.1.4 cmake_minimum_required
----------------------------

Require a minimum version of cmake.

     cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])

Sets the minimum required version of cmake for a project.  Also updates
the policy settings as explained below.

‘<min>’ and the optional ‘<max>’ are each CMake versions of the form
‘major.minor[.patch[.tweak]]’, and the ‘...’ is literal.

If the running version of CMake is lower than the ‘<min>’ required
version it will stop processing the project and report an error.  The
optional ‘<max>’ version, if specified, must be at least the ‘<min>’
version and affects policy settings as described below.  If the running
version of CMake is older than 3.12, the extra ‘...’ dots will be seen
as version component separators, resulting in the ‘...<max>’ part being
ignored and preserving the pre-3.12 behavior of basing policies on
‘<min>’.

This command will set the value of the
CMAKE_MINIMUM_REQUIRED_VERSION variable to ‘<min>’.

The ‘FATAL_ERROR’ option is accepted but ignored by CMake 2.6 and
higher.  It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.

     Note: Call the ‘cmake_minimum_required()’ command at the beginning
     of the top-level ‘CMakeLists.txt’ file even before calling the
     project() command.  It is important to establish
     version and policy settings before invoking other commands whose
     behavior they may affect.  See also policy CMP0000.

     Calling ‘cmake_minimum_required()’ inside a function().
     limits some effects to the function scope when invoked.  Such calls
     should not be made with the intention of having global effects.

7.1.4.1 Policy Settings
.......................

The ‘cmake_minimum_required(VERSION)’ command implicitly invokes the
cmake_policy(VERSION) command to specify that the current
project code is written for the given range of CMake versions.  All
policies known to the running version of CMake and introduced in the
‘<min>’ (or ‘<max>’, if specified) version or earlier will be set to use
‘NEW’ behavior.  All policies introduced in later versions will be
unset.  This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies.

When a ‘<min>’ version higher than 2.4 is specified the command
implicitly invokes

     cmake_policy(VERSION <min>[...<max>])

which sets CMake policies based on the range of versions specified.
When a ‘<min>’ version 2.4 or lower is given the command implicitly
invokes

     cmake_policy(VERSION 2.4[...<max>])

which enables compatibility features for CMake 2.4 and lower.

7.1.5 cmake_parse_arguments
---------------------------

New in version 3.5.

Parse function or macro arguments.

     cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                           <multi_value_keywords> <args>...)

     cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
                           <one_value_keywords> <multi_value_keywords>)

This command is for use in macros or functions.  It processes the
arguments given to that macro or function, and defines a set of
variables which hold the values of the respective options.

The first signature reads processes arguments passed in the ‘<args>...’.
This may be used in either a macro() or a function().

The ‘PARSE_ARGV’ signature is only for use in a function().
body.  In this case the arguments that are parsed come from the ‘ARGV#’
variables of the calling function.  The parsing starts with the ‘<N>’-th
argument, where ‘<N>’ is an unsigned integer.  This allows for the
values to have special characters like ‘;’ in them.

The ‘<options>’ argument contains all options for the respective macro,
i.e.  keywords which can be used when calling the macro without any
value following, like e.g.  the ‘OPTIONAL’ keyword of the
install() command.

The ‘<one_value_keywords>’ argument contains all keywords for this macro
which are followed by one value, like e.g.  ‘DESTINATION’ keyword of the
install() command.

The ‘<multi_value_keywords>’ argument contains all keywords for this
macro which can be followed by more than one value, like e.g.  the
‘TARGETS’ or ‘FILES’ keywords of the install() command.

     Note: All keywords shall be unique.  I.e.  every keyword shall only
     be specified once in either ‘<options>’, ‘<one_value_keywords>’ or
     ‘<multi_value_keywords>’.  A warning will be emitted if uniqueness
     is violated.

When done, ‘cmake_parse_arguments’ will consider for each of the
keywords listed in ‘<options>’, ‘<one_value_keywords>’ and
‘<multi_value_keywords>’ a variable composed of the given ‘<prefix>’
followed by ‘"_"’ and the name of the respective keyword.  These
variables will then hold the respective value from the argument list or
be undefined if the associated option could not be found.  For the
‘<options>’ keywords, these will always be defined, to ‘TRUE’ or
‘FALSE’, whether the option is in the argument list or not.

All remaining arguments are collected in a variable
‘<prefix>_UNPARSED_ARGUMENTS’ that will be undefined if all arguments
were recognized.  This can be checked afterwards to see whether your
macro was called with unrecognized parameters.

‘<one_value_keywords>’ and ‘<multi_value_keywords>’ that were given no
values at all are collected in a variable
‘<prefix>_KEYWORDS_MISSING_VALUES’ that will be undefined if all
keywords received values.  This can be checked to see if there were
keywords without any values given.

Consider the following example macro, ‘my_install()’, which takes
similar arguments to the real install() command:

     macro(my_install)
         set(options OPTIONAL FAST)
         set(oneValueArgs DESTINATION RENAME)
         set(multiValueArgs TARGETS CONFIGURATIONS)
         cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
                               "${multiValueArgs}" ${ARGN} )

         # ...

Assume ‘my_install()’ has been called like this:

     my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)

After the ‘cmake_parse_arguments’ call the macro will have set or
undefined the following variables:

     MY_INSTALL_OPTIONAL = TRUE
     MY_INSTALL_FAST = FALSE # was not used in call to my_install
     MY_INSTALL_DESTINATION = "bin"
     MY_INSTALL_RENAME <UNDEFINED> # was not used
     MY_INSTALL_TARGETS = "foo;bar"
     MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
     MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
     MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
              # No value for "CONFIGURATIONS" given

You can then continue and process these variables.

Keywords terminate lists of values, e.g.  if directly after a
‘one_value_keyword’ another recognized keyword follows, this is
interpreted as the beginning of the new option.  E.g.
‘my_install(TARGETS foo DESTINATION OPTIONAL)’ would result in
‘MY_INSTALL_DESTINATION’ set to ‘"OPTIONAL"’, but as ‘OPTIONAL’ is a
keyword itself ‘MY_INSTALL_DESTINATION’ will be empty (but added to
‘MY_INSTALL_KEYWORDS_MISSING_VALUES’) and ‘MY_INSTALL_OPTIONAL’ will
therefore be set to ‘TRUE’.

7.1.6 cmake_policy
------------------

Manage CMake Policy settings.  See the cmake-policies(7).
manual for defined policies.

As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior.  Each
new policy (behavioral change) is given an identifier of the form
‘CMP<NNNN>’ where ‘<NNNN>’ is an integer index.  Documentation
associated with each policy describes the ‘OLD’ and ‘NEW’ behavior and
the reason the policy was introduced.  Projects may set each policy to
select the desired behavior.  When CMake needs to know which behavior to
use it checks for a setting specified by the project.  If no setting is
available the ‘OLD’ behavior is assumed and a warning is produced
requesting that the policy be set.

7.1.6.1 Setting Policies by CMake Version
.........................................

The ‘cmake_policy’ command is used to set policies to ‘OLD’ or ‘NEW’
behavior.  While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:

     cmake_policy(VERSION <min>[...<max>])

‘<min>’ and the optional ‘<max>’ are each CMake versions of the form
‘major.minor[.patch[.tweak]]’, and the ‘...’ is literal.  The ‘<min>’
version must be at least ‘2.4’ and at most the running version of CMake.
The ‘<max>’ version, if specified, must be at least the ‘<min>’ version
but may exceed the running version of CMake.  If the running version of
CMake is older than 3.12, the extra ‘...’ dots will be seen as version
component separators, resulting in the ‘...<max>’ part being ignored and
preserving the pre-3.12 behavior of basing policies on ‘<min>’.

This specifies that the current CMake code is written for the given
range of CMake versions.  All policies known to the running version of
CMake and introduced in the ‘<min>’ (or ‘<max>’, if specified) version
or earlier will be set to use ‘NEW’ behavior.  All policies introduced
in later versions will be unset (unless the
CMAKE_POLICY_DEFAULT_CMP<NNNN> variable sets a default).  This
effectively requests behavior preferred as of a given CMake version and
tells newer CMake versions to warn about their new policies.

Note that the cmake_minimum_required(VERSION) command
implicitly calls ‘cmake_policy(VERSION)’ too.

7.1.6.2 Setting Policies Explicitly
...................................

     cmake_policy(SET CMP<NNNN> NEW)
     cmake_policy(SET CMP<NNNN> OLD)

Tell CMake to use the ‘OLD’ or ‘NEW’ behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to ‘OLD’.  Alternatively one
may fix the project to work with the new behavior and set the policy
state to ‘NEW’.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

7.1.6.3 Checking Policy Settings
................................

     cmake_policy(GET CMP<NNNN> <variable>)

Check whether a given policy is set to ‘OLD’ or ‘NEW’ behavior.  The
output ‘<variable>’ value will be ‘OLD’ or ‘NEW’ if the policy is set,
and empty otherwise.

7.1.6.4 CMake Policy Stack
..........................

CMake keeps policy settings on a stack, so changes made by the
‘cmake_policy’ command affect only the top of the stack.  A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings.  CMake also manages a new entry for
scripts loaded by include() and find_package().
commands except when invoked with the ‘NO_POLICY_SCOPE’ option (see also
policy CMP0011).  The ‘cmake_policy’ command provides an
interface to manage custom entries on the policy stack:

     cmake_policy(PUSH)
     cmake_policy(POP)

Each ‘PUSH’ must have a matching ‘POP’ to erase any changes.  This is
useful to make temporary changes to policy settings.  Calls to the
cmake_minimum_required(VERSION), ‘cmake_policy(VERSION)’, or
‘cmake_policy(SET)’ commands influence only the current top of the
policy stack.

Commands created by the function() and macro().
commands record policy settings when they are created and use the
pre-record policies when they are invoked.  If the function or macro
implementation sets policies, the changes automatically propagate up
through callers until they reach the closest nested policy stack entry.

7.1.7 configure_file
--------------------

Copy a file to another location and modify its contents.

     configure_file(<input> <output>
                    [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
                    [NO_SOURCE_PERMISSIONS]
                    [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Copies an ‘<input>’ file to an ‘<output>’ file and substitutes variable
values referenced as ‘@VAR@’ or ‘${VAR}’ in the input file content.
Each variable reference will be replaced with the current value of the
variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form

     #cmakedefine VAR ...

will be replaced with either

     #define VAR ...

or

     /* #undef VAR */

depending on whether ‘VAR’ is set in CMake to any value not considered a
false constant by the if() command.  The “…” content on the
line after the variable name, if any, is processed as above.  Input file
lines of the form ‘#cmakedefine01 VAR’ will be replaced with either
‘#define VAR 1’ or ‘#define VAR 0’ similarly.  The result lines (with
the exception of the ‘#undef’ comments) can be indented using spaces
and/or tabs between the ‘#’ character and the ‘cmakedefine’ or
‘cmakedefine01’ words.  This whitespace indentation will be preserved in
the output lines:

     #  cmakedefine VAR
     #  cmakedefine01 VAR

will be replaced, if ‘VAR’ is defined, with

     #  define VAR
     #  define VAR 1

If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.  The
generated file is modified and its timestamp updated on subsequent cmake
runs only if its content is changed.

The arguments are:

‘<input>’

     Path to the input file.  A relative path is treated with respect to
     the value of CMAKE_CURRENT_SOURCE_DIR.  The input path
     must be a file, not a directory.

‘<output>’

     Path to the output file or directory.  A relative path is treated
     with respect to the value of CMAKE_CURRENT_BINARY_DIR.
     If the path names an existing directory the output file is placed
     in that directory with the same file name as the input file.

‘COPYONLY’

     Copy the file without replacing any variable references or other
     content.  This option may not be used with ‘NEWLINE_STYLE’.

‘ESCAPE_QUOTES’

     Escape any substituted quotes with backslashes (C-style).

‘@ONLY’

     Restrict variable replacement to references of the form ‘@VAR@’.
     This is useful for configuring scripts that use ‘${VAR}’ syntax.

‘NO_SOURCE_PERMISSIONS’

     Does not transfer the file permissions of the original file to the
     copy.  The copied file permissions default to the standard 644
     value (-rw-r–r–).

‘NEWLINE_STYLE <style>’

     Specify the newline style for the output file.  Specify ‘UNIX’ or
     ‘LF’ for ‘\n’ newlines, or specify ‘DOS’, ‘WIN32’, or ‘CRLF’ for
     ‘\r\n’ newlines.  This option may not be used with ‘COPYONLY’.

7.1.7.1 Example
...............

Consider a source tree containing a ‘foo.h.in’ file:

     #cmakedefine FOO_ENABLE
     #cmakedefine FOO_STRING "@FOO_STRING@"

An adjacent ‘CMakeLists.txt’ may use ‘configure_file’ to configure the
header:

     option(FOO_ENABLE "Enable Foo" ON)
     if(FOO_ENABLE)
       set(FOO_STRING "foo")
     endif()
     configure_file(foo.h.in foo.h @ONLY)

This creates a ‘foo.h’ in the build directory corresponding to this
source directory.  If the ‘FOO_ENABLE’ option is on, the configured file
will contain:

     #define FOO_ENABLE
     #define FOO_STRING "foo"

Otherwise it will contain:

     /* #undef FOO_ENABLE */
     /* #undef FOO_STRING */

One may then use the include_directories() command to
specify the output directory as an include directory:

     include_directories(${CMAKE_CURRENT_BINARY_DIR})

so that sources may include the header as ‘#include <foo.h>’.

7.1.8 continue
--------------

New in version 3.2.

Continue to the top of enclosing foreach or while loop.

     continue()

The ‘continue’ command allows a cmake script to abort the rest of a
block in a foreach() or while() loop, and start
at the top of the next iteration.

See also the break() command.

7.1.9 else
----------

Starts the else portion of an if block.

     else([<condition>])

See the if() command.

7.1.10 elseif
-------------

Starts an elseif portion of an if block.

     elseif(<condition>)

See the if() command, especially for the syntax and logic of
the ‘<condition>’.

7.1.11 endforeach
-----------------

Ends a list of commands in a foreach block.

     endforeach([<loop_var>])

See the foreach() command.

The optional ‘<loop_var>’ argument is supported for backward
compatibility only.  If used it must be a verbatim repeat of the
‘<loop_var>’ argument of the opening ‘foreach’ clause.

7.1.12 endfunction
------------------

Ends a list of commands in a function block.

     endfunction([<name>])

See the function() command.

The optional ‘<name>’ argument is supported for backward compatibility
only.  If used it must be a verbatim repeat of the ‘<name>’ argument of
the opening ‘function’ command.

7.1.13 endif
------------

Ends a list of commands in an if block.

     endif([<condition>])

See the if() command.

The optional ‘<condition>’ argument is supported for backward
compatibility only.  If used it must be a verbatim repeat of the
argument of the opening ‘if’ clause.

7.1.14 endmacro
---------------

Ends a list of commands in a macro block.

     endmacro([<name>])

See the macro() command.

The optional ‘<name>’ argument is supported for backward compatibility
only.  If used it must be a verbatim repeat of the ‘<name>’ argument of
the opening ‘macro’ command.

7.1.15 endwhile
---------------

Ends a list of commands in a while block.

     endwhile([<condition>])

See the while() command.

The optional ‘<condition>’ argument is supported for backward
compatibility only.  If used it must be a verbatim repeat of the
argument of the opening ‘while’ clause.

7.1.16 execute_process
----------------------

Execute one or more child processes.

     execute_process(COMMAND <cmd1> [<arguments>]
                     [COMMAND <cmd2> [<arguments>]]...
                     [WORKING_DIRECTORY <directory>]
                     [TIMEOUT <seconds>]
                     [RESULT_VARIABLE <variable>]
                     [RESULTS_VARIABLE <variable>]
                     [OUTPUT_VARIABLE <variable>]
                     [ERROR_VARIABLE <variable>]
                     [INPUT_FILE <file>]
                     [OUTPUT_FILE <file>]
                     [ERROR_FILE <file>]
                     [OUTPUT_QUIET]
                     [ERROR_QUIET]
                     [COMMAND_ECHO <where>]
                     [OUTPUT_STRIP_TRAILING_WHITESPACE]
                     [ERROR_STRIP_TRAILING_WHITESPACE]
                     [ENCODING <name>]
                     [ECHO_OUTPUT_VARIABLE]
                     [ECHO_ERROR_VARIABLE]
                     [COMMAND_ERROR_IS_FATAL <ANY|LAST>])

Runs the given sequence of one or more commands.

Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.  A
single standard error pipe is used for all processes.

Options:

‘COMMAND’

     A child process command line.

     CMake executes the child process using operating system APIs
     directly.  All arguments are passed VERBATIM to the child process.
     No intermediate shell is used, so shell operators such as ‘>’ are
     treated as normal arguments.  (Use the ‘INPUT_*’, ‘OUTPUT_*’, and
     ‘ERROR_*’ options to redirect stdin, stdout, and stderr.)

     If a sequential execution of multiple commands is required, use
     multiple execute_process() calls with a single
     ‘COMMAND’ argument.

‘WORKING_DIRECTORY’

     The named directory will be set as the current working directory of
     the child processes.

‘TIMEOUT’

     After the specified number of seconds (fractions allowed), all
     unfinished child processes will be terminated, and the
     ‘RESULT_VARIABLE’ will be set to a string mentioning the “timeout”.

‘RESULT_VARIABLE’

     The variable will be set to contain the result of last child
     process.  This will be an integer return code from the last child
     or a string describing an error condition.

‘RESULTS_VARIABLE <variable>’

     The variable will be set to contain the result of all processes as
     a semicolon-separated list, in order of the given
     ‘COMMAND’ arguments.  Each entry will be an integer return code
     from the corresponding child or a string describing an error
     condition.

‘OUTPUT_VARIABLE’, ‘ERROR_VARIABLE’

     The variable named will be set with the contents of the standard
     output and standard error pipes, respectively.  If the same
     variable is named for both pipes their output will be merged in the
     order produced.

‘INPUT_FILE, OUTPUT_FILE’, ‘ERROR_FILE’

     The file named will be attached to the standard input of the first
     process, standard output of the last process, or standard error of
     all processes, respectively.  If the same file is named for both
     output and error then it will be used for both.

‘OUTPUT_QUIET’, ‘ERROR_QUIET’

     The standard output or standard error results will be quietly
     ignored.

‘COMMAND_ECHO <where>’

     The command being run will be echo’ed to ‘<where>’ with ‘<where>’
     being set to one of ‘STDERR’, ‘STDOUT’ or ‘NONE’.  See the
     CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable for a way to
     control the default behavior when this option is not present.

‘ENCODING <name>’

     On Windows, the encoding that is used to decode output from the
     process.  Ignored on other platforms.  Valid encoding names are:

     ‘NONE’

          Perform no decoding.  This assumes that the process output is
          encoded in the same way as CMake’s internal encoding (UTF-8).
          This is the default.

     ‘AUTO’

          Use the current active console’s codepage or if that isn’t
          available then use ANSI.

     ‘ANSI’

          Use the ANSI codepage.

     ‘OEM’

          Use the original equipment manufacturer (OEM) code page.

     ‘UTF8’ or ‘UTF-8’

          Use the UTF-8 codepage.  Prior to CMake 3.11.0, only ‘UTF8’
          was accepted for this encoding.  In CMake 3.11.0, ‘UTF-8’ was
          added for consistency with the UTF-8 RFC(1) naming convention.

‘ECHO_OUTPUT_VARIABLE’, ‘ECHO_ERROR_VARIABLE’

     The standard output or standard error will not be exclusively
     redirected to the configured variables.

     The output will be duplicated, it will be sent into the configured
     variables and also on standard output or standard error.

     This is analogous to the ‘tee’ Unix command.

‘COMMAND_ERROR_IS_FATAL <ANY|LAST>’

     The option following ‘COMMAND_ERROR_IS_FATAL’ determines the
     behavior when an error is encountered:

          ‘ANY’ If any of the commands in the list of commands fail, the
          ‘execute_process()’ command halts with an error.

          ‘LAST’ If the last command in the list of commands fails, the
          ‘execute_process()’ command halts with an error.  Commands
          earlier in the list will not cause a fatal error.

If more than one ‘OUTPUT_*’ or ‘ERROR_*’ option is given for the same
pipe the precedence is not specified.  If no ‘OUTPUT_*’ or ‘ERROR_*’
options are given the output will be shared with the corresponding pipes
of the CMake process itself.

The execute_process() command is a newer more powerful
version of exec_program(), but the old command has been kept
for compatibility.  Both commands run while CMake is processing the
project prior to build system generation.  Use
add_custom_target() and add_custom_command() to create
custom commands that run at build time.

   ---------- Footnotes ----------

   (1) https://www.ietf.org/rfc/rfc3629

7.1.17 file
-----------

File manipulation command.

7.1.17.1 Synopsis
.................

     See Reading.
       file(see READ. <filename> <out-var> [...])
       file(see STRINGS. <filename> <out-var> [...])
       file(see <HASH>.<filename> <out-var>)
       file(see TIMESTAMP. <filename> <out-var> [...])
       file(see GET_RUNTIME_DEPENDENCIES. [...])

     See Writing.
       file({see WRITE. | See APPEND.} <filename> <content>...)
       file({see TOUCH. | See TOUCH_NOCREATE.} [<file>...])
       file(see GENERATE. OUTPUT <output-file> [...])
       file(see CONFIGURE. OUTPUT <output-file> CONTENT <content> [...])

     See Filesystem.
       file({see GLOB. | See GLOB_RECURSE.} <out-var> [...] [<globbing-expr>...])
       file(see RENAME. <oldname> <newname>)
       file({see REMOVE. | See REMOVE_RECURSE. } [<files>...])
       file(see MAKE_DIRECTORY. [<dir>...])
       file({see COPY. | See INSTALL.} <file>... DESTINATION <dir> [...])
       file(see SIZE. <filename> <out-var>)
       file(see READ_SYMLINK. <linkname> <out-var>)
       file(see CREATE_LINK. <original> <linkname> [...])
       file(see CHMOD. <files>... <directories>... PERMISSIONS <permissions>... [...])
       file(see CHMOD_RECURSE. <files>... <directories>... PERMISSIONS <permissions>... [...])

     See Path Conversion.
       file(see REAL_PATH. <path> <out-var> [BASE_DIRECTORY <dir>])
       file(see RELATIVE_PATH. <out-var> <directory> <file>)
       file({see TO_CMAKE_PATH. | See TO_NATIVE_PATH.} <path> <out-var>)

     See Transfer.
       file(see DOWNLOAD. <url> [<file>] [...])
       file(see UPLOAD. <file> <url> [...])

     See Locking.
       file(see LOCK. <path> [...])

     See Archiving.
       file(see ARCHIVE_CREATE. OUTPUT <archive> PATHS <paths>... [...])
       file(see ARCHIVE_EXTRACT. INPUT <archive> [...])

7.1.17.2 Reading
................

     file(READ <filename> <variable>
          [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Read content from a file called ‘<filename>’ and store it in a
‘<variable>’.  Optionally start from the given ‘<offset>’ and read at
most ‘<max-in>’ bytes.  The ‘HEX’ option causes data to be converted to
a hexadecimal representation (useful for binary data).  If the ‘HEX’
option is specified, letters in the output (‘a’ through ‘f’) are in
lowercase.
     file(STRINGS <filename> <variable> [<options>...])

Parse a list of ASCII strings from ‘<filename>’ and store it in
‘<variable>’.  Binary data in the file are ignored.  Carriage return
(‘\r’, CR) characters are ignored.  The options are:

‘LENGTH_MAXIMUM <max-len>’

     Consider only strings of at most a given length.

‘LENGTH_MINIMUM <min-len>’

     Consider only strings of at least a given length.

‘LIMIT_COUNT <max-num>’

     Limit the number of distinct strings to be extracted.

‘LIMIT_INPUT <max-in>’

     Limit the number of input bytes to read from the file.

‘LIMIT_OUTPUT <max-out>’

     Limit the number of total bytes to store in the ‘<variable>’.

‘NEWLINE_CONSUME’

     Treat newline characters (‘\n’, LF) as part of string content
     instead of terminating at them.

‘NO_HEX_CONVERSION’

     Intel Hex and Motorola S-record files are automatically converted
     to binary while reading unless this option is given.

‘REGEX <regex>’

     Consider only strings that match the given regular expression.

‘ENCODING <encoding-type>’

     Consider strings of a given encoding.  Currently supported
     encodings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If
     the ENCODING option is not provided and the file has a Byte Order
     Mark, the ENCODING option will be defaulted to respect the Byte
     Order Mark.

For example, the code

     file(STRINGS myfile.txt myfile)

stores a list in the variable ‘myfile’ in which each item is a line from
the input file.

     file(<HASH> <filename> <variable>)

Compute a cryptographic hash of the content of ‘<filename>’ and store it
in a ‘<variable>’.  The supported ‘<HASH>’ algorithm names are those
listed by the string(<HASH>) command.
     file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Compute a string representation of the modification time of ‘<filename>’
and store it in ‘<variable>’.  Should the command be unable to obtain a
timestamp variable will be set to the empty string (“”).

See the string(TIMESTAMP) command for documentation of the
‘<format>’ and ‘UTC’ options.
     file(GET_RUNTIME_DEPENDENCIES
       [RESOLVED_DEPENDENCIES_VAR <deps_var>]
       [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
       [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
       [EXECUTABLES [<executable_files>...]]
       [LIBRARIES [<library_files>...]]
       [MODULES [<module_files>...]]
       [DIRECTORIES [<directories>...]]
       [BUNDLE_EXECUTABLE <bundle_executable_file>]
       [PRE_INCLUDE_REGEXES [<regexes>...]]
       [PRE_EXCLUDE_REGEXES [<regexes>...]]
       [POST_INCLUDE_REGEXES [<regexes>...]]
       [POST_EXCLUDE_REGEXES [<regexes>...]]
       )

Recursively get the list of libraries depended on by the given files.

Please note that this sub-command is not intended to be used in project
mode.  Instead, use it in an install(CODE) or
install(SCRIPT) block.  For example:

     install(CODE [[
       file(GET_RUNTIME_DEPENDENCIES
         # ...
         )
       ]])

The arguments are as follows:

‘RESOLVED_DEPENDENCIES_VAR <deps_var>’

     Name of the variable in which to store the list of resolved
     dependencies.

‘UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>’

     Name of the variable in which to store the list of unresolved
     dependencies.  If this variable is not specified, and there are any
     unresolved dependencies, an error is issued.

‘CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>’

     Variable prefix in which to store conflicting dependency
     information.  Dependencies are conflicting if two files with the
     same name are found in two different directories.  The list of
     filenames that conflict are stored in
     ‘<conflicting_deps_prefix>_FILENAMES’.  For each filename, the list
     of paths that were found for that filename are stored in
     ‘<conflicting_deps_prefix>_<filename>’.

‘EXECUTABLES <executable_files>’

     List of executable files to read for dependencies.  These are
     executables that are typically created with add_executable(),
     but they do not have to be created by CMake.  On Apple
     platforms, the paths to these files determine the value of
     ‘@executable_path’ when recursively resolving the libraries.
     Specifying any kind of library (‘STATIC’, ‘MODULE’, or ‘SHARED’)
     here will result in undefined behavior.

‘LIBRARIES <library_files>’

     List of library files to read for dependencies.  These are
     libraries that are typically created with
     add_library(SHARED), but they do not have to be created by
     CMake.  Specifying ‘STATIC’ libraries, ‘MODULE’ libraries, or
     executables here will result in undefined behavior.

‘MODULES <module_files>’

     List of loadable module files to read for dependencies.  These are
     modules that are typically created with add_library(MODULE),
     but they do not have to be created by CMake.  They are
     typically used by calling ‘dlopen()’ at runtime rather than linked
     at link time with ‘ld -l’.  Specifying ‘STATIC’ libraries, ‘SHARED’
     libraries, or executables here will result in undefined behavior.

‘DIRECTORIES <directories>’

     List of additional directories to search for dependencies.  On
     Linux platforms, these directories are searched if the dependency
     is not found in any of the other usual paths.  If it is found in
     such a directory, a warning is issued, because it means that the
     file is incomplete (it does not list all of the directories that
     contain its dependencies).  On Windows platforms, these directories
     are searched if the dependency is not found in any of the other
     search paths, but no warning is issued, because searching other
     paths is a normal part of Windows dependency resolution.  On Apple
     platforms, this argument has no effect.

‘BUNDLE_EXECUTABLE <bundle_executable_file>’

     Executable to treat as the “bundle executable” when resolving
     libraries.  On Apple platforms, this argument determines the value
     of ‘@executable_path’ when recursively resolving libraries for
     ‘LIBRARIES’ and ‘MODULES’ files.  It has no effect on ‘EXECUTABLES’
     files.  On other platforms, it has no effect.  This is typically
     (but not always) one of the executables in the ‘EXECUTABLES’
     argument which designates the “main” executable of the package.

The following arguments specify filters for including or excluding
libraries to be resolved.  See below for a full description of how they
work.

‘PRE_INCLUDE_REGEXES <regexes>’

     List of pre-include regexes through which to filter the names of
     not-yet-resolved dependencies.

‘PRE_EXCLUDE_REGEXES <regexes>’

     List of pre-exclude regexes through which to filter the names of
     not-yet-resolved dependencies.

‘POST_INCLUDE_REGEXES <regexes>’

     List of post-include regexes through which to filter the names of
     resolved dependencies.

‘POST_EXCLUDE_REGEXES <regexes>’

     List of post-exclude regexes through which to filter the names of
     resolved dependencies.

These arguments can be used to exclude unwanted system libraries when
resolving the dependencies, or to include libraries from a specific
directory.  The filtering works as follows:

  1. If the not-yet-resolved dependency matches any of the
     ‘PRE_INCLUDE_REGEXES’, steps 2 and 3 are skipped, and the
     dependency resolution proceeds to step 4.

  2. If the not-yet-resolved dependency matches any of the
     ‘PRE_EXCLUDE_REGEXES’, dependency resolution stops for that
     dependency.

  3. Otherwise, dependency resolution proceeds.

  4. ‘file(GET_RUNTIME_DEPENDENCIES)’ searches for the dependency
     according to the linking rules of the platform (see below).

  5. If the dependency is found, and its full path matches one of the
     ‘POST_INCLUDE_REGEXES’, the full path is added to the resolved
     dependencies, and ‘file(GET_RUNTIME_DEPENDENCIES)’ recursively
     resolves that library’s own dependencies.  Otherwise, resolution
     proceeds to step 6.

  6. If the dependency is found, but its full path matches one of the
     ‘POST_EXCLUDE_REGEXES’, it is not added to the resolved
     dependencies, and dependency resolution stops for that dependency.

  7. If the dependency is found, and its full path does not match either
     ‘POST_INCLUDE_REGEXES’ or ‘POST_EXCLUDE_REGEXES’, the full path is
     added to the resolved dependencies, and
     ‘file(GET_RUNTIME_DEPENDENCIES)’ recursively resolves that
     library’s own dependencies.

Different platforms have different rules for how dependencies are
resolved.  These specifics are described here.

On Linux platforms, library resolution works as follows:

  1. If the depending file does not have any ‘RUNPATH’ entries, and the
     library exists in one of the depending file’s ‘RPATH’ entries, or
     its parents’, in that order, the dependency is resolved to that
     file.

  2. Otherwise, if the depending file has any ‘RUNPATH’ entries, and the
     library exists in one of those entries, the dependency is resolved
     to that file.

  3. Otherwise, if the library exists in one of the directories listed
     by ‘ldconfig’, the dependency is resolved to that file.

  4. Otherwise, if the library exists in one of the ‘DIRECTORIES’
     entries, the dependency is resolved to that file.  In this case, a
     warning is issued, because finding a file in one of the
     ‘DIRECTORIES’ means that the depending file is not complete (it
     does not list all the directories from which it pulls
     dependencies).

  5. Otherwise, the dependency is unresolved.

On Windows platforms, library resolution works as follows:

  1. The dependent DLL name is converted to lowercase.  Windows DLL
     names are case-insensitive, and some linkers mangle the case of the
     DLL dependency names.  However, this makes it more difficult for
     ‘PRE_INCLUDE_REGEXES’, ‘PRE_EXCLUDE_REGEXES’,
     ‘POST_INCLUDE_REGEXES’, and ‘POST_EXCLUDE_REGEXES’ to properly
     filter DLL names - every regex would have to check for both
     uppercase and lowercase letters.  For example:

          file(GET_RUNTIME_DEPENDENCIES
            # ...
            PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
            )

     Converting the DLL name to lowercase allows the regexes to only
     match lowercase names, thus simplifying the regex.  For example:

          file(GET_RUNTIME_DEPENDENCIES
            # ...
            PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
            )

     This regex will match ‘mylibrary.dll’ regardless of how it is
     cased, either on disk or in the depending file.  (For example, it
     will match ‘mylibrary.dll’, ‘MyLibrary.dll’, and ‘MYLIBRARY.DLL’.)

     Please note that the directory portion of any resolved DLLs retains
     its casing and is not converted to lowercase.  Only the filename
     portion is converted.

  2. (`Not yet implemented') If the depending file is a Windows Store
     app, and the dependency is listed as a dependency in the
     application’s package manifest, the dependency is resolved to that
     file.

  3. Otherwise, if the library exists in the same directory as the
     depending file, the dependency is resolved to that file.

  4. Otherwise, if the library exists in either the operating system’s
     ‘system32’ directory or the ‘Windows’ directory, in that order, the
     dependency is resolved to that file.

  5. Otherwise, if the library exists in one of the directories
     specified by ‘DIRECTORIES’, in the order they are listed, the
     dependency is resolved to that file.  In this case, a warning is
     not issued, because searching other directories is a normal part of
     Windows library resolution.

  6. Otherwise, the dependency is unresolved.

On Apple platforms, library resolution works as follows:

  1. If the dependency starts with ‘@executable_path/’, and an
     ‘EXECUTABLES’ argument is in the process of being resolved, and
     replacing ‘@executable_path/’ with the directory of the executable
     yields an existing file, the dependency is resolved to that file.

  2. Otherwise, if the dependency starts with ‘@executable_path/’, and
     there is a ‘BUNDLE_EXECUTABLE’ argument, and replacing
     ‘@executable_path/’ with the directory of the bundle executable
     yields an existing file, the dependency is resolved to that file.

  3. Otherwise, if the dependency starts with ‘@loader_path/’, and
     replacing ‘@loader_path/’ with the directory of the depending file
     yields an existing file, the dependency is resolved to that file.

  4. Otherwise, if the dependency starts with ‘@rpath/’, and replacing
     ‘@rpath/’ with one of the ‘RPATH’ entries of the depending file
     yields an existing file, the dependency is resolved to that file.
     Note that ‘RPATH’ entries that start with ‘@executable_path/’ or
     ‘@loader_path/’ also have these items replaced with the appropriate
     path.

  5. Otherwise, if the dependency is an absolute file that exists, the
     dependency is resolved to that file.

  6. Otherwise, the dependency is unresolved.

This function accepts several variables that determine which tool is
used for dependency resolution:

 -- Variable: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

     Determines which operating system and executable format the files
     are built for.  This could be one of several values:

        * ‘linux+elf’

        * ‘windows+pe’

        * ‘macos+macho’

     If this variable is not specified, it is determined automatically
     by system introspection.

 -- Variable: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

     Determines the tool to use for dependency resolution.  It could be
     one of several values, depending on the value of
     CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM.:

     ‘CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM’             ‘CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL’

     --------------------------------------------------------------------------------------------------------

     ‘linux+elf’                                           ‘objdump’

     ‘windows+pe’                                          ‘dumpbin’

     ‘windows+pe’                                          ‘objdump’

     ‘macos+macho’                                         ‘otool’

     If this variable is not specified, it is determined automatically
     by system introspection.

 -- Variable: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

     Determines the path to the tool to use for dependency resolution.
     This is the actual path to ‘objdump’, ‘dumpbin’, or ‘otool’.

     If this variable is not specified, it is determined by the value of
     ‘CMAKE_OBJDUMP’ if set, else by system introspection.

7.1.17.3 Writing
................

     file(WRITE <filename> <content>...)
     file(APPEND <filename> <content>...)

Write ‘<content>’ into a file called ‘<filename>’.  If the file does not
exist, it will be created.  If the file already exists, ‘WRITE’ mode
will overwrite it and ‘APPEND’ mode will append to the end.  Any
directories in the path specified by ‘<filename>’ that do not exist will
be created.

If the file is a build input, use the configure_file().
command to update the file only when its content changes.
     file(TOUCH [<files>...])
     file(TOUCH_NOCREATE [<files>...])

Create a file with no content if it does not yet exist.  If the file
already exists, its access and/or modification will be updated to the
time when the function call is executed.

Use TOUCH_NOCREATE to touch a file if it exists but not create it.  If a
file does not exist it will be silently ignored.

With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
be modified.
     file(GENERATE OUTPUT output-file
          <INPUT input-file|CONTENT content>
          [CONDITION expression] [TARGET target])

Generate an output file for each build configuration supported by the
current CMake Generator.  Evaluate generator expressions
from the input content to produce the output content.
The options are:

‘CONDITION <condition>’

     Generate the output file for a particular configuration only if the
     condition is true.  The condition must be either ‘0’ or ‘1’ after
     evaluating generator expressions.

‘CONTENT <content>’

     Use the content given explicitly as input.

‘INPUT <input-file>’

     Use the content from a given file as input.  A relative path is
     treated with respect to the value of
     CMAKE_CURRENT_SOURCE_DIR.  See policy CMP0070.

‘OUTPUT <output-file>’

     Specify the output file name to generate.  Use generator
     expressions such as ‘$<CONFIG>’ to specify a configuration-specific
     output file name.  Multiple configurations may generate the same
     output file only if the generated content is identical.  Otherwise,
     the ‘<output-file>’ must evaluate to an unique name for each
     configuration.  A relative path (after evaluating generator
     expressions) is treated with respect to the value of
     CMAKE_CURRENT_BINARY_DIR.  See policy CMP0070.

‘TARGET <target>’

     Specify which target to use when evaluating generator expressions
     that require a target for evaluation (e.g.
     ‘$<COMPILE_FEATURES:...>’, ‘$<TARGET_PROPERTY:prop>’).

Exactly one ‘CONTENT’ or ‘INPUT’ option must be given.  A specific
‘OUTPUT’ file may be named by at most one invocation of
‘file(GENERATE)’.  Generated files are modified and their timestamp
updated on subsequent cmake runs only if their content is changed.

Note also that ‘file(GENERATE)’ does not create the output file until
the generation phase.  The output file will not yet have been written
when the ‘file(GENERATE)’ command returns, it is written only after
processing all of a project’s ‘CMakeLists.txt’ files.
     file(CONFIGURE OUTPUT output-file
          CONTENT content
          [ESCAPE_QUOTES] [@ONLY]
          [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Generate an output file using the input given by ‘CONTENT’ and
substitute variable values referenced as ‘@VAR@’ or ‘${VAR}’ contained
therein.  The substitution rules behave the same as the
configure_file() command.  In order to match
configure_file().’s behavior, generator expressions are not
supported for both ‘OUTPUT’ and ‘CONTENT’.

The arguments are:

‘OUTPUT <output-file>’

     Specify the output file name to generate.  A relative path is
     treated with respect to the value of
     CMAKE_CURRENT_BINARY_DIR.  ‘<output-file>’ does not support
     generator expressions.

‘CONTENT <content>’

     Use the content given explicitly as input.  ‘<content>’ does not
     support generator expressions.

‘ESCAPE_QUOTES’

     Escape any substituted quotes with backslashes (C-style).

‘@ONLY’

     Restrict variable replacement to references of the form ‘@VAR@’.
     This is useful for configuring scripts that use ‘${VAR}’ syntax.

‘NEWLINE_STYLE <style>’

     Specify the newline style for the output file.  Specify ‘UNIX’ or
     ‘LF’ for ‘\n’ newlines, or specify ‘DOS’, ‘WIN32’, or ‘CRLF’ for
     ‘\r\n’ newlines.

7.1.17.4 Filesystem
...................

     file(GLOB <variable>
          [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
          [<globbing-expressions>...])
     file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
          [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
          [<globbing-expressions>...])

Generate a list of files that match the ‘<globbing-expressions>’ and
store it into the ‘<variable>’.  Globbing expressions are similar to
regular expressions, but much simpler.  If ‘RELATIVE’ flag is specified,
the results will be returned as relative paths to the given path.  The
results will be ordered lexicographically.

On Windows and macOS, globbing is case-insensitive even if the
underlying filesystem is case-sensitive (both filenames and globbing
expressions are converted to lowercase before matching).  On other
platforms, globbing is case-sensitive.

If the ‘CONFIGURE_DEPENDS’ flag is specified, CMake will add logic to
the main build system check target to rerun the flagged ‘GLOB’ commands
at build time.  If any of the outputs change, CMake will regenerate the
build system.

By default ‘GLOB’ lists directories - directories are omitted in result
if ‘LIST_DIRECTORIES’ is set to false.

     Note: We do not recommend using GLOB to collect a list of source
     files from your source tree.  If no CMakeLists.txt file changes
     when a source is added or removed then the generated build system
     cannot know when to ask CMake to regenerate.  The
     ‘CONFIGURE_DEPENDS’ flag may not work reliably on all generators,
     or if a new generator is added in the future that cannot support
     it, projects using it will be stuck.  Even if ‘CONFIGURE_DEPENDS’
     works reliably, there is still a cost to perform the check on every
     rebuild.

Examples of globbing expressions include:

     *.cxx      - match all files with extension cxx
     *.vt?      - match all files with extension vta,...,vtz
     f[3-5].txt - match files f3.txt, f4.txt, f5.txt

The ‘GLOB_RECURSE’ mode will traverse all the subdirectories of the
matched directory and match the files.  Subdirectories that are symlinks
are only traversed if ‘FOLLOW_SYMLINKS’ is given or policy
CMP0009 is not set to ‘NEW’.

By default ‘GLOB_RECURSE’ omits directories from result list - setting
‘LIST_DIRECTORIES’ to true adds directories to result list.  If
‘FOLLOW_SYMLINKS’ is given or policy CMP0009 is not set to
‘NEW’ then ‘LIST_DIRECTORIES’ treats symlinks as directories.

Examples of recursive globbing include:

     /dir/*.py  - match all python files in /dir and subdirectories
     file(RENAME <oldname> <newname>)

Move a file or directory within a filesystem from ‘<oldname>’ to
‘<newname>’, replacing the destination atomically.
     file(REMOVE [<files>...])
     file(REMOVE_RECURSE [<files>...])

Remove the given files.  The ‘REMOVE_RECURSE’ mode will remove the given
files and directories, also non-empty directories.  No error is emitted
if a given file does not exist.  Relative input paths are evaluated with
respect to the current source directory.  Empty input paths are ignored
with a warning.
     file(MAKE_DIRECTORY [<directories>...])

Create the given directories and their parents as needed.
     file(<COPY|INSTALL> <files>... DESTINATION <dir>
          [FILE_PERMISSIONS <permissions>...]
          [DIRECTORY_PERMISSIONS <permissions>...]
          [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
          [FOLLOW_SYMLINK_CHAIN]
          [FILES_MATCHING]
          [[PATTERN <pattern> | REGEX <regex>]
           [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

The ‘COPY’ signature copies files, directories, and symlinks to a
destination folder.  Relative input paths are evaluated with respect to
the current source directory, and a relative destination is evaluated
with respect to the current build directory.  Copying preserves input
file timestamps, and optimizes out a file if it exists at the
destination with the same timestamp.  Copying preserves input
permissions unless explicit permissions or ‘NO_SOURCE_PERMISSIONS’ are
given (default is ‘USE_SOURCE_PERMISSIONS’).

If ‘FOLLOW_SYMLINK_CHAIN’ is specified, ‘COPY’ will recursively resolve
the symlinks at the paths given until a real file is found, and install
a corresponding symlink in the destination for each symlink encountered.
For each symlink that is installed, the resolution is stripped of the
directory, leaving only the filename, meaning that the new symlink
points to a file in the same directory as the symlink.  This feature is
useful on some Unix systems, where libraries are installed as a chain of
symlinks with version numbers, with less specific versions pointing to
more specific versions.  ‘FOLLOW_SYMLINK_CHAIN’ will install all of
these symlinks and the library itself into the destination directory.
For example, if you have the following directory structure:

   * ‘/opt/foo/lib/libfoo.so.1.2.3’

   * ‘/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3’

   * ‘/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2’

   * ‘/opt/foo/lib/libfoo.so -> libfoo.so.1’

and you do:

     file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

This will install all of the symlinks and ‘libfoo.so.1.2.3’ itself into
‘lib’.

See the install(DIRECTORY) command for documentation of
permissions, ‘FILES_MATCHING’, ‘PATTERN’, ‘REGEX’, and ‘EXCLUDE’
options.  Copying directories preserves the structure of their content
even if options are used to select a subset of files.

The ‘INSTALL’ signature differs slightly from ‘COPY’: it prints status
messages (subject to the CMAKE_INSTALL_MESSAGE variable),
and ‘NO_SOURCE_PERMISSIONS’ is default.  Installation scripts generated
by the install() command use this signature (with some
undocumented options for internal use).
     file(SIZE <filename> <variable>)

Determine the file size of the ‘<filename>’ and put the result in
‘<variable>’ variable.  Requires that ‘<filename>’ is a valid path
pointing to a file and is readable.
     file(READ_SYMLINK <linkname> <variable>)

This subcommand queries the symlink ‘<linkname>’ and stores the path it
points to in the result ‘<variable>’.  If ‘<linkname>’ does not exist or
is not a symlink, CMake issues a fatal error.

Note that this command returns the raw symlink path and does not resolve
a relative path.  The following is an example of how to ensure that an
absolute path is obtained:

     set(linkname "/path/to/foo.sym")
     file(READ_SYMLINK "${linkname}" result)
     if(NOT IS_ABSOLUTE "${result}")
       get_filename_component(dir "${linkname}" DIRECTORY)
       set(result "${dir}/${result}")
     endif()
     file(CREATE_LINK <original> <linkname>
          [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

Create a link ‘<linkname>’ that points to ‘<original>’.  It will be a
hard link by default, but providing the ‘SYMBOLIC’ option results in a
symbolic link instead.  Hard links require that ‘original’ exists and is
a file, not a directory.  If ‘<linkname>’ already exists, it will be
overwritten.

The ‘<result>’ variable, if specified, receives the status of the
operation.  It is set to ‘0’ upon success or an error message otherwise.
If ‘RESULT’ is not specified and the operation fails, a fatal error is
emitted.

Specifying ‘COPY_ON_ERROR’ enables copying the file as a fallback if
creating the link fails.  It can be useful for handling situations such
as ‘<original>’ and ‘<linkname>’ being on different drives or mount
points, which would make them unable to support a hard link.
     file(CHMOD <files>... <directories>...
         [PERMISSIONS <permissions>...]
         [FILE_PERMISSIONS <permissions>...]
         [DIRECTORY_PERMISSIONS <permissions>...])

Set the permissions for the ‘<files>...’ and ‘<directories>...’
specified.  Valid permissions are ‘OWNER_READ’, ‘OWNER_WRITE’,
‘OWNER_EXECUTE’, ‘GROUP_READ’, ‘GROUP_WRITE’, ‘GROUP_EXECUTE’,
‘WORLD_READ’, ‘WORLD_WRITE’, ‘WORLD_EXECUTE’.

Valid combination of keywords are:

‘PERMISSIONS’

     All items are changed.

‘FILE_PERMISSIONS’

     Only files are changed.

‘DIRECTORY_PERMISSIONS’

     Only directories are changed.

‘PERMISSIONS’ and ‘FILE_PERMISSIONS’

     ‘FILE_PERMISSIONS’ overrides ‘PERMISSIONS’ for files.

‘PERMISSIONS’ and ‘DIRECTORY_PERMISSIONS’

     ‘DIRECTORY_PERMISSIONS’ overrides ‘PERMISSIONS’ for directories.

‘FILE_PERMISSIONS’ and ‘DIRECTORY_PERMISSIONS’

     Use ‘FILE_PERMISSIONS’ for files and ‘DIRECTORY_PERMISSIONS’ for
     directories.
     file(CHMOD_RECURSE <files>... <directories>...
          [PERMISSIONS <permissions>...]
          [FILE_PERMISSIONS <permissions>...]
          [DIRECTORY_PERMISSIONS <permissions>...])

Same as CHMOD, but change the permissions of files and
directories present in the ‘<directories>...’ recursively.

7.1.17.5 Path Conversion
........................

     file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])

Compute the absolute path to an existing file or directory with symlinks
resolved.

If the provided ‘<path>’ is a relative path, it is evaluated relative to
the given base directory ‘<dir>’.  If no base directory is provided, the
default base directory will be CMAKE_CURRENT_SOURCE_DIR.
     file(RELATIVE_PATH <variable> <directory> <file>)

Compute the relative path from a ‘<directory>’ to a ‘<file>’ and store
it in the ‘<variable>’.
     file(TO_CMAKE_PATH "<path>" <variable>)
     file(TO_NATIVE_PATH "<path>" <variable>)

The ‘TO_CMAKE_PATH’ mode converts a native ‘<path>’ into a cmake-style
path with forward-slashes (‘/’).  The input can be a single path or a
system search path like ‘$ENV{PATH}’.  A search path will be converted
to a cmake-style list separated by ‘;’ characters.

The ‘TO_NATIVE_PATH’ mode converts a cmake-style ‘<path>’ into a native
path with platform-specific slashes (‘\’ on Windows and ‘/’ elsewhere).

Always use double quotes around the ‘<path>’ to be sure it is treated as
a single argument to this command.

7.1.17.6 Transfer
.................

     file(DOWNLOAD <url> [<file>] [<options>...])
     file(UPLOAD   <file> <url> [<options>...])

The ‘DOWNLOAD’ subcommand downloads the given ‘<url>’ to a local
‘<file>’.  If ‘<file>’ is not specified for ‘file(DOWNLOAD)’, the file
is not saved.  This can be useful if you want to know if a file can be
downloaded (for example, to check that it exists) without actually
saving it anywhere.  The ‘UPLOAD’ mode uploads a local ‘<file>’ to a
given ‘<url>’.

Options to both ‘DOWNLOAD’ and ‘UPLOAD’ are:

‘INACTIVITY_TIMEOUT <seconds>’

     Terminate the operation after a period of inactivity.

‘LOG <variable>’

     Store a human-readable log of the operation in a variable.

‘SHOW_PROGRESS’

     Print progress information as status messages until the operation
     is complete.

‘STATUS <variable>’

     Store the resulting status of the operation in a variable.  The
     status is a ‘;’ separated list of length 2.  The first element is
     the numeric return value for the operation, and the second element
     is a string value for the error.  A ‘0’ numeric error means no
     error in the operation.

‘TIMEOUT <seconds>’

     Terminate the operation after a given total time has elapsed.

‘USERPWD <username>:<password>’

     Set username and password for operation.

‘HTTPHEADER <HTTP-header>’

     HTTP header for operation.  Suboption can be repeated several
     times.

‘NETRC <level>’

     Specify whether the .netrc file is to be used for operation.  If
     this option is not specified, the value of the ‘CMAKE_NETRC’
     variable will be used instead.  Valid levels are:

     ‘IGNORED’

          The .netrc file is ignored.  This is the default.

     ‘OPTIONAL’

          The .netrc file is optional, and information in the URL is
          preferred.  The file will be scanned to find which ever
          information is not specified in the URL.

     ‘REQUIRED’

          The .netrc file is required, and information in the URL is
          ignored.

‘NETRC_FILE <file>’

     Specify an alternative .netrc file to the one in your home
     directory, if the ‘NETRC’ level is ‘OPTIONAL’ or ‘REQUIRED’.  If
     this option is not specified, the value of the ‘CMAKE_NETRC_FILE’
     variable will be used instead.

If neither ‘NETRC’ option is given CMake will check variables
‘CMAKE_NETRC’ and ‘CMAKE_NETRC_FILE’, respectively.

‘TLS_VERIFY <ON|OFF>’

     Specify whether to verify the server certificate for ‘https://’
     URLs.  The default is to `not' verify.

‘TLS_CAINFO <file>’

     Specify a custom Certificate Authority file for ‘https://’ URLs.

For ‘https://’ URLs CMake must be built with OpenSSL support.  ‘TLS/SSL’
certificates are not checked by default.  Set ‘TLS_VERIFY’ to ‘ON’ to
check certificates.  If neither ‘TLS’ option is given CMake will check
variables ‘CMAKE_TLS_VERIFY’ and ‘CMAKE_TLS_CAINFO’, respectively.

Additional options to ‘DOWNLOAD’ are:

‘EXPECTED_HASH ALGO=<value>’

     Verify that the downloaded content hash matches the expected value,
     where ‘ALGO’ is one of the algorithms supported by ‘file(<HASH>)’.
     If it does not match, the operation fails with an error.  It is an
     error to specify this if ‘DOWNLOAD’ is not given a ‘<file>’.

‘EXPECTED_MD5 <value>’

     Historical short-hand for ‘EXPECTED_HASH MD5=<value>’.  It is an
     error to specify this if ‘DOWNLOAD’ is not given a ‘<file>’.

7.1.17.7 Locking
................

     file(LOCK <path> [DIRECTORY] [RELEASE]
          [GUARD <FUNCTION|FILE|PROCESS>]
          [RESULT_VARIABLE <variable>]
          [TIMEOUT <seconds>])

Lock a file specified by ‘<path>’ if no ‘DIRECTORY’ option present and
file ‘<path>/cmake.lock’ otherwise.  File will be locked for scope
defined by ‘GUARD’ option (default value is ‘PROCESS’).  ‘RELEASE’
option can be used to unlock file explicitly.  If option ‘TIMEOUT’ is
not specified CMake will wait until lock succeed or until fatal error
occurs.  If ‘TIMEOUT’ is set to ‘0’ lock will be tried once and result
will be reported immediately.  If ‘TIMEOUT’ is not ‘0’ CMake will try to
lock file for the period specified by ‘<seconds>’ value.  Any errors
will be interpreted as fatal if there is no ‘RESULT_VARIABLE’ option.
Otherwise result will be stored in ‘<variable>’ and will be ‘0’ on
success or error message on failure.

Note that lock is advisory - there is no guarantee that other processes
will respect this lock, i.e.  lock synchronize two or more CMake
instances sharing some modifiable resources.  Similar logic applied to
‘DIRECTORY’ option - locking parent directory doesn’t prevent other
‘LOCK’ commands to lock any child directory or file.

Trying to lock file twice is not allowed.  Any intermediate directories
and file itself will be created if they not exist.  ‘GUARD’ and
‘TIMEOUT’ options ignored on ‘RELEASE’ operation.

7.1.17.8 Archiving
..................

     file(ARCHIVE_CREATE OUTPUT <archive>
       PATHS <paths>...
       [FORMAT <format>]
       [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
       [MTIME <mtime>]
       [VERBOSE])

Creates the specified ‘<archive>’ file with the files and directories
listed in ‘<paths>’.  Note that ‘<paths>’ must list actual files or
directories, wildcards are not supported.

Use the ‘FORMAT’ option to specify the archive format.  Supported values
for ‘<format>’ are ‘7zip’, ‘gnutar’, ‘pax’, ‘paxr’, ‘raw’ and ‘zip’.  If
‘FORMAT’ is not given, the default format is ‘paxr’.

Some archive formats allow the type of compression to be specified.  The
‘7zip’ and ‘zip’ archive formats already imply a specific type of
compression.  The other formats use no compression by default, but can
be directed to do so with the ‘COMPRESSION’ option.  Valid values for
‘<compression>’ are ‘None’, ‘BZip2’, ‘GZip’, ‘XZ’, and ‘Zstd’.

The compression level can be specified with the ‘COMPRESSION_LEVEL’
option.  The ‘<compression-level>’ should be between 0-9, with the
default being 0.  The ‘COMPRESSION’ option must be present when
‘COMPRESSION_LEVEL’ is given.

     Note: With ‘FORMAT’ set to ‘raw’ only one file will be compressed
     with the compression type specified by ‘COMPRESSION’.

The ‘VERBOSE’ option enables verbose output for the archive operation.

To specify the modification time recorded in tarball entries, use the
‘MTIME’ option.
     file(ARCHIVE_EXTRACT INPUT <archive>
       [DESTINATION <dir>]
       [PATTERNS <patterns>...]
       [LIST_ONLY]
       [VERBOSE])

Extracts or lists the content of the specified ‘<archive>’.

The directory where the content of the archive will be extracted to can
be specified using the ‘DESTINATION’ option.  If the directory does not
exist, it will be created.  If ‘DESTINATION’ is not given, the current
binary directory will be used.

If required, you may select which files and directories to list or
extract from the archive using the specified ‘<patterns>’.  Wildcards
are supported.  If the ‘PATTERNS’ option is not given, the entire
archive will be listed or extracted.

‘LIST_ONLY’ will list the files in the archive rather than extract them.

With ‘VERBOSE’, the command will produce verbose output.

7.1.18 find_file
----------------

A short-hand signature is:

     find_file (<VAR> name1 [path1 path2 ...])

The general signature is:

     find_file (
               <VAR>
               name | NAMES name1 [name2 ...]
               [HINTS path1 [path2 ... ENV var]]
               [PATHS path1 [path2 ... ENV var]]
               [PATH_SUFFIXES suffix1 [suffix2 ...]]
               [DOC "cache documentation string"]
               [REQUIRED]
               [NO_DEFAULT_PATH]
               [NO_PACKAGE_ROOT_PATH]
               [NO_CMAKE_PATH]
               [NO_CMAKE_ENVIRONMENT_PATH]
               [NO_SYSTEM_ENVIRONMENT_PATH]
               [NO_CMAKE_SYSTEM_PATH]
               [CMAKE_FIND_ROOT_PATH_BOTH |
                ONLY_CMAKE_FIND_ROOT_PATH |
                NO_CMAKE_FIND_ROOT_PATH]
              )

This command is used to find a full path to named file.  A cache entry
named by ‘<VAR>’ is created to store the result of this command.  If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared.  If
nothing is found, the result will be ‘<VAR>-NOTFOUND’.  The ‘REQUIRED’
option stops processing with an error message if nothing is found,
otherwise the search will be attempted again the next time find_file is
invoked with the same variable.

Options include:

‘NAMES’

     Specify one or more possible names for the full path to a file.

     When using this to specify names with and without a version suffix,
     we recommend specifying the unversioned name first so that
     locally-built packages can be found before those provided by
     distributions.

‘HINTS’, ‘PATHS’

     Specify directories to search in addition to the default locations.
     The ‘ENV var’ sub-option reads paths from a system environment
     variable.

‘PATH_SUFFIXES’

     Specify additional subdirectories to check below each directory
     location otherwise considered.

‘DOC’

     Specify the documentation string for the ‘<VAR>’ cache entry.

‘REQUIRED’

     Stop processing with an error message if nothing is found.

If ‘NO_DEFAULT_PATH’ is specified, then no additional paths are added to
the search.  If ‘NO_DEFAULT_PATH’ is not specified, the search process
is as follows:

  1. If called from within a find module or any other script loaded by a
     call to find_package(<PackageName>), search prefixes
     unique to the current package being found.  Specifically, look in
     the <PackageName>_ROOT. CMake variable and the
     <PackageName>_ROOT environment variable.  The package root
     variables are maintained as a stack, so if called from nested find
     modules or config packages, root paths from the parent’s find
     module or config package will be searched after paths from the
     current module or package.  In other words, the search order would
     be ‘<CurrentPackage>_ROOT’, ‘ENV{<CurrentPackage>_ROOT}’,
     ‘<ParentPackage>_ROOT’, ‘ENV{<ParentPackage>_ROOT}’, etc.  This can
     be skipped if ‘NO_PACKAGE_ROOT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_PACKAGE_ROOT_PATH to ‘FALSE’.  See
     policy CMP0074.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in the
          <PackageName>_ROOT. CMake variable and the
          <PackageName>_ROOT environment variable if called from
          within a find module loaded by
          find_package(<PackageName>).

  2. Search paths specified in cmake-specific cache variables.  These
     are intended to be used on the command line with a ‘-DVAR=value’.
     The values are interpreted as semicolon-separated lists.
     This can be skipped if ‘NO_CMAKE_PATH’ is passed or by setting the
     CMAKE_FIND_USE_CMAKE_PATH to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_INCLUDE_PATH.

        * CMAKE_FRAMEWORK_PATH.

  3. Search paths specified in cmake-specific environment variables.
     These are intended to be set in the user’s shell configuration, and
     therefore use the host’s native path separator (‘;’ on Windows and
     ‘:’ on UNIX). This can be skipped if ‘NO_CMAKE_ENVIRONMENT_PATH’ is
     passed or by setting the
     CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_INCLUDE_PATH.

        * CMAKE_FRAMEWORK_PATH.

  4. Search the paths specified by the ‘HINTS’ option.  These should be
     paths computed by system introspection, such as a hint provided by
     the location of another item already found.  Hard-coded guesses
     should be specified with the ‘PATHS’ option.

  5. Search the standard system environment variables.  This can be
     skipped if ‘NO_SYSTEM_ENVIRONMENT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to ‘FALSE’.

        * The directories in ‘PATH’ and ‘INCLUDE’.

        * On Windows hosts: ‘<prefix>/include/<arch>’ if
          CMAKE_LIBRARY_ARCHITECTURE is set, and
          ‘<prefix>/include’ for each ‘<prefix>/[s]bin’ in ‘PATH’, and
          ‘<entry>/include’ for other entries in ‘PATH’.

  6. Search cmake variables defined in the Platform files for the
     current system.  This can be skipped if ‘NO_CMAKE_SYSTEM_PATH’ is
     passed or by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
     to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_SYSTEM_PREFIX_PATH.

        * CMAKE_SYSTEM_INCLUDE_PATH.

        * CMAKE_SYSTEM_FRAMEWORK_PATH.

     The platform paths that these variables contain are locations that
     typically include installed software.  An example being
     ‘/usr/local’ for UNIX based platforms.

  7. Search the paths specified by the PATHS option or in the short-hand
     version of the command.  These are typically hard-coded guesses.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of preference
between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or
more directories to be prepended to all other search directories.  This
effectively “re-roots” the entire search under given locations.  Paths
which are descendants of the CMAKE_STAGING_PREFIX are
excluded from this re-rooting, because that variable is always a path on
the host system.  By default the CMAKE_FIND_ROOT_PATH is
empty.

The CMAKE_SYSROOT variable can also be used to specify
exactly one directory to use as a prefix.  Setting CMAKE_SYSROOT
also has other effects.  See the documentation for that variable
for more.

These variables are especially useful when cross-compiling to point to
the root directory of the target environment and CMake will search there
too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.  This behavior can be manually
overridden on a per-call basis using options:

‘CMAKE_FIND_ROOT_PATH_BOTH’

     Search in the order described above.

‘NO_CMAKE_FIND_ROOT_PATH’

     Do not use the CMAKE_FIND_ROOT_PATH variable.

‘ONLY_CMAKE_FIND_ROOT_PATH’

     Search only the re-rooted directories and directories below
     CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.  Projects may override the order by
simply calling the command multiple times and using the ‘NO_*’ options:

     find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
     find_file (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set and
stored in the cache so that no call will search again.

7.1.19 find_library
-------------------

A short-hand signature is:

     find_library (<VAR> name1 [path1 path2 ...])

The general signature is:

     find_library (
               <VAR>
               name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
               [HINTS path1 [path2 ... ENV var]]
               [PATHS path1 [path2 ... ENV var]]
               [PATH_SUFFIXES suffix1 [suffix2 ...]]
               [DOC "cache documentation string"]
               [REQUIRED]
               [NO_DEFAULT_PATH]
               [NO_PACKAGE_ROOT_PATH]
               [NO_CMAKE_PATH]
               [NO_CMAKE_ENVIRONMENT_PATH]
               [NO_SYSTEM_ENVIRONMENT_PATH]
               [NO_CMAKE_SYSTEM_PATH]
               [CMAKE_FIND_ROOT_PATH_BOTH |
                ONLY_CMAKE_FIND_ROOT_PATH |
                NO_CMAKE_FIND_ROOT_PATH]
              )

This command is used to find a library.  A cache entry named by ‘<VAR>’
is created to store the result of this command.  If the library is found
the result is stored in the variable and the search will not be repeated
unless the variable is cleared.  If nothing is found, the result will be
‘<VAR>-NOTFOUND’.  The ‘REQUIRED’ option stops processing with an error
message if nothing is found, otherwise the search will be attempted
again the next time find_library is invoked with the same variable.

Options include:

‘NAMES’

     Specify one or more possible names for the library.

     When using this to specify names with and without a version suffix,
     we recommend specifying the unversioned name first so that
     locally-built packages can be found before those provided by
     distributions.

‘HINTS’, ‘PATHS’

     Specify directories to search in addition to the default locations.
     The ‘ENV var’ sub-option reads paths from a system environment
     variable.

‘PATH_SUFFIXES’

     Specify additional subdirectories to check below each directory
     location otherwise considered.

‘DOC’

     Specify the documentation string for the ‘<VAR>’ cache entry.

‘REQUIRED’

     Stop processing with an error message if nothing is found.

If ‘NO_DEFAULT_PATH’ is specified, then no additional paths are added to
the search.  If ‘NO_DEFAULT_PATH’ is not specified, the search process
is as follows:

  1. If called from within a find module or any other script loaded by a
     call to find_package(<PackageName>), search prefixes
     unique to the current package being found.  Specifically, look in
     the <PackageName>_ROOT. CMake variable and the
     <PackageName>_ROOT environment variable.  The package root
     variables are maintained as a stack, so if called from nested find
     modules or config packages, root paths from the parent’s find
     module or config package will be searched after paths from the
     current module or package.  In other words, the search order would
     be ‘<CurrentPackage>_ROOT’, ‘ENV{<CurrentPackage>_ROOT}’,
     ‘<ParentPackage>_ROOT’, ‘ENV{<ParentPackage>_ROOT}’, etc.  This can
     be skipped if ‘NO_PACKAGE_ROOT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_PACKAGE_ROOT_PATH to ‘FALSE’.  See
     policy CMP0074.

        * ‘<prefix>/lib/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/lib’ for each ‘<prefix>’ in the
          <PackageName>_ROOT. CMake variable and the
          <PackageName>_ROOT environment variable if called from
          within a find module loaded by
          find_package(<PackageName>).

  2. Search paths specified in cmake-specific cache variables.  These
     are intended to be used on the command line with a ‘-DVAR=value’.
     The values are interpreted as semicolon-separated lists.
     This can be skipped if ‘NO_CMAKE_PATH’ is passed or by setting the
     CMAKE_FIND_USE_CMAKE_PATH to ‘FALSE’.

        * ‘<prefix>/lib/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/lib’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_LIBRARY_PATH.

        * CMAKE_FRAMEWORK_PATH.

  3. Search paths specified in cmake-specific environment variables.
     These are intended to be set in the user’s shell configuration, and
     therefore use the host’s native path separator (‘;’ on Windows and
     ‘:’ on UNIX). This can be skipped if ‘NO_CMAKE_ENVIRONMENT_PATH’ is
     passed or by setting the
     CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to ‘FALSE’.

        * ‘<prefix>/lib/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/lib’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_LIBRARY_PATH.

        * CMAKE_FRAMEWORK_PATH.

  4. Search the paths specified by the ‘HINTS’ option.  These should be
     paths computed by system introspection, such as a hint provided by
     the location of another item already found.  Hard-coded guesses
     should be specified with the ‘PATHS’ option.

  5. Search the standard system environment variables.  This can be
     skipped if ‘NO_SYSTEM_ENVIRONMENT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to ‘FALSE’.

        * The directories in ‘PATH’ and ‘INCLUDE’.

        * On Windows hosts: ‘<prefix>/lib/<arch>’ if
          CMAKE_LIBRARY_ARCHITECTURE is set, and ‘<prefix>/lib’
          for each ‘<prefix>/[s]bin’ in ‘PATH’, and ‘<entry>/lib’ for
          other entries in ‘PATH’.

  6. Search cmake variables defined in the Platform files for the
     current system.  This can be skipped if ‘NO_CMAKE_SYSTEM_PATH’ is
     passed or by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
     to ‘FALSE’.

        * ‘<prefix>/lib/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/lib’ for each ‘<prefix>’ in
          CMAKE_SYSTEM_PREFIX_PATH.

        * CMAKE_SYSTEM_LIBRARY_PATH.

        * CMAKE_SYSTEM_FRAMEWORK_PATH.

     The platform paths that these variables contain are locations that
     typically include installed software.  An example being
     ‘/usr/local’ for UNIX based platforms.

  7. Search the paths specified by the PATHS option or in the short-hand
     version of the command.  These are typically hard-coded guesses.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of preference
between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or
more directories to be prepended to all other search directories.  This
effectively “re-roots” the entire search under given locations.  Paths
which are descendants of the CMAKE_STAGING_PREFIX are
excluded from this re-rooting, because that variable is always a path on
the host system.  By default the CMAKE_FIND_ROOT_PATH is
empty.

The CMAKE_SYSROOT variable can also be used to specify
exactly one directory to use as a prefix.  Setting CMAKE_SYSROOT
also has other effects.  See the documentation for that variable
for more.

These variables are especially useful when cross-compiling to point to
the root directory of the target environment and CMake will search there
too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.  This behavior can be manually
overridden on a per-call basis using options:

‘CMAKE_FIND_ROOT_PATH_BOTH’

     Search in the order described above.

‘NO_CMAKE_FIND_ROOT_PATH’

     Do not use the CMAKE_FIND_ROOT_PATH variable.

‘ONLY_CMAKE_FIND_ROOT_PATH’

     Search only the re-rooted directories and directories below
     CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.  Projects may override the order by
simply calling the command multiple times and using the ‘NO_*’ options:

     find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
     find_library (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set and
stored in the cache so that no call will search again.

When more than one value is given to the ‘NAMES’ option this command by
default will consider one name at a time and search every directory for
it.  The ‘NAMES_PER_DIR’ option tells this command to consider one
directory at a time and search for all names in it.

Each library name given to the ‘NAMES’ option is first considered as a
library file name and then considered with platform-specific prefixes
(e.g.  ‘lib’) and suffixes (e.g.  ‘.so’).  Therefore one may specify
library file names such as ‘libfoo.a’ directly.  This can be used to
locate static libraries on UNIX-like systems.

If the library found is a framework, then ‘<VAR>’ will be set to the
full path to the framework ‘<fullPath>/A.framework’.  When a full path
to a framework is used as a library, CMake will use a ‘-framework A’,
and a ‘-F<fullPath>’ to link the framework to the target.

If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set
all search paths will be tested as normal, with the suffix appended, and
with all matches of ‘lib/’ replaced with
‘lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/’.  This variable overrides
the FIND_LIBRARY_USE_LIB32_PATHS,
FIND_LIBRARY_USE_LIBX32_PATHS, and
FIND_LIBRARY_USE_LIB64_PATHS global properties.

If the FIND_LIBRARY_USE_LIB32_PATHS global property is set
all search paths will be tested as normal, with ‘32/’ appended, and with
all matches of ‘lib/’ replaced with ‘lib32/’.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project().
command is enabled.

If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set
all search paths will be tested as normal, with ‘x32/’ appended, and
with all matches of ‘lib/’ replaced with ‘libx32/’.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project().
command is enabled.

If the FIND_LIBRARY_USE_LIB64_PATHS global property is set
all search paths will be tested as normal, with ‘64/’ appended, and with
all matches of ‘lib/’ replaced with ‘lib64/’.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project().
command is enabled.

7.1.20 find_package
-------------------

Find an external project, and load its settings.

7.1.20.1 Basic Signature and Module Mode
........................................

     find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
                  [REQUIRED] [[COMPONENTS] [components...]]
                  [OPTIONAL_COMPONENTS components...]
                  [NO_POLICY_SCOPE])

Finds and loads settings from an external project.
‘<PackageName>_FOUND’ will be set to indicate whether the package was
found.  When the package is found package-specific information is
provided through variables and Imported Targets documented
by the package itself.  The ‘QUIET’ option disables informational
messages, including those indicating that the package cannot be found if
it is not ‘REQUIRED’.  The ‘REQUIRED’ option stops processing with an
error message if the package cannot be found.

A package-specific list of required components may be listed after the
‘COMPONENTS’ option (or after the ‘REQUIRED’ option if present).
Additional optional components may be listed after
‘OPTIONAL_COMPONENTS’.  Available components and their influence on
whether a package is considered to be found are defined by the target
package.  The ‘[version]’ argument requests a version with which the
package found should be compatible.  There are two possible forms in
which it may be specified:

        * A single version with the format
          ‘major[.minor[.patch[.tweak]]]’.

        * A version range with the format ‘versionMin...[<]versionMax’
          where ‘versionMin’ and ‘versionMax’ have the same format as
          the single version.  By default, both end points are included.
          By specifying ‘<’, the upper end point will be excluded.
          Version ranges are only supported with CMake 3.19 or later.

The ‘EXACT’ option requests that the version be matched exactly.  This
option is incompatible with the specification of a version range.

If no ‘[version]’ and/or component list is given to a recursive
invocation inside a find-module, the corresponding arguments are
forwarded automatically from the outer call (including the ‘EXACT’ flag
for ‘[version]’).  Version support is currently provided only on a
package-by-package basis (see the Version Selection section
below).  When a version range is specified but the package is only
designed to expect a single version, the package will ignore the upper
end point of the range and only take the single version at the lower end
of the range into account.

See the cmake_policy() command documentation for discussion
of the ‘NO_POLICY_SCOPE’ option.

The command has two modes by which it searches for packages: “Module”
mode and “Config” mode.  The above signature selects Module mode.  If no
module is found the command falls back to Config mode, described below.
This fall back is disabled if the ‘MODULE’ option is given.

In Module mode, CMake searches for a file called
‘Find<PackageName>.cmake’.  The file is first searched in the
CMAKE_MODULE_PATH, then among the Find Modules provided
by the CMake installation.  If the file is found, it is read and
processed by CMake.  It is responsible for finding the package, checking
the version, and producing any needed messages.  Some find-modules
provide limited or no support for versioning; check the module
documentation.

If the ‘MODULE’ option is not specified in the above signature, CMake
first searches for the package using Module mode.  Then, if the package
is not found, it searches again using Config mode.  A user may set the
variable CMAKE_FIND_PACKAGE_PREFER_CONFIG to ‘TRUE’ to
direct CMake first search using Config mode before falling back to
Module mode.

7.1.20.2 Full Signature and Config Mode
.......................................

User code should generally look for packages using the above basic signature.
The remainder of this command documentation specifies
the full command signature and details of the search process.  Project
maintainers wishing to provide a package to be found by this command are
encouraged to read on.

The complete Config mode command signature is

     find_package(<PackageName> [version] [EXACT] [QUIET]
                  [REQUIRED] [[COMPONENTS] [components...]]
                  [OPTIONAL_COMPONENTS components...]
                  [CONFIG|NO_MODULE]
                  [NO_POLICY_SCOPE]
                  [NAMES name1 [name2 ...]]
                  [CONFIGS config1 [config2 ...]]
                  [HINTS path1 [path2 ... ]]
                  [PATHS path1 [path2 ... ]]
                  [PATH_SUFFIXES suffix1 [suffix2 ...]]
                  [NO_DEFAULT_PATH]
                  [NO_PACKAGE_ROOT_PATH]
                  [NO_CMAKE_PATH]
                  [NO_CMAKE_ENVIRONMENT_PATH]
                  [NO_SYSTEM_ENVIRONMENT_PATH]
                  [NO_CMAKE_PACKAGE_REGISTRY]
                  [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                  [NO_CMAKE_SYSTEM_PATH]
                  [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                  [CMAKE_FIND_ROOT_PATH_BOTH |
                   ONLY_CMAKE_FIND_ROOT_PATH |
                   NO_CMAKE_FIND_ROOT_PATH])

The ‘CONFIG’ option, the synonymous ‘NO_MODULE’ option, or the use of
options not specified in the basic signature all enforce
pure Config mode.  In pure Config mode, the command skips Module mode
search and proceeds at once with Config mode search.

Config mode search attempts to locate a configuration file provided by
the package to be found.  A cache entry called ‘<PackageName>_DIR’ is
created to hold the directory containing the file.  By default the
command searches for a package with the name ‘<PackageName>’.  If the
‘NAMES’ option is given the names following it are used instead of
‘<PackageName>’.  The command searches for a file called
‘<PackageName>Config.cmake’ or ‘<lower-case-package-name>-config.cmake’
for each name specified.  A replacement set of possible configuration
file names may be given using the ‘CONFIGS’ option.  The search
procedure is specified below.  Once found, the configuration file is
read and processed by CMake.  Since the file is provided by the package
it already knows the location of package contents.  The full path to the
configuration file is stored in the cmake variable
‘<PackageName>_CONFIG’.

All configuration files which have been considered by CMake while
searching for an installation of the package with an appropriate version
are stored in the cmake variable ‘<PackageName>_CONSIDERED_CONFIGS’, the
associated versions in ‘<PackageName>_CONSIDERED_VERSIONS’.

If the package configuration file cannot be found CMake will generate an
error describing the problem unless the ‘QUIET’ argument is specified.
If ‘REQUIRED’ is specified and the package is not found a fatal error is
generated and the configure step stops executing.  If
‘<PackageName>_DIR’ has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch.

Package maintainers providing CMake package configuration files are
encouraged to name and install them such that the Search Procedure
outlined below will find them without requiring use of
additional options.

7.1.20.3 Version Selection
..........................

When the ‘[version]’ argument is given, Config mode will only find a
version of the package that claims compatibility with the requested
version (see format specification).  If the ‘EXACT’ option
is given, only a version of the package claiming an exact match of the
requested version may be found.  CMake does not establish any convention
for the meaning of version numbers.  Package version numbers are checked
by “version” files provided by the packages themselves.  For a candidate
package configuration file ‘<config-file>.cmake’ the corresponding
version file is located next to it and named either
‘<config-file>-version.cmake’ or ‘<config-file>Version.cmake’.  If no
such version file is available then the configuration file is assumed to
not be compatible with any requested version.  A basic version file
containing generic version matching code can be created using the
CMakePackageConfigHelpers module.  When a version file is found it
is loaded to check the requested version number.  The version file is
loaded in a nested scope in which the following variables have been
defined:

‘PACKAGE_FIND_NAME’

     The ‘<PackageName>’

‘PACKAGE_FIND_VERSION’

     Full requested version string

‘PACKAGE_FIND_VERSION_MAJOR’

     Major version if requested, else 0

‘PACKAGE_FIND_VERSION_MINOR’

     Minor version if requested, else 0

‘PACKAGE_FIND_VERSION_PATCH’

     Patch version if requested, else 0

‘PACKAGE_FIND_VERSION_TWEAK’

     Tweak version if requested, else 0

‘PACKAGE_FIND_VERSION_COUNT’

     Number of version components, 0 to 4

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect
version ranges.  In addition, the version range will be described by the
following variables:

‘PACKAGE_FIND_VERSION_RANGE’

     Full requested version range string

‘PACKAGE_FIND_VERSION_RANGE_MIN’

     This specifies whether the lower end point of the version range
     should be included or excluded.  Currently, the only supported
     value for this variable is ‘INCLUDE’.

‘PACKAGE_FIND_VERSION_RANGE_MAX’

     This specifies whether the upper end point of the version range
     should be included or excluded.  The supported values for this
     variable are ‘INCLUDE’ and ‘EXCLUDE’.

‘PACKAGE_FIND_VERSION_MIN’

     Full requested version string of the lower end point of the range

‘PACKAGE_FIND_VERSION_MIN_MAJOR’

     Major version of the lower end point if requested, else 0

‘PACKAGE_FIND_VERSION_MIN_MINOR’

     Minor version of the lower end point if requested, else 0

‘PACKAGE_FIND_VERSION_MIN_PATCH’

     Patch version of the lower end point if requested, else 0

‘PACKAGE_FIND_VERSION_MIN_TWEAK’

     Tweak version of the lower end point if requested, else 0

‘PACKAGE_FIND_VERSION_MIN_COUNT’

     Number of version components of the lower end point, 0 to 4

‘PACKAGE_FIND_VERSION_MAX’

     Full requested version string of the upper end point of the range

‘PACKAGE_FIND_VERSION_MAX_MAJOR’

     Major version of the upper end point if requested, else 0

‘PACKAGE_FIND_VERSION_MAX_MINOR’

     Minor version of the upper end point if requested, else 0

‘PACKAGE_FIND_VERSION_MAX_PATCH’

     Patch version of the upper end point if requested, else 0

‘PACKAGE_FIND_VERSION_MAX_TWEAK’

     Tweak version of the upper end point if requested, else 0

‘PACKAGE_FIND_VERSION_MAX_COUNT’

     Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified,
the variable ‘PACKAGE_FIND_VERSION_COMPLETE’ will be defined and will
hold the full requested version string as specified.

The version file checks whether it satisfies the requested version and
sets these variables:

‘PACKAGE_VERSION’

     Full provided version string

‘PACKAGE_VERSION_EXACT’

     True if version is exact match

‘PACKAGE_VERSION_COMPATIBLE’

     True if version is compatible

‘PACKAGE_VERSION_UNSUITABLE’

     True if unsuitable as any version

These variables are checked by the ‘find_package’ command to determine
whether the configuration file provides an acceptable version.  They are
not available after the ‘find_package’ call returns.  If the version is
acceptable the following variables are set:

‘<PackageName>_VERSION’

     Full provided version string

‘<PackageName>_VERSION_MAJOR’

     Major version if provided, else 0

‘<PackageName>_VERSION_MINOR’

     Minor version if provided, else 0

‘<PackageName>_VERSION_PATCH’

     Patch version if provided, else 0

‘<PackageName>_VERSION_TWEAK’

     Tweak version if provided, else 0

‘<PackageName>_VERSION_COUNT’

     Number of version components, 0 to 4

and the corresponding package configuration file is loaded.  When
multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER
is set no attempt is made to choose a highest or closest version
number.

To control the order in which ‘find_package’ checks for compatibility
use the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and
CMAKE_FIND_PACKAGE_SORT_DIRECTION.  For instance in order to
select the highest version one can set

     SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
     SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

before calling ‘find_package’.

7.1.20.4 Search Procedure
.........................

CMake constructs a set of possible installation prefixes for the
package.  Under each prefix several directories are searched for a
configuration file.  The tables below show the directories searched.
Each entry is meant for installation trees following Windows (‘W’), UNIX
(‘U’), or Apple (‘A’) conventions:

     <prefix>/                                                       (W)
     <prefix>/(cmake|CMake)/                                         (W)
     <prefix>/<name>*/                                               (W)
     <prefix>/<name>*/(cmake|CMake)/                                 (W)
     <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
     <prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
     <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
     <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
     <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
     <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)

On systems supporting macOS FRAMEWORK and BUNDLE,
the following directories are searched for Frameworks or Application
Bundles containing a configuration file:

     <prefix>/<name>.framework/Resources/                    (A)
     <prefix>/<name>.framework/Resources/CMake/              (A)
     <prefix>/<name>.framework/Versions/*/Resources/         (A)
     <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
     <prefix>/<name>.app/Contents/Resources/                 (A)
     <prefix>/<name>.app/Contents/Resources/CMake/           (A)

In all cases the ‘<name>’ is treated as case-insensitive and corresponds
to any of the names specified (‘<PackageName>’ or names given by
‘NAMES’).

Paths with ‘lib/<arch>’ are enabled if the
CMAKE_LIBRARY_ARCHITECTURE variable is set.  ‘lib*’ includes one
or more of the values ‘lib64’, ‘lib32’, ‘libx32’ or ‘lib’ (searched in
that order).

   * Paths with ‘lib64’ are searched on 64 bit platforms if the
     FIND_LIBRARY_USE_LIB64_PATHS property is set to ‘TRUE’.

   * Paths with ‘lib32’ are searched on 32 bit platforms if the
     FIND_LIBRARY_USE_LIB32_PATHS property is set to ‘TRUE’.

   * Paths with ‘libx32’ are searched on platforms using the x32 ABI if
     the FIND_LIBRARY_USE_LIBX32_PATHS property is set to
     ‘TRUE’.

   * The ‘lib’ path is always searched.

If ‘PATH_SUFFIXES’ is specified, the suffixes are appended to each (‘W’)
or (‘U’) directory entry one-by-one.

This set of directories is intended to work in cooperation with projects
that provide configuration files in their installation trees.
Directories above marked with (‘W’) are intended for installations on
Windows where the prefix may point at the top of an application’s
installation directory.  Those marked with (‘U’) are intended for
installations on UNIX platforms where the prefix is shared by multiple
packages.  This is merely a convention, so all (‘W’) and (‘U’)
directories are still searched on all platforms.  Directories marked
with (‘A’) are intended for installations on Apple platforms.  The
CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE.
variables determine the order of preference.

The set of installation prefixes is constructed using the following
steps.  If ‘NO_DEFAULT_PATH’ is specified all ‘NO_*’ options are
enabled.

  1. Search paths specified in the <PackageName>_ROOT. CMake
     variable and the <PackageName>_ROOT environment
     variable, where ‘<PackageName>’ is the package to be found.  The
     package root variables are maintained as a stack so if called from
     within a find module, root paths from the parent’s find module will
     also be searched after paths for the current package.  This can be
     skipped if ‘NO_PACKAGE_ROOT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_PACKAGE_ROOT_PATH to ‘FALSE’.  See policy
     CMP0074.

  2. Search paths specified in cmake-specific cache variables.  These
     are intended to be used on the command line with a ‘-DVAR=value’.
     The values are interpreted as semicolon-separated lists.
     This can be skipped if ‘NO_CMAKE_PATH’ is passed or by setting the
     CMAKE_FIND_USE_CMAKE_PATH to ‘FALSE’:

        * CMAKE_PREFIX_PATH.

        * CMAKE_FRAMEWORK_PATH.

        * CMAKE_APPBUNDLE_PATH.

  3. Search paths specified in cmake-specific environment variables.
     These are intended to be set in the user’s shell configuration, and
     therefore use the host’s native path separator (‘;’ on Windows and
     ‘:’ on UNIX). This can be skipped if ‘NO_CMAKE_ENVIRONMENT_PATH’ is
     passed or by setting the
     CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to ‘FALSE’:

        * ‘<PackageName>_DIR’

        * CMAKE_PREFIX_PATH.

        * ‘CMAKE_FRAMEWORK_PATH’

        * ‘CMAKE_APPBUNDLE_PATH’

  4. Search paths specified by the ‘HINTS’ option.  These should be
     paths computed by system introspection, such as a hint provided by
     the location of another item already found.  Hard-coded guesses
     should be specified with the ‘PATHS’ option.

  5. Search the standard system environment variables.  This can be
     skipped if ‘NO_SYSTEM_ENVIRONMENT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to ‘FALSE’.
     Path entries ending in ‘/bin’ or ‘/sbin’ are automatically
     converted to their parent directories:

        * ‘PATH’

  6. Search paths stored in the CMake User Package Registry.
     This can be skipped if ‘NO_CMAKE_PACKAGE_REGISTRY’ is passed or by
     setting the variable CMAKE_FIND_USE_PACKAGE_REGISTRY to
     ‘FALSE’ or the deprecated variable
     CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to ‘TRUE’.

     See the cmake-packages(7) manual for details on the user
     package registry.

  7. Search cmake variables defined in the Platform files for the
     current system.  This can be skipped if ‘NO_CMAKE_SYSTEM_PATH’ is
     passed or by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
     to ‘FALSE’:

        * CMAKE_SYSTEM_PREFIX_PATH.

        * CMAKE_SYSTEM_FRAMEWORK_PATH.

        * CMAKE_SYSTEM_APPBUNDLE_PATH.

     The platform paths that these variables contain are locations that
     typically include installed software.  An example being
     ‘/usr/local’ for UNIX based platforms.

  8. Search paths stored in the CMake System Package Registry.
     This can be skipped if ‘NO_CMAKE_SYSTEM_PACKAGE_REGISTRY’ is
     passed or by setting the
     CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to ‘FALSE’ or
     the deprecated variable
     CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to ‘TRUE’.

     See the cmake-packages(7) manual for details on the
     system package registry.

  9. Search paths specified by the ‘PATHS’ option.  These are typically
     hard-coded guesses.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or
more directories to be prepended to all other search directories.  This
effectively “re-roots” the entire search under given locations.  Paths
which are descendants of the CMAKE_STAGING_PREFIX are
excluded from this re-rooting, because that variable is always a path on
the host system.  By default the CMAKE_FIND_ROOT_PATH is
empty.

The CMAKE_SYSROOT variable can also be used to specify
exactly one directory to use as a prefix.  Setting CMAKE_SYSROOT
also has other effects.  See the documentation for that variable
for more.

These variables are especially useful when cross-compiling to point to
the root directory of the target environment and CMake will search there
too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.  This behavior can be manually
overridden on a per-call basis using options:

‘CMAKE_FIND_ROOT_PATH_BOTH’

     Search in the order described above.

‘NO_CMAKE_FIND_ROOT_PATH’

     Do not use the CMAKE_FIND_ROOT_PATH variable.

‘ONLY_CMAKE_FIND_ROOT_PATH’

     Search only the re-rooted directories and directories below
     CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.  Projects may override the order by
simply calling the command multiple times and using the ‘NO_*’ options:

     find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
     find_package (<PackageName>)

Once one of the calls succeeds the result variable will be set and
stored in the cache so that no call will search again.

By default the value stored in the result variable will be the path at
which the file is found.  The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
variable may be set to ‘TRUE’ before calling ‘find_package’ in
order to resolve symbolic links and store the real path to the file.

Every non-REQUIRED ‘find_package’ call can be disabled by setting the
CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to ‘TRUE’.

7.1.20.5 Package File Interface Variables
.........................................

When loading a find module or package configuration file ‘find_package’
defines variables to provide information about the call arguments (and
restores their original state before returning):

‘CMAKE_FIND_PACKAGE_NAME’

     The ‘<PackageName>’ which is searched for

‘<PackageName>_FIND_REQUIRED’

     True if ‘REQUIRED’ option was given

‘<PackageName>_FIND_QUIETLY’

     True if ‘QUIET’ option was given

‘<PackageName>_FIND_VERSION’

     Full requested version string

‘<PackageName>_FIND_VERSION_MAJOR’

     Major version if requested, else 0

‘<PackageName>_FIND_VERSION_MINOR’

     Minor version if requested, else 0

‘<PackageName>_FIND_VERSION_PATCH’

     Patch version if requested, else 0

‘<PackageName>_FIND_VERSION_TWEAK’

     Tweak version if requested, else 0

‘<PackageName>_FIND_VERSION_COUNT’

     Number of version components, 0 to 4

‘<PackageName>_FIND_VERSION_EXACT’

     True if ‘EXACT’ option was given

‘<PackageName>_FIND_COMPONENTS’

     List of requested components

‘<PackageName>_FIND_REQUIRED_<c>’

     True if component ‘<c>’ is required, false if component ‘<c>’ is
     optional

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect
version ranges.  In addition, the version range will be described by the
following variables:

‘<PackageName>_FIND_VERSION_RANGE’

     Full requested version range string

‘<PackageName>_FIND_VERSION_RANGE_MIN’

     This specifies whether the lower end point of the version range is
     included or excluded.  Currently, ‘INCLUDE’ is the only supported
     value.

‘<PackageName>_FIND_VERSION_RANGE_MAX’

     This specifies whether the upper end point of the version range is
     included or excluded.  The possible values for this variable are
     ‘INCLUDE’ or ‘EXCLUDE’.

‘<PackageName>_FIND_VERSION_MIN’

     Full requested version string of the lower end point of the range

‘<PackageName>_FIND_VERSION_MIN_MAJOR’

     Major version of the lower end point if requested, else 0

‘<PackageName>_FIND_VERSION_MIN_MINOR’

     Minor version of the lower end point if requested, else 0

‘<PackageName>_FIND_VERSION_MIN_PATCH’

     Patch version of the lower end point if requested, else 0

‘<PackageName>_FIND_VERSION_MIN_TWEAK’

     Tweak version of the lower end point if requested, else 0

‘<PackageName>_FIND_VERSION_MIN_COUNT’

     Number of version components of the lower end point, 0 to 4

‘<PackageName>_FIND_VERSION_MAX’

     Full requested version string of the upper end point of the range

‘<PackageName>_FIND_VERSION_MAX_MAJOR’

     Major version of the upper end point if requested, else 0

‘<PackageName>_FIND_VERSION_MAX_MINOR’

     Minor version of the upper end point if requested, else 0

‘<PackageName>_FIND_VERSION_MAX_PATCH’

     Patch version of the upper end point if requested, else 0

‘<PackageName>_FIND_VERSION_MAX_TWEAK’

     Tweak version of the upper end point if requested, else 0

‘<PackageName>_FIND_VERSION_MAX_COUNT’

     Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified,
the variable ‘<PackageName>_FIND_VERSION_COMPLETE’ will be defined and
will hold the full requested version string as specified.

In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details.
In Config mode ‘find_package’ handles ‘REQUIRED’, ‘QUIET’, and
‘[version]’ options automatically but leaves it to the package
configuration file to handle components in a way that makes sense for
the package.  The package configuration file may set
‘<PackageName>_FOUND’ to false to tell ‘find_package’ that component
requirements are not satisfied.

7.1.21 find_path
----------------

A short-hand signature is:

     find_path (<VAR> name1 [path1 path2 ...])

The general signature is:

     find_path (
               <VAR>
               name | NAMES name1 [name2 ...]
               [HINTS path1 [path2 ... ENV var]]
               [PATHS path1 [path2 ... ENV var]]
               [PATH_SUFFIXES suffix1 [suffix2 ...]]
               [DOC "cache documentation string"]
               [REQUIRED]
               [NO_DEFAULT_PATH]
               [NO_PACKAGE_ROOT_PATH]
               [NO_CMAKE_PATH]
               [NO_CMAKE_ENVIRONMENT_PATH]
               [NO_SYSTEM_ENVIRONMENT_PATH]
               [NO_CMAKE_SYSTEM_PATH]
               [CMAKE_FIND_ROOT_PATH_BOTH |
                ONLY_CMAKE_FIND_ROOT_PATH |
                NO_CMAKE_FIND_ROOT_PATH]
              )

This command is used to find a directory containing the named file.  A
cache entry named by ‘<VAR>’ is created to store the result of this
command.  If the file in a directory is found the result is stored in
the variable and the search will not be repeated unless the variable is
cleared.  If nothing is found, the result will be ‘<VAR>-NOTFOUND’.  The
‘REQUIRED’ option stops processing with an error message if nothing is
found, otherwise the search will be attempted again the next time
find_path is invoked with the same variable.

Options include:

‘NAMES’

     Specify one or more possible names for the file in a directory.

     When using this to specify names with and without a version suffix,
     we recommend specifying the unversioned name first so that
     locally-built packages can be found before those provided by
     distributions.

‘HINTS’, ‘PATHS’

     Specify directories to search in addition to the default locations.
     The ‘ENV var’ sub-option reads paths from a system environment
     variable.

‘PATH_SUFFIXES’

     Specify additional subdirectories to check below each directory
     location otherwise considered.

‘DOC’

     Specify the documentation string for the ‘<VAR>’ cache entry.

‘REQUIRED’

     Stop processing with an error message if nothing is found.

If ‘NO_DEFAULT_PATH’ is specified, then no additional paths are added to
the search.  If ‘NO_DEFAULT_PATH’ is not specified, the search process
is as follows:

  1. If called from within a find module or any other script loaded by a
     call to find_package(<PackageName>), search prefixes
     unique to the current package being found.  Specifically, look in
     the <PackageName>_ROOT. CMake variable and the
     <PackageName>_ROOT environment variable.  The package root
     variables are maintained as a stack, so if called from nested find
     modules or config packages, root paths from the parent’s find
     module or config package will be searched after paths from the
     current module or package.  In other words, the search order would
     be ‘<CurrentPackage>_ROOT’, ‘ENV{<CurrentPackage>_ROOT}’,
     ‘<ParentPackage>_ROOT’, ‘ENV{<ParentPackage>_ROOT}’, etc.  This can
     be skipped if ‘NO_PACKAGE_ROOT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_PACKAGE_ROOT_PATH to ‘FALSE’.  See
     policy CMP0074.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in the
          <PackageName>_ROOT. CMake variable and the
          <PackageName>_ROOT environment variable if called from
          within a find module loaded by
          find_package(<PackageName>).

  2. Search paths specified in cmake-specific cache variables.  These
     are intended to be used on the command line with a ‘-DVAR=value’.
     The values are interpreted as semicolon-separated lists.
     This can be skipped if ‘NO_CMAKE_PATH’ is passed or by setting the
     CMAKE_FIND_USE_CMAKE_PATH to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_INCLUDE_PATH.

        * CMAKE_FRAMEWORK_PATH.

  3. Search paths specified in cmake-specific environment variables.
     These are intended to be set in the user’s shell configuration, and
     therefore use the host’s native path separator (‘;’ on Windows and
     ‘:’ on UNIX). This can be skipped if ‘NO_CMAKE_ENVIRONMENT_PATH’ is
     passed or by setting the
     CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_INCLUDE_PATH.

        * CMAKE_FRAMEWORK_PATH.

  4. Search the paths specified by the ‘HINTS’ option.  These should be
     paths computed by system introspection, such as a hint provided by
     the location of another item already found.  Hard-coded guesses
     should be specified with the ‘PATHS’ option.

  5. Search the standard system environment variables.  This can be
     skipped if ‘NO_SYSTEM_ENVIRONMENT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to ‘FALSE’.

        * The directories in ‘PATH’ and ‘INCLUDE’.

        * On Windows hosts: ‘<prefix>/include/<arch>’ if
          CMAKE_LIBRARY_ARCHITECTURE is set, and
          ‘<prefix>/include’ for each ‘<prefix>/[s]bin’ in ‘PATH’, and
          ‘<entry>/include’ for other entries in ‘PATH’.

  6. Search cmake variables defined in the Platform files for the
     current system.  This can be skipped if ‘NO_CMAKE_SYSTEM_PATH’ is
     passed or by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
     to ‘FALSE’.

        * ‘<prefix>/include/<arch>’ if CMAKE_LIBRARY_ARCHITECTURE
          is set, and ‘<prefix>/include’ for each ‘<prefix>’ in
          CMAKE_SYSTEM_PREFIX_PATH.

        * CMAKE_SYSTEM_INCLUDE_PATH.

        * CMAKE_SYSTEM_FRAMEWORK_PATH.

     The platform paths that these variables contain are locations that
     typically include installed software.  An example being
     ‘/usr/local’ for UNIX based platforms.

  7. Search the paths specified by the PATHS option or in the short-hand
     version of the command.  These are typically hard-coded guesses.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of preference
between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or
more directories to be prepended to all other search directories.  This
effectively “re-roots” the entire search under given locations.  Paths
which are descendants of the CMAKE_STAGING_PREFIX are
excluded from this re-rooting, because that variable is always a path on
the host system.  By default the CMAKE_FIND_ROOT_PATH is
empty.

The CMAKE_SYSROOT variable can also be used to specify
exactly one directory to use as a prefix.  Setting CMAKE_SYSROOT
also has other effects.  See the documentation for that variable
for more.

These variables are especially useful when cross-compiling to point to
the root directory of the target environment and CMake will search there
too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.  This behavior can be manually
overridden on a per-call basis using options:

‘CMAKE_FIND_ROOT_PATH_BOTH’

     Search in the order described above.

‘NO_CMAKE_FIND_ROOT_PATH’

     Do not use the CMAKE_FIND_ROOT_PATH variable.

‘ONLY_CMAKE_FIND_ROOT_PATH’

     Search only the re-rooted directories and directories below
     CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.  Projects may override the order by
simply calling the command multiple times and using the ‘NO_*’ options:

     find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
     find_path (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set and
stored in the cache so that no call will search again.

When searching for frameworks, if the file is specified as ‘A/b.h’, then
the framework search will look for ‘A.framework/Headers/b.h’.  If that
is found the path will be set to the path to the framework.  CMake will
convert this to the correct ‘-F’ option to include the file.

7.1.22 find_program
-------------------

A short-hand signature is:

     find_program (<VAR> name1 [path1 path2 ...])

The general signature is:

     find_program (
               <VAR>
               name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
               [HINTS path1 [path2 ... ENV var]]
               [PATHS path1 [path2 ... ENV var]]
               [PATH_SUFFIXES suffix1 [suffix2 ...]]
               [DOC "cache documentation string"]
               [REQUIRED]
               [NO_DEFAULT_PATH]
               [NO_PACKAGE_ROOT_PATH]
               [NO_CMAKE_PATH]
               [NO_CMAKE_ENVIRONMENT_PATH]
               [NO_SYSTEM_ENVIRONMENT_PATH]
               [NO_CMAKE_SYSTEM_PATH]
               [CMAKE_FIND_ROOT_PATH_BOTH |
                ONLY_CMAKE_FIND_ROOT_PATH |
                NO_CMAKE_FIND_ROOT_PATH]
              )

This command is used to find a program.  A cache entry named by ‘<VAR>’
is created to store the result of this command.  If the program is found
the result is stored in the variable and the search will not be repeated
unless the variable is cleared.  If nothing is found, the result will be
‘<VAR>-NOTFOUND’.  The ‘REQUIRED’ option stops processing with an error
message if nothing is found, otherwise the search will be attempted
again the next time find_program is invoked with the same variable.

Options include:

‘NAMES’

     Specify one or more possible names for the program.

     When using this to specify names with and without a version suffix,
     we recommend specifying the unversioned name first so that
     locally-built packages can be found before those provided by
     distributions.

‘HINTS’, ‘PATHS’

     Specify directories to search in addition to the default locations.
     The ‘ENV var’ sub-option reads paths from a system environment
     variable.

‘PATH_SUFFIXES’

     Specify additional subdirectories to check below each directory
     location otherwise considered.

‘DOC’

     Specify the documentation string for the ‘<VAR>’ cache entry.

‘REQUIRED’

     Stop processing with an error message if nothing is found.

If ‘NO_DEFAULT_PATH’ is specified, then no additional paths are added to
the search.  If ‘NO_DEFAULT_PATH’ is not specified, the search process
is as follows:

  1. If called from within a find module or any other script loaded by a
     call to find_package(<PackageName>), search prefixes
     unique to the current package being found.  Specifically, look in
     the <PackageName>_ROOT. CMake variable and the
     <PackageName>_ROOT environment variable.  The package root
     variables are maintained as a stack, so if called from nested find
     modules or config packages, root paths from the parent’s find
     module or config package will be searched after paths from the
     current module or package.  In other words, the search order would
     be ‘<CurrentPackage>_ROOT’, ‘ENV{<CurrentPackage>_ROOT}’,
     ‘<ParentPackage>_ROOT’, ‘ENV{<ParentPackage>_ROOT}’, etc.  This can
     be skipped if ‘NO_PACKAGE_ROOT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_PACKAGE_ROOT_PATH to ‘FALSE’.  See
     policy CMP0074.

        * ‘<prefix>/[s]bin’ for each ‘<prefix>’ in the
          <PackageName>_ROOT. CMake variable and the
          <PackageName>_ROOT environment variable if called from
          within a find module loaded by
          find_package(<PackageName>).

  2. Search paths specified in cmake-specific cache variables.  These
     are intended to be used on the command line with a ‘-DVAR=value’.
     The values are interpreted as semicolon-separated lists.
     This can be skipped if ‘NO_CMAKE_PATH’ is passed or by setting the
     CMAKE_FIND_USE_CMAKE_PATH to ‘FALSE’.

        * ‘<prefix>/[s]bin’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_PROGRAM_PATH.

        * CMAKE_APPBUNDLE_PATH.

  3. Search paths specified in cmake-specific environment variables.
     These are intended to be set in the user’s shell configuration, and
     therefore use the host’s native path separator (‘;’ on Windows and
     ‘:’ on UNIX). This can be skipped if ‘NO_CMAKE_ENVIRONMENT_PATH’ is
     passed or by setting the
     CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to ‘FALSE’.

        * ‘<prefix>/[s]bin’ for each ‘<prefix>’ in
          CMAKE_PREFIX_PATH.

        * CMAKE_PROGRAM_PATH.

        * CMAKE_APPBUNDLE_PATH.

  4. Search the paths specified by the ‘HINTS’ option.  These should be
     paths computed by system introspection, such as a hint provided by
     the location of another item already found.  Hard-coded guesses
     should be specified with the ‘PATHS’ option.

  5. Search the standard system environment variables.  This can be
     skipped if ‘NO_SYSTEM_ENVIRONMENT_PATH’ is passed or by setting the
     CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to ‘FALSE’.

        * The directories in ‘PATH’ itself.

        * On Windows hosts no extra search paths are included

  6. Search cmake variables defined in the Platform files for the
     current system.  This can be skipped if ‘NO_CMAKE_SYSTEM_PATH’ is
     passed or by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
     to ‘FALSE’.

        * ‘<prefix>/[s]bin’ for each ‘<prefix>’ in
          CMAKE_SYSTEM_PREFIX_PATH.

        * CMAKE_SYSTEM_PROGRAM_PATH.

        * CMAKE_SYSTEM_APPBUNDLE_PATH.

     The platform paths that these variables contain are locations that
     typically include installed software.  An example being
     ‘/usr/local’ for UNIX based platforms.

  7. Search the paths specified by the PATHS option or in the short-hand
     version of the command.  These are typically hard-coded guesses.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of preference
between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or
more directories to be prepended to all other search directories.  This
effectively “re-roots” the entire search under given locations.  Paths
which are descendants of the CMAKE_STAGING_PREFIX are
excluded from this re-rooting, because that variable is always a path on
the host system.  By default the CMAKE_FIND_ROOT_PATH is
empty.

The CMAKE_SYSROOT variable can also be used to specify
exactly one directory to use as a prefix.  Setting CMAKE_SYSROOT
also has other effects.  See the documentation for that variable
for more.

These variables are especially useful when cross-compiling to point to
the root directory of the target environment and CMake will search there
too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.  This behavior can be manually
overridden on a per-call basis using options:

‘CMAKE_FIND_ROOT_PATH_BOTH’

     Search in the order described above.

‘NO_CMAKE_FIND_ROOT_PATH’

     Do not use the CMAKE_FIND_ROOT_PATH variable.

‘ONLY_CMAKE_FIND_ROOT_PATH’

     Search only the re-rooted directories and directories below
     CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.  Projects may override the order by
simply calling the command multiple times and using the ‘NO_*’ options:

     find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
     find_program (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set and
stored in the cache so that no call will search again.

When more than one value is given to the ‘NAMES’ option this command by
default will consider one name at a time and search every directory for
it.  The ‘NAMES_PER_DIR’ option tells this command to consider one
directory at a time and search for all names in it.

7.1.23 foreach
--------------

Evaluate a group of commands for each value in a list.

     foreach(<loop_var> <items>)
       <commands>
     endforeach()

where ‘<items>’ is a list of items that are separated by semicolon or
whitespace.  All commands between ‘foreach’ and the matching
‘endforeach’ are recorded without being invoked.  Once the ‘endforeach’
is evaluated, the recorded list of commands is invoked once for each
item in ‘<items>’.  At the beginning of each iteration the variable
‘loop_var’ will be set to the value of the current item.

The commands break() and continue() provide
means to escape from the normal control flow.

Per legacy, the endforeach() command admits an optional
‘<loop_var>’ argument.  If used, it must be a verbatim repeat of the
argument of the opening ‘foreach’ command.

     foreach(<loop_var> RANGE <stop>)

In this variant, ‘foreach’ iterates over the numbers 0, 1, … up to (and
including) the nonnegative integer ‘<stop>’.

     foreach(<loop_var> RANGE <start> <stop> [<step>])

In this variant, ‘foreach’ iterates over the numbers from ‘<start>’ up
to at most ‘<stop>’ in steps of ‘<step>’.  If ‘<step>’ is not specified,
then the step size is 1.  The three arguments ‘<start>’ ‘<stop>’
‘<step>’ must all be nonnegative integers, and ‘<stop>’ must not be
smaller than ‘<start>’; otherwise you enter the danger zone of
undocumented behavior that may change in future releases.

     foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])

In this variant, ‘<lists>’ is a whitespace or semicolon separated list
of list-valued variables.  The ‘foreach’ command iterates over each item
in each given list.  The ‘<items>’ following the ‘ITEMS’ keyword are
processed as in the first variant of the ‘foreach’ command.  The forms
‘LISTS A’ and ‘ITEMS ${A}’ are equivalent.

The following example shows how the ‘LISTS’ option is processed:

     set(A 0;1)
     set(B 2 3)
     set(C "4 5")
     set(D 6;7 8)
     set(E "")
     foreach(X IN LISTS A B C D E)
         message(STATUS "X=${X}")
     endforeach()

yields

     -- X=0
     -- X=1
     -- X=2
     -- X=3
     -- X=4 5
     -- X=6
     -- X=7
     -- X=8

     foreach(<loop_var>... IN ZIP_LISTS <lists>)

In this variant, ‘<lists>’ is a whitespace or semicolon separated list
of list-valued variables.  The ‘foreach’ command iterates over each list
simultaneously setting the iteration variables as follows:

   - if the only ‘loop_var’ given, then it sets a series of ‘loop_var_N’
     variables to the current item from the corresponding list;

   - if multiple variable names passed, their count should match the
     lists variables count;

   - if any of the lists are shorter, the corresponding iteration
     variable is not defined for the current iteration.

     list(APPEND English one two three four)
     list(APPEND Bahasa satu dua tiga)

     foreach(num IN ZIP_LISTS English Bahasa)
         message(STATUS "num_0=${num_0}, num_1=${num_1}")
     endforeach()

     foreach(en ba IN ZIP_LISTS English Bahasa)
         message(STATUS "en=${en}, ba=${ba}")
     endforeach()

yields

     -- num_0=one, num_1=satu
     -- num_0=two, num_1=dua
     -- num_0=three, num_1=tiga
     -- num_0=four, num_1=
     -- en=one, ba=satu
     -- en=two, ba=dua
     -- en=three, ba=tiga
     -- en=four, ba=

7.1.24 function
---------------

Start recording a function for later invocation as a command.

     function(<name> [<arg1> ...])
       <commands>
     endfunction()

Defines a function named ‘<name>’ that takes arguments named ‘<arg1>’, …
The ‘<commands>’ in the function definition are recorded; they are not
executed until the function is invoked.

Per legacy, the endfunction() command admits an optional
‘<name>’ argument.  If used, it must be a verbatim repeat of the
argument of the opening ‘function’ command.

A function opens a new scope: see set(var PARENT_SCOPE) for
details.

See the cmake_policy() command documentation for the
behavior of policies inside functions.

See the macro() command documentation for differences
between CMake functions and macros.

7.1.24.1 Invocation
...................

The function invocation is case-insensitive.  A function defined as

     function(foo)
       <commands>
     endfunction()

can be invoked through any of

     foo()
     Foo()
     FOO()
     cmake_language(CALL foo)

and so on.  However, it is strongly recommended to stay with the case
chosen in the function definition.  Typically functions use
all-lowercase names.

The cmake_language(CALL ...) command can also be used to
invoke the function.

7.1.24.2 Arguments
..................

When the function is invoked, the recorded ‘<commands>’ are first
modified by replacing formal parameters (‘${arg1}’, …) with the
arguments passed, and then invoked as normal commands.

In addition to referencing the formal parameters you can reference the
‘ARGC’ variable which will be set to the number of arguments passed into
the function as well as ‘ARGV0’, ‘ARGV1’, ‘ARGV2’, … which will have the
actual values of the arguments passed in.  This facilitates creating
functions with optional arguments.

Furthermore, ‘ARGV’ holds the list of all arguments given to the
function and ‘ARGN’ holds the list of arguments past the last expected
argument.  Referencing to ‘ARGV#’ arguments beyond ‘ARGC’ have undefined
behavior.  Checking that ‘ARGC’ is greater than ‘#’ is the only way to
ensure that ‘ARGV#’ was passed to the function as an extra argument.

7.1.25 get_cmake_property
-------------------------

Get a global property of the CMake instance.

     get_cmake_property(<var> <property>)

Gets a global property from the CMake instance.  The value of the
‘<property>’ is stored in the variable ‘<var>’.  If the property is not
found, ‘<var>’ will be set to ‘NOTFOUND’.  See the
cmake-properties(7) manual for available properties.

See also the get_property() command ‘GLOBAL’ option.

In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory
properties.  It also supports a special ‘COMPONENTS’ global property
that lists the components given to the install() command.

7.1.26 get_directory_property
-----------------------------

Get a property of ‘DIRECTORY’ scope.

     get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)

Stores a property of directory scope in the named ‘<variable>’.

The ‘DIRECTORY’ argument specifies another directory from which to
retrieve the property value instead of the current directory.  It may
reference either a source directory, or since CMake 3.19, a binary
directory.  Relative paths are treated as relative to the current source
directory.  CMake must already know about the directory, either by
having added it through a call to add_subdirectory() or
being the top level directory.

If the property is not defined for the nominated directory scope, an
empty string is returned.  In the case of ‘INHERITED’ properties, if the
property is not found for the nominated directory scope, the search will
chain to a parent scope as described for the define_property()
command.

     get_directory_property(<variable> [DIRECTORY <dir>]
                            DEFINITION <var-name>)

Get a variable definition from a directory.  This form is useful to get
a variable definition from another directory.

See also the more general get_property() command.

7.1.27 get_filename_component
-----------------------------

Get a specific component of a full filename.

     get_filename_component(<var> <FileName> <mode> [CACHE])

Sets ‘<var>’ to a component of ‘<FileName>’, where ‘<mode>’ is one of:

     DIRECTORY = Directory without file name
     NAME      = File name without directory
     EXT       = File name longest extension (.b.c from d/a.b.c)
     NAME_WE   = File name with neither the directory nor the longest extension
     LAST_EXT  = File name last extension (.c from d/a.b.c)
     NAME_WLE  = File name with neither the directory nor the last extension
     PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)

Paths are returned with forward slashes and have no trailing slashes.
If the optional ‘CACHE’ argument is specified, the result variable is
added to the cache.

     get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])

Sets ‘<var>’ to the absolute path of ‘<FileName>’, where ‘<mode>’ is one
of:

     ABSOLUTE  = Full path to file
     REALPATH  = Full path to existing file with symlinks resolved

If the provided ‘<FileName>’ is a relative path, it is evaluated
relative to the given base directory ‘<dir>’.  If no base directory is
provided, the default base directory will be
CMAKE_CURRENT_SOURCE_DIR.

Paths are returned with forward slashes and have no trailing slashes.
If the optional ‘CACHE’ argument is specified, the result variable is
added to the cache.

     get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])

The program in ‘<FileName>’ will be found in the system search path or
left as a full path.  If ‘PROGRAM_ARGS’ is present with ‘PROGRAM’, then
any command-line arguments present in the ‘<FileName>’ string are split
from the program name and stored in ‘<arg_var>’.  This is used to
separate a program name from its arguments in a command line string.

     Note: The ‘REALPATH’ and ‘PROGRAM’ subcommands had been superseded,
     respectively, by file(REAL_PATH) and
     separate_arguments(PROGRAM) commands.

7.1.28 get_property
-------------------

Get a property.

     get_property(<variable>
                  <GLOBAL             |
                   DIRECTORY [<dir>]  |
                   TARGET    <target> |
                   SOURCE    <source> |
                             [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
                   INSTALL   <file>   |
                   TEST      <test>   |
                   CACHE     <entry>  |
                   VARIABLE           >
                  PROPERTY <name>
                  [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])

Gets one property from one object in a scope.

The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the property.
It must be one of the following:

‘GLOBAL’

     Scope is unique and does not accept a name.

‘DIRECTORY’

     Scope defaults to the current directory but another directory
     (already processed by CMake) may be named by the full or relative
     path ‘<dir>’.  The ‘<dir>’ may reference either a source directory,
     or since CMake 3.19, a binary directory.  Relative paths are
     treated as relative to the current source directory.  See also the
     get_directory_property() command.

‘TARGET’

     Scope must name one existing target.  See also the
     get_target_property() command.

‘SOURCE’

     Scope must name one source file.  By default, the source file’s
     property will be read from the current source directory’s scope,
     but this can be overridden with one of the following sub-options:

     ‘DIRECTORY <dir>’

          The source file property will be read from the ‘<dir>’
          directory’s scope.  The ‘<dir>’ may reference either a source
          directory, or since CMake 3.19, a binary directory.  CMake
          must already know about the directory, either by having added
          it through a call to add_subdirectory() or ‘<dir>’
          being the top level directory.  Relative paths are treated as
          relative to the current source directory.

     ‘TARGET_DIRECTORY <target>’

          The source file property will be read from the directory scope
          in which ‘<target>’ was created (‘<target>’ must therefore
          already exist).

     See also the get_source_file_property() command.

‘INSTALL’

     Scope must name one installed file path.

‘TEST’

     Scope must name one existing test.  See also the
     get_test_property() command.

‘CACHE’

     Scope must name one cache entry.

‘VARIABLE’

     Scope is unique and does not accept a name.

The required ‘PROPERTY’ option is immediately followed by the name of
the property to get.  If the property is not set an empty value is
returned, although some properties support inheriting from a parent
scope if defined to behave that way (see define_property()).

If the ‘SET’ option is given the variable is set to a boolean value
indicating whether the property has been set.  If the ‘DEFINED’ option
is given the variable is set to a boolean value indicating whether the
property has been defined such as with the define_property().
command.

If ‘BRIEF_DOCS’ or ‘FULL_DOCS’ is given then the variable is set to a
string containing documentation for the requested property.  If
documentation is requested for a property that has not been defined
‘NOTFOUND’ is returned.

7.1.29 if
---------

Conditionally execute a group of commands.

7.1.29.1 Synopsis
.................

     if(<condition>)
       <commands>
     elseif(<condition>) # optional block, can be repeated
       <commands>
     else()              # optional block
       <commands>
     endif()

Evaluates the ‘condition’ argument of the ‘if’ clause according to the
Condition syntax described below.  If the result is true,
then the ‘commands’ in the ‘if’ block are executed.  Otherwise, optional
‘elseif’ blocks are processed in the same way.  Finally, if no
‘condition’ is true, ‘commands’ in the optional ‘else’ block are
executed.

Per legacy, the else() and endif() commands
admit an optional ‘<condition>’ argument.  If used, it must be a
verbatim repeat of the argument of the opening ‘if’ command.

7.1.29.2 Condition Syntax
.........................

The following syntax applies to the ‘condition’ argument of the ‘if’,
‘elseif’ and while() clauses.

Compound conditions are evaluated in the following order of precedence:
Innermost parentheses are evaluated first.  Next come unary tests such
as ‘EXISTS’, ‘COMMAND’, and ‘DEFINED’.  Then binary tests such as
‘EQUAL’, ‘LESS’, ‘LESS_EQUAL’, ‘GREATER’, ‘GREATER_EQUAL’, ‘STREQUAL’,
‘STRLESS’, ‘STRLESS_EQUAL’, ‘STRGREATER’, ‘STRGREATER_EQUAL’,
‘VERSION_EQUAL’, ‘VERSION_LESS’, ‘VERSION_LESS_EQUAL’,
‘VERSION_GREATER’, ‘VERSION_GREATER_EQUAL’, and ‘MATCHES’.  Then the
boolean operators in the order ‘NOT’, ‘AND’, and finally ‘OR’.

Possible conditions are:

‘if(<constant>)’

     True if the constant is ‘1’, ‘ON’, ‘YES’, ‘TRUE’, ‘Y’, or a
     non-zero number.  False if the constant is ‘0’, ‘OFF’, ‘NO’,
     ‘FALSE’, ‘N’, ‘IGNORE’, ‘NOTFOUND’, the empty string, or ends in
     the suffix ‘-NOTFOUND’.  Named boolean constants are
     case-insensitive.  If the argument is not one of these specific
     constants, it is treated as a variable or string and the following
     signature is used.

‘if(<variable|string>)’

     True if given a variable that is defined to a value that is not a
     false constant.  False otherwise.  (Note macro arguments are not
     variables.)

‘if(NOT <condition>)’

     True if the condition is not true.

‘if(<cond1> AND <cond2>)’

     True if both conditions would be considered true individually.

‘if(<cond1> OR <cond2>)’

     True if either condition would be considered true individually.

‘if(COMMAND command-name)’

     True if the given name is a command, macro or function that can be
     invoked.

‘if(POLICY policy-id)’

     True if the given name is an existing policy (of the form
     ‘CMP<NNNN>’).

‘if(TARGET target-name)’

     True if the given name is an existing logical target name created
     by a call to the add_executable(), add_library(),
     or add_custom_target() command that has already
     been invoked (in any directory).

‘if(TEST test-name)’

     True if the given name is an existing test name created by the
     add_test() command.

‘if(EXISTS path-to-file-or-directory)’

     True if the named file or directory exists.  Behavior is
     well-defined only for full paths.  Resolves symbolic links, i.e.
     if the named file or directory is a symbolic link, returns true if
     the target of the symbolic link exists.

‘if(file1 IS_NEWER_THAN file2)’

     True if ‘file1’ is newer than ‘file2’ or if one of the two files
     doesn’t exist.  Behavior is well-defined only for full paths.  If
     the file time stamps are exactly the same, an ‘IS_NEWER_THAN’
     comparison returns true, so that any dependent build operations
     will occur in the event of a tie.  This includes the case of
     passing the same file name for both file1 and file2.

‘if(IS_DIRECTORY path-to-directory)’

     True if the given name is a directory.  Behavior is well-defined
     only for full paths.

‘if(IS_SYMLINK file-name)’

     True if the given name is a symbolic link.  Behavior is
     well-defined only for full paths.

‘if(IS_ABSOLUTE path)’

     True if the given path is an absolute path.

‘if(<variable|string> MATCHES regex)’

     True if the given string or variable’s value matches the given
     regular condition.  See Regex Specification for regex
     format.  ‘()’ groups are captured in CMAKE_MATCH_<n>.
     variables.

‘if(<variable|string> LESS <variable|string>)’

     True if the given string or variable’s value is a valid number and
     less than that on the right.

‘if(<variable|string> GREATER <variable|string>)’

     True if the given string or variable’s value is a valid number and
     greater than that on the right.

‘if(<variable|string> EQUAL <variable|string>)’

     True if the given string or variable’s value is a valid number and
     equal to that on the right.

‘if(<variable|string> LESS_EQUAL <variable|string>)’

     True if the given string or variable’s value is a valid number and
     less than or equal to that on the right.

‘if(<variable|string> GREATER_EQUAL <variable|string>)’

     True if the given string or variable’s value is a valid number and
     greater than or equal to that on the right.

‘if(<variable|string> STRLESS <variable|string>)’

     True if the given string or variable’s value is lexicographically
     less than the string or variable on the right.

‘if(<variable|string> STRGREATER <variable|string>)’

     True if the given string or variable’s value is lexicographically
     greater than the string or variable on the right.

‘if(<variable|string> STREQUAL <variable|string>)’

     True if the given string or variable’s value is lexicographically
     equal to the string or variable on the right.

‘if(<variable|string> STRLESS_EQUAL <variable|string>)’

     True if the given string or variable’s value is lexicographically
     less than or equal to the string or variable on the right.

‘if(<variable|string> STRGREATER_EQUAL <variable|string>)’

     True if the given string or variable’s value is lexicographically
     greater than or equal to the string or variable on the right.

‘if(<variable|string> VERSION_LESS <variable|string>)’

     Component-wise integer version number comparison (version format is
     ‘major[.minor[.patch[.tweak]]]’, omitted components are treated as
     zero).  Any non-integer version component or non-integer trailing
     part of a version component effectively truncates the string at
     that point.

‘if(<variable|string> VERSION_GREATER <variable|string>)’

     Component-wise integer version number comparison (version format is
     ‘major[.minor[.patch[.tweak]]]’, omitted components are treated as
     zero).  Any non-integer version component or non-integer trailing
     part of a version component effectively truncates the string at
     that point.

‘if(<variable|string> VERSION_EQUAL <variable|string>)’

     Component-wise integer version number comparison (version format is
     ‘major[.minor[.patch[.tweak]]]’, omitted components are treated as
     zero).  Any non-integer version component or non-integer trailing
     part of a version component effectively truncates the string at
     that point.

‘if(<variable|string> VERSION_LESS_EQUAL <variable|string>)’

     Component-wise integer version number comparison (version format is
     ‘major[.minor[.patch[.tweak]]]’, omitted components are treated as
     zero).  Any non-integer version component or non-integer trailing
     part of a version component effectively truncates the string at
     that point.

‘if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)’

     Component-wise integer version number comparison (version format is
     ‘major[.minor[.patch[.tweak]]]’, omitted components are treated as
     zero).  Any non-integer version component or non-integer trailing
     part of a version component effectively truncates the string at
     that point.

‘if(<variable|string> IN_LIST <variable>)’

     True if the given element is contained in the named list variable.

‘if(DEFINED <name>|CACHE{<name>}|ENV{<name>})’

     True if a variable, cache variable or environment variable with
     given ‘<name>’ is defined.  The value of the variable does not
     matter.  Note that macro arguments are not variables.

‘if((condition) AND (condition OR (condition)))’

     The conditions inside the parenthesis are evaluated first and then
     the remaining condition is evaluated as in the previous examples.
     Where there are nested parenthesis the innermost are evaluated as
     part of evaluating the condition that contains them.

7.1.29.3 Variable Expansion
...........................

The if command was written very early in CMake’s history, predating the
‘${}’ variable evaluation syntax, and for convenience evaluates
variables named by its arguments as shown in the above signatures.  Note
that normal variable evaluation with ‘${}’ applies before the if command
even receives the arguments.  Therefore code like

     set(var1 OFF)
     set(var2 "var1")
     if(${var2})

appears to the if command as

     if(var1)

and is evaluated according to the ‘if(<variable>)’ case documented
above.  The result is ‘OFF’ which is false.  However, if we remove the
‘${}’ from the example then the command sees

     if(var2)

which is true because ‘var2’ is defined to ‘var1’ which is not a false
constant.

Automatic evaluation applies in the other cases whenever the
above-documented condition syntax accepts ‘<variable|string>’:

   * The left hand argument to ‘MATCHES’ is first checked to see if it
     is a defined variable, if so the variable’s value is used,
     otherwise the original value is used.

   * If the left hand argument to ‘MATCHES’ is missing it returns false
     without error

   * Both left and right hand arguments to ‘LESS’, ‘GREATER’, ‘EQUAL’,
     ‘LESS_EQUAL’, and ‘GREATER_EQUAL’, are independently tested to see
     if they are defined variables, if so their defined values are used
     otherwise the original value is used.

   * Both left and right hand arguments to ‘STRLESS’, ‘STRGREATER’,
     ‘STREQUAL’, ‘STRLESS_EQUAL’, and ‘STRGREATER_EQUAL’ are
     independently tested to see if they are defined variables, if so
     their defined values are used otherwise the original value is used.

   * Both left and right hand arguments to ‘VERSION_LESS’,
     ‘VERSION_GREATER’, ‘VERSION_EQUAL’, ‘VERSION_LESS_EQUAL’, and
     ‘VERSION_GREATER_EQUAL’ are independently tested to see if they are
     defined variables, if so their defined values are used otherwise
     the original value is used.

   * The right hand argument to ‘NOT’ is tested to see if it is a
     boolean constant, if so the value is used, otherwise it is assumed
     to be a variable and it is dereferenced.

   * The left and right hand arguments to ‘AND’ and ‘OR’ are
     independently tested to see if they are boolean constants, if so
     they are used as such, otherwise they are assumed to be variables
     and are dereferenced.

To prevent ambiguity, potential variable or keyword names can be
specified in a Quoted Argument or a Bracket Argument.
A quoted or bracketed variable or keyword will be interpreted as a
string and not dereferenced or interpreted.  See policy CMP0054.

There is no automatic evaluation for environment or cache Variable References.
Their values must be referenced as ‘$ENV{<name>}’ or
‘$CACHE{<name>}’ wherever the above-documented condition syntax accepts
‘<variable|string>’.

7.1.30 include
--------------

Load and run CMake code from a file or module.

     include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
                           [NO_POLICY_SCOPE])

Loads and runs CMake code from the file given.  Variable reads and
writes access the scope of the caller (dynamic scoping).  If ‘OPTIONAL’
is present, then no error is raised if the file does not exist.  If
‘RESULT_VARIABLE’ is given the variable ‘<var>’ will be set to the full
filename which has been included or ‘NOTFOUND’ if it failed.

If a module is specified instead of a file, the file with name
‘<modulename>.cmake’ is searched first in CMAKE_MODULE_PATH,
then in the CMake module directory.  There is one exception to this: if
the file which calls ‘include()’ is located itself in the CMake builtin
module directory, then first the CMake builtin module directory is
searched and CMAKE_MODULE_PATH afterwards.  See also policy
CMP0017.

See the cmake_policy() command documentation for discussion
of the ‘NO_POLICY_SCOPE’ option.

7.1.31 include_guard
--------------------

New in version 3.10.

Provides an include guard for the file currently being processed by
CMake.

     include_guard([DIRECTORY|GLOBAL])

Sets up an include guard for the current CMake file (see the
CMAKE_CURRENT_LIST_FILE variable documentation).

CMake will end its processing of the current file at the location of the
include_guard() command if the current file has already been
processed for the applicable scope (see below).  This provides
functionality similar to the include guards commonly used in source
headers or to the ‘#pragma once’ directive.  If the current file has
been processed previously for the applicable scope, the effect is as
though return() had been called.  Do not call this command
from inside a function being defined within the current file.

An optional argument specifying the scope of the guard may be provided.
Possible values for the option are:

‘DIRECTORY’

     The include guard applies within the current directory and below.
     The file will only be included once within this directory scope,
     but may be included again by other files outside of this directory
     (i.e.  a parent directory or another directory not pulled in by
     add_subdirectory() or include() from the
     current file or its children).

‘GLOBAL’

     The include guard applies globally to the whole build.  The current
     file will only be included once regardless of the scope.

If no arguments given, ‘include_guard’ has the same scope as a variable,
meaning that the include guard effect is isolated by the most recent
function scope or current directory if no inner function scopes exist.
In this case the command behavior is the same as:

     if(__CURRENT_FILE_VAR__)
       return()
     endif()
     set(__CURRENT_FILE_VAR__ TRUE)

7.1.32 list
-----------

List operations.

7.1.32.1 Synopsis
.................

     See Reading.
       list(see LENGTH. <list> <out-var>)
       list(see GET. <list> <element index> [<index> ...] <out-var>)
       list(see JOIN. <list> <glue> <out-var>)
       list(see SUBLIST. <list> <begin> <length> <out-var>)

     See Search.
       list(see FIND. <list> <value> <out-var>)

     See Modification.
       list(see APPEND. <list> [<element>...])
       list(see FILTER. <list> {INCLUDE | EXCLUDE} REGEX <regex>)
       list(see INSERT. <list> <index> [<element>...])
       list(see POP_BACK. <list> [<out-var>...])
       list(see POP_FRONT. <list> [<out-var>...])
       list(see PREPEND. <list> [<element>...])
       list(see REMOVE_ITEM. <list> <value>...)
       list(see REMOVE_AT. <list> <index>...)
       list(see REMOVE_DUPLICATES. <list>)
       list(see TRANSFORM. <list> <ACTION> [...])

     See Ordering.
       list(see REVERSE. <list>)
       list(see SORT. <list> [...])

7.1.32.2 Introduction
.....................

The list subcommands ‘APPEND’, ‘INSERT’, ‘FILTER’, ‘PREPEND’,
‘POP_BACK’, ‘POP_FRONT’, ‘REMOVE_AT’, ‘REMOVE_ITEM’,
‘REMOVE_DUPLICATES’, ‘REVERSE’ and ‘SORT’ may create new values for the
list within the current CMake variable scope.  Similar to the
set() command, the LIST command creates new variable values in the
current scope, even if the list itself is actually defined in a parent
scope.  To propagate the results of these operations upwards, use
set() with ‘PARENT_SCOPE’, see set() with ‘CACHE INTERNAL’,
or some other means of value propagation.

     Note: A list in cmake is a ‘;’ separated group of strings.  To
     create a list the set command can be used.  For example, ‘set(var a
     b c d e)’ creates a list with ‘a;b;c;d;e’, and ‘set(var "a b c d
     e")’ creates a string or a list with one item in it.  (Note macro
     arguments are not variables, and therefore cannot be used in LIST
     commands.)

     Note: When specifying index values, if ‘<element index>’ is 0 or
     greater, it is indexed from the beginning of the list, with 0
     representing the first list element.  If ‘<element index>’ is -1 or
     lesser, it is indexed from the end of the list, with -1
     representing the last list element.  Be careful when counting with
     negative indices: they do not start from 0.  -0 is equivalent to 0,
     the first list element.

7.1.32.3 Reading
................

     list(LENGTH <list> <output variable>)

Returns the list’s length.
     list(GET <list> <element index> [<element index> ...] <output variable>)

Returns the list of elements specified by indices from the list.
     list(JOIN <list> <glue> <output variable>)

Returns a string joining all list’s elements using the glue string.  To
join multiple strings, which are not part of a list, use ‘JOIN’ operator
from string() command.
     list(SUBLIST <list> <begin> <length> <output variable>)

Returns a sublist of the given list.  If ‘<length>’ is 0, an empty list
will be returned.  If ‘<length>’ is -1 or the list is smaller than
‘<begin>+<length>’ then the remaining elements of the list starting at
‘<begin>’ will be returned.

7.1.32.4 Search
...............

     list(FIND <list> <value> <output variable>)

Returns the index of the element specified in the list or -1 if it
wasn’t found.

7.1.32.5 Modification
.....................

     list(APPEND <list> [<element> ...])

Appends elements to the list.
     list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)

Includes or removes items from the list that match the mode’s pattern.
In ‘REGEX’ mode, items will be matched against the given regular
expression.

For more information on regular expressions see also the string()
command.
     list(INSERT <list> <element_index> <element> [<element> ...])

Inserts elements to the list to the specified location.
     list(POP_BACK <list> [<out-var>...])

If no variable name is given, removes exactly one element.  Otherwise,
assign the last element’s value to the given variable and removes it, up
to the last variable name given.
     list(POP_FRONT <list> [<out-var>...])

If no variable name is given, removes exactly one element.  Otherwise,
assign the first element’s value to the given variable and removes it,
up to the last variable name given.
     list(PREPEND <list> [<element> ...])

Insert elements to the 0th position in the list.
     list(REMOVE_ITEM <list> <value> [<value> ...])

Removes all instances of the given items from the list.
     list(REMOVE_AT <list> <index> [<index> ...])

Removes items at given indices from the list.
     list(REMOVE_DUPLICATES <list>)

Removes duplicated items in the list.  The relative order of items is
preserved, but if duplicates are encountered, only the first instance is
preserved.
     list(TRANSFORM <list> <ACTION> [<SELECTOR>]
                           [OUTPUT_VARIABLE <output variable>])

Transforms the list by applying an action to all or, by specifying a
‘<SELECTOR>’, to the selected elements of the list, storing the result
in-place or in the specified output variable.

     Note: The ‘TRANSFORM’ sub-command does not change the number of
     elements in the list.  If a ‘<SELECTOR>’ is specified, only some
     elements will be changed, the other ones will remain the same as
     before the transformation.

‘<ACTION>’ specifies the action to apply to the elements of the list.
The actions have exactly the same semantics as sub-commands of the
string() command.  ‘<ACTION>’ must be one of the following:

‘APPEND’, ‘PREPEND’: Append, prepend specified value to each element of
the list.

          list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)

‘TOUPPER’, ‘TOLOWER’: Convert each element of the list to upper, lower
characters.

          list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)

‘STRIP’: Remove leading and trailing spaces from each element of the
list.

          list(TRANSFORM <list> STRIP ...)

‘GENEX_STRIP’: Strip any generator expressions from each
element of the list.

          list(TRANSFORM <list> GENEX_STRIP ...)

‘REPLACE’: Match the regular expression as many times as possible and
substitute the replacement expression for the match for each element of
the list (Same semantic as ‘REGEX REPLACE’ from string().
command).

          list(TRANSFORM <list> REPLACE <regular_expression>
                                        <replace_expression> ...)

‘<SELECTOR>’ determines which elements of the list will be transformed.
Only one type of selector can be specified at a time.  When given,
‘<SELECTOR>’ must be one of the following:

‘AT’: Specify a list of indexes.

          list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)

‘FOR’: Specify a range with, optionally, an increment used to iterate
over the range.

          list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)

‘REGEX’: Specify a regular expression.  Only elements matching the
regular expression will be transformed.

          list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)

7.1.32.6 Ordering
.................

     list(REVERSE <list>)

Reverses the contents of the list in-place.
     list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

Sorts the list in-place alphabetically.  Use the ‘COMPARE’ keyword to
select the comparison method for sorting.  The ‘<compare>’ option should
be one of:

   * ‘STRING’: Sorts a list of strings alphabetically.  This is the
     default behavior if the ‘COMPARE’ option is not given.

   * ‘FILE_BASENAME’: Sorts a list of pathnames of files by their
     basenames.

   * ‘NATURAL’: Sorts a list of strings using natural order (see
     ‘strverscmp(3)’ manual), i.e.  such that contiguous digits are
     compared as whole numbers.  For example: the following list ‘10.0
     1.1 2.1 8.0 2.0 3.1’ will be sorted as ‘1.1 2.0 2.1 3.1 8.0 10.0’
     if the ‘NATURAL’ comparison is selected where it will be sorted as
     ‘1.1 10.0 2.0 2.1 3.1 8.0’ with the ‘STRING’ comparison.

Use the ‘CASE’ keyword to select a case sensitive or case insensitive
sort mode.  The ‘<case>’ option should be one of:

   * ‘SENSITIVE’: List items are sorted in a case-sensitive manner.
     This is the default behavior if the ‘CASE’ option is not given.

   * ‘INSENSITIVE’: List items are sorted case insensitively.  The order
     of items which differ only by upper/lowercase is not specified.

To control the sort order, the ‘ORDER’ keyword can be given.  The
‘<order>’ option should be one of:

   * ‘ASCENDING’: Sorts the list in ascending order.  This is the
     default behavior when the ‘ORDER’ option is not given.

   * ‘DESCENDING’: Sorts the list in descending order.

7.1.33 macro
------------

Start recording a macro for later invocation as a command

     macro(<name> [<arg1> ...])
       <commands>
     endmacro()

Defines a macro named ‘<name>’ that takes arguments named ‘<arg1>’, …
Commands listed after macro, but before the matching endmacro(),
are not executed until the macro is invoked.

Per legacy, the endmacro() command admits an optional
‘<name>’ argument.  If used, it must be a verbatim repeat of the
argument of the opening ‘macro’ command.

See the cmake_policy() command documentation for the
behavior of policies inside macros.

See the Macro vs Function section below for differences
between CMake macros and functions.

7.1.33.1 Invocation
...................

The macro invocation is case-insensitive.  A macro defined as

     macro(foo)
       <commands>
     endmacro()

can be invoked through any of

     foo()
     Foo()
     FOO()
     cmake_language(CALL foo)

and so on.  However, it is strongly recommended to stay with the case
chosen in the macro definition.  Typically macros use all-lowercase
names.

The cmake_language(CALL ...) command can also be used to
invoke the macro.

7.1.33.2 Arguments
..................

When a macro is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (‘${arg1}’, …) with the
arguments passed, and then invoked as normal commands.

In addition to referencing the formal parameters you can reference the
values ‘${ARGC}’ which will be set to the number of arguments passed
into the function as well as ‘${ARGV0}’, ‘${ARGV1}’, ‘${ARGV2}’, … which
will have the actual values of the arguments passed in.  This
facilitates creating macros with optional arguments.

Furthermore, ‘${ARGV}’ holds the list of all arguments given to the
macro and ‘${ARGN}’ holds the list of arguments past the last expected
argument.  Referencing to ‘${ARGV#}’ arguments beyond ‘${ARGC}’ have
undefined behavior.  Checking that ‘${ARGC}’ is greater than ‘#’ is the
only way to ensure that ‘${ARGV#}’ was passed to the function as an
extra argument.

7.1.33.3 Macro vs Function
..........................

The ‘macro’ command is very similar to the function().
command.  Nonetheless, there are a few important differences.

In a function, ‘ARGN’, ‘ARGC’, ‘ARGV’ and ‘ARGV0’, ‘ARGV1’, … are true
variables in the usual CMake sense.  In a macro, they are not, they are
string replacements much like the C preprocessor would do with a macro.
This has a number of consequences, as explained in the Argument Caveats
section below.

Another difference between macros and functions is the control flow.  A
function is executed by transferring control from the calling statement
to the function body.  A macro is executed as if the macro body were
pasted in place of the calling statement.  This has the consequence that
a return() in a macro body does not just terminate execution
of the macro; rather, control is returned from the scope of the macro
call.  To avoid confusion, it is recommended to avoid return()
in macros altogether.

Unlike a function, the CMAKE_CURRENT_FUNCTION,
CMAKE_CURRENT_FUNCTION_LIST_DIR,
CMAKE_CURRENT_FUNCTION_LIST_FILE,
CMAKE_CURRENT_FUNCTION_LIST_LINE variables are not set for a
macro.

7.1.33.4 Argument Caveats
.........................

Since ‘ARGN’, ‘ARGC’, ‘ARGV’, ‘ARGV0’ etc.  are not variables, you will
NOT be able to use commands like

     if(ARGV1) # ARGV1 is not a variable
     if(DEFINED ARGV2) # ARGV2 is not a variable
     if(ARGC GREATER 2) # ARGC is not a variable
     foreach(loop_var IN LISTS ARGN) # ARGN is not a variable

In the first case, you can use ‘if(${ARGV1})’.  In the second and third
case, the proper way to check if an optional variable was passed to the
macro is to use ‘if(${ARGC} GREATER 2)’.  In the last case, you can use
‘foreach(loop_var ${ARGN})’ but this will skip empty arguments.  If you
need to include them, you can use

     set(list_var "${ARGN}")
     foreach(loop_var IN LISTS list_var)

Note that if you have a variable with the same name in the scope from
which the macro is called, using unreferenced names will use the
existing variable instead of the arguments.  For example:

     macro(bar)
       foreach(arg IN LISTS ARGN)
         <commands>
       endforeach()
     endmacro()

     function(foo)
       bar(x y z)
     endfunction()

     foo(a b c)

Will loop over ‘a;b;c’ and not over ‘x;y;z’ as one might have expected.
If you want true CMake variables and/or better CMake scope control you
should look at the function command.

7.1.34 mark_as_advanced
-----------------------

Mark cmake cached variables as advanced.

     mark_as_advanced([CLEAR|FORCE] <var1> ...)

Sets the advanced/non-advanced state of the named cached variables.

An advanced variable will not be displayed in any of the cmake GUIs
unless the ‘show advanced’ option is on.  In script mode, the
advanced/non-advanced state has no effect.

If the keyword ‘CLEAR’ is given then advanced variables are changed back
to unadvanced.  If the keyword ‘FORCE’ is given then the variables are
made advanced.  If neither ‘FORCE’ nor ‘CLEAR’ is specified, new values
will be marked as advanced, but if a variable already has an
advanced/non-advanced state, it will not be changed.

     Note: Policy CMP0102 affects the behavior of the
     ‘mark_as_advanced’ call.  When set to ‘NEW’, variables passed to
     this command which are not already in the cache are ignored.  See
     policy CMP0102.

7.1.35 math
-----------

Evaluate a mathematical expression.

     math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])

Evaluates a mathematical ‘<expression>’ and sets ‘<variable>’ to the
resulting value.  The result of the expression must be representable as
a 64-bit signed integer.

The mathematical expression must be given as a string (i.e.  enclosed in
double quotation marks).  An example is ‘"5 * (10 + 13)"’.  Supported
operators are ‘+’, ‘-’, ‘*’, ‘/’, ‘%’, ‘|’, ‘&’, ‘^’, ‘~’, ‘<<’, ‘>>’,
and ‘(...)’; they have the same meaning as in C code.

Hexadecimal numbers are recognized when prefixed with ‘0x’, as in C
code.

The result is formatted according to the option ‘OUTPUT_FORMAT’, where
‘<format>’ is one of

‘HEXADECIMAL’

     Hexadecimal notation as in C code, i.  e.  starting with “0x”.

‘DECIMAL’

     Decimal notation.  Which is also used if no ‘OUTPUT_FORMAT’ option
     is specified.

For example

     math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL)      # value is set to "1000"
     math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL)  # value is set to "0x3e8"

7.1.36 message
--------------

Log a message.

7.1.36.1 Synopsis
.................

     See General messages.
       message([<mode>] "message text" ...)

     See Reporting checks.
       message(<checkState> "message text" ...)

7.1.36.2 General messages
.........................

     message([<mode>] "message text" ...)

Record the specified message text in the log.  If more than one message
string is given, they are concatenated into a single message with no
separator between the strings.

The optional ‘<mode>’ keyword determines the type of message, which
influences the way the message is handled:

‘FATAL_ERROR’

     CMake Error, stop processing and generation.

‘SEND_ERROR’

     CMake Error, continue processing, but skip generation.

‘WARNING’

     CMake Warning, continue processing.

‘AUTHOR_WARNING’

     CMake Warning (dev), continue processing.

‘DEPRECATION’

     CMake Deprecation Error or Warning if variable
     CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED.
     is enabled, respectively, else no message.

(none) or ‘NOTICE’

     Important message printed to stderr to attract user’s attention.

‘STATUS’

     The main interesting messages that project users might be
     interested in.  Ideally these should be concise, no more than a
     single line, but still informative.

‘VERBOSE’

     Detailed informational messages intended for project users.  These
     messages should provide additional details that won’t be of
     interest in most cases, but which may be useful to those building
     the project when they want deeper insight into what’s happening.

‘DEBUG’

     Detailed informational messages intended for developers working on
     the project itself as opposed to users who just want to build it.
     These messages will not typically be of interest to other users
     building the project and will often be closely related to internal
     implementation details.

‘TRACE’

     Fine-grained messages with very low-level implementation details.
     Messages using this log level would normally only be temporary and
     would expect to be removed before releasing the project, packaging
     up the files, etc.

The CMake command-line tool displays ‘STATUS’ to ‘TRACE’ messages on
stdout with the message preceded by two hyphens and a space.  All other
message types are sent to stderr and are not prefixed with hyphens.  The
CMake GUI displays all messages in its log area.  The
curses interface shows ‘STATUS’ to ‘TRACE’ messages one at a time
on a status line and other messages in an interactive pop-up box.  The
‘--log-level’ command-line option to each of these tools can be used to
control which messages will be shown.  To make a log level persist
between CMake runs, the CMAKE_MESSAGE_LOG_LEVEL variable can
be set instead.  Note that the command line option takes precedence over
the cache variable.

Messages of log levels ‘NOTICE’ and below will have each line preceded
by the content of the CMAKE_MESSAGE_INDENT variable
(converted to a single string by concatenating its list items).  For
‘STATUS’ to ‘TRACE’ messages, this indenting content will be inserted
after the hyphens.

Messages of log levels ‘NOTICE’ and below can also have each line
preceded with context of the form ‘[some.context.example]’.  The content
between the square brackets is obtained by converting the
CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
The message context will always appear before any indenting content but
after any automatically added leading hyphens.  By default, message
context is not shown, it has to be explicitly enabled by giving the
cmake. ‘--log-context’ command-line option or by setting the
CMAKE_MESSAGE_CONTEXT_SHOW variable to true.  See the
CMAKE_MESSAGE_CONTEXT documentation for usage examples.

CMake Warning and Error message text displays using a simple markup
language.  Non-indented text is formatted in line-wrapped paragraphs
delimited by newlines.  Indented text is considered pre-formatted.

7.1.36.3 Reporting checks
.........................

A common pattern in CMake output is a message indicating the start of
some sort of check, followed by another message reporting the result of
that check.  For example:

     message(STATUS "Looking for someheader.h")
     #... do the checks, set checkSuccess with the result
     if(checkSuccess)
       message(STATUS "Looking for someheader.h - found")
     else()
       message(STATUS "Looking for someheader.h - not found")
     endif()

This can be more robustly and conveniently expressed using the
‘CHECK_...’ keyword form of the ‘message()’ command:

     message(<checkState> "message" ...)

where ‘<checkState>’ must be one of the following:

     ‘CHECK_START’

          Record a concise message about the check about to be
          performed.

     ‘CHECK_PASS’

          Record a successful result for a check.

     ‘CHECK_FAIL’

          Record an unsuccessful result for a check.

When recording a check result, the command repeats the message from the
most recently started check for which no result has yet been reported,
then some separator characters and then the message text provided after
the ‘CHECK_PASS’ or ‘CHECK_FAIL’ keyword.  Check messages are always
reported at ‘STATUS’ log level.

Checks may be nested and every ‘CHECK_START’ should have exactly one
matching ‘CHECK_PASS’ or ‘CHECK_FAIL’.  The CMAKE_MESSAGE_INDENT
variable can also be used to add indenting to nested checks if
desired.  For example:

     message(CHECK_START "Finding my things")
     list(APPEND CMAKE_MESSAGE_INDENT "  ")
     unset(missingComponents)

     message(CHECK_START "Finding partA")
     # ... do check, assume we find A
     message(CHECK_PASS "found")

     message(CHECK_START "Finding partB")
     # ... do check, assume we don't find B
     list(APPEND missingComponents B)
     message(CHECK_FAIL "not found")

     list(POP_BACK CMAKE_MESSAGE_INDENT)
     if(missingComponents)
       message(CHECK_FAIL "missing components: ${missingComponents}")
     else()
       message(CHECK_PASS "all components found")
     endif()

Output from the above would appear something like the following:

     -- Finding my things
     --   Finding partA
     --   Finding partA - found
     --   Finding partB
     --   Finding partB - not found
     -- Finding my things - missing components: B

7.1.37 option
-------------

Provide an option that the user can optionally select.

     option(<variable> "<help_text>" [value])

Provides an option for the user to select as ‘ON’ or ‘OFF’.  If no
initial ‘<value>’ is provided, ‘OFF’ is used.  If ‘<variable>’ is
already set as a normal or cache variable, then the command does nothing
(see policy CMP0077).

If you have options that depend on the values of other options, see the
module help for CMakeDependentOption.

7.1.38 return
-------------

Return from a file, directory or function.

     return()

Returns from a file, directory or function.  When this command is
encountered in an included file (via include() or
find_package()), it causes processing of the current file to stop
and control is returned to the including file.  If it is encountered in
a file which is not included by another file, e.g.  a ‘CMakeLists.txt’,
deferred calls scheduled by cmake_language(DEFER) are invoked
and control is returned to the parent directory if there is one.  If
return is called in a function, control is returned to the caller of the
function.

Note that a macro, unlike a function, is expanded
in place and therefore cannot handle ‘return()’.

7.1.39 separate_arguments
-------------------------

Parse command-line arguments into a semicolon-separated list.

     separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)

Parses a space-separated string ‘<args>’ into a list of items, and
stores this list in semicolon-separated standard form in ‘<variable>’.

This function is intended for parsing command-line arguments.  The
entire command line must be passed as one string in the argument
‘<args>’.

The exact parsing rules depend on the operating system.  They are
specified by the ‘<mode>’ argument which must be one of the following
keywords:

‘UNIX_COMMAND’

     Arguments are separated by unquoted whitespace.  Both single-quote
     and double-quote pairs are respected.  A backslash escapes the next
     literal character (‘\"’ is ‘"’); there are no special escapes (‘\n’
     is just ‘n’).

‘WINDOWS_COMMAND’

     A Windows command-line is parsed using the same syntax the runtime
     library uses to construct argv at startup.  It separates arguments
     by whitespace that is not double-quoted.  Backslashes are literal
     unless they precede double-quotes.  See the MSDN article Parsing C
     Command-Line Arguments(1) for details.

‘NATIVE_COMMAND’

     Proceeds as in ‘WINDOWS_COMMAND’ mode if the host system is
     Windows.  Otherwise proceeds as in ‘UNIX_COMMAND’ mode.

‘PROGRAM’

     The first item in ‘<args>’ is assumed to be an executable and will
     be searched in the system search path or left as a full path.  If
     not found, ‘<variable>’ will be empty.  Otherwise, ‘<variable>’ is
     a list of 2 elements:

            0. Absolute path of the program

            1. Any command-line arguments present in ‘<args>’ as a
               string

     For example:

          separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")

        * First element of the list: ‘/path/to/cc’

        * Second element of the list: ‘" -c main.c"’

‘SEPARATE_ARGS’

     When this sub-option of ‘PROGRAM’ option is specified, command-line
     arguments will be split as well and stored in ‘<variable>’.

     For example:

          separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")

     The contents of ‘out’ will be: ‘/path/to/cc;-c;main.c’

     separate_arguments(<var>)

Convert the value of ‘<var>’ to a semi-colon separated list.  All spaces
are replaced with ‘;’.  This helps with generating command lines.

   ---------- Footnotes ----------

   (1) https://msdn.microsoft.com/library/a1y7w461.aspx

7.1.40 set
----------

Set a normal, cache, or environment variable to a given value.  See the
cmake-language(7) variables documentation for the scopes and
interaction of normal variables and cache entries.

Signatures of this command that specify a ‘<value>...’ placeholder
expect zero or more arguments.  Multiple arguments will be joined as a
semicolon-separated list to form the actual variable value to
be set.  Zero arguments will cause normal variables to be unset.  See
the unset() command to unset variables explicitly.

7.1.40.1 Set Normal Variable
............................

     set(<variable> <value>... [PARENT_SCOPE])

Sets the given ‘<variable>’ in the current function or directory scope.

If the ‘PARENT_SCOPE’ option is given the variable will be set in the
scope above the current scope.  Each new directory or function creates a
new scope.  This command will set the value of a variable into the
parent directory or calling function (whichever is applicable to the
case at hand).  The previous state of the variable’s value stays the
same in the current scope (e.g., if it was undefined before, it is still
undefined and if it had a value, it is still that value).

7.1.40.2 Set Cache Entry
........................

     set(<variable> <value>... CACHE <type> <docstring> [FORCE])

Sets the given cache ‘<variable>’ (cache entry).  Since cache entries
are meant to provide user-settable values this does not overwrite
existing cache entries by default.  Use the ‘FORCE’ option to overwrite
existing entries.

The ‘<type>’ must be specified as one of:

‘BOOL’

     Boolean ‘ON/OFF’ value.  cmake-gui(1) offers a checkbox.

‘FILEPATH’

     Path to a file on disk.  cmake-gui(1) offers a file
     dialog.

‘PATH’

     Path to a directory on disk.  cmake-gui(1) offers a file
     dialog.

‘STRING’

     A line of text.  cmake-gui(1) offers a text field or a
     drop-down selection if the STRINGS cache entry property
     is set.

‘INTERNAL’

     A line of text.  cmake-gui(1) does not show internal
     entries.  They may be used to store variables persistently across
     runs.  Use of this type implies ‘FORCE’.

The ‘<docstring>’ must be specified as a line of text providing a quick
summary of the option for presentation to cmake-gui(1) users.

If the cache entry does not exist prior to the call or the ‘FORCE’
option is given then the cache entry will be set to the given value.
Furthermore, any normal variable binding in the current scope will be
removed to expose the newly cached value to any immediately following
evaluation.

It is possible for the cache entry to exist prior to the call but have
no type set if it was created on the cmake(1) command line by
a user through the ‘-D<var>=<value>’ option without specifying a type.
In this case the ‘set’ command will add the type.  Furthermore, if the
‘<type>’ is ‘PATH’ or ‘FILEPATH’ and the ‘<value>’ provided on the
command line is a relative path, then the ‘set’ command will treat the
path as relative to the current working directory and convert it to an
absolute path.

7.1.40.3 Set Environment Variable
.................................

     set(ENV{<variable>} [<value>])

Sets an Environment Variable to the given value.  Subsequent
calls of ‘$ENV{<variable>}’ will return this new value.

This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large, nor
the environment of subsequent build or test processes.

If no argument is given after ‘ENV{<variable>}’ or if ‘<value>’ is an
empty string, then this command will clear any existing value of the
environment variable.

Arguments after ‘<value>’ are ignored.  If extra arguments are found,
then an author warning is issued.

7.1.41 set_directory_properties
-------------------------------

Set properties of the current directory and subdirectories.

     set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)

Sets properties of the current directory and its subdirectories in
key-value pairs.

See also the set_property(DIRECTORY) command.

See Properties on Directories for the list of properties
known to CMake and their individual documentation for the behavior of
each property.

7.1.42 set_property
-------------------

Set a named property in a given scope.

     set_property(<GLOBAL                      |
                   DIRECTORY [<dir>]           |
                   TARGET    [<target1> ...]   |
                   SOURCE    [<src1> ...]
                             [DIRECTORY <dirs> ...] |
                             [TARGET_DIRECTORY <targets> ...]
                   INSTALL   [<file1> ...]     |
                   TEST      [<test1> ...]     |
                   CACHE     [<entry1> ...]    >
                  [APPEND] [APPEND_STRING]
                  PROPERTY <name> [<value1> ...])

Sets one property on zero or more objects of a scope.

The first argument determines the scope in which the property is set.
It must be one of the following:

‘GLOBAL’

     Scope is unique and does not accept a name.

‘DIRECTORY’

     Scope defaults to the current directory but other directories
     (already processed by CMake) may be named by full or relative path.
     Each path may reference either a source directory, or since CMake
     3.19, a binary directory.  Relative paths are treated as relative
     to the current source directory.  See also the
     set_directory_properties() command.

‘TARGET’

     Scope may name zero or more existing targets.  See also the
     set_target_properties() command.

‘SOURCE’

     Scope may name zero or more source files.  By default, source file
     properties are only visible to targets added in the same directory
     (‘CMakeLists.txt’).  Visibility can be set in other directory
     scopes using one or both of the following sub-options:

     ‘DIRECTORY <dirs>...’

          The source file property will be set in each of the ‘<dirs>’
          directories’ scopes.  Each path may reference either a source
          directory, or since CMake 3.19, a binary directory.  CMake
          must already know about each of these directories, either by
          having added them through a call to add_subdirectory()
          or it being the top level source directory.  Relative
          paths are treated as relative to the current source directory.

     ‘TARGET_DIRECTORY <targets>...’

          The source file property will be set in each of the directory
          scopes where any of the specified ‘<targets>’ were created
          (the ‘<targets>’ must therefore already exist).

     See also the set_source_files_properties() command.

‘INSTALL’

     Scope may name zero or more installed file paths.  These are made
     available to CPack to influence deployment.

     Both the property key and value may use generator expressions.
     Specific properties may apply to installed files and/or
     directories.

     Path components have to be separated by forward slashes, must be
     normalized and are case sensitive.

     To reference the installation prefix itself with a relative path
     use ‘.’.

     Currently installed file properties are only defined for the WIX
     generator where the given paths are relative to the installation
     prefix.

‘TEST’

     Scope may name zero or more existing tests.  See also the
     set_tests_properties() command.

‘CACHE’

     Scope must name zero or more cache existing entries.

The required ‘PROPERTY’ option is immediately followed by the name of
the property to set.  Remaining arguments are used to compose the
property value in the form of a semicolon-separated list.

If the ‘APPEND’ option is given the list is appended to any existing
property value (except that empty values are ignored and not appended).
If the ‘APPEND_STRING’ option is given the string is appended to any
existing property value as string, i.e.  it results in a longer string
and not a list of strings.  When using ‘APPEND’ or ‘APPEND_STRING’ with
a property defined to support ‘INHERITED’ behavior (see
define_property()), no inheriting occurs when finding the initial
value to append to.  If the property is not already directly set in the
nominated scope, the command will behave as though ‘APPEND’ or
‘APPEND_STRING’ had not been given.

See the cmake-properties(7) manual for a list of properties
in each scope.

7.1.43 site_name
----------------

Set the given variable to the name of the computer.

     site_name(variable)

7.1.44 string
-------------

String operations.

7.1.44.1 Synopsis
.................

     See Search and Replace.
       string(see FIND. <string> <substring> <out-var> [...])
       string(see REPLACE. <match-string> <replace-string> <out-var> <input>...)
       string(see REGEX MATCH. <match-regex> <out-var> <input>...)
       string(see REGEX MATCHALL. <match-regex> <out-var> <input>...)
       string(see REGEX REPLACE. <match-regex> <replace-expr> <out-var> <input>...)

     See Manipulation.
       string(see APPEND. <string-var> [<input>...])
       string(see PREPEND. <string-var> [<input>...])
       string(see CONCAT. <out-var> [<input>...])
       string(see JOIN. <glue> <out-var> [<input>...])
       string(see TOLOWER. <string> <out-var>)
       string(see TOUPPER. <string> <out-var>)
       string(see LENGTH. <string> <out-var>)
       string(see SUBSTRING. <string> <begin> <length> <out-var>)
       string(see STRIP. <string> <out-var>)
       string(see GENEX_STRIP. <string> <out-var>)
       string(see REPEAT. <string> <count> <out-var>)

     See Comparison.
       string(see COMPARE. <op> <string1> <string2> <out-var>)

     See Hashing.
       string(see <HASH>.<out-var> <input>)

     See Generation.
       string(see ASCII. <number>... <out-var>)
       string(see HEX. <string> <out-var>)
       string(see CONFIGURE. <string> <out-var> [...])
       string(see MAKE_C_IDENTIFIER. <string> <out-var>)
       string(see RANDOM. [<option>...] <out-var>)
       string(see TIMESTAMP. <out-var> [<format string>] [UTC])
       string(see UUID. <out-var> ...)

     See JSON.
       string(JSON <out-var> [ERROR_VARIABLE <error-var>]
              {see GET. | See TYPE. | See LENGTH. | See REMOVE.}
              <json-string> <member|index> [<member|index> ...])
       string(JSON <out-var> [ERROR_VARIABLE <error-var>]
              See MEMBER. <json-string>
              [<member|index> ...] <index>)
       string(JSON <out-var> [ERROR_VARIABLE <error-var>]
              See SET. <json-string>
              <member|index> [<member|index> ...] <value>)
       string(JSON <out-var> [ERROR_VARIABLE <error-var>]
              See EQUAL. <json-string1> <json-string2>)

7.1.44.2 Search and Replace
...........................

7.1.44.3 Search and Replace With Plain Strings
..............................................

     string(FIND <string> <substring> <output_variable> [REVERSE])

Return the position where the given ‘<substring>’ was found in the
supplied ‘<string>’.  If the ‘REVERSE’ flag was used, the command will
search for the position of the last occurrence of the specified
‘<substring>’.  If the ‘<substring>’ is not found, a position of -1 is
returned.

The ‘string(FIND)’ subcommand treats all strings as ASCII-only
characters.  The index stored in ‘<output_variable>’ will also be
counted in bytes, so strings containing multi-byte characters may lead
to unexpected results.
     string(REPLACE <match_string>
            <replace_string> <output_variable>
            <input> [<input>...])

Replace all occurrences of ‘<match_string>’ in the ‘<input>’ with
‘<replace_string>’ and store the result in the ‘<output_variable>’.

7.1.44.4 Search and Replace With Regular Expressions
....................................................

     string(REGEX MATCH <regular_expression>
            <output_variable> <input> [<input>...])

Match the ‘<regular_expression>’ once and store the match in the
‘<output_variable>’.  All ‘<input>’ arguments are concatenated before
matching.  Regular expressions are specified in the subsection just
below.
     string(REGEX MATCHALL <regular_expression>
            <output_variable> <input> [<input>...])

Match the ‘<regular_expression>’ as many times as possible and store the
matches in the ‘<output_variable>’ as a list.  All ‘<input>’ arguments
are concatenated before matching.
     string(REGEX REPLACE <regular_expression>
            <replacement_expression> <output_variable>
            <input> [<input>...])

Match the ‘<regular_expression>’ as many times as possible and
substitute the ‘<replacement_expression>’ for the match in the output.
All ‘<input>’ arguments are concatenated before matching.

The ‘<replacement_expression>’ may refer to parenthesis-delimited
subexpressions of the match using ‘\1’, ‘\2’, …, ‘\9’.  Note that two
backslashes (‘\\1’) are required in CMake code to get a backslash
through argument parsing.

7.1.44.5 Regex Specification
............................

The following characters have special meaning in regular expressions:

‘^’

     Matches at beginning of input

‘$’

     Matches at end of input

‘.’

     Matches any single character

‘\<char>’

     Matches the single character specified by ‘<char>’.  Use this to
     match special regex characters, e.g.  ‘\.’ for a literal ‘.’ or
     ‘\\’ for a literal backslash ‘\’.  Escaping a non-special character
     is unnecessary but allowed, e.g.  ‘\a’ matches ‘a’.

‘[ ]’

     Matches any character(s) inside the brackets

‘[^ ]’

     Matches any character(s) not inside the brackets

‘-’

     Inside brackets, specifies an inclusive range between characters on
     either side e.g.  ‘[a-f]’ is ‘[abcdef]’ To match a literal ‘-’
     using brackets, make it the first or the last character e.g.
     ‘[+*/-]’ matches basic mathematical operators.

‘*’

     Matches preceding pattern zero or more times

‘+’

     Matches preceding pattern one or more times

‘?’

     Matches preceding pattern zero or once only

‘|’

     Matches a pattern on either side of the ‘|’

‘()’

     Saves a matched subexpression, which can be referenced in the
     ‘REGEX REPLACE’ operation.  Additionally it is saved by all regular
     expression-related commands, including e.g.  see if(MATCHES),
     in the variables CMAKE_MATCH_<n> for ‘<n>’ 0..9.

‘*’, ‘+’ and ‘?’ have higher precedence than concatenation.  ‘|’ has
lower precedence than concatenation.  This means that the regular
expression ‘^ab+d$’ matches ‘abbd’ but not ‘ababd’, and the regular
expression ‘^(ab|cd)$’ matches ‘ab’ but not ‘abd’.

CMake language Escape Sequences such as ‘\t’, ‘\r’, ‘\n’,
and ‘\\’ may be used to construct literal tabs, carriage returns,
newlines, and backslashes (respectively) to pass in a regex.  For
example:

   * The quoted argument ‘"[ \t\r\n]"’ specifies a regex that matches
     any single whitespace character.

   * The quoted argument ‘"[/\\]"’ specifies a regex that matches a
     single forward slash ‘/’ or backslash ‘\’.

   * The quoted argument ‘"[A-Za-z0-9_]"’ specifies a regex that matches
     any single “word” character in the C locale.

   * The quoted argument ‘"\\(\\a\\+b\\)"’ specifies a regex that
     matches the exact string ‘(a+b)’.  Each ‘\\’ is parsed in a quoted
     argument as just ‘\’, so the regex itself is actually ‘\(\a\+\b\)’.
     This can alternatively be specified in a Bracket Argument
     without having to escape the backslashes, e.g.
     ‘[[\(\a\+\b\)]]’.

7.1.44.6 Manipulation
.....................

     string(APPEND <string_variable> [<input>...])

Append all the ‘<input>’ arguments to the string.
     string(PREPEND <string_variable> [<input>...])

Prepend all the ‘<input>’ arguments to the string.
     string(CONCAT <output_variable> [<input>...])

Concatenate all the ‘<input>’ arguments together and store the result in
the named ‘<output_variable>’.
     string(JOIN <glue> <output_variable> [<input>...])

Join all the ‘<input>’ arguments together using the ‘<glue>’ string and
store the result in the named ‘<output_variable>’.

To join a list’s elements, prefer to use the ‘JOIN’ operator from the
list() command.  This allows for the elements to have
special characters like ‘;’ in them.
     string(TOLOWER <string> <output_variable>)

Convert ‘<string>’ to lower characters.
     string(TOUPPER <string> <output_variable>)

Convert ‘<string>’ to upper characters.
     string(LENGTH <string> <output_variable>)

Store in an ‘<output_variable>’ a given string’s length in bytes.  Note
that this means if ‘<string>’ contains multi-byte characters, the result
stored in ‘<output_variable>’ will `not' be the number of characters.
     string(SUBSTRING <string> <begin> <length> <output_variable>)

Store in an ‘<output_variable>’ a substring of a given ‘<string>’.  If
‘<length>’ is ‘-1’ the remainder of the string starting at ‘<begin>’
will be returned.  If ‘<string>’ is shorter than ‘<length>’ then the end
of the string is used instead.

Both ‘<begin>’ and ‘<length>’ are counted in bytes, so care must be
exercised if ‘<string>’ could contain multi-byte characters.

     Note: CMake 3.1 and below reported an error if ‘<length>’ pointed
     past the end of ‘<string>’.
     string(STRIP <string> <output_variable>)

Store in an ‘<output_variable>’ a substring of a given ‘<string>’ with
leading and trailing spaces removed.
     string(GENEX_STRIP <string> <output_variable>)

Strip any generator expressions from the input ‘<string>’ and
store the result in the ‘<output_variable>’.
     string(REPEAT <string> <count> <output_variable>)

Produce the output string as the input ‘<string>’ repeated ‘<count>’
times.

7.1.44.7 Comparison
...................

     string(COMPARE LESS <string1> <string2> <output_variable>)
     string(COMPARE GREATER <string1> <string2> <output_variable>)
     string(COMPARE EQUAL <string1> <string2> <output_variable>)
     string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
     string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
     string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)

Compare the strings and store true or false in the ‘<output_variable>’.

7.1.44.8 Hashing
................

     string(<HASH> <output_variable> <input>)

Compute a cryptographic hash of the ‘<input>’ string.  The supported
‘<HASH>’ algorithm names are:

‘MD5’

     Message-Digest Algorithm 5, RFC 1321.

‘SHA1’

     US Secure Hash Algorithm 1, RFC 3174.

‘SHA224’

     US Secure Hash Algorithms, RFC 4634.

‘SHA256’

     US Secure Hash Algorithms, RFC 4634.

‘SHA384’

     US Secure Hash Algorithms, RFC 4634.

‘SHA512’

     US Secure Hash Algorithms, RFC 4634.

‘SHA3_224’

     Keccak SHA-3.

‘SHA3_256’

     Keccak SHA-3.

‘SHA3_384’

     Keccak SHA-3.

‘SHA3_512’

     Keccak SHA-3.

7.1.44.9 Generation
...................

     string(ASCII <number> [<number> ...] <output_variable>)

Convert all numbers into corresponding ASCII characters.
     string(HEX <string> <output_variable>)

Convert each byte in the input ‘<string>’ to its hexadecimal
representation and store the concatenated hex digits in the
‘<output_variable>’.  Letters in the output (‘a’ through ‘f’) are in
lowercase.
     string(CONFIGURE <string> <output_variable>
            [@ONLY] [ESCAPE_QUOTES])

Transform a ‘<string>’ like configure_file() transforms a
file.
     string(MAKE_C_IDENTIFIER <string> <output_variable>)

Convert each non-alphanumeric character in the input ‘<string>’ to an
underscore and store the result in the ‘<output_variable>’.  If the
first character of the ‘<string>’ is a digit, an underscore will also be
prepended to the result.
     string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
            [RANDOM_SEED <seed>] <output_variable>)

Return a random string of given ‘<length>’ consisting of characters from
the given ‘<alphabet>’.  Default length is 5 characters and default
alphabet is all numbers and upper and lower case letters.  If an integer
‘RANDOM_SEED’ is given, its value will be used to seed the random number
generator.
     string(TIMESTAMP <output_variable> [<format_string>] [UTC])

Write a string representation of the current date and/or time to the
‘<output_variable>’.

If the command is unable to obtain a timestamp, the ‘<output_variable>’
will be set to the empty string ‘""’.

The optional ‘UTC’ flag requests the current date/time representation to
be in Coordinated Universal Time (UTC) rather than local time.

The optional ‘<format_string>’ may contain the following format
specifiers:

     %%        A literal percent sign (%).
     %d        The day of the current month (01-31).
     %H        The hour on a 24-hour clock (00-23).
     %I        The hour on a 12-hour clock (01-12).
     %j        The day of the current year (001-366).
     %m        The month of the current year (01-12).
     %b        Abbreviated month name (e.g. Oct).
     %B        Full month name (e.g. October).
     %M        The minute of the current hour (00-59).
     %s        Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
     %S        The second of the current minute.
               60 represents a leap second. (00-60)
     %U        The week number of the current year (00-53).
     %w        The day of the current week. 0 is Sunday. (0-6)
     %a        Abbreviated weekday name (e.g. Fri).
     %A        Full weekday name (e.g. Friday).
     %y        The last two digits of the current year (00-99)
     %Y        The current year.

Unknown format specifiers will be ignored and copied to the output
as-is.

If no explicit ‘<format_string>’ is given, it will default to:

     %Y-%m-%dT%H:%M:%S    for local time.
     %Y-%m-%dT%H:%M:%SZ   for UTC.

     Note: If the ‘SOURCE_DATE_EPOCH’ environment variable is set, its
     value will be used instead of the current time.  See
     ‘https://reproducible-builds.org/specs/source-date-epoch/’ for
     details.
     string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
            TYPE <MD5|SHA1> [UPPER])

Create a universally unique identifier (aka GUID) as per RFC4122 based
on the hash of the combined values of ‘<namespace>’ (which itself has to
be a valid UUID) and ‘<name>’.  The hash algorithm can be either ‘MD5’
(Version 3 UUID) or ‘SHA1’ (Version 5 UUID). A UUID has the format
‘xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ where each ‘x’ represents a lower
case hexadecimal character.  Where required, an uppercase representation
can be requested with the optional ‘UPPER’ flag.

7.1.44.10 JSON
..............

Functionality for querying a JSON string.

     Note: In each of the following JSON-related subcommands, if the
     optional ‘ERROR_VARIABLE’ argument is given, errors will be
     reported in ‘<error-variable>’ and the ‘<out-var>’ will be set to
     ‘<member|index>-[<member|index>...]-NOTFOUND’ with the path
     elements up to the point where the error occurred, or just
     ‘NOTFOUND’ if there is no relevant path.  If an error occurs but
     the ‘ERROR_VARIABLE’ option is not present, a fatal error message
     is generated.  If no error occurs, the ‘<error-variable>’ will be
     set to ‘NOTFOUND’.
     string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
            GET <json-string> <member|index> [<member|index> ...])

Get an element from ‘<json-string>’ at the location given by the list of
‘<member|index>’ arguments.  Array and object elements will be returned
as a JSON string.  Boolean elements will be returned as ‘ON’ or ‘OFF’.
Null elements will be returned as an empty string.  Number and string
types will be returned as strings.
     string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
            TYPE <json-string> <member|index> [<member|index> ...])

Get the type of an element in ‘<json-string>’ at the location given by
the list of ‘<member|index>’ arguments.  The ‘<out-var>’ will be set to
one of ‘NULL’, ‘NUMBER’, ‘STRING’, ‘BOOLEAN’, ‘ARRAY’, or ‘OBJECT’.
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
            MEMBER <json-string>
            [<member|index> ...] <index>)

Get the name of the ‘<index>’-th member in ‘<json-string>’ at the
location given by the list of ‘<member|index>’ arguments.  Requires an
element of object type.
     string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
            LENGTH <json-string> <member|index> [<member|index> ...])

Get the length of an element in ‘<json-string>’ at the location given by
the list of ‘<member|index>’ arguments.  Requires an element of array or
object type.
     string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
            REMOVE <json-string> <member|index> [<member|index> ...])

Remove an element from ‘<json-string>’ at the location given by the list
of ‘<member|index>’ arguments.  The JSON string without the removed
element will be stored in ‘<out-var>’.
     string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
            SET <json-string> <member|index> [<member|index> ...] <value>)

Set an element in ‘<json-string>’ at the location given by the list of
‘<member|index>’ arguments to ‘<value>’.  The contents of ‘<value>’
should be valid JSON.
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
            EQUAL <json-string1> <json-string2>)

Compare the two JSON objects given by ‘<json-string1>’ and
‘<json-string2>’ for equality.  The contents of ‘<json-string1>’ and
‘<json-string2>’ should be valid JSON. The ‘<out-var>’ will be set to a
true value if the JSON objects are considered equal, or a false value
otherwise.

7.1.45 unset
------------

Unset a variable, cache variable, or environment variable.

7.1.45.1 Unset Normal Variable or Cache Entry
.............................................

     unset(<variable> [CACHE | PARENT_SCOPE])

Removes a normal variable from the current scope, causing it to become
undefined.  If ‘CACHE’ is present, then a cache variable is removed
instead of a normal variable.  Note that when evaluating Variable References
of the form ‘${VAR}’, CMake first searches for a normal
variable with that name.  If no such normal variable exists, CMake will
then search for a cache entry with that name.  Because of this unsetting
a normal variable can expose a cache variable that was previously
hidden.  To force a variable reference of the form ‘${VAR}’ to return an
empty string, use ‘set(<variable> "")’, which clears the normal variable
but leaves it defined.

If ‘PARENT_SCOPE’ is present then the variable is removed from the scope
above the current scope.  See the same option in the set().
command for further details.

7.1.45.2 Unset Environment Variable
...................................

     unset(ENV{<variable>})

Removes ‘<variable>’ from the currently available Environment Variables.
Subsequent calls of ‘$ENV{<variable>}’ will return the
empty string.

This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large, nor
the environment of subsequent build or test processes.

7.1.46 variable_watch
---------------------

Watch the CMake variable for change.

     variable_watch(<variable> [<command>])

If the specified ‘<variable>’ changes and no ‘<command>’ is given, a
message will be printed to inform about the change.

If ‘<command>’ is given, this command will be executed instead.  The
command will receive the following arguments: ‘COMMAND(<variable>
<access> <value> <current_list_file> <stack>)’

‘<variable>’

     Name of the variable being accessed.

‘<access>’

     One of ‘READ_ACCESS’, ‘UNKNOWN_READ_ACCESS’, ‘MODIFIED_ACCESS’,
     ‘UNKNOWN_MODIFIED_ACCESS’, or ‘REMOVED_ACCESS’.  The ‘UNKNOWN_’
     values are only used when the variable has never been set.  Once
     set, they are never used again during the same CMake run, even if
     the variable is later unset.

‘<value>’

     The value of the variable.  On a modification, this is the new
     (modified) value of the variable.  On removal, the value is empty.

‘<current_list_file>’

     Full path to the file doing the access.

‘<stack>’

     List of absolute paths of all files currently on the stack of file
     inclusion, with the bottom-most file first and the currently
     processed file (that is, ‘current_list_file’) last.

Note that for some accesses such as list(APPEND), the watcher
is executed twice, first with a read access and then with a write one.
Also note that an if(DEFINED) query on the variable does not
register as an access and the watcher is not executed.

Only non-cache variables can be watched using this command.  Access to
cache variables is never watched.  However, the existence of a cache
variable ‘var’ causes accesses to the non-cache variable ‘var’ to not
use the ‘UNKNOWN_’ prefix, even if a non-cache variable ‘var’ has never
existed.

7.1.47 while
------------

Evaluate a group of commands while a condition is true

     while(<condition>)
       <commands>
     endwhile()

All commands between while and the matching endwhile() are
recorded without being invoked.  Once the endwhile() is
evaluated, the recorded list of commands is invoked as long as the
‘<condition>’ is true.

The ‘<condition>’ has the same syntax and is evaluated using the same
logic as described at length for the if() command.

The commands break() and continue() provide
means to escape from the normal control flow.

Per legacy, the endwhile() command admits an optional
‘<condition>’ argument.  If used, it must be a verbatim repeat of the
argument of the opening ‘while’ command.

7.2 Project Commands
====================

These commands are available only in CMake projects.

7.2.1 add_compile_definitions
-----------------------------

New in version 3.12.

Add preprocessor definitions to the compilation of source files.

     add_compile_definitions(<definition> ...)

Adds preprocessor definitions to the compiler command line.

The preprocessor definitions are added to the COMPILE_DEFINITIONS
directory property for the current ‘CMakeLists’ file.  They are
also added to the COMPILE_DEFINITIONS target property for
each target in the current ‘CMakeLists’ file.

Definitions are specified using the syntax ‘VAR’ or ‘VAR=value’.
Function-style definitions are not supported.  CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).

Arguments to ‘add_compile_definitions’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

7.2.2 add_compile_options
-------------------------

Add options to the compilation of source files.

     add_compile_options(<option> ...)

Adds options to the COMPILE_OPTIONS directory property.
These options are used when compiling targets from the current directory
and below.

7.2.2.1 Arguments
.................

Arguments to ‘add_compile_options’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

The final set of compile or link options used for a target is
constructed by accumulating options from the current target and the
usage requirements of its dependencies.  The set of options is
de-duplicated to avoid repetition.  While beneficial for individual
options, the de-duplication step can break up option groups.  For
example, ‘-D A -D B’ becomes ‘-D A B’.  One may specify a group of
options using shell-like quoting along with a ‘SHELL:’ prefix.  The
‘SHELL:’ prefix is dropped, and the rest of the option string is parsed
using the separate_arguments(). ‘UNIX_COMMAND’ mode.  For
example, ‘"SHELL:-D A" "SHELL:-D B"’ becomes ‘-D A -D B’.

7.2.2.2 Example
...............

Since different compilers support different options, a typical use of
this command is in a compiler-specific conditional clause:

     if (MSVC)
         # warning level 4 and all warnings as errors
         add_compile_options(/W4 /WX)
     else()
         # lots of warnings and all warnings as errors
         add_compile_options(-Wall -Wextra -pedantic -Werror)
     endif()

7.2.2.3 See Also
................

This command can be used to add any options.  However, for adding
preprocessor definitions and include directories it is recommended to
use the more specific commands add_compile_definitions() and
include_directories().

The command target_compile_options() adds target-specific
options.

The source file property COMPILE_OPTIONS adds options to one
source file.

7.2.3 add_custom_command
------------------------

Add a custom build rule to the generated build system.

There are two main signatures for ‘add_custom_command’.

7.2.3.1 Generating Files
........................

The first signature is for adding a custom command to produce an output:

     add_custom_command(OUTPUT output1 [output2 ...]
                        COMMAND command1 [ARGS] [args1...]
                        [COMMAND command2 [ARGS] [args2...] ...]
                        [MAIN_DEPENDENCY depend]
                        [DEPENDS [depends...]]
                        [BYPRODUCTS [files...]]
                        [IMPLICIT_DEPENDS <lang1> depend1
                                         [<lang2> depend2] ...]
                        [WORKING_DIRECTORY dir]
                        [COMMENT comment]
                        [DEPFILE depfile]
                        [JOB_POOL job_pool]
                        [VERBATIM] [APPEND] [USES_TERMINAL]
                        [COMMAND_EXPAND_LISTS])

This defines a command to generate specified ‘OUTPUT’ file(s).  A target
created in the same directory (‘CMakeLists.txt’ file) that specifies any
output of the custom command as a source file is given a rule to
generate the file using the command at build time.  Do not list the
output in more than one independent target that may build in parallel or
the two instances of the rule may conflict (instead use the
add_custom_target() command to drive the command and make the
other targets depend on that one).  In makefile terms this creates a new
target in the following form:

     OUTPUT: MAIN_DEPENDENCY DEPENDS
             COMMAND

The options are:

‘APPEND’

     Append the ‘COMMAND’ and ‘DEPENDS’ option values to the custom
     command for the first output specified.  There must have already
     been a previous call to this command with the same output.  The
     ‘COMMENT’, ‘MAIN_DEPENDENCY’, and ‘WORKING_DIRECTORY’ options are
     currently ignored when APPEND is given, but may be used in the
     future.

‘BYPRODUCTS’

     Specify the files the command is expected to produce but whose
     modification time may or may not be newer than the dependencies.
     If a byproduct name is a relative path it will be interpreted
     relative to the build tree directory corresponding to the current
     source directory.  Each byproduct file will be marked with the
     GENERATED source file property automatically.

     Explicit specification of byproducts is supported by the
     Ninja generator to tell the ‘ninja’ build tool how to
     regenerate byproducts when they are missing.  It is also useful
     when other build rules (e.g.  custom commands) depend on the
     byproducts.  Ninja requires a build rule for any generated file on
     which another rule depends even if there are order-only
     dependencies to ensure the byproducts will be available before
     their dependents build.

     The Makefile Generators will remove ‘BYPRODUCTS’ and
     other GENERATED files during ‘make clean’.

‘COMMAND’

     Specify the command-line(s) to execute at build time.  If more than
     one ‘COMMAND’ is specified they will be executed in order, but
     `not' necessarily composed into a stateful shell or batch script.
     (To run a full script, use the configure_file() command
     or the file(GENERATE) command to create it, and then
     specify a ‘COMMAND’ to launch it.)  The optional ‘ARGS’ argument is
     for backward compatibility and will be ignored.

     If ‘COMMAND’ specifies an executable target name (created by the
     add_executable() command), it will automatically be
     replaced by the location of the executable created at build time if
     either of the following is true:

        * The target is not being cross-compiled (i.e.  the
          CMAKE_CROSSCOMPILING variable is not set to true).

        * The target is being cross-compiled and an emulator is provided
          (i.e.  its CROSSCOMPILING_EMULATOR target property
          is set).  In this case, the contents of
          CROSSCOMPILING_EMULATOR will be prepended to the command
          before the location of the target executable.

     If neither of the above conditions are met, it is assumed that the
     command name is a program to be found on the ‘PATH’ at build time.

     Arguments to ‘COMMAND’ may use generator expressions.
     Use the ‘TARGET_FILE’ generator expression to refer to the location
     of a target later in the command line (i.e.  as a command argument
     rather than as the command to execute).

     Whenever one of the following target based generator expressions
     are used as a command to execute or is mentioned in a command
     argument, a target-level dependency will be added automatically so
     that the mentioned target will be built before any target using
     this custom command (see policy CMP0112).

             * ‘TARGET_FILE’

             * ‘TARGET_LINKER_FILE’

             * ‘TARGET_SONAME_FILE’

             * ‘TARGET_PDB_FILE’

     This target-level dependency does NOT add a file-level dependency
     that would cause the custom command to re-run whenever the
     executable is recompiled.  List target names with the ‘DEPENDS’
     option to add such file-level dependencies.

‘COMMENT’

     Display the given message before the commands are executed at build
     time.

‘DEPENDS’

     Specify files on which the command depends.  Each argument is
     converted to a dependency as follows:

       1. If the argument is the name of a target (created by the
          add_custom_target(), add_executable(), or
          add_library() command) a target-level dependency is
          created to make sure the target is built before any target
          using this custom command.  Additionally, if the target is an
          executable or library, a file-level dependency is created to
          cause the custom command to re-run whenever the target is
          recompiled.

       2. If the argument is an absolute path, a file-level dependency
          is created on that path.

       3. If the argument is the name of a source file that has been
          added to a target or on which a source file property has been
          set, a file-level dependency is created on that source file.

       4. If the argument is a relative path and it exists in the
          current source directory, a file-level dependency is created
          on that file in the current source directory.

       5. Otherwise, a file-level dependency is created on that path
          relative to the current binary directory.

     If any dependency is an ‘OUTPUT’ of another custom command in the
     same directory (‘CMakeLists.txt’ file), CMake automatically brings
     the other custom command into the target in which this command is
     built.  A target-level dependency is added if any dependency is
     listed as ‘BYPRODUCTS’ of a target or any of its build events in
     the same directory to ensure the byproducts will be available.

     If ‘DEPENDS’ is not specified, the command will run whenever the
     ‘OUTPUT’ is missing; if the command does not actually create the
     ‘OUTPUT’, the rule will always run.

     Arguments to ‘DEPENDS’ may use generator expressions.

‘COMMAND_EXPAND_LISTS’

     Lists in ‘COMMAND’ arguments will be expanded, including those
     created with generator expressions, allowing ‘COMMAND’
     arguments such as ‘${CC}
     "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc’
     to be properly expanded.

‘IMPLICIT_DEPENDS’

     Request scanning of implicit dependencies of an input file.  The
     language given specifies the programming language whose
     corresponding dependency scanner should be used.  Currently only
     ‘C’ and ‘CXX’ language scanners are supported.  The language has to
     be specified for every file in the ‘IMPLICIT_DEPENDS’ list.
     Dependencies discovered from the scanning are added to those of the
     custom command at build time.  Note that the ‘IMPLICIT_DEPENDS’
     option is currently supported only for Makefile generators and will
     be ignored by other generators.

‘JOB_POOL’

     Specify a pool for the Ninja generator.
     Incompatible with ‘USES_TERMINAL’, which implies the ‘console’
     pool.  Using a pool that is not defined by JOB_POOLS.
     causes an error by ninja at build time.

‘MAIN_DEPENDENCY’

     Specify the primary input source file to the command.  This is
     treated just like any value given to the ‘DEPENDS’ option but also
     suggests to Visual Studio generators where to hang the custom
     command.  Each source file may have at most one command specifying
     it as its main dependency.  A compile command (i.e.  for a library
     or an executable) counts as an implicit main dependency which gets
     silently overwritten by a custom command specification.

‘OUTPUT’

     Specify the output files the command is expected to produce.  If an
     output name is a relative path it will be interpreted relative to
     the build tree directory corresponding to the current source
     directory.  Each output file will be marked with the
     GENERATED source file property automatically.  If the output
     of the custom command is not actually created as a file on disk it
     should be marked with the SYMBOLIC source file
     property.

‘USES_TERMINAL’

     The command will be given direct access to the terminal if
     possible.  With the Ninja generator, this places the
     command in the ‘console’ pool.

‘VERBATIM’

     All arguments to the commands will be escaped properly for the
     build tool so that the invoked command receives each argument
     unchanged.  Note that one level of escapes is still used by the
     CMake language processor before add_custom_command even sees the
     arguments.  Use of ‘VERBATIM’ is recommended as it enables correct
     behavior.  When ‘VERBATIM’ is not given the behavior is platform
     specific because there is no protection of tool-specific special
     characters.

‘WORKING_DIRECTORY’

     Execute the command with the given current working directory.  If
     it is a relative path it will be interpreted relative to the build
     tree directory corresponding to the current source directory.

     Arguments to ‘WORKING_DIRECTORY’ may use generator expressions.

‘DEPFILE’

     Specify a ‘.d’ depfile for the Ninja generator.  A ‘.d’
     file holds dependencies usually emitted by the custom command
     itself.  Using ‘DEPFILE’ with other generators than Ninja is an
     error.

7.2.3.2 Build Events
....................

The second signature adds a custom command to a target such as a library
or executable.  This is useful for performing an operation before or
after building the target.  The command becomes part of the target and
will only execute when the target itself is built.  If the target is
already built, the command will not execute.

     add_custom_command(TARGET <target>
                        PRE_BUILD | PRE_LINK | POST_BUILD
                        COMMAND command1 [ARGS] [args1...]
                        [COMMAND command2 [ARGS] [args2...] ...]
                        [BYPRODUCTS [files...]]
                        [WORKING_DIRECTORY dir]
                        [COMMENT comment]
                        [VERBATIM] [USES_TERMINAL]
                        [COMMAND_EXPAND_LISTS])

This defines a new command that will be associated with building the
specified ‘<target>’.  The ‘<target>’ must be defined in the current
directory; targets defined in other directories may not be specified.

When the command will happen is determined by which of the following is
specified:

‘PRE_BUILD’

     On Visual Studio Generators, run before any other rules
     are executed within the target.  On other generators, run just
     before ‘PRE_LINK’ commands.

‘PRE_LINK’

     Run after sources have been compiled but before linking the binary
     or running the librarian or archiver tool of a static library.
     This is not defined for targets created by the
     add_custom_target() command.

‘POST_BUILD’

     Run after all other rules within the target have been executed.

     Note: Because generator expressions can be used in custom commands,
     it is possible to define ‘COMMAND’ lines or whole custom commands
     which evaluate to empty strings for certain configurations.  For
     `Visual Studio 2010 (and newer)' generators these command lines or
     custom commands will be omitted for the specific configuration and
     no “empty-string-command” will be added.

     This allows to add individual build events for every configuration.

7.2.4 add_custom_target
-----------------------

Add a target with no output so it will always be built.

     add_custom_target(Name [ALL] [command1 [args1...]]
                       [COMMAND command2 [args2...] ...]
                       [DEPENDS depend depend depend ... ]
                       [BYPRODUCTS [files...]]
                       [WORKING_DIRECTORY dir]
                       [COMMENT comment]
                       [JOB_POOL job_pool]
                       [VERBATIM] [USES_TERMINAL]
                       [COMMAND_EXPAND_LISTS]
                       [SOURCES src1 [src2...]])

Adds a target with the given name that executes the given commands.  The
target has no output file and is `always considered out of date' even if
the commands try to create a file with the name of the target.  Use the
add_custom_command() command to generate a file with
dependencies.  By default nothing depends on the custom target.  Use the
add_dependencies() command to add dependencies to or from
other targets.

The options are:

‘ALL’

     Indicate that this target should be added to the default build
     target so that it will be run every time (the command cannot be
     called ‘ALL’).

‘BYPRODUCTS’

     Specify the files the command is expected to produce but whose
     modification time may or may not be updated on subsequent builds.
     If a byproduct name is a relative path it will be interpreted
     relative to the build tree directory corresponding to the current
     source directory.  Each byproduct file will be marked with the
     GENERATED source file property automatically.

     Explicit specification of byproducts is supported by the
     Ninja generator to tell the ‘ninja’ build tool how to
     regenerate byproducts when they are missing.  It is also useful
     when other build rules (e.g.  custom commands) depend on the
     byproducts.  Ninja requires a build rule for any generated file on
     which another rule depends even if there are order-only
     dependencies to ensure the byproducts will be available before
     their dependents build.

     The Makefile Generators will remove ‘BYPRODUCTS’ and
     other GENERATED files during ‘make clean’.

‘COMMAND’

     Specify the command-line(s) to execute at build time.  If more than
     one ‘COMMAND’ is specified they will be executed in order, but
     `not' necessarily composed into a stateful shell or batch script.
     (To run a full script, use the configure_file() command
     or the file(GENERATE) command to create it, and then
     specify a ‘COMMAND’ to launch it.)

     If ‘COMMAND’ specifies an executable target name (created by the
     add_executable() command), it will automatically be
     replaced by the location of the executable created at build time if
     either of the following is true:

        * The target is not being cross-compiled (i.e.  the
          CMAKE_CROSSCOMPILING variable is not set to true).

        * The target is being cross-compiled and an emulator is provided
          (i.e.  its CROSSCOMPILING_EMULATOR target property
          is set).  In this case, the contents of
          CROSSCOMPILING_EMULATOR will be prepended to the command
          before the location of the target executable.

     If neither of the above conditions are met, it is assumed that the
     command name is a program to be found on the ‘PATH’ at build time.

     Arguments to ‘COMMAND’ may use generator expressions.
     Use the ‘TARGET_FILE’ generator expression to refer to the location
     of a target later in the command line (i.e.  as a command argument
     rather than as the command to execute).

     Whenever one of the following target based generator expressions
     are used as a command to execute or is mentioned in a command
     argument, a target-level dependency will be added automatically so
     that the mentioned target will be built before this custom target
     (see policy CMP0112).

             * ‘TARGET_FILE’

             * ‘TARGET_LINKER_FILE’

             * ‘TARGET_SONAME_FILE’

             * ‘TARGET_PDB_FILE’

     The command and arguments are optional and if not specified an
     empty target will be created.

‘COMMENT’

     Display the given message before the commands are executed at build
     time.

‘DEPENDS’

     Reference files and outputs of custom commands created with
     add_custom_command() command calls in the same directory
     (‘CMakeLists.txt’ file).  They will be brought up to date when the
     target is built.  A target-level dependency is added if any
     dependency is a byproduct of a target or any of its build events in
     the same directory to ensure the byproducts will be available
     before this target is built.

     Use the add_dependencies() command to add dependencies
     on other targets.

‘COMMAND_EXPAND_LISTS’

     Lists in ‘COMMAND’ arguments will be expanded, including those
     created with generator expressions, allowing ‘COMMAND’
     arguments such as ‘${CC}
     "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc’
     to be properly expanded.

‘JOB_POOL’

     Specify a pool for the Ninja generator.
     Incompatible with ‘USES_TERMINAL’, which implies the ‘console’
     pool.  Using a pool that is not defined by JOB_POOLS.
     causes an error by ninja at build time.

‘SOURCES’

     Specify additional source files to be included in the custom
     target.  Specified source files will be added to IDE project files
     for convenience in editing even if they have no build rules.

‘VERBATIM’

     All arguments to the commands will be escaped properly for the
     build tool so that the invoked command receives each argument
     unchanged.  Note that one level of escapes is still used by the
     CMake language processor before ‘add_custom_target’ even sees the
     arguments.  Use of ‘VERBATIM’ is recommended as it enables correct
     behavior.  When ‘VERBATIM’ is not given the behavior is platform
     specific because there is no protection of tool-specific special
     characters.

‘USES_TERMINAL’

     The command will be given direct access to the terminal if
     possible.  With the Ninja generator, this places the
     command in the ‘console’ pool.

‘WORKING_DIRECTORY’

     Execute the command with the given current working directory.  If
     it is a relative path it will be interpreted relative to the build
     tree directory corresponding to the current source directory.

     Arguments to ‘WORKING_DIRECTORY’ may use generator expressions.

7.2.5 add_definitions
---------------------

Add -D define flags to the compilation of source files.

     add_definitions(-DFOO -DBAR ...)

Adds definitions to the compiler command line for targets in the current
directory, whether added before or after this command is invoked, and
for the ones in sub-directories added after.  This command can be used
to add any flags, but it is intended to add preprocessor definitions.

     Note: This command has been superseded by alternatives:

        * Use add_compile_definitions() to add preprocessor
          definitions.

        * Use include_directories() to add include
          directories.

        * Use add_compile_options() to add other options.

Flags beginning in ‘-D’ or ‘/D’ that look like preprocessor definitions
are automatically added to the COMPILE_DEFINITIONS directory
property for the current directory.  Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons
of backwards compatibility.  See documentation of the directory,
see target, source file. ‘COMPILE_DEFINITIONS’
properties for details on adding preprocessor definitions to specific
scopes and configurations.

See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

7.2.6 add_dependencies
----------------------

Add a dependency between top-level targets.

     add_dependencies(<target> [<target-dependency>]...)

Makes a top-level ‘<target>’ depend on other top-level targets to ensure
that they build before ‘<target>’ does.  A top-level target is one
created by one of the add_executable(), add_library(),
or add_custom_target() commands (but not targets
generated by CMake like ‘install’).

Dependencies added to an imported target or an
interface library are followed transitively in its place since the
target itself does not build.

See the ‘DEPENDS’ option of add_custom_target() and
add_custom_command() commands for adding file-level dependencies in
custom rules.  See the OBJECT_DEPENDS source file property
to add file-level dependencies to object files.

7.2.7 add_executable
--------------------

Add an executable to the project using the specified source files.

7.2.7.1 Normal Executables
..........................

     add_executable(<name> [WIN32] [MACOSX_BUNDLE]
                    [EXCLUDE_FROM_ALL]
                    [source1] [source2 ...])

Adds an executable target called ‘<name>’ to be built from the source
files listed in the command invocation.  (The source files can be
omitted here if they are added later using target_sources())
The ‘<name>’ corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the executable built
is constructed based on conventions of the native platform (such as
‘<name>.exe’ or just ‘<name>’).

By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked.  See documentation of the
RUNTIME_OUTPUT_DIRECTORY target property to change this location.
See documentation of the OUTPUT_NAME target property to
change the ‘<name>’ part of the final file name.

If ‘WIN32’ is given the property WIN32_EXECUTABLE will be
set on the target created.  See documentation of that target property
for details.

If ‘MACOSX_BUNDLE’ is given the corresponding property will be set on
the created target.  See documentation of the MACOSX_BUNDLE.
target property for details.

If ‘EXCLUDE_FROM_ALL’ is given the corresponding property will be set on
the created target.  See documentation of the EXCLUDE_FROM_ALL
target property for details.

Source arguments to ‘add_executable’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

See also HEADER_FILE_ONLY on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

7.2.7.2 Imported Executables
............................

     add_executable(<name> IMPORTED [GLOBAL])

An IMPORTED executable target references an executable file
located outside the project.  No rules are generated to build it, and
the IMPORTED target property is ‘True’.  The target name has
scope in the directory in which it is created and below, but the
‘GLOBAL’ option extends visibility.  It may be referenced like any
target built within the project.  ‘IMPORTED’ executables are useful for
convenient reference from commands like add_custom_command().
Details about the imported executable are specified by setting
properties whose names begin in ‘IMPORTED_’.  The most important such
property is IMPORTED_LOCATION. (and its per-configuration
version IMPORTED_LOCATION_<CONFIG>) which specifies the
location of the main executable file on disk.  See documentation of the
‘IMPORTED_*’ properties for more information.

7.2.7.3 Alias Executables
.........................

     add_executable(<name> ALIAS <target>)

Creates an Alias Target, such that ‘<name>’ can be used to
refer to ‘<target>’ in subsequent commands.  The ‘<name>’ does not
appear in the generated buildsystem as a make target.  The ‘<target>’
may not be an ‘ALIAS’.

An ‘ALIAS’ to a non-‘GLOBAL’ Imported Target has scope in
the directory in which the alias is created and below.  The
ALIAS_GLOBAL target property can be used to check if the alias is
global or not.

‘ALIAS’ targets can be used as targets to read properties from,
executables for custom commands and custom targets.  They can also be
tested for existence with the regular if(TARGET) subcommand.
The ‘<name>’ may not be used to modify properties of ‘<target>’, that
is, it may not be used as the operand of set_property(),
set_target_properties(), target_link_libraries().
etc.  An ‘ALIAS’ target may not be installed or exported.

7.2.8 add_library
-----------------

Add a library to the project using the specified source files.

7.2.8.1 Normal Libraries
........................

     add_library(<name> [STATIC | SHARED | MODULE]
                 [EXCLUDE_FROM_ALL]
                 [<source>...])

Adds a library target called ‘<name>’ to be built from the source files
listed in the command invocation.  (The source files can be omitted here
if they are added later using target_sources())  The
‘<name>’ corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the library built is
constructed based on conventions of the native platform (such as
‘lib<name>.a’ or ‘<name>.lib’).

‘STATIC’, ‘SHARED’, or ‘MODULE’ may be given to specify the type of
library to be created.  ‘STATIC’ libraries are archives of object files
for use when linking other targets.  ‘SHARED’ libraries are linked
dynamically and loaded at runtime.  ‘MODULE’ libraries are plugins that
are not linked into other targets but may be loaded dynamically at
runtime using dlopen-like functionality.  If no type is given explicitly
the type is ‘STATIC’ or ‘SHARED’ based on whether the current value of
the variable BUILD_SHARED_LIBS is ‘ON’.  For ‘SHARED’ and
‘MODULE’ libraries the POSITION_INDEPENDENT_CODE target
property is set to ‘ON’ automatically.  A ‘SHARED’ or ‘STATIC’ library
may be marked with the FRAMEWORK target property to create an
macOS Framework.

If a library does not export any symbols, it must not be declared as a
‘SHARED’ library.  For example, a Windows resource DLL or a managed
C++/CLI DLL that exports no unmanaged symbols would need to be a
‘MODULE’ library.  This is because CMake expects a ‘SHARED’ library to
always have an associated import library on Windows.

By default the library file will be created in the build tree directory
corresponding to the source tree directory in which the command was
invoked.  See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY
target properties to change this location.  See documentation of
the OUTPUT_NAME target property to change the ‘<name>’ part
of the final file name.

If ‘EXCLUDE_FROM_ALL’ is given the corresponding property will be set on
the created target.  See documentation of the EXCLUDE_FROM_ALL
target property for details.

Source arguments to ‘add_library’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

See also HEADER_FILE_ONLY on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

7.2.8.2 Object Libraries
........................

     add_library(<name> OBJECT [<source>...])

Creates an Object Library.  An object library compiles source
files but does not archive or link their object files into a library.
Instead other targets created by add_library() or
add_executable() may reference the objects using an expression of
the form ‘$<TARGET_OBJECTS:objlib>’ as a source, where ‘objlib’ is the
object library name.  For example:

     add_library(... $<TARGET_OBJECTS:objlib> ...)
     add_executable(... $<TARGET_OBJECTS:objlib> ...)

will include objlib’s object files in a library and an executable along
with those compiled from their own sources.  Object libraries may
contain only sources that compile, header files, and other files that
would not affect linking of a normal library (e.g.  ‘.txt’).  They may
contain custom commands generating such sources, but not ‘PRE_BUILD’,
‘PRE_LINK’, or ‘POST_BUILD’ commands.  Some native build systems (such
as Xcode) may not like targets that have only object files, so consider
adding at least one real source file to any target that references
‘$<TARGET_OBJECTS:objlib>’.

7.2.8.3 Interface Libraries
...........................

     add_library(<name> INTERFACE)

Creates an Interface Library.  An ‘INTERFACE’ library target
does not compile sources and does not produce a library artifact on
disk.  However, it may have properties set on it and it may be installed
and exported.  Typically, ‘INTERFACE_*’ properties are populated on an
interface target using the commands:

   * set_property()

   * target_link_libraries(INTERFACE)

   * target_link_options(INTERFACE)

   * target_include_directories(INTERFACE)

   * target_compile_options(INTERFACE)

   * target_compile_definitions(INTERFACE), and

   * target_sources(INTERFACE)

and then it is used as an argument to target_link_libraries().
like any other target.

An interface library created with the above signature has no source
files itself and is not included as a target in the generated
buildsystem.

Since CMake 3.19, an interface library target may be created with source
files:

     add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])

Source files may be listed directly in the ‘add_library’ call or added
later by calls to target_sources() with the ‘PRIVATE’ or
‘PUBLIC’ keywords.

If an interface library has source files (i.e.  the SOURCES.
target property is set), it will appear in the generated buildsystem as
a build target much like a target defined by the
add_custom_target() command.  It does not compile any sources, but
does contain build rules for custom commands created by the
add_custom_command() command.

     Note: In most command signatures where the ‘INTERFACE’ keyword
     appears, the items listed after it only become part of that
     target’s usage requirements and are not part of the target’s own
     settings.  However, in this signature of ‘add_library’, the
     ‘INTERFACE’ keyword refers to the library type only.  Sources
     listed after it in the ‘add_library’ call are ‘PRIVATE’ to the
     interface library and do not appear in its INTERFACE_SOURCES
     target property.

7.2.8.4 Imported Libraries
..........................

     add_library(<name> <type> IMPORTED [GLOBAL])

Creates an IMPORTED library target called ‘<name>’.  No
rules are generated to build it, and the IMPORTED target
property is ‘True’.  The target name has scope in the directory in which
it is created and below, but the ‘GLOBAL’ option extends visibility.  It
may be referenced like any target built within the project.  ‘IMPORTED’
libraries are useful for convenient reference from commands like
target_link_libraries().  Details about the imported library are
specified by setting properties whose names begin in ‘IMPORTED_’ and
‘INTERFACE_’.

The ‘<type>’ must be one of:

‘STATIC’, ‘SHARED’, ‘MODULE’, ‘UNKNOWN’

     References a library file located outside the project.  The
     IMPORTED_LOCATION target property (or its per-configuration
     variant IMPORTED_LOCATION_<CONFIG>) specifies the
     location of the main library file on disk.  In the case of a
     ‘SHARED’ library on Windows, the IMPORTED_IMPLIB target
     property (or its per-configuration variant
     IMPORTED_IMPLIB_<CONFIG>) specifies the location of the DLL
     import library file (‘.lib’ or ‘.dll.a’) on disk, and the
     ‘IMPORTED_LOCATION’ is the location of the ‘.dll’ runtime library
     (and is optional).  Additional usage requirements may be specified
     in ‘INTERFACE_*’ properties.

     An ‘UNKNOWN’ library type is typically only used in the
     implementation of Find Modules.  It allows the path to
     an imported library (often found using the find_library()
     command) to be used without having to know what type of
     library it is.  This is especially useful on Windows where a static
     library and a DLL’s import library both have the same file
     extension.

‘OBJECT’

     References a set of object files located outside the project.  The
     IMPORTED_OBJECTS target property (or its
     per-configuration variant IMPORTED_OBJECTS_<CONFIG>)
     specifies the locations of object files on disk.  Additional usage
     requirements may be specified in ‘INTERFACE_*’ properties.

‘INTERFACE’

     Does not reference any library or object files on disk, but may
     specify usage requirements in ‘INTERFACE_*’ properties.

See documentation of the ‘IMPORTED_*’ and ‘INTERFACE_*’ properties for
more information.

7.2.8.5 Alias Libraries
.......................

     add_library(<name> ALIAS <target>)

Creates an Alias Target, such that ‘<name>’ can be used to
refer to ‘<target>’ in subsequent commands.  The ‘<name>’ does not
appear in the generated buildsystem as a make target.  The ‘<target>’
may not be an ‘ALIAS’.

An ‘ALIAS’ to a non-‘GLOBAL’ Imported Target has scope in
the directory in which the alias is created and below.  The
ALIAS_GLOBAL target property can be used to check if the alias is
global or not.

‘ALIAS’ targets can be used as linkable targets and as targets to read
properties from.  They can also be tested for existence with the regular
if(TARGET) subcommand.  The ‘<name>’ may not be used to
modify properties of ‘<target>’, that is, it may not be used as the
operand of set_property(), set_target_properties(),
see target_link_libraries() etc.  An ‘ALIAS’ target may not
be installed or exported.

7.2.9 add_link_options
----------------------

New in version 3.13.

Add options to the link step for executable, shared library or module
library targets in the current directory and below that are added after
this command is invoked.

     add_link_options(<option> ...)

This command can be used to add any link options, but alternative
commands exist to add libraries ( see target_link_libraries() or
link_libraries()).  See documentation of the
directory and target. ‘LINK_OPTIONS’ properties.

     Note: This command cannot be used to add options for static library
     targets, since they do not use a linker.  To add archiver or MSVC
     librarian flags, see the STATIC_LIBRARY_OPTIONS target
     property.

Arguments to ‘add_link_options’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

When a device link step is involved, which is controlled by
CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
properties and policy CMP0105, the raw options will be
delivered to the host and device link steps (wrapped in ‘-Xcompiler’ or
equivalent for device link).  Options wrapped with ‘$<DEVICE_LINK:...>’
generator expression will be used only for the device link
step.  Options wrapped with ‘$<HOST_LINK:...>’ generator expression
will be used only for the host link step.

The final set of compile or link options used for a target is
constructed by accumulating options from the current target and the
usage requirements of its dependencies.  The set of options is
de-duplicated to avoid repetition.  While beneficial for individual
options, the de-duplication step can break up option groups.  For
example, ‘-D A -D B’ becomes ‘-D A B’.  One may specify a group of
options using shell-like quoting along with a ‘SHELL:’ prefix.  The
‘SHELL:’ prefix is dropped, and the rest of the option string is parsed
using the separate_arguments(). ‘UNIX_COMMAND’ mode.  For
example, ‘"SHELL:-D A" "SHELL:-D B"’ becomes ‘-D A -D B’.

To pass options to the linker tool, each compiler driver has its own
syntax.  The ‘LINKER:’ prefix and ‘,’ separator can be used to specify,
in a portable way, options to pass to the linker tool.  ‘LINKER:’ is
replaced by the appropriate driver option and ‘,’ by the appropriate
driver separator.  The driver prefix and driver separator are given by
the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, ‘"LINKER:-z,defs"’ becomes ‘-Xlinker -z -Xlinker defs’ for
‘Clang’ and ‘-Wl,-z,defs’ for ‘GNU GCC’.

The ‘LINKER:’ prefix can be specified as part of a ‘SHELL:’ prefix
expression.

The ‘LINKER:’ prefix supports, as an alternative syntax, specification
of arguments using the ‘SHELL:’ prefix and space as separator.  The
previous example then becomes ‘"LINKER:SHELL:-z defs"’.

     Note: Specifying the ‘SHELL:’ prefix anywhere other than at the
     beginning of the ‘LINKER:’ prefix is not supported.

7.2.10 add_subdirectory
-----------------------

Add a subdirectory to the build.

     add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

Adds a subdirectory to the build.  The source_dir specifies the
directory in which the source CMakeLists.txt and code files are located.
If it is a relative path it will be evaluated with respect to the
current directory (the typical usage), but it may also be an absolute
path.  The ‘binary_dir’ specifies the directory in which to place the
output files.  If it is a relative path it will be evaluated with
respect to the current output directory, but it may also be an absolute
path.  If ‘binary_dir’ is not specified, the value of ‘source_dir’,
before expanding any relative path, will be used (the typical usage).
The CMakeLists.txt file in the specified source directory will be
processed immediately by CMake before processing in the current input
file continues beyond this command.

If the ‘EXCLUDE_FROM_ALL’ argument is provided then targets in the
subdirectory will not be included in the ‘ALL’ target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory.  This is meant
for use when the subdirectory contains a separate part of the project
that is useful but not necessary, such as a set of examples.  Typically
the subdirectory should contain its own project() command
invocation so that a full build system will be generated in the
subdirectory (such as a VS IDE solution file).  Note that inter-target
dependencies supersede this exclusion.  If a target built by the parent
project depends on a target in the subdirectory, the dependee target
will be included in the parent project build system to satisfy the
dependency.

7.2.11 add_test
---------------

Add a test to the project to be run by ctest(1).

     add_test(NAME <name> COMMAND <command> [<arg>...]
              [CONFIGURATIONS <config>...]
              [WORKING_DIRECTORY <dir>]
              [COMMAND_EXPAND_LISTS])

Adds a test called ‘<name>’.  The test name may contain arbitrary
characters, expressed as a Quoted Argument or Bracket Argument
if necessary.  See policy CMP0110.  The
options are:

‘COMMAND’

     Specify the test command-line.  If ‘<command>’ specifies an
     executable target (created by add_executable()) it will
     automatically be replaced by the location of the executable created
     at build time.

‘CONFIGURATIONS’

     Restrict execution of the test only to the named configurations.

‘WORKING_DIRECTORY’

     Set the WORKING_DIRECTORY test property to specify the
     working directory in which to execute the test.  If not specified
     the test will be run with the current working directory set to the
     build directory corresponding to the current source directory.

‘COMMAND_EXPAND_LISTS’

     Lists in ‘COMMAND’ arguments will be expanded, including those
     created with generator expressions.

The given test command is expected to exit with code ‘0’ to pass and
non-zero to fail, or vice-versa if the WILL_FAIL test
property is set.  Any output written to stdout or stderr will be
captured by ctest(1) but does not affect the pass/fail status
unless the PASS_REGULAR_EXPRESSION,
FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test
property is used.

The ‘COMMAND’ and ‘WORKING_DIRECTORY’ options may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.

Example usage:

     add_test(NAME mytest
              COMMAND testDriver --config $<CONFIGURATION>
                                 --exe $<TARGET_FILE:myexe>)

This creates a test ‘mytest’ whose command runs a ‘testDriver’ tool
passing the configuration name and the full path to the executable file
produced by target ‘myexe’.

     Note: CMake will generate tests only if the enable_testing()
     command has been invoked.  The CTest module invokes
     the command automatically unless the ‘BUILD_TESTING’ option is
     turned ‘OFF’.

__________________________________________________________________

     add_test(<name> <command> [<arg>...])

Add a test called ‘<name>’ with the given command-line.  Unlike the
above ‘NAME’ signature no transformation is performed on the
command-line to support target names or generator expressions.

7.2.12 aux_source_directory
---------------------------

Find all source files in a directory.

     aux_source_directory(<dir> <variable>)

Collects the names of all the source files in the specified directory
and stores the list in the ‘<variable>’ provided.  This command is
intended to be used by projects that use explicit template
instantiation.  Template instantiation files can be stored in a
‘Templates’ subdirectory and collected automatically using this command
to avoid manually listing all instantiations.

It is tempting to use this command to avoid writing the list of source
files for a library or executable target.  While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added.  Normally the generated build system
knows when it needs to rerun CMake because the ‘CMakeLists.txt’ file is
modified to add a new source.  When the source is just added to the
directory without modifying this file, one would have to manually rerun
CMake to generate a build system incorporating the new file.

7.2.13 build_command
--------------------

Get a command line to build the current project.  This is mainly
intended for internal use by the CTest module.

     build_command(<variable>
                   [CONFIGURATION <config>]
                   [TARGET <target>]
                   [PROJECT_NAME <projname>] # legacy, causes warning
                  )

Sets the given ‘<variable>’ to a command-line string of the form:

     <cmake> --build . [--config <config>] [--target <target>...] [-- -i]

where ‘<cmake>’ is the location of the cmake(1) command-line
tool, and ‘<config>’ and ‘<target>’ are the values provided to the
‘CONFIGURATION’ and ‘TARGET’ options, if any.  The trailing ‘-- -i’
option is added for Makefile Generators if policy
CMP0061 is not set to ‘NEW’.

When invoked, this ‘cmake --build’ command line will launch the
underlying build system tool.

     build_command(<cachevariable> <makecommand>)

This second signature is deprecated, but still available for backwards
compatibility.  Use the first signature instead.

It sets the given ‘<cachevariable>’ to a command-line string as above
but without the ‘--target’ option.  The ‘<makecommand>’ is ignored but
should be the full path to devenv, nmake, make or one of the end user
build tools for legacy invocations.

     Note: In CMake versions prior to 3.0 this command returned a
     command line that directly invokes the native build tool for the
     current generator.  Their implementation of the ‘PROJECT_NAME’
     option had no useful effects, so CMake now warns on use of the
     option.

7.2.14 create_test_sourcelist
-----------------------------

Create a test driver and source list for building test programs.

     create_test_sourcelist(sourceListName driverName
                            test1 test2 test3
                            EXTRA_INCLUDE include.h
                            FUNCTION function)

A test driver is a program that links together many small tests into a
single executable.  This is useful when building static executables with
large libraries to shrink the total required size.  The list of source
files needed to build the test driver will be in ‘sourceListName’.
‘driverName’ is the name of the test driver program.  The rest of the
arguments consist of a list of test source files, can be semicolon
separated.  Each test source file should have a function in it that is
the same name as the file with no extension (foo.cxx should have int
foo(int, char*[]);) ‘driverName’ will be able to call each of the tests
by name on the command line.  If ‘EXTRA_INCLUDE’ is specified, then the
next argument is included into the generated file.  If ‘FUNCTION’ is
specified, then the next argument is taken as a function name that is
passed a pointer to ac and av.  This can be used to add extra command
line processing to each test.  The ‘CMAKE_TESTDRIVER_BEFORE_TESTMAIN’
cmake variable can be set to have code that will be placed directly
before calling the test main function.
‘CMAKE_TESTDRIVER_AFTER_TESTMAIN’ can be set to have code that will be
placed directly after the call to the test main function.

7.2.15 define_property
----------------------

Define and document custom properties.

     define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                      TEST | VARIABLE | CACHED_VARIABLE>
                      PROPERTY <name> [INHERITED]
                      BRIEF_DOCS <brief-doc> [docs...]
                      FULL_DOCS <full-doc> [docs...])

Defines one property in a scope for use with the set_property()
and get_property() commands.  This is primarily useful
to associate documentation with property names that may be retrieved
with the get_property() command.  The first argument
determines the kind of scope in which the property should be used.  It
must be one of the following:

     GLOBAL    = associated with the global namespace
     DIRECTORY = associated with one directory
     TARGET    = associated with one target
     SOURCE    = associated with one source file
     TEST      = associated with a test named with add_test
     VARIABLE  = documents a CMake language variable
     CACHED_VARIABLE = documents a CMake cache variable

Note that unlike set_property() and get_property()
no actual scope needs to be given; only the kind of scope is
important.

The required ‘PROPERTY’ option is immediately followed by the name of
the property being defined.

If the ‘INHERITED’ option is given, then the get_property().
command will chain up to the next higher scope when the requested
property is not set in the scope given to the command.

   * ‘DIRECTORY’ scope chains to its parent directory’s scope,
     continuing the walk up parent directories until a directory has the
     property set or there are no more parents.  If still not found at
     the top level directory, it chains to the ‘GLOBAL’ scope.

   * ‘TARGET’, ‘SOURCE’ and ‘TEST’ properties chain to ‘DIRECTORY’
     scope, including further chaining up the directories, etc.  as
     needed.

Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(),
get_target_property(), get_source_file_property() and
get_test_property().  There is no inheriting behavior when
`setting' properties, so using ‘APPEND’ or ‘APPEND_STRING’ with the
set_property() command will not consider inherited values
when working out the contents to append to.

The ‘BRIEF_DOCS’ and ‘FULL_DOCS’ options are followed by strings to be
associated with the property as its brief and full documentation.
Corresponding options to the get_property() command will
retrieve the documentation.

7.2.16 enable_language
----------------------

Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)

     enable_language(<lang> [OPTIONAL] )

Enables support for the named language in CMake.  This is the same as
the project() command but does not create any of the extra
variables that are created by the project command.  Example languages
are ‘CXX’, ‘C’, ‘CUDA’, ‘OBJC’, ‘OBJCXX’, ‘Fortran’, ‘ISPC’, and ‘ASM’.

If enabling ‘ASM’, enable it last so that CMake can check whether
compilers for other languages like ‘C’ work for assembly too.

This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies.  It is simplest to enable all
needed languages in the top-level directory of a project.

The ‘OPTIONAL’ keyword is a placeholder for future implementation and
does not currently work.  Instead you can use the CheckLanguage
module to verify support before enabling.

7.2.17 enable_testing
---------------------

Enable testing for current directory and below.

     enable_testing()

Enables testing for this directory and below.

This command should be in the source directory root because ctest
expects to find a test file in the build directory root.

This command is automatically invoked when the CTest module
is included, except if the ‘BUILD_TESTING’ option is turned off.

See also the add_test() command.

7.2.18 export
-------------

Export targets from the build tree for use by outside projects.

     export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])

Creates a file ‘<filename>’ that may be included by outside projects to
import targets from the current project’s build tree.  This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform.  If the ‘NAMESPACE’ option is
given the ‘<namespace>’ string will be prepended to all target names
written to the file.

Target installations are associated with the export ‘<export-name>’
using the ‘EXPORT’ option of the install(TARGETS) command.

The file created by this command is specific to the build tree and
should never be installed.  See the install(EXPORT) command
to export targets from an installation tree.

The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.

     export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
            [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])

This signature is similar to the ‘EXPORT’ signature, but targets are
listed explicitly rather than specified as an export-name.  If the
APPEND option is given the generated code will be appended to the file
instead of overwriting it.  The EXPORT_LINK_INTERFACE_LIBRARIES keyword,
if present, causes the contents of the properties matching
‘(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?’ to be exported, when
policy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.

     Note: Object Libraries under Xcode have
     special handling if multiple architectures are listed in
     CMAKE_OSX_ARCHITECTURES.  In this case they will be exported
     as Interface Libraries with no object files available
     to clients.  This is sufficient to satisfy transitive usage
     requirements of other targets that link to the object libraries in
     their implementation.

     export(PACKAGE <PackageName>)

Store the current build directory in the CMake user package registry for
package ‘<PackageName>’.  The find_package() command may
consider the directory while searching for package ‘<PackageName>’.
This helps dependent projects find and use a package from the current
project’s build tree without help from the user.  Note that the entry in
the package registry that this command creates works only in conjunction
with a package configuration file (‘<PackageName>Config.cmake’) that
works with the build tree.  In some cases, for example for packaging and
for system wide installations, it is not desirable to write the user
package registry.

By default the ‘export(PACKAGE)’ command does nothing (see policy
CMP0090) because populating the user package registry has effects
outside the source and build trees.  Set the
CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to
the CMake user package registry.

     export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])

This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt
targets.  The Android NDK supports the use of prebuilt libraries, both
static and shared.  This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries.  The signature takes a list of targets and puts them in the
Android.mk file specified by the ‘<filename>’ given.  This signature can
only be used if policy CMP0022 is NEW for all targets given.  A error
will be issued if that policy is set to OLD for one of the targets.

7.2.19 fltk_wrap_ui
-------------------

Create FLTK user interfaces Wrappers.

     fltk_wrap_ui(resultingLibraryName source1
                  source2 ... sourceN )

Produce .h and .cxx files for all the .fl and .fld files listed.  The
resulting .h and .cxx files will be added to a variable named
‘resultingLibraryName_FLTK_UI_SRCS’ which should be added to your
library.

7.2.20 get_source_file_property
-------------------------------

Get a property for a source file.

     get_source_file_property(<variable> <file>
                              [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
                              <property>)

Gets a property from a source file.  The value of the property is stored
in the specified ‘<variable>’.  If the source property is not found, the
behavior depends on whether it has been defined to be an ‘INHERITED’
property or not (see define_property()).  Non-inherited
properties will set ‘variable’ to ‘NOTFOUND’, whereas inherited
properties will search the relevant parent scope as described for the
define_property() command and if still unable to find the
property, ‘variable’ will be set to an empty string.

By default, the source file’s property will be read from the current
source directory’s scope, but this can be overridden with one of the
following sub-options:

‘DIRECTORY <dir>’

     The source file property will be read from the ‘<dir>’ directory’s
     scope.  CMake must already know about that source directory, either
     by having added it through a call to add_subdirectory().
     or ‘<dir>’ being the top level source directory.  Relative paths
     are treated as relative to the current source directory.

‘TARGET_DIRECTORY <target>’

     The source file property will be read from the directory scope in
     which ‘<target>’ was created (‘<target>’ must therefore already
     exist).

Use set_source_files_properties() to set property values.
Source file properties usually control how the file is built.  One
property that is always there is LOCATION.

See also the more general get_property() command.

7.2.21 get_target_property
--------------------------

Get a property from a target.

     get_target_property(<VAR> target property)

Get a property from a target.  The value of the property is stored in
the variable ‘<VAR>’.  If the target property is not found, the behavior
depends on whether it has been defined to be an ‘INHERITED’ property or
not (see define_property()).  Non-inherited properties will
set ‘<VAR>’ to ‘<VAR>-NOTFOUND’, whereas inherited properties will
search the relevant parent scope as described for the
define_property() command and if still unable to find the
property, ‘<VAR>’ will be set to an empty string.

Use set_target_properties() to set target property values.
Properties are usually used to control how a target is built, but some
query the target instead.  This command can get properties for any
target so far created.  The targets do not need to be in the current
‘CMakeLists.txt’ file.

See also the more general get_property() command.

See Properties on Targets for the list of properties known
to CMake.

7.2.22 get_test_property
------------------------

Get a property of the test.

     get_test_property(test property VAR)

Get a property from the test.  The value of the property is stored in
the variable ‘VAR’.  If the test property is not found, the behavior
depends on whether it has been defined to be an ‘INHERITED’ property or
not (see define_property()).  Non-inherited properties will
set ‘VAR’ to “NOTFOUND”, whereas inherited properties will search the
relevant parent scope as described for the define_property().
command and if still unable to find the property, ‘VAR’ will be set to
an empty string.

For a list of standard properties you can type ‘cmake
--help-property-list’.

See also the more general get_property() command.

7.2.23 include_directories
--------------------------

Add include directories to the build.

     include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])

Add the given directories to those the compiler uses to search for
include files.  Relative paths are interpreted as relative to the
current source directory.

The include directories are added to the INCLUDE_DIRECTORIES.
directory property for the current ‘CMakeLists’ file.  They are also
added to the INCLUDE_DIRECTORIES target property for each
target in the current ‘CMakeLists’ file.  The target property values are
the ones used by the generators.

By default the directories specified are appended onto the current list
of directories.  This default behavior can be changed by setting
CMAKE_INCLUDE_DIRECTORIES_BEFORE to ‘ON’.  By using ‘AFTER’ or
‘BEFORE’ explicitly, you can select between appending and prepending,
independent of the default.

If the ‘SYSTEM’ option is given, the compiler will be told the
directories are meant as system include directories on some platforms.
Signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs.

Arguments to ‘include_directories’ may use “generator expressions” with
the syntax “$<…>”.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

     Note: Prefer the target_include_directories() command to
     add include directories to individual targets and optionally
     propagate/export them to dependents.

7.2.24 include_external_msproject
---------------------------------

Include an external Microsoft project file in a workspace.

     include_external_msproject(projectname location
                                [TYPE projectTypeGUID]
                                [GUID projectGUID]
                                [PLATFORM platformName]
                                dep1 dep2 ...)

Includes an external Microsoft project in the generated workspace file.
Currently does nothing on UNIX. This will create a target named
‘[projectname]’.  This can be used in the add_dependencies().
command to make things depend on the external project.

‘TYPE’, ‘GUID’ and ‘PLATFORM’ are optional parameters that allow one to
specify the type of project, id (‘GUID’) of the project and the name of
the target platform.  This is useful for projects requiring values other
than the default (e.g.  WIX projects).

If the imported project has different configuration names than the
current project, set the MAP_IMPORTED_CONFIG_<CONFIG> target
property to specify the mapping.

7.2.25 include_regular_expression
---------------------------------

Set the regular expression used for dependency checking.

     include_regular_expression(regex_match [regex_complain])

Sets the regular expressions used in dependency checking.  Only files
matching ‘regex_match’ will be traced as dependencies.  Only files
matching ‘regex_complain’ will generate warnings if they cannot be found
(standard header paths are not searched).  The defaults are:

     regex_match    = "^.*$" (match everything)
     regex_complain = "^$" (match empty string only)

7.2.26 install
--------------

Specify rules to run at install time.

7.2.26.1 Synopsis
.................

     install(see TARGETS. <target>... [...])
     install({see FILES. | See PROGRAMS.} <file>... [...])
     install(see DIRECTORY. <dir>... [...])
     install(see SCRIPT. <file> [...])
     install(see CODE. <code> [...])
     install(see EXPORT. <export-name> [...])

7.2.26.2 Introduction
.....................

This command generates installation rules for a project.  Install rules
specified by calls to the ‘install()’ command within a source directory
are executed in order during installation.  Install rules in
subdirectories added by calls to the add_subdirectory().
command are interleaved with those in the parent directory to run in the
order declared (see policy CMP0082).

There are multiple signatures for this command.  Some of them define
installation options for files and targets.  Options common to multiple
signatures are covered here but they are valid only for signatures that
specify them.  The common options are:

‘DESTINATION’

     Specify the directory on disk to which a file will be installed.
     Arguments can be relative or absolute paths.

     If a relative path is given it is interpreted relative to the value
     of the CMAKE_INSTALL_PREFIX variable.  The prefix can be
     relocated at install time using the ‘DESTDIR’ mechanism explained
     in the CMAKE_INSTALL_PREFIX variable documentation.

     If an absolute path (with a leading slash or drive letter) is given
     it is used verbatim.

     As absolute paths are not supported by cpack installer
     generators, it is preferable to use relative paths throughout.  In
     particular, there is no need to make paths absolute by prepending
     CMAKE_INSTALL_PREFIX.; this prefix is used by default if
     the DESTINATION is a relative path.

‘PERMISSIONS’

     Specify permissions for installed files.  Valid permissions are
     ‘OWNER_READ’, ‘OWNER_WRITE’, ‘OWNER_EXECUTE’, ‘GROUP_READ’,
     ‘GROUP_WRITE’, ‘GROUP_EXECUTE’, ‘WORLD_READ’, ‘WORLD_WRITE’,
     ‘WORLD_EXECUTE’, ‘SETUID’, and ‘SETGID’.  Permissions that do not
     make sense on certain platforms are ignored on those platforms.

‘CONFIGURATIONS’

     Specify a list of build configurations for which the install rule
     applies (Debug, Release, etc.).  Note that the values specified for
     this option only apply to options listed AFTER the ‘CONFIGURATIONS’
     option.  For example, to set separate install paths for the Debug
     and Release configurations, do the following:

          install(TARGETS target
                  CONFIGURATIONS Debug
                  RUNTIME DESTINATION Debug/bin)
          install(TARGETS target
                  CONFIGURATIONS Release
                  RUNTIME DESTINATION Release/bin)

     Note that ‘CONFIGURATIONS’ appears BEFORE ‘RUNTIME DESTINATION’.

‘COMPONENT’

     Specify an installation component name with which the install rule
     is associated, such as “runtime” or “development”.  During
     component-specific installation only install rules associated with
     the given component name will be executed.  During a full
     installation all components are installed unless marked with
     ‘EXCLUDE_FROM_ALL’.  If ‘COMPONENT’ is not provided a default
     component “Unspecified” is created.  The default component name may
     be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
     variable.

‘EXCLUDE_FROM_ALL’

     Specify that the file is excluded from a full installation and only
     installed as part of a component-specific installation

‘RENAME’

     Specify a name for an installed file that may be different from the
     original file.  Renaming is allowed only when a single file is
     installed by the command.

‘OPTIONAL’

     Specify that it is not an error if the file to be installed does
     not exist.

Command signatures that install files may print messages during
installation.  Use the CMAKE_INSTALL_MESSAGE variable to
control which messages are printed.

Many of the ‘install()’ variants implicitly create the directories
containing the installed files.  If
CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS is set, these
directories will be created with the permissions specified.  Otherwise,
they will be created according to the uname rules on Unix-like
platforms.  Windows platforms are unaffected.

7.2.26.3 Installing Targets
...........................

     install(TARGETS targets... [EXPORT <export-name>]
             [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
               PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
              [DESTINATION <dir>]
              [PERMISSIONS permissions...]
              [CONFIGURATIONS [Debug|Release|...]]
              [COMPONENT <component>]
              [NAMELINK_COMPONENT <component>]
              [OPTIONAL] [EXCLUDE_FROM_ALL]
              [NAMELINK_ONLY|NAMELINK_SKIP]
             ] [...]
             [INCLUDES DESTINATION [<dir> ...]]
             )

The ‘TARGETS’ form specifies rules for installing targets from a
project.  There are several kinds of target Output Artifacts.
that may be installed:

‘ARCHIVE’

     Target artifacts of this kind include:

        * `Static libraries' (except on macOS when marked as
          ‘FRAMEWORK’, see below);

        * `DLL import libraries' (on all Windows-based systems including
          Cygwin; they have extension ‘.lib’, in contrast to the ‘.dll’
          libraries that go to ‘RUNTIME’);

        * On AIX, the `linker import file' created for executables with
          ENABLE_EXPORTS enabled.

‘LIBRARY’

     Target artifacts of this kind include:

        * `Shared libraries', except

             - DLLs (these go to ‘RUNTIME’, see below),

             - on macOS when marked as ‘FRAMEWORK’ (see below).

‘RUNTIME’

     Target artifacts of this kind include:

        * `Executables' (except on macOS when marked as ‘MACOSX_BUNDLE’,
          see ‘BUNDLE’ below);

        * DLLs (on all Windows-based systems including Cygwin; note that
          the accompanying import libraries are of kind ‘ARCHIVE’).

‘OBJECTS’

     Object files associated with `object libraries'.

‘FRAMEWORK’

     Both static and shared libraries marked with the ‘FRAMEWORK’
     property are treated as ‘FRAMEWORK’ targets on macOS.

‘BUNDLE’

     Executables marked with the MACOSX_BUNDLE property are
     treated as ‘BUNDLE’ targets on macOS.

‘PUBLIC_HEADER’

     Any PUBLIC_HEADER files associated with a library are
     installed in the destination specified by the ‘PUBLIC_HEADER’
     argument on non-Apple platforms.  Rules defined by this argument
     are ignored for FRAMEWORK libraries on Apple platforms
     because the associated files are installed into the appropriate
     locations inside the framework folder.  See PUBLIC_HEADER
     for details.

‘PRIVATE_HEADER’

     Similar to ‘PUBLIC_HEADER’, but for ‘PRIVATE_HEADER’ files.  See
     PRIVATE_HEADER for details.

‘RESOURCE’

     Similar to ‘PUBLIC_HEADER’ and ‘PRIVATE_HEADER’, but for ‘RESOURCE’
     files.  See RESOURCE for details.

For each of these arguments given, the arguments following them only
apply to the target or file type specified in the argument.  If none is
given, the installation properties apply to all target types.  If only
one is given then only targets of that type will be installed (which can
be used to install just a DLL or just an import library.)

For regular executables, static libraries and shared libraries, the
‘DESTINATION’ argument is not required.  For these target types, when
‘DESTINATION’ is omitted, a default destination will be taken from the
appropriate variable from GNUInstallDirs, or set to a
built-in default value if that variable is not defined.  The same is
true for the public and private headers associated with the installed
targets through the PUBLIC_HEADER and PRIVATE_HEADER
target properties.  A destination must always be provided for
module libraries, Apple bundles and frameworks.  A destination can be
omitted for interface and object libraries, but they are handled
differently (see the discussion of this topic toward the end of this
section).

The following table shows the target types with their associated
variables and built-in defaults that apply when no destination is given:

Target Type            GNUInstallDirs Variable             Built-In Default

--------------------------------------------------------------------------------------

‘RUNTIME’              ‘${CMAKE_INSTALL_BINDIR}’           ‘bin’

‘LIBRARY’              ‘${CMAKE_INSTALL_LIBDIR}’           ‘lib’

‘ARCHIVE’              ‘${CMAKE_INSTALL_LIBDIR}’           ‘lib’

‘PRIVATE_HEADER’       ‘${CMAKE_INSTALL_INCLUDEDIR}’       ‘include’

‘PUBLIC_HEADER’        ‘${CMAKE_INSTALL_INCLUDEDIR}’       ‘include’

Projects wishing to follow the common practice of installing headers
into a project-specific subdirectory will need to provide a destination
rather than rely on the above.

To make packages compliant with distribution filesystem layout policies,
if projects must specify a ‘DESTINATION’, it is recommended that they
use a path that begins with the appropriate GNUInstallDirs.
variable.  This allows package maintainers to control the install
destination by setting the appropriate cache variables.  The following
example shows a static library being installed to the default
destination provided by GNUInstallDirs, but with its headers
installed to a project-specific subdirectory that follows the above
recommendation:

     add_library(mylib STATIC ...)
     set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
     include(GNUInstallDirs)
     install(TARGETS mylib
             PUBLIC_HEADER
               DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
     )

In addition to the common options listed above, each target can accept
the following additional arguments:

‘NAMELINK_COMPONENT’

     On some platforms a versioned shared library has a symbolic link
     such as:

          lib<name>.so -> lib<name>.so.1

     where ‘lib<name>.so.1’ is the soname of the library and
     ‘lib<name>.so’ is a “namelink” allowing linkers to find the library
     when given ‘-l<name>’.  The ‘NAMELINK_COMPONENT’ option is similar
     to the ‘COMPONENT’ option, but it changes the installation
     component of a shared library namelink if one is generated.  If not
     specified, this defaults to the value of ‘COMPONENT’.  It is an
     error to use this parameter outside of a ‘LIBRARY’ block.

     Consider the following example:

          install(TARGETS mylib
                  LIBRARY
                    COMPONENT Libraries
                    NAMELINK_COMPONENT Development
                  PUBLIC_HEADER
                    COMPONENT Development
                 )

     In this scenario, if you choose to install only the ‘Development’
     component, both the headers and namelink will be installed without
     the library.  (If you don’t also install the ‘Libraries’ component,
     the namelink will be a dangling symlink, and projects that link to
     the library will have build errors.)  If you install only the
     ‘Libraries’ component, only the library will be installed, without
     the headers and namelink.

     This option is typically used for package managers that have
     separate runtime and development packages.  For example, on Debian
     systems, the library is expected to be in the runtime package, and
     the headers and namelink are expected to be in the development
     package.

     See the VERSION and SOVERSION target
     properties for details on creating versioned shared libraries.

‘NAMELINK_ONLY’

     This option causes the installation of only the namelink when a
     library target is installed.  On platforms where versioned shared
     libraries do not have namelinks or when a library is not versioned,
     the ‘NAMELINK_ONLY’ option installs nothing.  It is an error to use
     this parameter outside of a ‘LIBRARY’ block.

     When ‘NAMELINK_ONLY’ is given, either ‘NAMELINK_COMPONENT’ or
     ‘COMPONENT’ may be used to specify the installation component of
     the namelink, but ‘COMPONENT’ should generally be preferred.

‘NAMELINK_SKIP’

     Similar to ‘NAMELINK_ONLY’, but it has the opposite effect: it
     causes the installation of library files other than the namelink
     when a library target is installed.  When neither ‘NAMELINK_ONLY’
     or ‘NAMELINK_SKIP’ are given, both portions are installed.  On
     platforms where versioned shared libraries do not have symlinks or
     when a library is not versioned, ‘NAMELINK_SKIP’ installs the
     library.  It is an error to use this parameter outside of a
     ‘LIBRARY’ block.

     If ‘NAMELINK_SKIP’ is specified, ‘NAMELINK_COMPONENT’ has no
     effect.  It is not recommended to use ‘NAMELINK_SKIP’ in
     conjunction with ‘NAMELINK_COMPONENT’.

The install(TARGETS) command can also accept the following
options at the top level:

‘EXPORT’

     This option associates the installed target files with an export
     called ‘<export-name>’.  It must appear before any target options.
     To actually install the export file itself, call
     install(EXPORT), documented below.  See documentation of the
     EXPORT_NAME target property to change the name of the
     exported target.

‘INCLUDES DESTINATION’

     This option specifies a list of directories which will be added to
     the INTERFACE_INCLUDE_DIRECTORIES target property of
     the ‘<targets>’ when exported by the install(EXPORT).
     command.  If a relative path is specified, it is treated as
     relative to the ‘$<INSTALL_PREFIX>’.

One or more groups of properties may be specified in a single call to
the ‘TARGETS’ form of this command.  A target may be installed more than
once to different locations.  Consider hypothetical targets ‘myExe’,
‘mySharedLib’, and ‘myStaticLib’.  The code:

     install(TARGETS myExe mySharedLib myStaticLib
             RUNTIME DESTINATION bin
             LIBRARY DESTINATION lib
             ARCHIVE DESTINATION lib/static)
     install(TARGETS mySharedLib DESTINATION /some/full/path)

will install ‘myExe’ to ‘<prefix>/bin’ and ‘myStaticLib’ to
‘<prefix>/lib/static’.  On non-DLL platforms ‘mySharedLib’ will be
installed to ‘<prefix>/lib’ and ‘/some/full/path’.  On DLL platforms the
‘mySharedLib’ DLL will be installed to ‘<prefix>/bin’ and
‘/some/full/path’ and its import library will be installed to
‘<prefix>/lib/static’ and ‘/some/full/path’.

Interface Libraries may be listed among the targets to
install.  They install no artifacts but will be included in an
associated ‘EXPORT’.  If Object Libraries are listed but
given no destination for their object files, they will be exported as
Interface Libraries.  This is sufficient to satisfy
transitive usage requirements of other targets that link to the object
libraries in their implementation.

Installing a target with the EXCLUDE_FROM_ALL target
property set to ‘TRUE’ has undefined behavior.

install(TARGETS) can install targets that were created in
other directories.  When using such cross-directory install rules,
running ‘make install’ (or similar) from a subdirectory will not
guarantee that targets from other directories are up-to-date.  You can
use target_link_libraries() or add_dependencies().
to ensure that such out-of-directory targets are built before the
subdirectory-specific install rules are run.

An install destination given as a ‘DESTINATION’ argument may use
“generator expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.

7.2.26.4 Installing Files
.........................

     install(<FILES|PROGRAMS> files...
             TYPE <type> | DESTINATION <dir>
             [PERMISSIONS permissions...]
             [CONFIGURATIONS [Debug|Release|...]]
             [COMPONENT <component>]
             [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

The ‘FILES’ form specifies rules for installing files for a project.
File names given as relative paths are interpreted with respect to the
current source directory.  Files installed by this form are by default
given permissions ‘OWNER_WRITE’, ‘OWNER_READ’, ‘GROUP_READ’, and
‘WORLD_READ’ if no ‘PERMISSIONS’ argument is given.

The ‘PROGRAMS’ form is identical to the ‘FILES’ form except that the
default permissions for the installed file also include ‘OWNER_EXECUTE’,
‘GROUP_EXECUTE’, and ‘WORLD_EXECUTE’.  This form is intended to install
programs that are not targets, such as shell scripts.  Use the ‘TARGETS’
form to install targets built within the project.

The list of ‘files...’ given to ‘FILES’ or ‘PROGRAMS’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
However, if any item begins in a generator expression it must evaluate
to a full path.

Either a ‘TYPE’ or a ‘DESTINATION’ must be provided, but not both.  A
‘TYPE’ argument specifies the generic file type of the files being
installed.  A destination will then be set automatically by taking the
corresponding variable from GNUInstallDirs, or by using a
built-in default if that variable is not defined.  See the table below
for the supported file types and their corresponding variables and
built-in defaults.  Projects can provide a ‘DESTINATION’ argument
instead of a file type if they wish to explicitly define the install
destination.

‘TYPE’ Argument             GNUInstallDirs Variable                Built-In Default

-------------------------------------------------------------------------------------------------

‘BIN’                       ‘${CMAKE_INSTALL_BINDIR}’              ‘bin’

‘SBIN’                      ‘${CMAKE_INSTALL_SBINDIR}’             ‘sbin’

‘LIB’                       ‘${CMAKE_INSTALL_LIBDIR}’              ‘lib’

‘INCLUDE’                   ‘${CMAKE_INSTALL_INCLUDEDIR}’          ‘include’

‘SYSCONF’                   ‘${CMAKE_INSTALL_SYSCONFDIR}’          ‘etc’

‘SHAREDSTATE’               ‘${CMAKE_INSTALL_SHARESTATEDIR}’       ‘com’

‘LOCALSTATE’                ‘${CMAKE_INSTALL_LOCALSTATEDIR}’       ‘var’

‘RUNSTATE’                  ‘${CMAKE_INSTALL_RUNSTATEDIR}’         ‘<LOCALSTATE dir>/run’

‘DATA’                      ‘${CMAKE_INSTALL_DATADIR}’             ‘<DATAROOT dir>’

‘INFO’                      ‘${CMAKE_INSTALL_INFODIR}’             ‘<DATAROOT dir>/info’

‘LOCALE’                    ‘${CMAKE_INSTALL_LOCALEDIR}’           ‘<DATAROOT dir>/locale’

‘MAN’                       ‘${CMAKE_INSTALL_MANDIR}’              ‘<DATAROOT dir>/man’

‘DOC’                       ‘${CMAKE_INSTALL_DOCDIR}’              ‘<DATAROOT dir>/doc’

Projects wishing to follow the common practice of installing headers
into a project-specific subdirectory will need to provide a destination
rather than rely on the above.

Note that some of the types’ built-in defaults use the ‘DATAROOT’
directory as a prefix.  The ‘DATAROOT’ prefix is calculated similarly to
the types, with ‘CMAKE_INSTALL_DATAROOTDIR’ as the variable and ‘share’
as the built-in default.  You cannot use ‘DATAROOT’ as a ‘TYPE’
parameter; please use ‘DATA’ instead.

To make packages compliant with distribution filesystem layout policies,
if projects must specify a ‘DESTINATION’, it is recommended that they
use a path that begins with the appropriate GNUInstallDirs.
variable.  This allows package maintainers to control the install
destination by setting the appropriate cache variables.  The following
example shows how to follow this advice while installing headers to a
project-specific subdirectory:

     include(GNUInstallDirs)
     install(FILES mylib.h
             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
     )

An install destination given as a ‘DESTINATION’ argument may use
“generator expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.

7.2.26.5 Installing Directories
...............................

     install(DIRECTORY dirs...
             TYPE <type> | DESTINATION <dir>
             [FILE_PERMISSIONS permissions...]
             [DIRECTORY_PERMISSIONS permissions...]
             [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
             [CONFIGURATIONS [Debug|Release|...]]
             [COMPONENT <component>] [EXCLUDE_FROM_ALL]
             [FILES_MATCHING]
             [[PATTERN <pattern> | REGEX <regex>]
              [EXCLUDE] [PERMISSIONS permissions...]] [...])

The ‘DIRECTORY’ form installs contents of one or more directories to a
given destination.  The directory structure is copied verbatim to the
destination.  The last component of each directory name is appended to
the destination directory but a trailing slash may be used to avoid this
because it leaves the last component empty.  Directory names given as
relative paths are interpreted with respect to the current source
directory.  If no input directory names are given the destination
directory will be created but nothing will be installed into it.  The
‘FILE_PERMISSIONS’ and ‘DIRECTORY_PERMISSIONS’ options specify
permissions given to files and directories in the destination.  If
‘USE_SOURCE_PERMISSIONS’ is specified and ‘FILE_PERMISSIONS’ is not,
file permissions will be copied from the source directory structure.  If
no permissions are specified files will be given the default permissions
specified in the ‘FILES’ form of the command, and the directories will
be given the default permissions specified in the ‘PROGRAMS’ form of the
command.

The ‘MESSAGE_NEVER’ option disables file installation status output.

Installation of directories may be controlled with fine granularity
using the ‘PATTERN’ or ‘REGEX’ options.  These “match” options specify a
globbing pattern or regular expression to match directories or files
encountered within input directories.  They may be used to apply certain
options (see below) to a subset of the files and directories
encountered.  The full path to each input file or directory (with
forward slashes) is matched against the expression.  A ‘PATTERN’ will
match only complete file names: the portion of the full path matching
the pattern must occur at the end of the file name and be preceded by a
slash.  A ‘REGEX’ will match any portion of the full path but it may use
‘/’ and ‘$’ to simulate the ‘PATTERN’ behavior.  By default all files
and directories are installed whether or not they are matched.  The
‘FILES_MATCHING’ option may be given before the first match option to
disable installation of files (but not directories) not matched by any
expression.  For example, the code

     install(DIRECTORY src/ DESTINATION include/myproj
             FILES_MATCHING PATTERN "*.h")

will extract and install header files from a source tree.

Some options may follow a ‘PATTERN’ or ‘REGEX’ expression and are
applied only to files or directories matching them.  The ‘EXCLUDE’
option will skip the matched file or directory.  The ‘PERMISSIONS’
option overrides the permissions setting for the matched file or
directory.  For example the code

     install(DIRECTORY icons scripts/ DESTINATION share/myproj
             PATTERN "CVS" EXCLUDE
             PATTERN "scripts/*"
             PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
                         GROUP_EXECUTE GROUP_READ)

will install the ‘icons’ directory to ‘share/myproj/icons’ and the
‘scripts’ directory to ‘share/myproj’.  The icons will get default file
permissions, the scripts will be given specific permissions, and any
‘CVS’ directories will be excluded.

Either a ‘TYPE’ or a ‘DESTINATION’ must be provided, but not both.  A
‘TYPE’ argument specifies the generic file type of the files within the
listed directories being installed.  A destination will then be set
automatically by taking the corresponding variable from
GNUInstallDirs, or by using a built-in default if that variable is
not defined.  See the table below for the supported file types and their
corresponding variables and built-in defaults.  Projects can provide a
‘DESTINATION’ argument instead of a file type if they wish to explicitly
define the install destination.

‘TYPE’ Argument             GNUInstallDirs Variable                Built-In Default

-------------------------------------------------------------------------------------------------

‘BIN’                       ‘${CMAKE_INSTALL_BINDIR}’              ‘bin’

‘SBIN’                      ‘${CMAKE_INSTALL_SBINDIR}’             ‘sbin’

‘LIB’                       ‘${CMAKE_INSTALL_LIBDIR}’              ‘lib’

‘INCLUDE’                   ‘${CMAKE_INSTALL_INCLUDEDIR}’          ‘include’

‘SYSCONF’                   ‘${CMAKE_INSTALL_SYSCONFDIR}’          ‘etc’

‘SHAREDSTATE’               ‘${CMAKE_INSTALL_SHARESTATEDIR}’       ‘com’

‘LOCALSTATE’                ‘${CMAKE_INSTALL_LOCALSTATEDIR}’       ‘var’

‘RUNSTATE’                  ‘${CMAKE_INSTALL_RUNSTATEDIR}’         ‘<LOCALSTATE dir>/run’

‘DATA’                      ‘${CMAKE_INSTALL_DATADIR}’             ‘<DATAROOT dir>’

‘INFO’                      ‘${CMAKE_INSTALL_INFODIR}’             ‘<DATAROOT dir>/info’

‘LOCALE’                    ‘${CMAKE_INSTALL_LOCALEDIR}’           ‘<DATAROOT dir>/locale’

‘MAN’                       ‘${CMAKE_INSTALL_MANDIR}’              ‘<DATAROOT dir>/man’

‘DOC’                       ‘${CMAKE_INSTALL_DOCDIR}’              ‘<DATAROOT dir>/doc’

Note that some of the types’ built-in defaults use the ‘DATAROOT’
directory as a prefix.  The ‘DATAROOT’ prefix is calculated similarly to
the types, with ‘CMAKE_INSTALL_DATAROOTDIR’ as the variable and ‘share’
as the built-in default.  You cannot use ‘DATAROOT’ as a ‘TYPE’
parameter; please use ‘DATA’ instead.

To make packages compliant with distribution filesystem layout policies,
if projects must specify a ‘DESTINATION’, it is recommended that they
use a path that begins with the appropriate GNUInstallDirs.
variable.  This allows package maintainers to control the install
destination by setting the appropriate cache variables.

The list of ‘dirs...’ given to ‘DIRECTORY’ and an install destination
given as a ‘DESTINATION’ argument may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.

7.2.26.6 Custom Installation Logic
..................................

     install([[SCRIPT <file>] [CODE <code>]]
             [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])

The ‘SCRIPT’ form will invoke the given CMake script files during
installation.  If the script file name is a relative path it will be
interpreted with respect to the current source directory.  The ‘CODE’
form will invoke the given CMake code during installation.  Code is
specified as a single argument inside a double-quoted string.  For
example, the code

     install(CODE "MESSAGE(\"Sample install message.\")")

will print a message during installation.

‘<file>’ or ‘<code>’ may use “generator expressions” with the syntax
‘$<...>’ (in the case of ‘<file>’, this refers to their use in the file
name, not the file’s contents).  See the
cmake-generator-expressions(7) manual for available expressions.

7.2.26.7 Installing Exports
...........................

     install(EXPORT <export-name> DESTINATION <dir>
             [NAMESPACE <namespace>] [[FILE <name>.cmake]|
             [PERMISSIONS permissions...]
             [CONFIGURATIONS [Debug|Release|...]]
             [EXPORT_LINK_INTERFACE_LIBRARIES]
             [COMPONENT <component>]
             [EXCLUDE_FROM_ALL])
     install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

The ‘EXPORT’ form generates and installs a CMake file containing code to
import targets from the installation tree into another project.  Target
installations are associated with the export ‘<export-name>’ using the
‘EXPORT’ option of the install(TARGETS) signature documented
above.  The ‘NAMESPACE’ option will prepend ‘<namespace>’ to the target
names as they are written to the import file.  By default the generated
file will be called ‘<export-name>.cmake’ but the ‘FILE’ option may be
used to specify a different name.  The value given to the ‘FILE’ option
must be a file name with the ‘.cmake’ extension.  If a ‘CONFIGURATIONS’
option is given then the file will only be installed when one of the
named configurations is installed.  Additionally, the generated import
file will reference only the matching target configurations.  The
‘EXPORT_LINK_INTERFACE_LIBRARIES’ keyword, if present, causes the
contents of the properties matching
‘(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?’ to be exported, when
policy CMP0022 is ‘NEW’.

     Note: The installed ‘<export-name>.cmake’ file may come with
     additional per-configuration ‘<export-name>-*.cmake’ files to be
     loaded by globbing.  Do not use an export name that is the same as
     the package name in combination with installing a
     ‘<package-name>-config.cmake’ file or the latter may be incorrectly
     matched by the glob and loaded.

When a ‘COMPONENT’ option is given, the listed ‘<component>’ implicitly
depends on all components mentioned in the export set.  The exported
‘<name>.cmake’ file will require each of the exported components to be
present in order for dependent projects to build properly.  For example,
a project may define components ‘Runtime’ and ‘Development’, with shared
libraries going into the ‘Runtime’ component and static libraries and
headers going into the ‘Development’ component.  The export set would
also typically be part of the ‘Development’ component, but it would
export targets from both the ‘Runtime’ and ‘Development’ components.
Therefore, the ‘Runtime’ component would need to be installed if the
‘Development’ component was installed, but not vice versa.  If the
‘Development’ component was installed without the ‘Runtime’ component,
dependent projects that try to link against it would have build errors.
Package managers, such as APT and RPM, typically handle this by listing
the ‘Runtime’ component as a dependency of the ‘Development’ component
in the package metadata, ensuring that the library is always installed
if the headers and CMake export file are present.

In addition to cmake language files, the ‘EXPORT_ANDROID_MK’ mode maybe
used to specify an export to the android ndk build system.  This mode
accepts the same options as the normal export mode.  The Android NDK
supports the use of prebuilt libraries, both static and shared.  This
allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include
flags and defines required to use the libraries.

The ‘EXPORT’ form is useful to help outside projects use targets built
and installed by the current project.  For example, the code

     install(TARGETS myexe EXPORT myproj DESTINATION bin)
     install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
     install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)

will install the executable ‘myexe’ to ‘<prefix>/bin’ and code to import
it in the file ‘<prefix>/lib/myproj/myproj.cmake’ and
‘<prefix>/share/ndk-modules/Android.mk’.  An outside project may load
this file with the include command and reference the ‘myexe’ executable
from the installation tree using the imported target name ‘mp_myexe’ as
if the target were built in its own tree.

     Note: This command supercedes the install_targets().
     command and the PRE_INSTALL_SCRIPT and
     POST_INSTALL_SCRIPT target properties.  It also replaces the
     ‘FILES’ forms of the install_files() and
     install_programs() commands.  The processing order of these
     install rules relative to those generated by
     install_targets(), install_files(), and
     install_programs() commands is not defined.

7.2.26.8 Generated Installation Script
......................................

     Note: Use of this feature is not recommended.  Please consider
     using the ‘--install’ argument of cmake(1) instead.

The ‘install()’ command generates a file, ‘cmake_install.cmake’, inside
the build directory, which is used internally by the generated install
target and by CPack.  You can also invoke this script manually with
‘cmake -P’.  This script accepts several variables:

‘COMPONENT’

     Set this variable to install only a single CPack component as
     opposed to all of them.  For example, if you only want to install
     the ‘Development’ component, run ‘cmake -DCOMPONENT=Development -P
     cmake_install.cmake’.

‘BUILD_TYPE’

     Set this variable to change the build type if you are using a
     multi-config generator.  For example, to install with the ‘Debug’
     configuration, run ‘cmake -DBUILD_TYPE=Debug -P
     cmake_install.cmake’.

‘DESTDIR’

     This is an environment variable rather than a CMake variable.  It
     allows you to change the installation prefix on UNIX systems.  See
     DESTDIR for details.

7.2.27 link_directories
-----------------------

Add directories in which the linker will look for libraries.

     link_directories([AFTER|BEFORE] directory1 [directory2 ...])

Adds the paths in which the linker should search for libraries.
Relative paths given to this command are interpreted as relative to the
current source directory, see CMP0015.

The directories are added to the LINK_DIRECTORIES directory
property for the current ‘CMakeLists.txt’ file, converting relative
paths to absolute as needed.  The command will apply only to targets
created after it is called.

By default the directories specified are appended onto the current list
of directories.  This default behavior can be changed by setting
CMAKE_LINK_DIRECTORIES_BEFORE to ‘ON’.  By using ‘AFTER’ or
‘BEFORE’ explicitly, you can select between appending and prepending,
independent of the default.

Arguments to ‘link_directories’ may use “generator expressions” with the
syntax “$<…>”.  See the cmake-generator-expressions(7) manual
for available expressions.  See the cmake-buildsystem(7).
manual for more on defining buildsystem properties.

     Note: This command is rarely necessary and should be avoided where
     there are other choices.  Prefer to pass full absolute paths to
     libraries where possible, since this ensures the correct library
     will always be linked.  The find_library() command
     provides the full path, which can generally be used directly in
     calls to target_link_libraries().  Situations where a
     library search path may be needed include:

        - Project generators like Xcode where the user can switch target
          architecture at build time, but a full path to a library
          cannot be used because it only provides one architecture (i.e.
          it is not a universal binary).

        - Libraries may themselves have other private library
          dependencies that expect to be found via ‘RPATH’ mechanisms,
          but some linkers are not able to fully decode those paths
          (e.g.  due to the presence of things like ‘$ORIGIN’).

     If a library search path must be provided, prefer to localize the
     effect where possible by using the target_link_directories()
     command rather than ‘link_directories()’.  The target-specific
     command can also control how the search directories propagate to
     other dependent targets.

7.2.28 link_libraries
---------------------

Link libraries to all targets added later.

     link_libraries([item1 [item2 [...]]]
                    [[debug|optimized|general] <item>] ...)

Specify libraries or flags to use when linking any targets created later
in the current directory or below by commands such as
add_executable() or add_library().  See the
target_link_libraries() command for meaning of arguments.

     Note: The target_link_libraries() command should be
     preferred whenever possible.  Library dependencies are chained
     automatically, so directory-wide specification of link libraries is
     rarely needed.

7.2.29 load_cache
-----------------

Load in the values from another project’s CMake cache.

     load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)

Reads the cache and store the requested entries in variables with their
name prefixed with the given prefix.  This only reads the values, and
does not create entries in the local project’s cache.

     load_cache(pathToBuildDirectory [EXCLUDE entry1...]
                [INCLUDE_INTERNALS entry1...])

Loads in the values from another cache and store them in the local
project’s cache as internal entries.  This is useful for a project that
depends on another project built in a different tree.  ‘EXCLUDE’ option
can be used to provide a list of entries to be excluded.
‘INCLUDE_INTERNALS’ can be used to provide a list of internal entries to
be included.  Normally, no internal entries are brought in.  Use of this
form of the command is strongly discouraged, but it is provided for
backward compatibility.

7.2.30 project
--------------

Set the name of the project.

7.2.30.1 Synopsis
.................

     project(<PROJECT-NAME> [<language-name>...])
     project(<PROJECT-NAME>
             [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
             [DESCRIPTION <project-description-string>]
             [HOMEPAGE_URL <url-string>]
             [LANGUAGES <language-name>...])

Sets the name of the project, and stores it in the variable
PROJECT_NAME.  When called from the top-level ‘CMakeLists.txt’ also
stores the project name in the variable CMAKE_PROJECT_NAME.

Also sets the variables

   * PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR.

   * PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR.

Further variables are set by the optional arguments described in the
following.  If any of these arguments is not used, then the
corresponding variables are set to the empty string.

7.2.30.2 Options
................

The options are:

‘VERSION <version>’

     Optional; may not be used unless policy CMP0048 is set
     to ‘NEW’.

     Takes a ‘<version>’ argument composed of non-negative integer
     components, i.e.  ‘<major>[.<minor>[.<patch>[.<tweak>]]]’, and sets
     the variables

        * PROJECT_VERSION, <PROJECT-NAME>_VERSION.

        * PROJECT_VERSION_MAJOR,
          <PROJECT-NAME>_VERSION_MAJOR.

        * PROJECT_VERSION_MINOR,
          <PROJECT-NAME>_VERSION_MINOR.

        * PROJECT_VERSION_PATCH,
          <PROJECT-NAME>_VERSION_PATCH.

        * PROJECT_VERSION_TWEAK,
          <PROJECT-NAME>_VERSION_TWEAK.

     When the ‘project()’ command is called from the top-level
     ‘CMakeLists.txt’, then the version is also stored in the variable
     CMAKE_PROJECT_VERSION.

‘DESCRIPTION <project-description-string>’

     Optional.  Sets the variables

        * PROJECT_DESCRIPTION,
          <PROJECT-NAME>_DESCRIPTION.

     to ‘<project-description-string>’.  It is recommended that this
     description is a relatively short string, usually no more than a
     few words.

     When the ‘project()’ command is called from the top-level
     ‘CMakeLists.txt’, then the description is also stored in the
     variable CMAKE_PROJECT_DESCRIPTION.

‘HOMEPAGE_URL <url-string>’

     Optional.  Sets the variables

        * PROJECT_HOMEPAGE_URL,
          <PROJECT-NAME>_HOMEPAGE_URL.

     to ‘<url-string>’, which should be the canonical home URL for the
     project.

     When the ‘project()’ command is called from the top-level
     ‘CMakeLists.txt’, then the URL also is stored in the variable
     CMAKE_PROJECT_HOMEPAGE_URL.

‘LANGUAGES <language-name>...’

     Optional.  Can also be specified without ‘LANGUAGES’ keyword per
     the first, short signature.

     Selects which programming languages are needed to build the
     project.  Supported languages include ‘C’, ‘CXX’ (i.e.  C++),
     ‘CUDA’, ‘OBJC’ (i.e.  Objective-C), ‘OBJCXX’, ‘Fortran’, ‘ISPC’,
     and ‘ASM’.  By default ‘C’ and ‘CXX’ are enabled if no language
     options are given.  Specify language ‘NONE’, or use the ‘LANGUAGES’
     keyword and list no languages, to skip enabling any languages.

     If enabling ‘ASM’, list it last so that CMake can check whether
     compilers for other languages like ‘C’ work for assembly too.

The variables set through the ‘VERSION’, ‘DESCRIPTION’ and
‘HOMEPAGE_URL’ options are intended for use as default values in package
metadata and documentation.

7.2.30.3 Code Injection
.......................

If the CMAKE_PROJECT_INCLUDE_BEFORE or
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables are set, the
files they point to will be included as the first step of the
‘project()’ command.  If both are set, then
CMAKE_PROJECT_INCLUDE_BEFORE will be included before
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.

If the CMAKE_PROJECT_INCLUDE or
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE variables are set, the files
they point to will be included as the last step of the ‘project()’
command.  If both are set, then CMAKE_PROJECT_INCLUDE will
be included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.

7.2.30.4 Usage
..............

The top-level ‘CMakeLists.txt’ file for a project must contain a
literal, direct call to the ‘project()’ command; loading one through the
include() command is not sufficient.  If no such call
exists, CMake will issue a warning and pretend there is a
‘project(Project)’ at the top to enable the default languages (‘C’ and
‘CXX’).

     Note: Call the ‘project()’ command near the top of the top-level
     ‘CMakeLists.txt’, but `after' calling
     cmake_minimum_required().  It is important to establish
     version and policy settings before invoking other commands whose
     behavior they may affect.  See also policy CMP0000.

7.2.31 remove_definitions
-------------------------

Remove -D define flags added by add_definitions().

     remove_definitions(-DFOO -DBAR ...)

Removes flags (added by add_definitions()) from the compiler
command line for sources in the current directory and below.

7.2.32 set_source_files_properties
----------------------------------

Source files can have properties that affect how they are built.

     set_source_files_properties(<files> ...
                                 [DIRECTORY <dirs> ...]
                                 [TARGET_DIRECTORY <targets> ...]
                                 PROPERTIES <prop1> <value1>
                                 [<prop2> <value2>] ...)

Sets properties associated with source files using a key/value paired
list.

By default, source file properties are only visible to targets added in
the same directory (‘CMakeLists.txt’).  Visibility can be set in other
directory scopes using one or both of the following options:

‘DIRECTORY <dirs>...’

     The source file properties will be set in each of the ‘<dirs>’
     directories’ scopes.  CMake must already know about each of these
     source directories, either by having added them through a call to
     add_subdirectory() or it being the top level source
     directory.  Relative paths are treated as relative to the current
     source directory.

‘TARGET_DIRECTORY <targets>...’

     The source file properties will be set in each of the directory
     scopes where any of the specified ‘<targets>’ were created (the
     ‘<targets>’ must therefore already exist).

Use get_source_file_property() to get property values.  See
also the set_property(SOURCE) command.

See Properties on Source Files for the list of properties
known to CMake.

7.2.33 set_target_properties
----------------------------

Targets can have properties that affect how they are built.

     set_target_properties(target1 target2 ...
                           PROPERTIES prop1 value1
                           prop2 value2 ...)

Sets properties on targets.  The syntax for the command is to list all
the targets you want to change, and then provide the values you want to
set next.  You can use any prop value pair you want and extract it later
with the get_property() or get_target_property().
command.

See also the set_property(TARGET) command.

See Properties on Targets for the list of properties known
to CMake.

7.2.34 set_tests_properties
---------------------------

Set a property of the tests.

     set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)

Sets a property for the tests.  If the test is not found, CMake will
report an error.  Generator expressions will be expanded the
same as supported by the test’s add_test() call.

See also the set_property(TEST) command.

See Properties on Tests for the list of properties known to
CMake.

7.2.35 source_group
-------------------

Define a grouping for source files in IDE project generation.  There are
two different signatures to create source groups.

     source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
     source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])

Defines a group into which sources will be placed in project files.
This is intended to set up file tabs in Visual Studio.  The options are:

‘TREE’

     CMake will automatically detect, from ‘<src>’ files paths, source
     groups it needs to create, to keep structure of source groups
     analogically to the actual files and directories structure in the
     project.  Paths of ‘<src>’ files will be cut to be relative to
     ‘<root>’.

‘PREFIX’

     Source group and files located directly in ‘<root>’ path, will be
     placed in ‘<prefix>’ source groups.

‘FILES’

     Any source file specified explicitly will be placed in group
     ‘<name>’.  Relative paths are interpreted with respect to the
     current source directory.

‘REGULAR_EXPRESSION’

     Any source file whose name matches the regular expression will be
     placed in group ‘<name>’.

If a source file matches multiple groups, the `last' group that
explicitly lists the file with ‘FILES’ will be favored, if any.  If no
group explicitly lists the file, the `last' group whose regular
expression matches the file will be favored.

The ‘<name>’ of the group and ‘<prefix>’ argument may contain forward
slashes or backslashes to specify subgroups.  Backslashes need to be
escaped appropriately:

     source_group(base/subdir ...)
     source_group(outer\\inner ...)
     source_group(TREE <root> PREFIX sources\\inc ...)

For backwards compatibility, the short-hand signature

     source_group(<name> <regex>)

is equivalent to

     source_group(<name> REGULAR_EXPRESSION <regex>)

7.2.36 target_compile_definitions
---------------------------------

Add compile definitions to a target.

     target_compile_definitions(<target>
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies compile definitions to use when compiling a given ‘<target>’.
The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the following arguments.  ‘PRIVATE’ and ‘PUBLIC’ items will
populate the COMPILE_DEFINITIONS property of ‘<target>’.
‘PUBLIC’ and ‘INTERFACE’ items will populate the
INTERFACE_COMPILE_DEFINITIONS property of ‘<target>’.  (see
IMPORTED targets only support ‘INTERFACE’ items.)  The following
arguments specify compile definitions.  Repeated calls for the same
‘<target>’ append items in the order called.

Arguments to ‘target_compile_definitions’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

Any leading ‘-D’ on an item will be removed.  Empty items are ignored.
For example, the following are all equivalent:

     target_compile_definitions(foo PUBLIC FOO)
     target_compile_definitions(foo PUBLIC -DFOO)  # -D removed
     target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
     target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored

7.2.37 target_compile_features
------------------------------

New in version 3.1.

Add expected compiler features to a target.

     target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])

Specifies compiler features required when compiling a given target.  If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or
CMAKE_CXX_COMPILE_FEATURES variables, then an error will be
reported by CMake.  If the use of the feature requires an additional
compiler flag, such as ‘-std=gnu++11’, the flag will be added
automatically.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the features.  ‘PRIVATE’ and ‘PUBLIC’ items will populate
the COMPILE_FEATURES property of ‘<target>’.  ‘PUBLIC’ and
‘INTERFACE’ items will populate the INTERFACE_COMPILE_FEATURES
property of ‘<target>’.  (see IMPORTED targets only support
‘INTERFACE’ items.)  Repeated calls for the same ‘<target>’ append
items.

The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

Arguments to ‘target_compile_features’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-compile-features(7) manual for information on compile
features and a list of supported compilers.

7.2.38 target_compile_options
-----------------------------

Add compile options to a target.

     target_compile_options(<target> [BEFORE]
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Adds options to the COMPILE_OPTIONS or
INTERFACE_COMPILE_OPTIONS target properties.  These options are
used when compiling the given ‘<target>’, which must have been created
by a command such as add_executable() or add_library()
and must not be an ALIAS target.

7.2.38.1 Arguments
..................

If ‘BEFORE’ is specified, the content will be prepended to the property
instead of being appended.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the following arguments.  ‘PRIVATE’ and ‘PUBLIC’ items will
populate the COMPILE_OPTIONS property of ‘<target>’.
‘PUBLIC’ and ‘INTERFACE’ items will populate the
INTERFACE_COMPILE_OPTIONS property of ‘<target>’.  (see IMPORTED targets
only support ‘INTERFACE’ items.)  The following arguments
specify compile options.  Repeated calls for the same ‘<target>’ append
items in the order called.

Arguments to ‘target_compile_options’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

The final set of compile or link options used for a target is
constructed by accumulating options from the current target and the
usage requirements of its dependencies.  The set of options is
de-duplicated to avoid repetition.  While beneficial for individual
options, the de-duplication step can break up option groups.  For
example, ‘-D A -D B’ becomes ‘-D A B’.  One may specify a group of
options using shell-like quoting along with a ‘SHELL:’ prefix.  The
‘SHELL:’ prefix is dropped, and the rest of the option string is parsed
using the separate_arguments(). ‘UNIX_COMMAND’ mode.  For
example, ‘"SHELL:-D A" "SHELL:-D B"’ becomes ‘-D A -D B’.

7.2.38.2 See Also
.................

This command can be used to add any options.  However, for adding
preprocessor definitions and include directories it is recommended to
use the more specific commands target_compile_definitions().
and target_include_directories().

For directory-wide settings, there is the command
add_compile_options().

For file-specific settings, there is the source file property
COMPILE_OPTIONS.

7.2.39 target_include_directories
---------------------------------

Add include directories to a target.

     target_include_directories(<target> [SYSTEM] [BEFORE]
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies include directories to use when compiling a given target.  The
named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

If ‘BEFORE’ is specified, the content will be prepended to the property
instead of being appended.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the following arguments.  ‘PRIVATE’ and ‘PUBLIC’ items will
populate the INCLUDE_DIRECTORIES property of ‘<target>’.
‘PUBLIC’ and ‘INTERFACE’ items will populate the
INTERFACE_INCLUDE_DIRECTORIES property of ‘<target>’.  (see
IMPORTED targets only support ‘INTERFACE’ items.)  The following
arguments specify include directories.

Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If ‘SYSTEM’ is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings, or
these fixed-install system files not being considered in dependency
calculations - see compiler docs).  If ‘SYSTEM’ is used together with
‘PUBLIC’ or ‘INTERFACE’, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
target property will be populated with the specified directories.

Arguments to ‘target_include_directories’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

Include directories usage requirements commonly differ between the
build-tree and the install-tree.  The ‘BUILD_INTERFACE’ and
‘INSTALL_INTERFACE’ generator expressions can be used to describe
separate usage requirements based on the usage location.  Relative paths
are allowed within the ‘INSTALL_INTERFACE’ expression and are
interpreted relative to the installation prefix.  For example:

     target_include_directories(mylib PUBLIC
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
       $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
     )

7.2.39.1 Creating Relocatable Packages
......................................

Note that it is not advisable to populate the ‘INSTALL_INTERFACE’ of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute
paths to the include directories of dependencies.  That would hard-code
into installed packages the include directory paths for dependencies `as
found on the machine the package was made on'.

The ‘INSTALL_INTERFACE’ of the INTERFACE_INCLUDE_DIRECTORIES.
is only suitable for specifying the required include directories for
headers provided with the target itself, not those provided by the
transitive dependencies listed in its INTERFACE_LINK_LIBRARIES
target property.  Those dependencies should themselves be targets
that specify their own header locations in
INTERFACE_INCLUDE_DIRECTORIES.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

7.2.40 target_link_directories
------------------------------

New in version 3.13.

Add link directories to a target.

     target_link_directories(<target> [BEFORE]
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies the paths in which the linker should search for libraries when
linking a given target.  Each item can be an absolute or relative path,
with the latter being interpreted as relative to the current source
directory.  These items will be added to the link command.

The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the items that follow them.  ‘PRIVATE’ and ‘PUBLIC’ items
will populate the LINK_DIRECTORIES property of ‘<target>’.
‘PUBLIC’ and ‘INTERFACE’ items will populate the
INTERFACE_LINK_DIRECTORIES property of ‘<target>’ (see IMPORTED targets
only support ‘INTERFACE’ items).  Each item specifies a
link directory and will be converted to an absolute path if necessary
before adding it to the relevant property.  Repeated calls for the same
‘<target>’ append items in the order called.

If ‘BEFORE’ is specified, the content will be prepended to the relevant
property instead of being appended.

Arguments to ‘target_link_directories’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

     Note: This command is rarely necessary and should be avoided where
     there are other choices.  Prefer to pass full absolute paths to
     libraries where possible, since this ensures the correct library
     will always be linked.  The find_library() command
     provides the full path, which can generally be used directly in
     calls to target_link_libraries().  Situations where a
     library search path may be needed include:

        - Project generators like Xcode where the user can switch target
          architecture at build time, but a full path to a library
          cannot be used because it only provides one architecture (i.e.
          it is not a universal binary).

        - Libraries may themselves have other private library
          dependencies that expect to be found via ‘RPATH’ mechanisms,
          but some linkers are not able to fully decode those paths
          (e.g.  due to the presence of things like ‘$ORIGIN’).

7.2.41 target_link_libraries
----------------------------

Specify libraries or flags to use when linking a given target and/or its
dependents.  Usage requirements from linked library targets
will be propagated.  Usage requirements of a target’s dependencies
affect compilation of its own sources.

7.2.41.1 Overview
.................

This command has several signatures as detailed in subsections below.
All of them have the general form

     target_link_libraries(<target> ... <item>... ...)

The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.  If policy CMP0079 is not set to
‘NEW’ then the target must have been created in the current directory.
Repeated calls for the same ‘<target>’ append items in the order called.

Each ‘<item>’ may be:

   * `A library target name': The generated link line will have the full
     path to the linkable library file associated with the target.  The
     buildsystem will have a dependency to re-link ‘<target>’ if the
     library file changes.

     The named target must be created by add_library() within
     the project or as an IMPORTED library.  If it is created
     within the project an ordering dependency will automatically be
     added in the build system to make sure the named library target is
     up-to-date before the ‘<target>’ links.

     If an imported library has the IMPORTED_NO_SONAME.
     target property set, CMake may ask the linker to search for the
     library instead of using the full path (e.g.  ‘/usr/lib/libfoo.so’
     becomes ‘-lfoo’).

     The full path to the target’s artifact will be quoted/escaped for
     the shell automatically.

   * `A full path to a library file': The generated link line will
     normally preserve the full path to the file.  The buildsystem will
     have a dependency to re-link ‘<target>’ if the library file
     changes.

     There are some cases where CMake may ask the linker to search for
     the library (e.g.  ‘/usr/lib/libfoo.so’ becomes ‘-lfoo’), such as
     when a shared library is detected to have no ‘SONAME’ field.  See
     policy CMP0060 for discussion of another case.

     If the library file is in a macOS framework, the ‘Headers’
     directory of the framework will also be processed as a usage requirement.
     This has the same effect as passing the
     framework directory as an include directory.

     On Visual Studio Generators for VS 2010 and above,
     library files ending in ‘.targets’ will be treated as MSBuild
     targets files and imported into generated project files.  This is
     not supported by other generators.

     The full path to the library file will be quoted/escaped for the
     shell automatically.

   * `A plain library name': The generated link line will ask the linker
     to search for the library (e.g.  ‘foo’ becomes ‘-lfoo’ or
     ‘foo.lib’).

     The library name/flag is treated as a command-line string fragment
     and will be used with no extra quoting or escaping.

   * `A link flag': Item names starting with ‘-’, but not ‘-l’ or
     ‘-framework’, are treated as linker flags.  Note that such flags
     will be treated like any other library link item for purposes of
     transitive dependencies, so they are generally safe to specify only
     as private link items that will not propagate to dependents.

     Link flags specified here are inserted into the link command in the
     same place as the link libraries.  This might not be correct,
     depending on the linker.  Use the LINK_OPTIONS target
     property or target_link_options() command to add link
     flags explicitly.  The flags will then be placed at the
     toolchain-defined flag position in the link command.

     The link flag is treated as a command-line string fragment and will
     be used with no extra quoting or escaping.

   * `A generator expression': A ‘$<...>’ generator expression
     may evaluate to any of the above items or to a
     semicolon-separated list of them.  If the ‘...’ contains any
     ‘;’ characters, e.g.  after evaluation of a ‘${list}’ variable, be
     sure to use an explicitly quoted argument ‘"$<...>"’ so that this
     command receives it as a single ‘<item>’.

     Additionally, a generator expression may be used as a fragment of
     any of the above items, e.g.  ‘foo$<1:_d>’.

     Note that generator expressions will not be used in OLD handling of
     policy CMP0003 or policy CMP0004.

   * A ‘debug’, ‘optimized’, or ‘general’ keyword immediately followed
     by another ‘<item>’.  The item following such a keyword will be
     used only for the corresponding build configuration.  The ‘debug’
     keyword corresponds to the ‘Debug’ configuration (or to
     configurations named in the DEBUG_CONFIGURATIONS global
     property if it is set).  The ‘optimized’ keyword corresponds to all
     other configurations.  The ‘general’ keyword corresponds to all
     configurations, and is purely optional.  Higher granularity may be
     achieved for per-configuration rules by creating and linking to
     IMPORTED library targets.  These keywords are
     interpreted immediately by this command and therefore have no
     special meaning when produced by a generator expression.

Items containing ‘::’, such as ‘Foo::Bar’, are assumed to be
IMPORTED or ALIAS library target names and will cause
an error if no such target exists.  See policy CMP0028.

See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

7.2.41.2 Libraries for a Target and/or its Dependents
.....................................................

     target_link_libraries(<target>
                           <PRIVATE|PUBLIC|INTERFACE> <item>...
                          [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

The ‘PUBLIC’, ‘PRIVATE’ and ‘INTERFACE’ keywords can be used to specify
both the link dependencies and the link interface in one command.
Libraries and targets following ‘PUBLIC’ are linked to, and are made
part of the link interface.  Libraries and targets following ‘PRIVATE’
are linked to, but are not made part of the link interface.  Libraries
following ‘INTERFACE’ are appended to the link interface and are not
used for linking ‘<target>’.

7.2.41.3 Libraries for both a Target and its Dependents
.......................................................

     target_link_libraries(<target> <item>...)

Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries linked
to this target will appear on the link line for the other target too.
This transitive “link interface” is stored in the
INTERFACE_LINK_LIBRARIES target property and may be overridden by
setting the property directly.  When CMP0022 is not set to
‘NEW’, transitive linking is built in but may be overridden by the
LINK_INTERFACE_LIBRARIES property.  Calls to other signatures of
this command may set the property making any libraries linked
exclusively by this signature private.

7.2.41.4 Libraries for a Target and/or its Dependents (Legacy)
..............................................................

     target_link_libraries(<target>
                           <LINK_PRIVATE|LINK_PUBLIC> <lib>...
                          [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)

The ‘LINK_PUBLIC’ and ‘LINK_PRIVATE’ modes can be used to specify both
the link dependencies and the link interface in one command.

This signature is for compatibility only.  Prefer the ‘PUBLIC’ or
‘PRIVATE’ keywords instead.

Libraries and targets following ‘LINK_PUBLIC’ are linked to, and are
made part of the INTERFACE_LINK_LIBRARIES.  If policy
CMP0022 is not ‘NEW’, they are also made part of the
LINK_INTERFACE_LIBRARIES.  Libraries and targets following
‘LINK_PRIVATE’ are linked to, but are not made part of the
INTERFACE_LINK_LIBRARIES. (or LINK_INTERFACE_LIBRARIES).

7.2.41.5 Libraries for Dependents Only (Legacy)
...............................................

     target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)

The ‘LINK_INTERFACE_LIBRARIES’ mode appends the libraries to the
INTERFACE_LINK_LIBRARIES target property instead of using them for
linking.  If policy CMP0022 is not ‘NEW’, then this mode
also appends libraries to the LINK_INTERFACE_LIBRARIES and
its per-configuration equivalent.

This signature is for compatibility only.  Prefer the ‘INTERFACE’ mode
instead.

Libraries specified as ‘debug’ are wrapped in a generator expression to
correspond to debug builds.  If policy CMP0022 is not ‘NEW’,
the libraries are also appended to the
LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties
corresponding to configurations listed in the
DEBUG_CONFIGURATIONS global property if it is set).  Libraries
specified as ‘optimized’ are appended to the
INTERFACE_LINK_LIBRARIES property.  If policy CMP0022.
is not ‘NEW’, they are also appended to the
LINK_INTERFACE_LIBRARIES property.  Libraries specified as
‘general’ (or without any keyword) are treated as if specified for both
‘debug’ and ‘optimized’.

7.2.41.6 Linking Object Libraries
.................................

Object Libraries may be used as the ‘<target>’ (first)
argument of ‘target_link_libraries’ to specify dependencies of their
sources on other libraries.  For example, the code

     add_library(A SHARED a.c)
     target_compile_definitions(A PUBLIC A)

     add_library(obj OBJECT obj.c)
     target_compile_definitions(obj PUBLIC OBJ)
     target_link_libraries(obj PUBLIC A)

compiles ‘obj.c’ with ‘-DA -DOBJ’ and establishes usage requirements for
‘obj’ that propagate to its dependents.

Normal libraries and executables may link to Object Libraries.
to get their objects and usage requirements.  Continuing the above
example, the code

     add_library(B SHARED b.c)
     target_link_libraries(B PUBLIC obj)

compiles ‘b.c’ with ‘-DA -DOBJ’, creates shared library ‘B’ with object
files from ‘b.c’ and ‘obj.c’, and links ‘B’ to ‘A’.  Furthermore, the
code

     add_executable(main main.c)
     target_link_libraries(main B)

compiles ‘main.c’ with ‘-DA -DOBJ’ and links executable ‘main’ to ‘B’
and ‘A’.  The object library’s usage requirements are propagated
transitively through ‘B’, but its object files are not.

Object Libraries may “link” to other object libraries to get
usage requirements, but since they do not have a link step nothing is
done with their object files.  Continuing from the above example, the
code:

     add_library(obj2 OBJECT obj2.c)
     target_link_libraries(obj2 PUBLIC obj)

     add_executable(main2 main2.c)
     target_link_libraries(main2 obj2)

compiles ‘obj2.c’ with ‘-DA -DOBJ’, creates executable ‘main2’ with
object files from ‘main2.c’ and ‘obj2.c’, and links ‘main2’ to ‘A’.

In other words, when Object Libraries appear in a target’s
INTERFACE_LINK_LIBRARIES property they will be treated as
Interface Libraries, but when they appear in a target’s
LINK_LIBRARIES property their object files will be included in the
link too.

7.2.41.7 Cyclic Dependencies of Static Libraries
................................................

The library dependency graph is normally acyclic (a DAG), but in the
case of mutually-dependent ‘STATIC’ libraries CMake allows the graph to
contain cycles (strongly connected components).  When another target
links to one of the libraries, CMake repeats the entire connected
component.  For example, the code

     add_library(A STATIC a.c)
     add_library(B STATIC b.c)
     target_link_libraries(A B)
     target_link_libraries(B A)
     add_executable(main main.c)
     target_link_libraries(main A)

links ‘main’ to ‘A B A B’.  While one repetition is usually sufficient,
pathological object file and symbol arrangements can require more.  One
may handle such cases by using the LINK_INTERFACE_MULTIPLICITY
target property or by manually repeating the component in the last
‘target_link_libraries’ call.  However, if two archives are really so
interdependent they should probably be combined into a single archive,
perhaps by using Object Libraries.

7.2.41.8 Creating Relocatable Packages
......................................

Note that it is not advisable to populate the
INTERFACE_LINK_LIBRARIES of a target with absolute paths to
dependencies.  That would hard-code into installed packages the library
file paths for dependencies `as found on the machine the package was
made on'.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

7.2.42 target_link_options
--------------------------

New in version 3.13.

Add options to the link step for an executable, shared library or module
library target.

     target_link_options(<target> [BEFORE]
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

This command can be used to add any link options, but alternative
commands exist to add libraries ( see target_link_libraries() or
link_libraries()).  See documentation of the
directory and target. ‘LINK_OPTIONS’ properties.

     Note: This command cannot be used to add options for static library
     targets, since they do not use a linker.  To add archiver or MSVC
     librarian flags, see the STATIC_LIBRARY_OPTIONS target
     property.

If ‘BEFORE’ is specified, the content will be prepended to the property
instead of being appended.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the following arguments.  ‘PRIVATE’ and ‘PUBLIC’ items will
populate the LINK_OPTIONS property of ‘<target>’.  ‘PUBLIC’
and ‘INTERFACE’ items will populate the INTERFACE_LINK_OPTIONS
property of ‘<target>’.  (see IMPORTED targets only support
‘INTERFACE’ items.)  The following arguments specify link options.
Repeated calls for the same ‘<target>’ append items in the order called.

Arguments to ‘target_link_options’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

When a device link step is involved, which is controlled by
CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
properties and policy CMP0105, the raw options will be
delivered to the host and device link steps (wrapped in ‘-Xcompiler’ or
equivalent for device link).  Options wrapped with ‘$<DEVICE_LINK:...>’
generator expression will be used only for the device link
step.  Options wrapped with ‘$<HOST_LINK:...>’ generator expression
will be used only for the host link step.

The final set of compile or link options used for a target is
constructed by accumulating options from the current target and the
usage requirements of its dependencies.  The set of options is
de-duplicated to avoid repetition.  While beneficial for individual
options, the de-duplication step can break up option groups.  For
example, ‘-D A -D B’ becomes ‘-D A B’.  One may specify a group of
options using shell-like quoting along with a ‘SHELL:’ prefix.  The
‘SHELL:’ prefix is dropped, and the rest of the option string is parsed
using the separate_arguments(). ‘UNIX_COMMAND’ mode.  For
example, ‘"SHELL:-D A" "SHELL:-D B"’ becomes ‘-D A -D B’.

To pass options to the linker tool, each compiler driver has its own
syntax.  The ‘LINKER:’ prefix and ‘,’ separator can be used to specify,
in a portable way, options to pass to the linker tool.  ‘LINKER:’ is
replaced by the appropriate driver option and ‘,’ by the appropriate
driver separator.  The driver prefix and driver separator are given by
the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, ‘"LINKER:-z,defs"’ becomes ‘-Xlinker -z -Xlinker defs’ for
‘Clang’ and ‘-Wl,-z,defs’ for ‘GNU GCC’.

The ‘LINKER:’ prefix can be specified as part of a ‘SHELL:’ prefix
expression.

The ‘LINKER:’ prefix supports, as an alternative syntax, specification
of arguments using the ‘SHELL:’ prefix and space as separator.  The
previous example then becomes ‘"LINKER:SHELL:-z defs"’.

     Note: Specifying the ‘SHELL:’ prefix anywhere other than at the
     beginning of the ‘LINKER:’ prefix is not supported.

7.2.43 target_precompile_headers
--------------------------------

New in version 3.16.

Add a list of header files to precompile.

Precompiling header files can speed up compilation by creating a
partially processed version of some header files, and then using that
version during compilations rather than repeatedly parsing the original
headers.

7.2.43.1 Main Form
..................

     target_precompile_headers(<target>
       <INTERFACE|PUBLIC|PRIVATE> [header1...]
       [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])

The command adds header files to the PRECOMPILE_HEADERS.
and/or INTERFACE_PRECOMPILE_HEADERS target properties of
‘<target>’.  The named ‘<target>’ must have been created by a command
such as add_executable() or add_library() and must
not be an ALIAS target.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the following arguments.  ‘PRIVATE’ and ‘PUBLIC’ items will
populate the PRECOMPILE_HEADERS property of ‘<target>’.
‘PUBLIC’ and ‘INTERFACE’ items will populate the
INTERFACE_PRECOMPILE_HEADERS property of ‘<target>’ (see
IMPORTED targets only support ‘INTERFACE’ items).  Repeated calls
for the same ‘<target>’ will append items in the order called.

Projects should generally avoid using ‘PUBLIC’ or ‘INTERFACE’ for
targets that will be exported, or they should at least use
the ‘$<BUILD_INTERFACE:...>’ generator expression to prevent precompile
headers from appearing in an installed exported target.  Consumers of a
target should typically be in control of what precompile headers they
use, not have precompile headers forced on them by the targets being
consumed (since precompile headers are not typically usage
requirements).  A notable exception to this is where an interface library
is created to define a commonly used set of precompile
headers in one place and then other targets link to that interface
library privately.  In this case, the interface library exists
specifically to propagate the precompile headers to its consumers and
the consumer is effectively still in control, since it decides whether
to link to the interface library or not.

The list of header files is used to generate a header file named
‘cmake_pch.h|xx’ which is used to generate the precompiled header file
(‘.pch’, ‘.gch’, ‘.pchi’) artifact.  The ‘cmake_pch.h|xx’ header file
will be force included (‘-include’ for GCC, ‘/FI’ for MSVC) to all
source files, so sources do not need to have ‘#include "pch.h"’.

Header file names specified with angle brackets (e.g.
‘<unordered_map>’) or explicit double quotes (escaped for the
cmake-language(7), e.g.  ‘[["other_header.h"]]’) will be treated as
is, and include directories must be available for the compiler to find
them.  Other header file names (e.g.  ‘project_header.h’) are
interpreted as being relative to the current source directory (e.g.
see CMAKE_CURRENT_SOURCE_DIR) and will be included by absolute
path.  For example:

     target_precompile_headers(myTarget
       PUBLIC
         project_header.h
       PRIVATE
         [["other_header.h"]]
         <unordered_map>
     )

Arguments to ‘target_precompile_headers()’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
The ‘$<COMPILE_LANGUAGE:...>’ generator expression is particularly
useful for specifying a language-specific header to precompile for only
one language (e.g.  ‘CXX’ and not ‘C’).  In this case, header file names
that are not explicitly in double quotes or angle brackets must be
specified by absolute path.  Also, when specifying angle brackets inside
a generator expression, be sure to encode the closing ‘>’ as
‘$<ANGLE-R>’.  For example:

     target_precompile_headers(mylib PRIVATE
       "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
       "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
       "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
     )

7.2.43.2 Reusing Precompile Headers
...................................

The command also supports a second signature which can be used to
specify that one target re-uses a precompiled header file artifact from
another target instead of generating its own:

     target_precompile_headers(<target> REUSE_FROM <other_target>)

This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
‘<other_target>’ and adds a dependency such that ‘<target>’ will depend
on ‘<other_target>’.  CMake will halt with an error if the
PRECOMPILE_HEADERS property of ‘<target>’ is already set when the
‘REUSE_FROM’ form is used.

     Note: The ‘REUSE_FROM’ form requires the same set of compiler
     options, compiler flags and compiler definitions for both
     ‘<target>’ and ‘<other_target>’.  Some compilers (e.g.  GCC) may
     issue a warning if the precompiled header file cannot be used
     (‘-Winvalid-pch’).

7.2.43.3 See Also
.................

To disable precompile headers for specific targets, see the
DISABLE_PRECOMPILE_HEADERS target property.

To prevent precompile headers from being used when compiling a specific
source file, see the SKIP_PRECOMPILE_HEADERS source file
property.

7.2.44 target_sources
---------------------

New in version 3.1.

Add sources to a target.

     target_sources(<target>
       <INTERFACE|PUBLIC|PRIVATE> [items1...]
       [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies sources to use when building a target and/or its dependents.
Relative source file paths are interpreted as being relative to the
current source directory (i.e.  see CMAKE_CURRENT_SOURCE_DIR).
The named ‘<target>’ must have been created by a command such as
add_executable() or add_library() and must not be an
ALIAS target.

The ‘INTERFACE’, ‘PUBLIC’ and ‘PRIVATE’ keywords are required to specify
the scope of the items following them.  ‘PRIVATE’ and ‘PUBLIC’ items
will populate the SOURCES property of ‘<target>’, which are
used when building the target itself.  ‘PUBLIC’ and ‘INTERFACE’ items
will populate the INTERFACE_SOURCES property of ‘<target>’,
which are used when building dependents.  (see IMPORTED targets.
only support ‘INTERFACE’ items because they are not build targets.)  The
following arguments specify sources.  Repeated calls for the same
‘<target>’ append items in the order called.

Arguments to ‘target_sources’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

See also the CMP0076 policy for older behavior related to
the handling of relative source file paths.

7.2.45 try_compile
------------------

Try building some code.

7.2.45.1 Try Compiling Whole Projects
.....................................

     try_compile(<resultVar> <bindir> <srcdir>
                 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
                 [OUTPUT_VARIABLE <var>])

Try building a project.  The success or failure of the ‘try_compile’,
i.e.  ‘TRUE’ or ‘FALSE’ respectively, is returned in ‘<resultVar>’.

In this form, ‘<srcdir>’ should contain a complete CMake project with a
‘CMakeLists.txt’ file and all sources.  The ‘<bindir>’ and ‘<srcdir>’
will not be deleted after this command is run.  Specify ‘<targetName>’
to build a specific target instead of the ‘all’ or ‘ALL_BUILD’ target.
See below for the meaning of other options.

7.2.45.2 Try Compiling Source Files
...................................

     try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
                 [CMAKE_FLAGS <flags>...]
                 [COMPILE_DEFINITIONS <defs>...]
                 [LINK_OPTIONS <options>...]
                 [LINK_LIBRARIES <libs>...]
                 [OUTPUT_VARIABLE <var>]
                 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
                 [<LANG>_STANDARD <std>]
                 [<LANG>_STANDARD_REQUIRED <bool>]
                 [<LANG>_EXTENSIONS <bool>]
                 )

Try building an executable or static library from one or more source
files (which one is determined by the
CMAKE_TRY_COMPILE_TARGET_TYPE variable).  The success or failure
of the ‘try_compile’, i.e.  ‘TRUE’ or ‘FALSE’ respectively, is returned
in ‘<resultVar>’.

In this form, one or more source files must be provided.  If
CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to ‘EXECUTABLE’,
the sources must include a definition for ‘main’ and CMake will create a
‘CMakeLists.txt’ file to build the source(s) as an executable.  If
CMAKE_TRY_COMPILE_TARGET_TYPE is set to ‘STATIC_LIBRARY’, a static
library will be built instead and no definition for ‘main’ is required.
For an executable, the generated ‘CMakeLists.txt’ file would contain
something like the following:

     add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
     include_directories(${INCLUDE_DIRECTORIES})
     link_directories(${LINK_DIRECTORIES})
     add_executable(cmTryCompileExec <srcfile>...)
     target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
     target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

The options are:

‘CMAKE_FLAGS <flags>...’

     Specify flags of the form ‘-DVAR:TYPE=VALUE’ to be passed to the
     ‘cmake’ command-line used to drive the test build.  The above
     example shows how values for variables ‘INCLUDE_DIRECTORIES’,
     ‘LINK_DIRECTORIES’, and ‘LINK_LIBRARIES’ are used.

‘COMPILE_DEFINITIONS <defs>...’

     Specify ‘-Ddefinition’ arguments to pass to
     add_definitions() in the generated test project.

‘COPY_FILE <fileName>’

     Copy the built executable or static library to the given
     ‘<fileName>’.

‘COPY_FILE_ERROR <var>’

     Use after ‘COPY_FILE’ to capture into variable ‘<var>’ any error
     message encountered while trying to copy the file.

‘LINK_LIBRARIES <libs>...’

     Specify libraries to be linked in the generated project.  The list
     of libraries may refer to system libraries and to Imported Targets
     from the calling project.

     If this option is specified, any ‘-DLINK_LIBRARIES=...’ value given
     to the ‘CMAKE_FLAGS’ option will be ignored.

‘LINK_OPTIONS <options>...’

     Specify link step options to pass to target_link_options()
     or to set the STATIC_LIBRARY_OPTIONS target
     property in the generated project, depending on the
     CMAKE_TRY_COMPILE_TARGET_TYPE variable.

‘OUTPUT_VARIABLE <var>’

     Store the output from the build process in the given variable.

‘<LANG>_STANDARD <std>’

     Specify the C_STANDARD, CXX_STANDARD,
     OBJC_STANDARD, OBJCXX_STANDARD, or
     CUDA_STANDARD target property of the generated project.

‘<LANG>_STANDARD_REQUIRED <bool>’

     Specify the C_STANDARD_REQUIRED,
     CXX_STANDARD_REQUIRED, OBJC_STANDARD_REQUIRED,
     OBJCXX_STANDARD_REQUIRED,or
     CUDA_STANDARD_REQUIRED target property of the generated
     project.

‘<LANG>_EXTENSIONS <bool>’

     Specify the C_EXTENSIONS, CXX_EXTENSIONS,
     OBJC_EXTENSIONS, OBJCXX_EXTENSIONS, or
     CUDA_EXTENSIONS target property of the generated project.

In this version all files in ‘<bindir>/CMakeFiles/CMakeTmp’ will be
cleaned automatically.  For debugging, ‘--debug-trycompile’ can be
passed to ‘cmake’ to avoid this clean.  However, multiple sequential
‘try_compile’ operations reuse this single output directory.  If you use
‘--debug-trycompile’, you can only debug one ‘try_compile’ call at a
time.  The recommended procedure is to protect all ‘try_compile’ calls
in your project by ‘if(NOT DEFINED <resultVar>)’ logic, configure with
cmake all the way through once, then delete the cache entry associated
with the try_compile call of interest, and then re-run cmake again with
‘--debug-trycompile’.

7.2.45.3 Other Behavior Settings
................................

If set, the following variables are passed in to the generated
try_compile CMakeLists.txt to initialize compile target properties with
default values:

   * CMAKE_CUDA_RUNTIME_LIBRARY.

   * CMAKE_ENABLE_EXPORTS.

   * CMAKE_LINK_SEARCH_START_STATIC.

   * CMAKE_LINK_SEARCH_END_STATIC.

   * CMAKE_MSVC_RUNTIME_LIBRARY.

   * CMAKE_POSITION_INDEPENDENT_CODE.

If CMP0056 is set to ‘NEW’, then
CMAKE_EXE_LINKER_FLAGS is passed in as well.

If CMP0083 is set to ‘NEW’, then in order to obtain correct
behavior at link time, the ‘check_pie_supported()’ command from the
CheckPIESupported module must be called before using the
try_compile() command.

The current settings of CMP0065 and CMP0083 are
propagated through to the generated test project.

Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a
build configuration.

Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify
the type of target used for the source file signature.

Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to
specify variables that must be propagated into the test project.  This
variable is meant for use only in toolchain files and is only honored by
the ‘try_compile()’ command for the source files form, not when given a
whole project.

If CMP0067 is set to ‘NEW’, or any of the ‘<LANG>_STANDARD’,
‘<LANG>_STANDARD_REQUIRED’, or ‘<LANG>_EXTENSIONS’ options are used,
then the language standard variables are honored:

   * CMAKE_C_STANDARD.

   * CMAKE_C_STANDARD_REQUIRED.

   * CMAKE_C_EXTENSIONS.

   * CMAKE_CXX_STANDARD.

   * CMAKE_CXX_STANDARD_REQUIRED.

   * CMAKE_CXX_EXTENSIONS.

   * CMAKE_OBJC_STANDARD.

   * CMAKE_OBJC_STANDARD_REQUIRED.

   * CMAKE_OBJC_EXTENSIONS.

   * CMAKE_OBJCXX_STANDARD.

   * CMAKE_OBJCXX_STANDARD_REQUIRED.

   * CMAKE_OBJCXX_EXTENSIONS.

   * CMAKE_CUDA_STANDARD.

   * CMAKE_CUDA_STANDARD_REQUIRED.

   * CMAKE_CUDA_EXTENSIONS.

Their values are used to set the corresponding target properties in the
generated project (unless overridden by an explicit option).

For the Green Hills MULTI generator the GHS toolset and
target system customization cache variables are also propagated into the
test project.

7.2.46 try_run
--------------

Try compiling and then running some code.

7.2.46.1 Try Compiling and Running Source Files
...............................................

     try_run(<runResultVar> <compileResultVar>
             <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
             [COMPILE_DEFINITIONS <defs>...]
             [LINK_OPTIONS <options>...]
             [LINK_LIBRARIES <libs>...]
             [COMPILE_OUTPUT_VARIABLE <var>]
             [RUN_OUTPUT_VARIABLE <var>]
             [OUTPUT_VARIABLE <var>]
             [ARGS <args>...])

Try compiling a ‘<srcfile>’.  Returns ‘TRUE’ or ‘FALSE’ for success or
failure in ‘<compileResultVar>’.  If the compile succeeded, runs the
executable and returns its exit code in ‘<runResultVar>’.  If the
executable was built, but failed to run, then ‘<runResultVar>’ will be
set to ‘FAILED_TO_RUN’.  See the try_compile() command for
information on how the test project is constructed to build the source
file.

The options are:

‘CMAKE_FLAGS <flags>...’

     Specify flags of the form ‘-DVAR:TYPE=VALUE’ to be passed to the
     ‘cmake’ command-line used to drive the test build.  The example in
     try_compile() shows how values for variables
     ‘INCLUDE_DIRECTORIES’, ‘LINK_DIRECTORIES’, and ‘LINK_LIBRARIES’ are
     used.

‘COMPILE_DEFINITIONS <defs>...’

     Specify ‘-Ddefinition’ arguments to pass to
     add_definitions() in the generated test project.

‘COMPILE_OUTPUT_VARIABLE <var>’

     Report the compile step build output in a given variable.

‘LINK_LIBRARIES <libs>...’

     Specify libraries to be linked in the generated project.  The list
     of libraries may refer to system libraries and to Imported Targets
     from the calling project.

     If this option is specified, any ‘-DLINK_LIBRARIES=...’ value given
     to the ‘CMAKE_FLAGS’ option will be ignored.

‘LINK_OPTIONS <options>...’

     Specify link step options to pass to target_link_options()
     in the generated project.

‘OUTPUT_VARIABLE <var>’

     Report the compile build output and the output from running the
     executable in the given variable.  This option exists for legacy
     reasons.  Prefer ‘COMPILE_OUTPUT_VARIABLE’ and
     ‘RUN_OUTPUT_VARIABLE’ instead.

‘RUN_OUTPUT_VARIABLE <var>’

     Report the output from running the executable in a given variable.

7.2.46.2 Other Behavior Settings
................................

Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a
build configuration.

7.2.46.3 Behavior when Cross Compiling
......................................

When cross compiling, the executable compiled in the first step usually
cannot be run on the build host.  The ‘try_run’ command checks the
CMAKE_CROSSCOMPILING variable to detect whether CMake is in
cross-compiling mode.  If that is the case, it will still try to compile
the executable, but it will not try to run the executable unless the
CMAKE_CROSSCOMPILING_EMULATOR variable is set.  Instead it
will create cache variables which must be filled by the user or by
presetting them in some CMake script file to the values the executable
would have produced if it had been run on its actual target platform.
These cache entries are:

‘<runResultVar>’

     Exit code if the executable were to be run on the target platform.

‘<runResultVar>__TRYRUN_OUTPUT’

     Output from stdout and stderr if the executable were to be run on
     the target platform.  This is created only if the
     ‘RUN_OUTPUT_VARIABLE’ or ‘OUTPUT_VARIABLE’ option was used.

In order to make cross compiling your project easier, use ‘try_run’ only
if really required.  If you use ‘try_run’, use the ‘RUN_OUTPUT_VARIABLE’
or ‘OUTPUT_VARIABLE’ options only if really required.  Using them will
require that when cross-compiling, the cache variables will have to be
set manually to the output of the executable.  You can also “guard” the
calls to ‘try_run’ with an if() block checking the
CMAKE_CROSSCOMPILING variable and provide an easy-to-preset
alternative for this case.

7.3 CTest Commands
==================

These commands are available only in CTest scripts.

7.3.1 ctest_build
-----------------

Perform the CTest Build Step as a Dashboard Client.

     ctest_build([BUILD <build-dir>] [APPEND]
                 [CONFIGURATION <config>]
                 [FLAGS <flags>]
                 [PROJECT_NAME <project-name>]
                 [TARGET <target-name>]
                 [NUMBER_ERRORS <num-err-var>]
                 [NUMBER_WARNINGS <num-warn-var>]
                 [RETURN_VALUE <result-var>]
                 [CAPTURE_CMAKE_ERROR <result-var>]
                 )

Build the project and store results in ‘Build.xml’ for submission with
the ctest_submit() command.

The CTEST_BUILD_COMMAND variable may be set to explicitly
specify the build command line.  Otherwise the build command line is
computed automatically based on the options given.

The options are:

‘BUILD <build-dir>’

     Specify the top-level build directory.  If not given, the
     CTEST_BINARY_DIRECTORY variable is used.

‘APPEND’

     Mark ‘Build.xml’ for append to results previously submitted to a
     dashboard server since the last ctest_start() call.
     Append semantics are defined by the dashboard server in use.  This
     does `not' cause results to be appended to a ‘.xml’ file produced
     by a previous call to this command.

‘CONFIGURATION <config>’

     Specify the build configuration (e.g.  ‘Debug’).  If not specified
     the ‘CTEST_BUILD_CONFIGURATION’ variable will be checked.
     Otherwise the ‘-C <cfg>’ option given to the ctest(1).
     command will be used, if any.

‘FLAGS <flags>’

     Pass additional arguments to the underlying build command.  If not
     specified the ‘CTEST_BUILD_FLAGS’ variable will be checked.  This
     can, e.g., be used to trigger a parallel build using the ‘-j’
     option of make.  See the ProcessorCount module for an
     example.

‘PROJECT_NAME <project-name>’

     Ignored.  This was once used but is no longer needed.

‘TARGET <target-name>’

     Specify the name of a target to build.  If not specified the
     ‘CTEST_BUILD_TARGET’ variable will be checked.  Otherwise the
     default target will be built.  This is the “all” target (called
     ‘ALL_BUILD’ in Visual Studio Generators).

‘NUMBER_ERRORS <num-err-var>’

     Store the number of build errors detected in the given variable.

‘NUMBER_WARNINGS <num-warn-var>’

     Store the number of build warnings detected in the given variable.

‘RETURN_VALUE <result-var>’

     Store the return value of the native build tool in the given
     variable.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Suppress any CTest-specific non-error output that would have been
     printed to the console otherwise.  The summary of warnings /
     errors, as well as the output from the native build tool is
     unaffected by this option.

7.3.2 ctest_configure
---------------------

Perform the CTest Configure Step as a Dashboard Client.

     ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
                     [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
                     [CAPTURE_CMAKE_ERROR <result-var>])

Configure the project build tree and record results in ‘Configure.xml’
for submission with the ctest_submit() command.

The options are:

‘BUILD <build-dir>’

     Specify the top-level build directory.  If not given, the
     CTEST_BINARY_DIRECTORY variable is used.

‘SOURCE <source-dir>’

     Specify the source directory.  If not given, the
     CTEST_SOURCE_DIRECTORY variable is used.

‘APPEND’

     Mark ‘Configure.xml’ for append to results previously submitted to
     a dashboard server since the last ctest_start() call.
     Append semantics are defined by the dashboard server in use.  This
     does `not' cause results to be appended to a ‘.xml’ file produced
     by a previous call to this command.

‘OPTIONS <options>’

     Specify command-line arguments to pass to the configuration tool.

‘RETURN_VALUE <result-var>’

     Store in the ‘<result-var>’ variable the return value of the native
     configuration tool.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Suppress any CTest-specific non-error messages that would have
     otherwise been printed to the console.  Output from the underlying
     configure command is not affected.

7.3.3 ctest_coverage
--------------------

Perform the CTest Coverage Step as a Dashboard Client.

     ctest_coverage([BUILD <build-dir>] [APPEND]
                    [LABELS <label>...]
                    [RETURN_VALUE <result-var>]
                    [CAPTURE_CMAKE_ERROR <result-var>]
                    [QUIET]
                    )

Collect coverage tool results and stores them in ‘Coverage.xml’ for
submission with the ctest_submit() command.

The options are:

‘BUILD <build-dir>’

     Specify the top-level build directory.  If not given, the
     CTEST_BINARY_DIRECTORY variable is used.

‘APPEND’

     Mark ‘Coverage.xml’ for append to results previously submitted to a
     dashboard server since the last ctest_start() call.
     Append semantics are defined by the dashboard server in use.  This
     does `not' cause results to be appended to a ‘.xml’ file produced
     by a previous call to this command.

‘LABELS’

     Filter the coverage report to include only source files labeled
     with at least one of the labels specified.

‘RETURN_VALUE <result-var>’

     Store in the ‘<result-var>’ variable ‘0’ if coverage tools ran
     without error and non-zero otherwise.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Suppress any CTest-specific non-error output that would have been
     printed to the console otherwise.  The summary indicating how many
     lines of code were covered is unaffected by this option.

7.3.4 ctest_empty_binary_directory
----------------------------------

empties the binary directory

     ctest_empty_binary_directory( directory )

Removes a binary directory.  This command will perform some checks prior
to deleting the directory in an attempt to avoid malicious or accidental
directory deletion.

7.3.5 ctest_memcheck
--------------------

Perform the CTest MemCheck Step as a Dashboard Client.

     ctest_memcheck([BUILD <build-dir>] [APPEND]
                    [START <start-number>]
                    [END <end-number>]
                    [STRIDE <stride-number>]
                    [EXCLUDE <exclude-regex>]
                    [INCLUDE <include-regex>]
                    [EXCLUDE_LABEL <label-exclude-regex>]
                    [INCLUDE_LABEL <label-include-regex>]
                    [EXCLUDE_FIXTURE <regex>]
                    [EXCLUDE_FIXTURE_SETUP <regex>]
                    [EXCLUDE_FIXTURE_CLEANUP <regex>]
                    [PARALLEL_LEVEL <level>]
                    [TEST_LOAD <threshold>]
                    [SCHEDULE_RANDOM <ON|OFF>]
                    [STOP_TIME <time-of-day>]
                    [RETURN_VALUE <result-var>]
                    [DEFECT_COUNT <defect-count-var>]
                    [QUIET]
                    )

Run tests with a dynamic analysis tool and store results in
‘MemCheck.xml’ for submission with the ctest_submit().
command.

Most options are the same as those for the ctest_test().
command.

The options unique to this command are:

‘DEFECT_COUNT <defect-count-var>’

     Store in the ‘<defect-count-var>’ the number of defects found.

7.3.6 ctest_read_custom_files
-----------------------------

read CTestCustom files.

     ctest_read_custom_files( directory ... )

Read all the CTestCustom.ctest or CTestCustom.cmake files from the given
directory.

By default, invoking ctest(1) without a script will read
custom files from the binary directory.

7.3.7 ctest_run_script
----------------------

runs a ctest -S script

     ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
                 script_file_name2 ... [RETURN_VALUE var])

Runs a script or scripts much like if it was run from ctest -S. If no
argument is provided then the current script is run using the current
settings of the variables.  If ‘NEW_PROCESS’ is specified then each
script will be run in a separate process.If ‘RETURN_VALUE’ is specified
the return value of the last script run will be put into ‘var’.

7.3.8 ctest_sleep
-----------------

sleeps for some amount of time

     ctest_sleep(<seconds>)

Sleep for given number of seconds.

     ctest_sleep(<time1> <duration> <time2>)

Sleep for t=(time1 + duration - time2) seconds if t > 0.

7.3.9 ctest_start
-----------------

Starts the testing for a given model

     ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])

     ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])

Starts the testing for a given model.  The command should be called
after the binary directory is initialized.

The parameters are as follows:

‘<model>’

     Set the dashboard model.  Must be one of ‘Experimental’,
     ‘Continuous’, or ‘Nightly’.  This parameter is required unless
     ‘APPEND’ is specified.

‘<source>’

     Set the source directory.  If not specified, the value of
     CTEST_SOURCE_DIRECTORY is used instead.

‘<binary>’

     Set the binary directory.  If not specified, the value of
     CTEST_BINARY_DIRECTORY is used instead.

‘GROUP <group>’

     If ‘GROUP’ is used, the submissions will go to the specified group
     on the CDash server.  If no ‘GROUP’ is specified, the name of the
     model is used by default.  This replaces the deprecated option
     ‘TRACK’.  Despite the name change its behavior is unchanged.

‘APPEND’

     If ‘APPEND’ is used, the existing ‘TAG’ is used rather than
     creating a new one based on the current time stamp.  If you use
     ‘APPEND’, you can omit the ‘<model>’ and ‘GROUP <group>’
     parameters, because they will be read from the generated ‘TAG’
     file.  For example:

          ctest_start(Experimental GROUP GroupExperimental)

     Later, in another ‘ctest -S’ script:

          ctest_start(APPEND)

     When the second script runs ‘ctest_start(APPEND)’, it will read the
     ‘Experimental’ model and ‘GroupExperimental’ group from the ‘TAG’
     file generated by the first ‘ctest_start()’ command.  Please note
     that if you call ‘ctest_start(APPEND)’ and specify a different
     model or group than in the first ‘ctest_start()’ command, a warning
     will be issued, and the new model and group will be used.

‘QUIET’

     If ‘QUIET’ is used, CTest will suppress any non-error messages that
     it otherwise would have printed to the console.

The parameters for ‘ctest_start()’ can be issued in any order, with the
exception that ‘<model>’, ‘<source>’, and ‘<binary>’ have to appear in
that order with respect to each other.  The following are all valid and
equivalent:

     ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)

     ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)

     ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)

However, for the sake of readability, it is recommended that you order
your parameters in the order listed at the top of this page.

If the CTEST_CHECKOUT_COMMAND variable (or the
CTEST_CVS_CHECKOUT variable) is set, its content is treated as
command-line.  The command is invoked with the current working directory
set to the parent of the source directory, even if the source directory
already exists.  This can be used to create the source tree from a
version control repository.

7.3.10 ctest_submit
-------------------

Perform the CTest Submit Step as a Dashboard Client.

     ctest_submit([PARTS <part>...] [FILES <file>...]
                  [SUBMIT_URL <url>]
                  [BUILD_ID <result-var>]
                  [HTTPHEADER <header>]
                  [RETRY_COUNT <count>]
                  [RETRY_DELAY <delay>]
                  [RETURN_VALUE <result-var>]
                  [CAPTURE_CMAKE_ERROR <result-var>]
                  [QUIET]
                  )

Submit results to a dashboard server.  By default all available parts
are submitted.

The options are:

‘PARTS <part>...’

     Specify a subset of parts to submit.  Valid part names are:

          Start      = nothing
          Update     = ctest_update results, in Update.xml
          Configure  = ctest_configure results, in Configure.xml
          Build      = ctest_build results, in Build.xml
          Test       = ctest_test results, in Test.xml
          Coverage   = ctest_coverage results, in Coverage.xml
          MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
          Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
          ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
          Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
          Submit     = nothing
          Done       = Build is complete, in Done.xml

‘FILES <file>...’

     Specify an explicit list of specific files to be submitted.  Each
     individual file must exist at the time of the call.

‘SUBMIT_URL <url>’

     The ‘http’ or ‘https’ URL of the dashboard server to send the
     submission to.  If not given, the CTEST_SUBMIT_URL.
     variable is used.

‘BUILD_ID <result-var>’

     Store in the ‘<result-var>’ variable the ID assigned to this build
     by CDash.

‘HTTPHEADER <HTTP-header>’

     Specify HTTP header to be included in the request to CDash during
     submission.  For example, CDash can be configured to only accept
     submissions from authenticated clients.  In this case, you should
     provide a bearer token in your header:

          ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")

     This suboption can be repeated several times for multiple headers.

‘RETRY_COUNT <count>’

     Specify how many times to retry a timed-out submission.

‘RETRY_DELAY <delay>’

     Specify how long (in seconds) to wait after a timed-out submission
     before attempting to re-submit.

‘RETURN_VALUE <result-var>’

     Store in the ‘<result-var>’ variable ‘0’ for success and non-zero
     on failure.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Suppress all non-error messages that would have otherwise been
     printed to the console.

7.3.10.1 Submit to CDash Upload API
...................................

     ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
                  [SUBMIT_URL <url>]
                  [HTTPHEADER <header>]
                  [RETRY_COUNT <count>]
                  [RETRY_DELAY <delay>]
                  [RETURN_VALUE <result-var>]
                  [QUIET])

This second signature is used to upload files to CDash via the CDash
file upload API. The API first sends a request to upload to CDash along
with a content hash of the file.  If CDash does not already have the
file, then it is uploaded.  Along with the file, a CDash type string is
specified to tell CDash which handler to use to process the data.

This signature accepts the ‘SUBMIT_URL’, ‘BUILD_ID’, ‘HTTPHEADER’,
‘RETRY_COUNT’, ‘RETRY_DELAY’, ‘RETURN_VALUE’ and ‘QUIET’ options as
described above.

7.3.11 ctest_test
-----------------

Perform the CTest Test Step as a Dashboard Client.

     ctest_test([BUILD <build-dir>] [APPEND]
                [START <start-number>]
                [END <end-number>]
                [STRIDE <stride-number>]
                [EXCLUDE <exclude-regex>]
                [INCLUDE <include-regex>]
                [EXCLUDE_LABEL <label-exclude-regex>]
                [INCLUDE_LABEL <label-include-regex>]
                [EXCLUDE_FIXTURE <regex>]
                [EXCLUDE_FIXTURE_SETUP <regex>]
                [EXCLUDE_FIXTURE_CLEANUP <regex>]
                [PARALLEL_LEVEL <level>]
                [RESOURCE_SPEC_FILE <file>]
                [TEST_LOAD <threshold>]
                [SCHEDULE_RANDOM <ON|OFF>]
                [STOP_ON_FAILURE]
                [STOP_TIME <time-of-day>]
                [RETURN_VALUE <result-var>]
                [CAPTURE_CMAKE_ERROR <result-var>]
                [REPEAT <mode>:<n>]
                [QUIET]
                )

Run tests in the project build tree and store results in ‘Test.xml’ for
submission with the ctest_submit() command.

The options are:

‘BUILD <build-dir>’

     Specify the top-level build directory.  If not given, the
     CTEST_BINARY_DIRECTORY variable is used.

‘APPEND’

     Mark ‘Test.xml’ for append to results previously submitted to a
     dashboard server since the last ctest_start() call.
     Append semantics are defined by the dashboard server in use.  This
     does `not' cause results to be appended to a ‘.xml’ file produced
     by a previous call to this command.

‘START <start-number>’

     Specify the beginning of a range of test numbers.

‘END <end-number>’

     Specify the end of a range of test numbers.

‘STRIDE <stride-number>’

     Specify the stride by which to step across a range of test numbers.

‘EXCLUDE <exclude-regex>’

     Specify a regular expression matching test names to exclude.

‘INCLUDE <include-regex>’

     Specify a regular expression matching test names to include.  Tests
     not matching this expression are excluded.

‘EXCLUDE_LABEL <label-exclude-regex>’

     Specify a regular expression matching test labels to exclude.

‘INCLUDE_LABEL <label-include-regex>’

     Specify a regular expression matching test labels to include.
     Tests not matching this expression are excluded.

‘EXCLUDE_FIXTURE <regex>’

     If a test in the set of tests to be executed requires a particular
     fixture, that fixture’s setup and cleanup tests would normally be
     added to the test set automatically.  This option prevents adding
     setup or cleanup tests for fixtures matching the ‘<regex>’.  Note
     that all other fixture behavior is retained, including test
     dependencies and skipping tests that have fixture setup tests that
     fail.

‘EXCLUDE_FIXTURE_SETUP <regex>’

     Same as ‘EXCLUDE_FIXTURE’ except only matching setup tests are
     excluded.

‘EXCLUDE_FIXTURE_CLEANUP <regex>’

     Same as ‘EXCLUDE_FIXTURE’ except only matching cleanup tests are
     excluded.

‘PARALLEL_LEVEL <level>’

     Specify a positive number representing the number of tests to be
     run in parallel.

‘RESOURCE_SPEC_FILE <file>’

     Specify a resource specification file.  See
     Resource Allocation for more information.

‘TEST_LOAD <threshold>’

     While running tests in parallel, try not to start tests when they
     may cause the CPU load to pass above a given threshold.  If not
     specified the CTEST_TEST_LOAD variable will be checked,
     and then the ‘--test-load’ command-line argument to ctest(1).
     See also the ‘TestLoad’ setting in the CTest Test Step.

‘REPEAT <mode>:<n>’

     Run tests repeatedly based on the given ‘<mode>’ up to ‘<n>’ times.
     The modes are:

     ‘UNTIL_FAIL’

          Require each test to run ‘<n>’ times without failing in order
          to pass.  This is useful in finding sporadic failures in test
          cases.

     ‘UNTIL_PASS’

          Allow each test to run up to ‘<n>’ times in order to pass.
          Repeats tests if they fail for any reason.  This is useful in
          tolerating sporadic failures in test cases.

     ‘AFTER_TIMEOUT’

          Allow each test to run up to ‘<n>’ times in order to pass.
          Repeats tests only if they timeout.  This is useful in
          tolerating sporadic timeouts in test cases on busy machines.

‘SCHEDULE_RANDOM <ON|OFF>’

     Launch tests in a random order.  This may be useful for detecting
     implicit test dependencies.

‘STOP_ON_FAILURE’

     Stop the execution of the tests once one has failed.

‘STOP_TIME <time-of-day>’

     Specify a time of day at which the tests should all stop running.

‘RETURN_VALUE <result-var>’

     Store in the ‘<result-var>’ variable ‘0’ if all tests passed.
     Store non-zero if anything went wrong.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Suppress any CTest-specific non-error messages that would have
     otherwise been printed to the console.  Output from the underlying
     test command is not affected.  Summary info detailing the
     percentage of passing tests is also unaffected by the ‘QUIET’
     option.

See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.
and CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.

7.3.12 ctest_update
-------------------

Perform the CTest Update Step as a Dashboard Client.

     ctest_update([SOURCE <source-dir>]
                  [RETURN_VALUE <result-var>]
                  [CAPTURE_CMAKE_ERROR <result-var>]
                  [QUIET])

Update the source tree from version control and record results in
‘Update.xml’ for submission with the ctest_submit() command.

The options are:

‘SOURCE <source-dir>’

     Specify the source directory.  If not given, the
     CTEST_SOURCE_DIRECTORY variable is used.

‘RETURN_VALUE <result-var>’

     Store in the ‘<result-var>’ variable the number of files updated or
     ‘-1’ on error.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

‘QUIET’

     Tell CTest to suppress most non-error messages that it would have
     otherwise printed to the console.  CTest will still report the new
     revision of the repository and any conflicting files that were
     found.

The update always follows the version control branch currently checked
out in the source directory.  See the CTest Update Step.
documentation for information about variables that change the behavior
of ‘ctest_update()’.

7.3.13 ctest_upload
-------------------

Upload files to a dashboard server as a Dashboard Client.

     ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])

The options are:

‘FILES <file>...’

     Specify a list of files to be sent along with the build results to
     the dashboard server.

‘QUIET’

     Suppress any CTest-specific non-error output that would have been
     printed to the console otherwise.

‘CAPTURE_CMAKE_ERROR <result-var>’

     Store in the ‘<result-var>’ variable -1 if there are any errors
     running the command and prevent ctest from returning non-zero if an
     error occurs.

7.4 Deprecated Commands
=======================

These commands are deprecated and are only made available to maintain
backward compatibility.  The documentation of each command states the
CMake version in which it was deprecated.  Do not use these commands in
new code.

7.4.1 build_name
----------------

Disallowed since version 3.0.  See CMake Policy CMP0036.

Use ‘${CMAKE_SYSTEM}’ and ‘${CMAKE_CXX_COMPILER}’ instead.

     build_name(variable)

Sets the specified variable to a string representing the platform and
compiler settings.  These values are now available through the
CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.

7.4.2 exec_program
------------------

Deprecated since version 3.0: Use the execute_process().
command instead.

Run an executable program during the processing of the CMakeList.txt
file.

     exec_program(Executable [directory in which to run]
                  [ARGS <arguments to executable>]
                  [OUTPUT_VARIABLE <var>]
                  [RETURN_VALUE <var>])

The executable is run in the optionally specified directory.  The
executable can include arguments if it is double quoted, but it is
better to use the optional ‘ARGS’ argument to specify arguments to the
program.  This is because cmake will then be able to escape spaces in
the executable path.  An optional argument ‘OUTPUT_VARIABLE’ specifies a
variable in which to store the output.  To capture the return value of
the execution, provide a ‘RETURN_VALUE’.  If ‘OUTPUT_VARIABLE’ is
specified, then no output will go to the stdout/stderr of the console
running cmake.

7.4.3 export_library_dependencies
---------------------------------

Disallowed since version 3.0.  See CMake Policy CMP0033.

Use install(EXPORT) or export() command.

This command generates an old-style library dependencies file.  Projects
requiring CMake 2.6 or later should not use the command.  Use instead
the install(EXPORT) command to help export targets from an
installation tree and the export() command to export targets
from a build tree.

The old-style library dependencies file does not take into account
per-configuration names of libraries or the
LINK_INTERFACE_LIBRARIES target property.

     export_library_dependencies(<file> [APPEND])

Create a file named ‘<file>’ that can be included into a CMake listfile
with the INCLUDE command.  The file will contain a number of SET
commands that will set all the variables needed for library dependency
information.  This should be the last command in the top level
CMakeLists.txt file of the project.  If the ‘APPEND’ option is
specified, the SET commands will be appended to the given file instead
of replacing it.

7.4.4 install_files
-------------------

Deprecated since version 3.0: Use the install(FILES) command
instead.

This command has been superceded by the install() command.
It is provided for compatibility with older CMake code.  The ‘FILES’
form is directly replaced by the ‘FILES’ form of the install()
command.  The regexp form can be expressed more clearly using the
‘GLOB’ form of the file() command.

     install_files(<dir> extension file file ...)

Create rules to install the listed files with the given extension into
the given directory.  Only files existing in the current source tree or
its corresponding location in the binary tree may be listed.  If a file
specified already has an extension, that extension will be removed
first.  This is useful for providing lists of source files such as
foo.cxx when you want the corresponding foo.h to be installed.  A
typical extension is ‘.h’.

     install_files(<dir> regexp)

Any files in the current source directory that match the regular
expression will be installed.

     install_files(<dir> FILES file file ...)

Any files listed after the ‘FILES’ keyword will be installed explicitly
from the names given.  Full paths are allowed in this form.

The directory ‘<dir>’ is relative to the installation prefix, which is
stored in the variable CMAKE_INSTALL_PREFIX.

7.4.5 install_programs
----------------------

Deprecated since version 3.0: Use the install(PROGRAMS).
command instead.

This command has been superceded by the install() command.
It is provided for compatibility with older CMake code.  The ‘FILES’
form is directly replaced by the ‘PROGRAMS’ form of the install()
command.  The regexp form can be expressed more clearly using the
‘GLOB’ form of the file() command.

     install_programs(<dir> file1 file2 [file3 ...])
     install_programs(<dir> FILES file1 [file2 ...])

Create rules to install the listed programs into the given directory.
Use the ‘FILES’ argument to guarantee that the file list version of the
command will be used even when there is only one argument.

     install_programs(<dir> regexp)

In the second form any program in the current source directory that
matches the regular expression will be installed.

This command is intended to install programs that are not built by
cmake, such as shell scripts.  See the ‘TARGETS’ form of the
install() command to create installation rules for targets built
by cmake.

The directory ‘<dir>’ is relative to the installation prefix, which is
stored in the variable CMAKE_INSTALL_PREFIX.

7.4.6 install_targets
---------------------

Deprecated since version 3.0: Use the install(TARGETS).
command instead.

This command has been superceded by the install() command.
It is provided for compatibility with older CMake code.

     install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)

Create rules to install the listed targets into the given directory.
The directory ‘<dir>’ is relative to the installation prefix, which is
stored in the variable CMAKE_INSTALL_PREFIX.  If
‘RUNTIME_DIRECTORY’ is specified, then on systems with special runtime
files (Windows DLL), the files will be copied to that directory.

7.4.7 load_command
------------------

Disallowed since version 3.0.  See CMake Policy CMP0031.

Load a command into a running CMake.

     load_command(COMMAND_NAME <loc1> [loc2 ...])

The given locations are searched for a library whose name is
cmCOMMAND_NAME. If found, it is loaded as a module and the command is
added to the set of available CMake commands.  Usually, see
try_compile() is used before this command to compile the module.
If the command is successfully loaded a variable named

     CMAKE_LOADED_COMMAND_<COMMAND_NAME>

will be set to the full path of the module that was loaded.  Otherwise
the variable will not be set.

7.4.8 make_directory
--------------------

Deprecated since version 3.0: Use the file(MAKE_DIRECTORY).
command instead.

     make_directory(directory)

Creates the specified directory.  Full paths should be given.  Any
parent directories that do not exist will also be created.  Use with
care.

7.4.9 output_required_files
---------------------------

Disallowed since version 3.0.  See CMake Policy CMP0032.

Approximate C preprocessor dependency scanning.

This command exists only because ancient CMake versions provided it.
CMake handles preprocessor dependency scanning automatically using a
more advanced scanner.

     output_required_files(srcfile outputfile)

Outputs a list of all the source files that are required by the
specified ‘srcfile’.  This list is written into ‘outputfile’.  This is
similar to writing out the dependencies for ‘srcfile’ except that it
jumps from ‘.h’ files into ‘.cxx’, ‘.c’ and ‘.cpp’ files if possible.

7.4.10 qt_wrap_cpp
------------------

Deprecated since version 3.14: This command was originally added to
support Qt 3 before the add_custom_command() command was
sufficiently mature.  The FindQt4 module provides the
‘qt4_wrap_cpp()’ macro, which should be used instead for Qt 4 projects.
For projects using Qt 5 or later, use the equivalent macro provided by
Qt itself (e.g.  Qt 5 provides ‘qt5_wrap_cpp()’).

Manually create Qt Wrappers.

     qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)

Produces moc files for all the .h files listed in the SourceLists.  The
moc files will be added to the library using the ‘DestName’ source list.

Consider updating the project to use the AUTOMOC target
property instead for a more automated way of invoking the ‘moc’ tool.

7.4.11 qt_wrap_ui
-----------------

Deprecated since version 3.14: This command was originally added to
support Qt 3 before the add_custom_command() command was
sufficiently mature.  The FindQt4 module provides the
‘qt4_wrap_ui()’ macro, which should be used instead for Qt 4 projects.
For projects using Qt 5 or later, use the equivalent macro provided by
Qt itself (e.g.  Qt 5 provides ‘qt5_wrap_ui()’).

Manually create Qt user interfaces Wrappers.

     qt_wrap_ui(resultingLibraryName HeadersDestName
                SourcesDestName SourceLists ...)

Produces .h and .cxx files for all the .ui files listed in the
‘SourceLists’.  The .h files will be added to the library using the
‘HeadersDestNamesource’ list.  The .cxx files will be added to the
library using the ‘SourcesDestNamesource’ list.

Consider updating the project to use the AUTOUIC target
property instead for a more automated way of invoking the ‘uic’ tool.

7.4.12 remove
-------------

Deprecated since version 3.0: Use the list(REMOVE_ITEM).
command instead.

     remove(VAR VALUE VALUE ...)

Removes ‘VALUE’ from the variable ‘VAR’.  This is typically used to
remove entries from a vector (e.g.  semicolon separated list).  ‘VALUE’
is expanded.

7.4.13 subdir_depends
---------------------

Disallowed since version 3.0.  See CMake Policy CMP0029.

Does nothing.

     subdir_depends(subdir dep1 dep2 ...)

Does not do anything.  This command used to help projects order parallel
builds correctly.  This functionality is now automatic.

7.4.14 subdirs
--------------

Deprecated since version 3.0: Use the add_subdirectory().
command instead.

Add a list of subdirectories to the build.

     subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
             [PREORDER] )

Add a list of subdirectories to the build.  The
add_subdirectory() command should be used instead of ‘subdirs’
although ‘subdirs’ will still work.  This will cause any CMakeLists.txt
files in the sub directories to be processed by CMake.  Any directories
after the ‘PREORDER’ flag are traversed first by makefile builds, the
‘PREORDER’ flag has no effect on IDE projects.  Any directories after
the ‘EXCLUDE_FROM_ALL’ marker will not be included in the top level
makefile or project file.  This is useful for having CMake create
makefiles or projects for a set of examples in a project.  You would
want CMake to generate makefiles or project files for all the examples
at the same time, but you would not want them to show up in the top
level project or be built each time make is run from the top.

7.4.15 use_mangled_mesa
-----------------------

Disallowed since version 3.0.  See CMake Policy CMP0030.

Copy mesa headers for use in combination with system GL.

     use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)

The path to mesa includes, should contain ‘gl_mangle.h’.  The mesa
headers are copied to the specified output directory.  This allows
mangled mesa headers to override other GL headers by being added to the
include directory path earlier.

7.4.16 utility_source
---------------------

Disallowed since version 3.0.  See CMake Policy CMP0034.

Specify the source tree of a third-party utility.

     utility_source(cache_entry executable_name
                    path_to_source [file1 file2 ...])

When a third-party utility’s source is included in the distribution,
this command specifies its location and name.  The cache entry will not
be set unless the ‘path_to_source’ and all listed files exist.  It is
assumed that the source tree of the utility will have been built before
it is needed.

When cross compiling CMake will print a warning if a ‘utility_source()’
command is executed, because in many cases it is used to build an
executable which is executed later on.  This doesn’t work when cross
compiling, since the executable can run only on their target platform.
So in this case the cache entry has to be adjusted manually so it points
to an executable which is runnable on the build host.

7.4.17 variable_requires
------------------------

Disallowed since version 3.0.  See CMake Policy CMP0035.

Use the if() command instead.

Assert satisfaction of an option’s required variables.

     variable_requires(TEST_VARIABLE RESULT_VARIABLE
                       REQUIRED_VARIABLE1
                       REQUIRED_VARIABLE2 ...)

The first argument (‘TEST_VARIABLE’) is the name of the variable to be
tested, if that variable is false nothing else is done.  If
‘TEST_VARIABLE’ is true, then the next argument (‘RESULT_VARIABLE’) is a
variable that is set to true if all the required variables are set.  The
rest of the arguments are variables that must be true or not set to
‘NOTFOUND’ to avoid an error.  If any are not true, an error is
reported.

7.4.18 write_file
-----------------

Deprecated since version 3.0: Use the file(WRITE) command
instead.

     write_file(filename "message to write"... [APPEND])

The first argument is the file name, the rest of the arguments are
messages to write.  If the argument ‘APPEND’ is specified, then the
message will be appended.

NOTE 1: file(WRITE) and file(APPEND) do exactly
the same as this one but add some more functionality.

NOTE 2: When using ‘write_file’ the produced file cannot be used as an
input to CMake (CONFIGURE_FILE, source file …) because it will lead to
an infinite loop.  Use configure_file() if you want to
generate input files to CMake.

8 cmake-compile-features(7)
***************************

8.1 Introduction
================

Project source code may depend on, or be conditional on, the
availability of certain features of the compiler.  There are three
use-cases which arise: Compile Feature Requirements,
Optional Compile Features and Conditional Compilation Options.

While features are typically specified in programming language
standards, CMake provides a primary user interface based on granular
handling of the features, not the language standard that introduced the
feature.

The CMAKE_C_KNOWN_FEATURES, CMAKE_CUDA_KNOWN_FEATURES,
and CMAKE_CXX_KNOWN_FEATURES global properties contain
all the features known to CMake, regardless of compiler support for the
feature.  The CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES. , and
CMAKE_CXX_COMPILE_FEATURES variables contain all features CMake
knows are known to the compiler, regardless of language standard or
compile flags needed to use them.

Features known to CMake are named mostly following the same convention
as the Clang feature test macros.  There are some exceptions, such as
CMake using ‘cxx_final’ and ‘cxx_override’ instead of the single
‘cxx_override_control’ used by Clang.

Note that there are no separate compile features properties or variables
for the ‘OBJC’ or ‘OBJCXX’ languages.  These are based off ‘C’ or ‘C++’
respectively, so the properties and variables for their corresponding
base language should be used instead.

8.2 Compile Feature Requirements
================================

Compile feature requirements may be specified with the
target_compile_features() command.  For example, if a target must
be compiled with compiler support for the cxx_constexpr.
feature:

     add_library(mylib requires_constexpr.cpp)
     target_compile_features(mylib PRIVATE cxx_constexpr)

In processing the requirement for the ‘cxx_constexpr’ feature, see
cmake(1) will ensure that the in-use C++ compiler is capable of the
feature, and will add any necessary flags such as ‘-std=gnu++11’ to the
compile lines of C++ files in the ‘mylib’ target.  A ‘FATAL_ERROR’ is
issued if the compiler is not capable of the feature.

The exact compile flags and language standard are deliberately not part
of the user interface for this use-case.  CMake will compute the
appropriate compile flags to use by considering the features specified
for each target.

Such compile flags are added even if the compiler supports the
particular feature without the flag.  For example, the GNU compiler
supports variadic templates (with a warning) even if ‘-std=gnu++98’ is
used.  CMake adds the ‘-std=gnu++11’ flag if ‘cxx_variadic_templates’ is
specified as a requirement.

In the above example, ‘mylib’ requires ‘cxx_constexpr’ when it is built
itself, but consumers of ‘mylib’ are not required to use a compiler
which supports ‘cxx_constexpr’.  If the interface of ‘mylib’ does
require the ‘cxx_constexpr’ feature (or any other known feature), that
may be specified with the ‘PUBLIC’ or ‘INTERFACE’ signatures of
target_compile_features().:

     add_library(mylib requires_constexpr.cpp)
     # cxx_constexpr is a usage-requirement
     target_compile_features(mylib PUBLIC cxx_constexpr)

     # main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr.
     add_executable(myexe main.cpp)
     target_link_libraries(myexe mylib)

Feature requirements are evaluated transitively by consuming the link
implementation.  See cmake-buildsystem(7) for more on
transitive behavior of build properties and usage requirements.

8.2.1 Requiring Language Standards
----------------------------------

In projects that use a large number of commonly available features from
a particular language standard (e.g.  C++ 11) one may specify a
meta-feature (e.g.  ‘cxx_std_11’) that requires use of a compiler mode
that is at minimum aware of that standard, but could be greater.  This
is simpler than specifying all the features individually, but does not
guarantee the existence of any particular feature.  Diagnosis of use of
unsupported features will be delayed until compile time.

For example, if C++ 11 features are used extensively in a project’s
header files, then clients must use a compiler mode that is no less than
C++ 11.  This can be requested with the code:

     target_compile_features(mylib PUBLIC cxx_std_11)

In this example, CMake will ensure the compiler is invoked in a mode of
at-least C++ 11 (or C++ 14, C++ 17, …), adding flags such as
‘-std=gnu++11’ if necessary.  This applies to sources within ‘mylib’ as
well as any dependents (that may include headers from ‘mylib’).

8.2.2 Availability of Compiler Extensions
-----------------------------------------

Because the CXX_EXTENSIONS target property is ‘ON’ by
default, CMake uses extended variants of language dialects by default,
such as ‘-std=gnu++11’ instead of ‘-std=c++11’.  That target property
may be set to ‘OFF’ to use the non-extended variant of the dialect flag.
Note that because most compilers enable extensions by default, this
could expose cross-platform bugs in user code or in the headers of
third-party dependencies.

8.3 Optional Compile Features
=============================

Compile features may be preferred if available, without creating a hard
requirement.  For example, a library may provides alternative
implementations depending on whether the ‘cxx_variadic_templates’
feature is available:

     #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
     template<int I, int... Is>
     struct Interface;

     template<int I>
     struct Interface<I>
     {
       static int accumulate()
       {
         return I;
       }
     };

     template<int I, int... Is>
     struct Interface
     {
       static int accumulate()
       {
         return I + Interface<Is...>::accumulate();
       }
     };
     #else
     template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
     struct Interface
     {
       static int accumulate() { return I1 + I2 + I3 + I4; }
     };
     #endif

Such an interface depends on using the correct preprocessor defines for
the compiler features.  CMake can generate a header file containing such
defines using the WriteCompilerDetectionHeader module.  The
module contains the ‘write_compiler_detection_header’ function which
accepts parameters to control the content of the generated header file:

     write_compiler_detection_header(
       FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
       PREFIX Foo
       COMPILERS GNU
       FEATURES
         cxx_variadic_templates
     )

Such a header file may be used internally in the source code of a
project, and it may be installed and used in the interface of library
code.

For each feature listed in ‘FEATURES’, a preprocessor definition is
created in the header file, and defined to either ‘1’ or ‘0’.

Additionally, some features call for additional defines, such as the
‘cxx_final’ and ‘cxx_override’ features.  Rather than being used in
‘#ifdef’ code, the ‘final’ keyword is abstracted by a symbol which is
defined to either ‘final’, a compiler-specific equivalent, or to empty.
That way, C++ code can be written to unconditionally use the symbol, and
compiler support determines what it is expanded to:

     struct Interface {
       virtual void Execute() = 0;
     };

     struct Concrete Foo_FINAL {
       void Execute() Foo_OVERRIDE;
     };

In this case, ‘Foo_FINAL’ will expand to ‘final’ if the compiler
supports the keyword, or to empty otherwise.

In this use-case, the CMake code will wish to enable a particular
language standard if available from the compiler.  The
CXX_STANDARD target property variable may be set to the desired
language standard for a particular target, and the
CMAKE_CXX_STANDARD may be set to influence all following targets:

     write_compiler_detection_header(
       FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
       PREFIX Foo
       COMPILERS GNU
       FEATURES
         cxx_final cxx_override
     )

     # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
     # which will expand to 'final' if the compiler supports the requested
     # CXX_STANDARD.
     add_library(foo foo.cpp)
     set_property(TARGET foo PROPERTY CXX_STANDARD 11)

     # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
     # which will expand to 'final' if the compiler supports the feature,
     # even though CXX_STANDARD is not set explicitly.  The requirement of
     # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
     # affects the compile flags.
     add_library(foo_impl foo_impl.cpp)
     target_compile_features(foo_impl PRIVATE cxx_constexpr)

The ‘write_compiler_detection_header’ function also creates
compatibility code for other features which have standard equivalents.
For example, the ‘cxx_static_assert’ feature is emulated with a template
and abstracted via the ‘<PREFIX>_STATIC_ASSERT’ and
‘<PREFIX>_STATIC_ASSERT_MSG’ function-macros.

8.4 Conditional Compilation Options
===================================

Libraries may provide entirely different header files depending on
requested compiler features.

For example, a header at ‘with_variadics/interface.h’ may contain:

     template<int I, int... Is>
     struct Interface;

     template<int I>
     struct Interface<I>
     {
       static int accumulate()
       {
         return I;
       }
     };

     template<int I, int... Is>
     struct Interface
     {
       static int accumulate()
       {
         return I + Interface<Is...>::accumulate();
       }
     };

while a header at ‘no_variadics/interface.h’ may contain:

     template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
     struct Interface
     {
       static int accumulate() { return I1 + I2 + I3 + I4; }
     };

It would be possible to write a abstraction ‘interface.h’ header
containing something like:

     #include "foo_compiler_detection.h"
     #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
     #include "with_variadics/interface.h"
     #else
     #include "no_variadics/interface.h"
     #endif

However this could be unmaintainable if there are many files to
abstract.  What is needed is to use alternative include directories
depending on the compiler capabilities.

CMake provides a ‘COMPILE_FEATURES’ generator expression to
implement such conditions.  This may be used with the build-property
commands such as target_include_directories() and
target_link_libraries() to set the appropriate buildsystem
properties:

     add_library(foo INTERFACE)
     set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
     set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
     target_include_directories(foo
       INTERFACE
         "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
         "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
       )

Consuming code then simply links to the ‘foo’ target as usual and uses
the feature-appropriate include directory

     add_executable(consumer_with consumer_with.cpp)
     target_link_libraries(consumer_with foo)
     set_property(TARGET consumer_with CXX_STANDARD 11)

     add_executable(consumer_no consumer_no.cpp)
     target_link_libraries(consumer_no foo)

8.5 Supported Compilers
=======================

CMake is currently aware of the C++ standards and
compile features available from the following compiler ids
as of the versions specified for each:

   * ‘AppleClang’: Apple Clang for Xcode versions 4.4+.

   * ‘Clang’: Clang compiler versions 2.9+.

   * ‘GNU’: GNU compiler versions 4.4+.

   * ‘MSVC’: Microsoft Visual Studio versions 2010+.

   * ‘SunPro’: Oracle SolarisStudio versions 12.4+.

   * ‘Intel’: Intel compiler versions 12.1+.

CMake is currently aware of the C standards and
compile features available from the following compiler ids
as of the versions specified for each:

   * all compilers and versions listed above for C++.

   * ‘GNU’: GNU compiler versions 3.4+

CMake is currently aware of the C++ standards and their
associated meta-features (e.g.  ‘cxx_std_11’) available from the
following compiler ids as of the versions specified for
each:

   * ‘Cray’: Cray Compiler Environment version 8.1+.

   * ‘PGI’: PGI version 12.10+.

   * ‘TI’: Texas Instruments compiler.

   * ‘XL’: IBM XL version 10.1+.

CMake is currently aware of the C standards and their
associated meta-features (e.g.  ‘c_std_99’) available from the following
compiler ids as of the versions specified for each:

   * all compilers and versions listed above with only meta-features for
     C++.

CMake is currently aware of the CUDA standards and their
associated meta-features (e.g.  ‘cuda_std_11’) available from the
following compiler ids as of the versions specified for
each:

   * ‘NVIDIA’: NVIDIA nvcc compiler 7.5+.

9 cmake-developer(7)
********************

9.1 Introduction
================

This manual is intended for reference by developers working with
cmake-language(7) code, whether writing their own modules,
authoring their own build systems, or working on CMake itself.

See ‘https://cmake.org/get-involved/’ to get involved in development of
CMake upstream.  It includes links to contribution instructions, which
in turn link to developer guides for CMake itself.

9.2 Find Modules
================

A “find module” is a ‘Find<PackageName>.cmake’ file to be loaded by the
find_package() command when invoked for ‘<PackageName>’.

The primary task of a find module is to determine whether a package
exists on the system, set the ‘<PackageName>_FOUND’ variable to reflect
this and provide any variables, macros and imported targets required to
use the package.  A find module is useful in cases where an upstream
library does not provide a config file package.

The traditional approach is to use variables for everything, including
libraries and executables: see the Standard Variable Names.
section below.  This is what most of the existing find modules provided
by CMake do.

The more modern approach is to behave as much like config file packages
files as possible, by providing imported target.
This has the advantage of propagating Transitive Usage Requirements
to consumers.

In either case (or even when providing both variables and imported
targets), find modules should provide backwards compatibility with old
versions that had the same name.

A FindFoo.cmake module will typically be loaded by the command:

     find_package(Foo [major[.minor[.patch[.tweak]]]]
                  [EXACT] [QUIET] [REQUIRED]
                  [[COMPONENTS] [components...]]
                  [OPTIONAL_COMPONENTS components...]
                  [NO_POLICY_SCOPE])

See the find_package() documentation for details on what
variables are set for the find module.  Most of these are dealt with by
using FindPackageHandleStandardArgs.

Briefly, the module should only locate versions of the package
compatible with the requested version, as described by the
‘Foo_FIND_VERSION’ family of variables.  If ‘Foo_FIND_QUIETLY’ is set to
true, it should avoid printing messages, including anything complaining
about the package not being found.  If ‘Foo_FIND_REQUIRED’ is set to
true, the module should issue a ‘FATAL_ERROR’ if the package cannot be
found.  If neither are set to true, it should print a non-fatal message
if it cannot find the package.

Packages that find multiple semi-independent parts (like bundles of
libraries) should search for the components listed in
‘Foo_FIND_COMPONENTS’ if it is set , and only set ‘Foo_FOUND’ to true if
for each searched-for component ‘<c>’ that was not found,
‘Foo_FIND_REQUIRED_<c>’ is not set to true.  The ‘HANDLE_COMPONENTS’
argument of ‘find_package_handle_standard_args()’ can be used to
implement this.

If ‘Foo_FIND_COMPONENTS’ is not set, which modules are searched for and
required is up to the find module, but should be documented.

For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.

9.2.1 Standard Variable Names
-----------------------------

For a ‘FindXxx.cmake’ module that takes the approach of setting
variables (either instead of or in addition to creating imported
targets), the following variable names should be used to keep things
consistent between find modules.  Note that all variables start with
‘Xxx_’ to make sure they do not interfere with other find modules; the
same consideration applies to macros, functions and imported targets.

‘Xxx_INCLUDE_DIRS’

     The final set of include directories listed in one variable for use
     by client code.  This should not be a cache entry.

‘Xxx_LIBRARIES’

     The libraries to link against to use Xxx.  These should include
     full paths.  This should not be a cache entry.

‘Xxx_DEFINITIONS’

     Definitions to use when compiling code that uses Xxx.  This really
     shouldn’t include options such as ‘-DHAS_JPEG’ that a client
     source-code file uses to decide whether to ‘#include <jpeg.h>’

‘Xxx_EXECUTABLE’

     Where to find the Xxx tool.

‘Xxx_Yyy_EXECUTABLE’

     Where to find the Yyy tool that comes with Xxx.

‘Xxx_LIBRARY_DIRS’

     Optionally, the final set of library directories listed in one
     variable for use by client code.  This should not be a cache entry.

‘Xxx_ROOT_DIR’

     Where to find the base directory of Xxx.

‘Xxx_VERSION_Yy’

     Expect Version Yy if true.  Make sure at most one of these is ever
     true.

‘Xxx_WRAP_Yy’

     If False, do not try to use the relevant CMake wrapping command.

‘Xxx_Yy_FOUND’

     If False, optional Yy part of Xxx system is not available.

‘Xxx_FOUND’

     Set to false, or undefined, if we haven’t found, or don’t want to
     use Xxx.

‘Xxx_NOT_FOUND_MESSAGE’

     Should be set by config-files in the case that it has set
     ‘Xxx_FOUND’ to FALSE. The contained message will be printed by the
     find_package() command and by
     ‘find_package_handle_standard_args()’ to inform the user about the
     problem.

‘Xxx_RUNTIME_LIBRARY_DIRS’

     Optionally, the runtime library search path for use when running an
     executable linked to shared libraries.  The list should be used by
     user code to create the ‘PATH’ on windows or ‘LD_LIBRARY_PATH’ on
     UNIX. This should not be a cache entry.

‘Xxx_VERSION’

     The full version string of the package found, if any.  Note that
     many existing modules provide ‘Xxx_VERSION_STRING’ instead.

‘Xxx_VERSION_MAJOR’

     The major version of the package found, if any.

‘Xxx_VERSION_MINOR’

     The minor version of the package found, if any.

‘Xxx_VERSION_PATCH’

     The patch version of the package found, if any.

The following names should not usually be used in CMakeLists.txt files,
but are typically cache variables for users to edit and control the
behaviour of find modules (like entering the path to a library manually)

‘Xxx_LIBRARY’

     The path of the Xxx library (as used with find_library(),
     for example).

‘Xxx_Yy_LIBRARY’

     The path of the Yy library that is part of the Xxx system.  It may
     or may not be required to use Xxx.

‘Xxx_INCLUDE_DIR’

     Where to find headers for using the Xxx library.

‘Xxx_Yy_INCLUDE_DIR’

     Where to find headers for using the Yy library of the Xxx system.

To prevent users being overwhelmed with settings to configure, try to
keep as many options as possible out of the cache, leaving at least one
option which can be used to disable use of the module, or locate a
not-found library (e.g.  ‘Xxx_ROOT_DIR’).  For the same reason, mark
most cache options as advanced.  For packages which provide both debug
and release binaries, it is common to create cache variables with a
‘_LIBRARY_<CONFIG>’ suffix, such as ‘Foo_LIBRARY_RELEASE’ and
‘Foo_LIBRARY_DEBUG’.

While these are the standard variable names, you should provide
backwards compatibility for any old names that were actually in use.
Make sure you comment them as deprecated, so that no-one starts using
them.

9.2.2 A Sample Find Module
--------------------------

We will describe how to create a simple find module for a library ‘Foo’.

The top of the module should begin with a license notice, followed by a
blank line, and then followed by a Bracket Comment.  The
comment should begin with ‘.rst:’ to indicate that the rest of its
content is reStructuredText-format documentation.  For example:

     # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
     # file Copyright.txt or https://cmake.org/licensing for details.

     #[=======================================================================[.rst:
     FindFoo
     -------

     Finds the Foo library.

     Imported Targets
     ^^^^^^^^^^^^^^^^

     This module provides the following imported targets, if found:

     ``Foo::Foo``
       The Foo library

     Result Variables
     ^^^^^^^^^^^^^^^^

     This will define the following variables:

     ``Foo_FOUND``
       True if the system has the Foo library.
     ``Foo_VERSION``
       The version of the Foo library which was found.
     ``Foo_INCLUDE_DIRS``
       Include directories needed to use Foo.
     ``Foo_LIBRARIES``
       Libraries needed to link to Foo.

     Cache Variables
     ^^^^^^^^^^^^^^^

     The following cache variables may also be set:

     ``Foo_INCLUDE_DIR``
       The directory containing ``foo.h``.
     ``Foo_LIBRARY``
       The path to the Foo library.

     #]=======================================================================]

The module documentation consists of:

   * An underlined heading specifying the module name.

   * A simple description of what the module finds.  More description
     may be required for some packages.  If there are caveats or other
     details users of the module should be aware of, specify them here.

   * A section listing imported targets provided by the module, if any.

   * A section listing result variables provided by the module.

   * Optionally a section listing cache variables used by the module, if
     any.

If the package provides any macros or functions, they should be listed
in an additional section, but can be documented by additional ‘.rst:’
comment blocks immediately above where those macros or functions are
defined.

The find module implementation may begin below the documentation block.
Now the actual libraries and so on have to be found.  The code here will
obviously vary from module to module (dealing with that, after all, is
the point of find modules), but there tends to be a common pattern for
libraries.

First, we try to use ‘pkg-config’ to find the library.  Note that we
cannot rely on this, as it may not be available, but it provides a good
starting point.

     find_package(PkgConfig)
     pkg_check_modules(PC_Foo QUIET Foo)

This should define some variables starting ‘PC_Foo_’ that contain the
information from the ‘Foo.pc’ file.

Now we need to find the libraries and include files; we use the
information from ‘pkg-config’ to provide hints to CMake about where to
look.

     find_path(Foo_INCLUDE_DIR
       NAMES foo.h
       PATHS ${PC_Foo_INCLUDE_DIRS}
       PATH_SUFFIXES Foo
     )
     find_library(Foo_LIBRARY
       NAMES foo
       PATHS ${PC_Foo_LIBRARY_DIRS}
     )

If you have a good way of getting the version (from a header file, for
example), you can use that information to set ‘Foo_VERSION’ (although
note that find modules have traditionally used ‘Foo_VERSION_STRING’, so
you may want to set both).  Otherwise, attempt to use the information
from ‘pkg-config’

     set(Foo_VERSION ${PC_Foo_VERSION})

Now we can use FindPackageHandleStandardArgs to do most of
the rest of the work for us

     include(FindPackageHandleStandardArgs)
     find_package_handle_standard_args(Foo
       FOUND_VAR Foo_FOUND
       REQUIRED_VARS
         Foo_LIBRARY
         Foo_INCLUDE_DIR
       VERSION_VAR Foo_VERSION
     )

This will check that the ‘REQUIRED_VARS’ contain values (that do not end
in ‘-NOTFOUND’) and set ‘Foo_FOUND’ appropriately.  It will also cache
those values.  If ‘Foo_VERSION’ is set, and a required version was
passed to find_package(), it will check the requested version
against the one in ‘Foo_VERSION’.  It will also print messages as
appropriate; note that if the package was found, it will print the
contents of the first required variable to indicate where it was found.

At this point, we have to provide a way for users of the find module to
link to the library or libraries that were found.  There are two
approaches, as discussed in the Find Modules section above.
The traditional variable approach looks like

     if(Foo_FOUND)
       set(Foo_LIBRARIES ${Foo_LIBRARY})
       set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
       set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
     endif()

If more than one library was found, all of them should be included in
these variables (see the Standard Variable Names section for
more information).

When providing imported targets, these should be namespaced (hence the
‘Foo::’ prefix); CMake will recognize that values passed to
target_link_libraries() that contain ‘::’ in their name are
supposed to be imported targets (rather than just library names), and
will produce appropriate diagnostic messages if that target does not
exist (see policy CMP0028).

     if(Foo_FOUND AND NOT TARGET Foo::Foo)
       add_library(Foo::Foo UNKNOWN IMPORTED)
       set_target_properties(Foo::Foo PROPERTIES
         IMPORTED_LOCATION "${Foo_LIBRARY}"
         INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
         INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
       )
     endif()

One thing to note about this is that the ‘INTERFACE_INCLUDE_DIRECTORIES’
and similar properties should only contain information about the target
itself, and not any of its dependencies.  Instead, those dependencies
should also be targets, and CMake should be told that they are
dependencies of this target.  CMake will then combine all the necessary
information automatically.

The type of the IMPORTED target created in the
add_library() command can always be specified as ‘UNKNOWN’ type.
This simplifies the code in cases where static or shared variants may be
found, and CMake will determine the type by inspecting the files.

If the library is available with multiple configurations, the
IMPORTED_CONFIGURATIONS target property should also be populated:

     if(Foo_FOUND)
       if (NOT TARGET Foo::Foo)
         add_library(Foo::Foo UNKNOWN IMPORTED)
       endif()
       if (Foo_LIBRARY_RELEASE)
         set_property(TARGET Foo::Foo APPEND PROPERTY
           IMPORTED_CONFIGURATIONS RELEASE
         )
         set_target_properties(Foo::Foo PROPERTIES
           IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
         )
       endif()
       if (Foo_LIBRARY_DEBUG)
         set_property(TARGET Foo::Foo APPEND PROPERTY
           IMPORTED_CONFIGURATIONS DEBUG
         )
         set_target_properties(Foo::Foo PROPERTIES
           IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"
         )
       endif()
       set_target_properties(Foo::Foo PROPERTIES
         INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
         INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
       )
     endif()

The ‘RELEASE’ variant should be listed first in the property so that the
variant is chosen if the user uses a configuration which is not an exact
match for any listed ‘IMPORTED_CONFIGURATIONS’.

Most of the cache variables should be hidden in the ‘ccmake’ interface
unless the user explicitly asks to edit them.

     mark_as_advanced(
       Foo_INCLUDE_DIR
       Foo_LIBRARY
     )

If this module replaces an older version, you should set compatibility
variables to cause the least disruption possible.

     # compatibility variables
     set(Foo_VERSION_STRING ${Foo_VERSION})

10 cmake-env-variables(7)
*************************

This page lists environment variables that have special meaning to
CMake.

For general information on environment variables, see the
Environment Variables section in the cmake-language manual.

10.1 Environment Variables that Change Behavior
===============================================

10.1.1 CMAKE_PREFIX_PATH
------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

The ‘CMAKE_PREFIX_PATH’ environment variable may be set to a list of
directories specifying installation `prefixes' to be searched by the
find_package(), find_program(),
find_library(), find_file(), and find_path().
commands.  Each command will add appropriate subdirectories (like ‘bin’,
‘lib’, or ‘include’) as specified in its own documentation.

This variable may hold a single prefix or a list of prefixes separated
by ‘:’ on UNIX or ‘;’ on Windows (the same as the ‘PATH’ environment
variable convention on those platforms).

See also the CMAKE_PREFIX_PATH. CMake variable.

10.2 Environment Variables that Control the Build
=================================================

10.2.1 CMAKE_APPLE_SILICON_PROCESSOR
------------------------------------

New in version 3.19.2.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

On Apple Silicon hosts running macOS, set this environment variable to
tell CMake what architecture to use for
CMAKE_HOST_SYSTEM_PROCESSOR.  The value must be either ‘arm64’ or
‘x86_64’.

The CMAKE_APPLE_SILICON_PROCESSOR normal variable, if set,
overrides this environment variable.

10.2.2 CMAKE_BUILD_PARALLEL_LEVEL
---------------------------------

New in version 3.12.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Specifies the maximum number of concurrent processes to use when
building using the ‘cmake --build’ command line Build Tool Mode.

If this variable is defined empty the native build tool’s default number
is used.

10.2.3 CMAKE_CONFIG_TYPE
------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

The default build configuration for Build a Project and
‘ctest’ build handler when there is no explicit configuration given.

10.2.4 CMAKE_EXPORT_COMPILE_COMMANDS
------------------------------------

New in version 3.17.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

The default value for CMAKE_EXPORT_COMPILE_COMMANDS when
there is no explicit configuration given on the first run while creating
a new build tree.  On later runs in an existing build tree the value
persists in the cache as CMAKE_EXPORT_COMPILE_COMMANDS.

10.2.5 CMAKE_GENERATOR
----------------------

New in version 3.15.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Specifies the CMake default generator to use when no generator is
supplied with ‘-G’.  If the provided value doesn’t name a generator
known by CMake, the internal default is used.  Either way the resulting
generator selection is stored in the CMAKE_GENERATOR.
variable.

Some generators may be additionally configured using the environment
variables:

   * CMAKE_GENERATOR_PLATFORM.

   * CMAKE_GENERATOR_TOOLSET.

   * CMAKE_GENERATOR_INSTANCE.

10.2.6 CMAKE_GENERATOR_INSTANCE
-------------------------------

New in version 3.15.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default value for CMAKE_GENERATOR_INSTANCE if no Cache entry
is present.  This value is only applied if CMAKE_GENERATOR is
set.

10.2.7 CMAKE_GENERATOR_PLATFORM
-------------------------------

New in version 3.15.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default value for CMAKE_GENERATOR_PLATFORM if no Cache entry
is present and no value is specified by cmake(1). ‘-A’ option.
This value is only applied if CMAKE_GENERATOR is set.

10.2.8 CMAKE_GENERATOR_TOOLSET
------------------------------

New in version 3.15.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default value for CMAKE_GENERATOR_TOOLSET if no Cache entry
is present and no value is specified by cmake(1). ‘-T’ option.
This value is only applied if CMAKE_GENERATOR is set.

10.2.9 CMAKE_<LANG>_COMPILER_LAUNCHER
-------------------------------------

New in version 3.17.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compiler launcher to use for the specified language.  Will only
be used by CMake to initialize the variable on the first configuration.
Afterwards, it is available through the cache setting of the variable of
the same name.  For any configuration run (including the first), the
environment variable will be ignored if the
CMAKE_<LANG>_COMPILER_LAUNCHER variable is defined.

10.2.10 CMAKE_MSVCIDE_RUN_PATH
------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Extra PATH locations for custom commands when using Visual Studio 9 2008.
(or above) generators.

The ‘CMAKE_MSVCIDE_RUN_PATH’ environment variable sets the default value
for the CMAKE_MSVCIDE_RUN_PATH variable if not already
explicitly set.

10.2.11 CMAKE_NO_VERBOSE
------------------------

New in version 3.14.

Disables verbose output from CMake when VERBOSE environment
variable is set.

Only your build tool of choice will still print verbose output when you
start to actually build your project.

10.2.12 CMAKE_OSX_ARCHITECTURES
-------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Target specific architectures for macOS.

The ‘CMAKE_OSX_ARCHITECTURES’ environment variable sets the default
value for the CMAKE_OSX_ARCHITECTURES variable.  See
OSX_ARCHITECTURES for more information.

10.2.13 DESTDIR
---------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

On UNIX one can use the ‘DESTDIR’ mechanism in order to relocate the
whole installation.  ‘DESTDIR’ means DESTination DIRectory.  It is
commonly used by makefile users in order to install software at
non-default location.  It is usually invoked like this:

     make DESTDIR=/home/john install

which will install the concerned software using the installation prefix,
e.g.  ‘/usr/local’ prepended with the ‘DESTDIR’ value which finally
gives ‘/home/john/usr/local’.

WARNING: ‘DESTDIR’ may not be used on Windows because installation
prefix usually contains a drive letter like in ‘C:/Program Files’ which
cannot be prepended with some other prefix.

10.2.14 LDFLAGS
---------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Will only be used by CMake on the first configuration to determine the
default linker flags, after which the value for ‘LDFLAGS’ is stored in
the cache as CMAKE_EXE_LINKER_FLAGS_INIT,
CMAKE_SHARED_LINKER_FLAGS_INIT, and
CMAKE_MODULE_LINKER_FLAGS_INIT.  For any configuration run
(including the first), the environment variable will be ignored if the
equivalent ‘CMAKE_<TYPE>_LINKER_FLAGS_INIT’ variable is defined.

10.2.15 MACOSX_DEPLOYMENT_TARGET
--------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Specify the minimum version of macOS on which the target binaries are to
be deployed.

The ‘MACOSX_DEPLOYMENT_TARGET’ environment variable sets the default
value for the CMAKE_OSX_DEPLOYMENT_TARGET variable.

10.2.16 <PackageName>_ROOT
--------------------------

New in version 3.12.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Calls to find_package(<PackageName>) will search in prefixes
specified by the ‘<PackageName>_ROOT’ environment variable, where
‘<PackageName>’ is the name given to the find_package() call
and ‘_ROOT’ is literal.  For example, ‘find_package(Foo)’ will search
prefixes specified in the ‘Foo_ROOT’ environment variable (if set).  See
policy CMP0074.

This variable may hold a single prefix or a list of prefixes separated
by ‘:’ on UNIX or ‘;’ on Windows (the same as the ‘PATH’ environment
variable convention on those platforms).

See also the <PackageName>_ROOT. CMake variable.

10.2.17 VERBOSE
---------------

New in version 3.14.

Activates verbose output from CMake and your build tools of choice when
you start to actually build your project.

Note that any given value is ignored.  It’s just checked for existence.

See also Build Tool Mode and CMAKE_NO_VERBOSE.
environment variable

10.3 Environment Variables for Languages
========================================

10.3.1 ASM<DIALECT>
-------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling a specific dialect of assembly
language files.  ‘ASM<DIALECT>’ can be ‘ASM’, ‘ASM_NASM’ (Netwide
Assembler), ‘ASM_MASM’ (Microsoft Assembler) or ‘ASM-ATT’ (Assembler
AT&T). Will only be used by CMake on the first configuration to
determine ‘ASM<DIALECT>’ compiler, after which the value for
‘ASM<DIALECT>’ is stored in the cache as
CMAKE_ASM<DIALECT>_COMPILER.  For subsequent configuration runs,
the environment variable will be ignored in favor of
CMAKE_ASM<DIALECT>_COMPILER.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export ASM="custom-compiler --arg1 --arg2"

10.3.2 ASM<DIALECT>FLAGS
------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling a specific dialect
of an assembly language.  ‘ASM<DIALECT>FLAGS’ can be ‘ASMFLAGS’,
‘ASM_NASMFLAGS’, ‘ASM_MASMFLAGS’ or ‘ASM-ATTFLAGS’.  Will only be used
by CMake on the first configuration to determine ‘ASM_<DIALECT>’ default
compilation flags, after which the value for ‘ASM<DIALECT>FLAGS’ is
stored in the cache as ‘CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>’.
For any configuration run (including the first), the environment
variable will be ignored, if the ‘CMAKE_ASM<DIALECT>_FLAGS
<CMAKE_<LANG>_FLAGS>’ variable is defined.

See also CMAKE_ASM<DIALECT>_FLAGS_INIT.

10.3.3 CC
---------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘C’ language files.  Will only be
used by CMake on the first configuration to determine ‘C’ compiler,
after which the value for ‘CC’ is stored in the cache as
CMAKE_C_COMPILER.  For any configuration run (including the first),
the environment variable will be ignored if the CMAKE_C_COMPILER
variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export CC="custom-compiler --arg1 --arg2"

10.3.4 CFLAGS
-------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘C’ files.  Will
only be used by CMake on the first configuration to determine ‘CC’
default compilation flags, after which the value for ‘CFLAGS’ is stored
in the cache as CMAKE_C_FLAGS.  For any configuration run
(including the first), the environment variable will be ignored if the
CMAKE_C_FLAGS variable is defined.

See also CMAKE_C_FLAGS_INIT.

10.3.5 CSFLAGS
--------------

New in version 3.9.2.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘CSharp’ files.
Will only be used by CMake on the first configuration to determine
‘CSharp’ default compilation flags, after which the value for ‘CSFLAGS’
is stored in the cache as CMAKE_CSharp_FLAGS.  For any
configuration run (including the first), the environment variable will
be ignored if the CMAKE_CSharp_FLAGS variable is defined.

See also CMAKE_CSharp_FLAGS_INIT.

10.3.6 CUDACXX
--------------

New in version 3.8.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘CUDA’ language files.  Will only be
used by CMake on the first configuration to determine ‘CUDA’ compiler,
after which the value for ‘CUDA’ is stored in the cache as
CMAKE_CUDA_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_CUDA_COMPILER variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export CUDACXX="custom-compiler --arg1 --arg2"

10.3.7 CUDAFLAGS
----------------

New in version 3.8.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘CUDA’ files.  Will
only be used by CMake on the first configuration to determine ‘CUDA’
default compilation flags, after which the value for ‘CUDAFLAGS’ is
stored in the cache as CMAKE_CUDA_FLAGS.  For any
configuration run (including the first), the environment variable will
be ignored if the CMAKE_CUDA_FLAGS variable is defined.

See also CMAKE_CUDA_FLAGS_INIT.

10.3.8 CUDAHOSTCXX
------------------

New in version 3.8.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling host code when compiling ‘CUDA’
language files.  Will only be used by CMake on the first configuration
to determine ‘CUDA’ host compiler, after which the value for
‘CUDAHOSTCXX’ is stored in the cache as CMAKE_CUDA_HOST_COMPILER.
For any configuration run (including the first), the environment
variable will be ignored if the CMAKE_CUDA_HOST_COMPILER.
variable is defined.

This environment variable is primarily meant for use with projects that
enable ‘CUDA’ as a first-class language.  The FindCUDA.
module will also use it to initialize its ‘CUDA_HOST_COMPILER’ setting.

10.3.9 CXX
----------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘CXX’ language files.  Will only be
used by CMake on the first configuration to determine ‘CXX’ compiler,
after which the value for ‘CXX’ is stored in the cache as
CMAKE_CXX_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_CXX_COMPILER variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export CXX="custom-compiler --arg1 --arg2"

10.3.10 CXXFLAGS
----------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘CXX’ (C++) files.
Will only be used by CMake on the first configuration to determine ‘CXX’
default compilation flags, after which the value for ‘CXXFLAGS’ is
stored in the cache as CMAKE_CXX_FLAGS.  For any
configuration run ( including the first), the environment variable will
be ignored if the CMAKE_CXX_FLAGS variable is defined.

See also CMAKE_CXX_FLAGS_INIT.

10.3.11 FC
----------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘Fortran’ language files.  Will only
be used by CMake on the first configuration to determine ‘Fortran’
compiler, after which the value for ‘Fortran’ is stored in the cache as
CMAKE_Fortran_COMPILER.  For any configuration run (including
the first), the environment variable will be ignored if the
CMAKE_Fortran_COMPILER variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export FC="custom-compiler --arg1 --arg2"

10.3.12 FFLAGS
--------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘Fortran’ files.
Will only be used by CMake on the first configuration to determine
‘Fortran’ default compilation flags, after which the value for ‘FFLAGS’
is stored in the cache as CMAKE_Fortran_FLAGS.  For any
configuration run (including the first), the environment variable will
be ignored if the CMAKE_Fortran_FLAGS variable is defined.

See also CMAKE_Fortran_FLAGS_INIT.

10.3.13 ISPC
------------

New in version 3.19.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘ISPC’ language files.  Will only be
used by CMake on the first configuration to determine ‘ISPC’ compiler,
after which the value for ‘ISPC’ is stored in the cache as
CMAKE_ISPC_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_ISPC_COMPILER variable is defined.

10.3.14 ISPCFLAGS
-----------------

New in version 3.19.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘ISPC’ files.  Will
only be used by CMake on the first configuration to determine ‘ISPC’
default compilation flags, after which the value for ‘ISPCFLAGS’ is
stored in the cache as CMAKE_ISPC_FLAGS.  For any
configuration run (including the first), the environment variable will
be ignored if the CMAKE_ISPC_FLAGS variable is defined.

See also CMAKE_ISPC_FLAGS_INIT.

10.3.15 OBJC
------------

New in version 3.16.7.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘OBJC’ language files.  Will only be
used by CMake on the first configuration to determine ‘OBJC’ compiler,
after which the value for ‘OBJC’ is stored in the cache as
CMAKE_OBJC_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_OBJC_COMPILER variable is defined.

If ‘OBJC’ is not defined, the CC environment variable will
be checked instead.

10.3.16 OBJCXX
--------------

New in version 3.16.7.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘OBJCXX’ language files.  Will only
be used by CMake on the first configuration to determine ‘OBJCXX’
compiler, after which the value for ‘OBJCXX’ is stored in the cache as
CMAKE_OBJCXX_COMPILER.  For any configuration run (including
the first), the environment variable will be ignored if the
CMAKE_OBJCXX_COMPILER variable is defined.

If ‘OBJCXX’ is not defined, the CXX environment variable
will be checked instead.

10.3.17 RC
----------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘resource’ files.  Will only be used
by CMake on the first configuration to determine ‘resource’ compiler,
after which the value for ‘RC’ is stored in the cache as
CMAKE_RC_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_RC_COMPILER variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export RC="custom-compiler --arg1 --arg2"

10.3.18 RCFLAGS
---------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Default compilation flags to be used when compiling ‘resource’ files.
Will only be used by CMake on the first configuration to determine
‘resource’ default compilation flags, after which the value for
‘RCFLAGS’ is stored in the cache as CMAKE_RC_FLAGS.  For any
configuration run (including the first), the environment variable will
be ignored if the CMAKE_RC_FLAGS variable is defined.

See also CMAKE_RC_FLAGS_INIT.

10.3.19 SWIFTC
--------------

New in version 3.15.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Preferred executable for compiling ‘Swift’ language files.  Will only be
used by CMake on the first configuration to determine ‘Swift’ compiler,
after which the value for ‘SWIFTC’ is stored in the cache as
CMAKE_Swift_COMPILER.  For any configuration run (including the
first), the environment variable will be ignored if the
CMAKE_Swift_COMPILER variable is defined.

     Note: Options that are required to make the compiler work correctly
     can be included; they can not be changed.

     $ export SWIFTC="custom-compiler --arg1 --arg2"

10.4 Environment Variables for CTest
====================================

10.4.1 CTEST_INTERACTIVE_DEBUG_MODE
-----------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Environment variable that will exist and be set to ‘1’ when a test
executed by ctest(1) is run in interactive mode.

10.4.2 CTEST_OUTPUT_ON_FAILURE
------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Boolean environment variable that controls if the output should be
logged for failed tests.  Set the value to ‘1’, ‘True’, or ‘ON’ to
enable output on failure.  See ctest(1) for more information
on controlling output of failed tests.

10.4.3 CTEST_PARALLEL_LEVEL
---------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Specify the number of tests for CTest to run in parallel.  See
ctest(1) for more information on parallel test execution.

10.4.4 CTEST_PROGRESS_OUTPUT
----------------------------

New in version 3.13.

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Boolean environment variable that affects how ctest command
output reports overall progress.  When set to ‘1’, ‘TRUE’, ‘ON’ or
anything else that evaluates to boolean true, progress is reported by
repeatedly updating the same line.  This greatly reduces the overall
verbosity, but is only supported when output is sent directly to a
terminal.  If the environment variable is not set or has a value that
evaluates to false, output is reported normally with each test having
its own start and end lines logged to the output.

The ‘--progress’ option to ctest overrides this environment
variable if both are given.

10.4.5 CTEST_USE_LAUNCHERS_DEFAULT
----------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Initializes the CTEST_USE_LAUNCHERS variable if not already
defined.

10.4.6 DASHBOARD_TEST_FROM_CTEST
--------------------------------

This is a CMake Environment Variable.  Its initial value is
taken from the calling process environment.

Environment variable that will exist when a test executed by
ctest(1) is run in non-interactive mode.  The value will be equal
to CMAKE_VERSION.

10.5 Environment Variables for the CMake curses interface
=========================================================

10.5.1 CCMAKE_COLORS
--------------------

New in version 3.18.

Determines what colors are used by the CMake curses interface, when run
on a terminal that supports colors.  The syntax follows the same
conventions as ‘LS_COLORS’; that is, a list of key/value pairs separated
by ‘:’.

Keys are a single letter corresponding to a CMake cache variable type:

   - ‘s’: A ‘STRING’.

   - ‘p’: A ‘FILEPATH’.

   - ‘c’: A value which has an associated list of choices.

   - ‘y’: A ‘BOOL’ which has a true-like value (e.g.  ‘ON’, ‘YES’).

   - ‘n’: A ‘BOOL’ which has a false-like value (e.g.  ‘OFF’, ‘NO’).

Values are an integer number that specifies what color to use.  ‘0’ is
black (you probably don’t want to use that).  Others are determined by
your terminal’s color support.  Most (color) terminals will support at
least 8 or 16 colors.  Some will support up to 256 colors.  The colors
will likely match this chart(1), although the first 16 colors may match
the original CGA color palette(2).  (Many modern terminal emulators also
allow their color palette, at least for the first 16 colors, to be
configured by the user.)

Note that fairly minimal checking is done for bad colors (although a
value higher than what curses believes your terminal supports will be
silently ignored) or bad syntax.

For example:

     CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'

   ---------- Footnotes ----------

   (1)
https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg

   (2)
https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette

11 cmake-file-api(7)
********************

11.1 Introduction
=================

CMake provides a file-based API that clients may use to get semantic
information about the buildsystems CMake generates.  Clients may use the
API by writing query files to a specific location in a build tree to
request zero or more Object Kinds.  When CMake generates the
buildsystem in that build tree it will read the query files and write
reply files for the client to read.

The file-based API uses a ‘<build>/.cmake/api/’ directory at the top of
a build tree.  The API is versioned to support changes to the layout of
files within the API directory.  API file layout versioning is
orthogonal to the versioning of Object Kinds used in
replies.  This version of CMake supports only one API version, see API v1.

11.2 API v1
===========

API v1 is housed in the ‘<build>/.cmake/api/v1/’ directory.  It has the
following subdirectories:

‘query/’

     Holds query files written by clients.  These may be v1 Shared Stateless Query Files,
     see v1 Client Stateless Query Files,
     or v1 Client Stateful Query Files.

‘reply/’

     Holds reply files written by CMake whenever it runs to generate a
     build system.  These are indexed by a v1 Reply Index File
     file that may reference additional v1 Reply Files.
     CMake owns all reply files.  Clients must never remove them.

     Clients may look for and read a reply index file at any time.
     Clients may optionally create the ‘reply/’ directory at any time
     and monitor it for the appearance of a new reply index file.

11.2.1 v1 Shared Stateless Query Files
--------------------------------------

Shared stateless query files allow clients to share requests for major
versions of the Object Kinds and get all requested versions
recognized by the CMake that runs.

Clients may create shared requests by creating empty files in the
‘v1/query/’ directory.  The form is:

     <build>/.cmake/api/v1/query/<kind>-v<major>

where ‘<kind>’ is one of the Object Kinds, ‘-v’ is literal,
and ‘<major>’ is the major version number.

Files of this form are stateless shared queries not owned by any
specific client.  Once created they should not be removed without
external client coordination or human intervention.

11.2.2 v1 Client Stateless Query Files
--------------------------------------

Client stateless query files allow clients to create owned requests for
major versions of the Object Kinds and get all requested
versions recognized by the CMake that runs.

Clients may create owned requests by creating empty files in
client-specific query subdirectories.  The form is:

     <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>

where ‘client-’ is literal, ‘<client>’ is a string uniquely identifying
the client, ‘<kind>’ is one of the Object Kinds, ‘-v’ is
literal, and ‘<major>’ is the major version number.  Each client must
choose a unique ‘<client>’ identifier via its own means.

Files of this form are stateless queries owned by the client ‘<client>’.
The owning client may remove them at any time.

11.2.3 v1 Client Stateful Query Files
-------------------------------------

Stateful query files allow clients to request a list of versions of each
of the Object Kinds and get only the most recent version
recognized by the CMake that runs.

Clients may create owned stateful queries by creating ‘query.json’ files
in client-specific query subdirectories.  The form is:

     <build>/.cmake/api/v1/query/client-<client>/query.json

where ‘client-’ is literal, ‘<client>’ is a string uniquely identifying
the client, and ‘query.json’ is literal.  Each client must choose a
unique ‘<client>’ identifier via its own means.

‘query.json’ files are stateful queries owned by the client ‘<client>’.
The owning client may update or remove them at any time.  When a given
client installation is updated it may then update the stateful query it
writes to build trees to request newer object versions.  This can be
used to avoid asking CMake to generate multiple object versions
unnecessarily.

A ‘query.json’ file must contain a JSON object:

     {
       "requests": [
         { "kind": "<kind>" , "version": 1 },
         { "kind": "<kind>" , "version": { "major": 1, "minor": 2 } },
         { "kind": "<kind>" , "version": [2, 1] },
         { "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] },
         { "kind": "<kind>" , "version": 1, "client": {} },
         { "kind": "..." }
       ],
       "client": {}
     }

The members are:

‘requests’

     A JSON array containing zero or more requests.  Each request is a
     JSON object with members:

     ‘kind’

          Specifies one of the Object Kinds to be included
          in the reply.

     ‘version’

          Indicates the version(s) of the object kind that the client
          understands.  Versions have major and minor components
          following semantic version conventions.  The value must be

             * a JSON integer specifying a (non-negative) major version
               number, or

             * a JSON object containing ‘major’ and (optionally) ‘minor’
               members specifying non-negative integer version
               components, or

             * a JSON array whose elements are each one of the above.

     ‘client’

          Optional member reserved for use by the client.  This value is
          preserved in the reply written for the client in the v1 Reply Index File
          but is otherwise ignored.  Clients may
          use this to pass custom information with a request through to
          its reply.

     For each requested object kind CMake will choose the `first'
     version that it recognizes for that kind among those listed in the
     request.  The response will use the selected `major' version with
     the highest `minor' version known to the running CMake for that
     major version.  Therefore clients should list all supported major
     versions in preferred order along with the minimal minor version
     required for each major version.

‘client’

     Optional member reserved for use by the client.  This value is
     preserved in the reply written for the client in the v1 Reply Index File
     but is otherwise ignored.  Clients may use this to
     pass custom information with a query through to its reply.

Other ‘query.json’ top-level members are reserved for future use.  If
present they are ignored for forward compatibility.

11.2.4 v1 Reply Index File
--------------------------

CMake writes an ‘index-*.json’ file to the ‘v1/reply/’ directory
whenever it runs to generate a build system.  Clients must read the
reply index file first and may read other v1 Reply Files.
only by following references.  The form of the reply index file name is:

     <build>/.cmake/api/v1/reply/index-<unspecified>.json

where ‘index-’ is literal and ‘<unspecified>’ is an unspecified name
selected by CMake.  Whenever a new index file is generated it is given a
new name and any old one is deleted.  During the short time between
these steps there may be multiple index files present; the one with the
largest name in lexicographic order is the current index file.

The reply index file contains a JSON object:

     {
       "cmake": {
         "version": {
           "major": 3, "minor": 14, "patch": 0, "suffix": "",
           "string": "3.14.0", "isDirty": false
         },
         "paths": {
           "cmake": "/prefix/bin/cmake",
           "ctest": "/prefix/bin/ctest",
           "cpack": "/prefix/bin/cpack",
           "root": "/prefix/share/cmake-3.14"
         },
         "generator": {
           "multiConfig": false,
           "name": "Unix Makefiles"
         }
       },
       "objects": [
         { "kind": "<kind>",
           "version": { "major": 1, "minor": 0 },
           "jsonFile": "<file>" },
         { "...": "..." }
       ],
       "reply": {
         "<kind>-v<major>": { "kind": "<kind>",
                              "version": { "major": 1, "minor": 0 },
                              "jsonFile": "<file>" },
         "<unknown>": { "error": "unknown query file" },
         "...": {},
         "client-<client>": {
           "<kind>-v<major>": { "kind": "<kind>",
                                "version": { "major": 1, "minor": 0 },
                                "jsonFile": "<file>" },
           "<unknown>": { "error": "unknown query file" },
           "...": {},
           "query.json": {
             "requests": [ {}, {}, {} ],
             "responses": [
               { "kind": "<kind>",
                 "version": { "major": 1, "minor": 0 },
                 "jsonFile": "<file>" },
               { "error": "unknown query file" },
               { "...": {} }
             ],
             "client": {}
           }
         }
       }
     }

The members are:

‘cmake’

     A JSON object containing information about the instance of CMake
     that generated the reply.  It contains members:

     ‘version’

          A JSON object specifying the version of CMake with members:

          ‘major’, ‘minor’, ‘patch’

               Integer values specifying the major, minor, and patch
               version components.

          ‘suffix’

               A string specifying the version suffix, if any, e.g.
               ‘g0abc3’.

          ‘string’

               A string specifying the full version in the format
               ‘<major>.<minor>.<patch>[-<suffix>]’.

          ‘isDirty’

               A boolean indicating whether the version was built from a
               version controlled source tree with local modifications.

     ‘paths’

          A JSON object specifying paths to things that come with CMake.
          It has members for ‘cmake’, ‘ctest’, and ‘cpack’ whose values
          are JSON strings specifying the absolute path to each tool,
          represented with forward slashes.  It also has a ‘root’ member
          for the absolute path to the directory containing CMake
          resources like the ‘Modules/’ directory (see CMAKE_ROOT).

     ‘generator’

          A JSON object describing the CMake generator used for the
          build.  It has members:

          ‘multiConfig’

               A boolean specifying whether the generator supports
               multiple output configurations.

          ‘name’

               A string specifying the name of the generator.

          ‘platform’

               If the generator supports CMAKE_GENERATOR_PLATFORM,
               this is a string specifying the generator platform
               name.

‘objects’

     A JSON array listing all versions of all Object Kinds.
     generated as part of the reply.  Each array entry is a v1 Reply File Reference.

‘reply’

     A JSON object mirroring the content of the ‘query/’ directory that
     CMake loaded to produce the reply.  The members are of the form

     ‘<kind>-v<major>’

          A member of this form appears for each of the v1 Shared Stateless Query Files
          that CMake recognized as a request
          for object kind ‘<kind>’ with major version ‘<major>’.  The
          value is a v1 Reply File Reference to the
          corresponding reply file for that object kind and version.

     ‘<unknown>’

          A member of this form appears for each of the v1 Shared Stateless Query Files
          that CMake did not recognize.  The
          value is a JSON object with a single ‘error’ member containing
          a string with an error message indicating that the query file
          is unknown.

     ‘client-<client>’

          A member of this form appears for each client-owned directory
          holding v1 Client Stateless Query Files.  The value
          is a JSON object mirroring the content of the
          ‘query/client-<client>/’ directory.  The members are of the
          form:

          ‘<kind>-v<major>’

               A member of this form appears for each of the v1 Client Stateless Query Files
               that CMake recognized
               as a request for object kind ‘<kind>’ with major version
               ‘<major>’.  The value is a v1 Reply File Reference
               to the corresponding reply file for that object kind
               and version.

          ‘<unknown>’

               A member of this form appears for each of the v1 Client Stateless Query Files
               that CMake did not
               recognize.  The value is a JSON object with a single
               ‘error’ member containing a string with an error message
               indicating that the query file is unknown.

          ‘query.json’

               This member appears for clients using v1 Client Stateful Query Files.
               If the ‘query.json’ file
               failed to read or parse as a JSON object, this member is
               a JSON object with a single ‘error’ member containing a
               string with an error message.  Otherwise, this member is
               a JSON object mirroring the content of the ‘query.json’
               file.  The members are:

               ‘client’

                    A copy of the ‘query.json’ file ‘client’ member, if
                    it exists.

               ‘requests’

                    A copy of the ‘query.json’ file ‘requests’ member,
                    if it exists.

               ‘responses’

                    If the ‘query.json’ file ‘requests’ member is
                    missing or invalid, this member is a JSON object
                    with a single ‘error’ member containing a string
                    with an error message.  Otherwise, this member
                    contains a JSON array with a response for each entry
                    of the ‘requests’ array, in the same order.  Each
                    response is

                       * a JSON object with a single ‘error’ member
                         containing a string with an error message, or

                       * a v1 Reply File Reference to the
                         corresponding reply file for the requested
                         object kind and selected version.

After reading the reply index file, clients may read the other v1 Reply Files
it references.

11.2.4.1 v1 Reply File Reference
................................

The reply index file represents each reference to another reply file
using a JSON object with members:

‘kind’

     A string specifying one of the Object Kinds.

‘version’

     A JSON object with members ‘major’ and ‘minor’ specifying integer
     version components of the object kind.

‘jsonFile’

     A JSON string specifying a path relative to the reply index file to
     another JSON file containing the object.

11.2.5 v1 Reply Files
---------------------

Reply files containing specific Object Kinds are written by
CMake.  The names of these files are unspecified and must not be
interpreted by clients.  Clients must first read the v1 Reply Index File
and and follow references to the names of the desired
response objects.

Reply files (including the index file) will never be replaced by files
of the same name but different content.  This allows a client to read
the files concurrently with a running CMake that may generate a new
reply.  However, after generating a new reply CMake will attempt to
remove reply files from previous runs that it did not just write.  If a
client attempts to read a reply file referenced by the index but finds
the file missing, that means a concurrent CMake has generated a new
reply.  The client may simply start again by reading the new reply index
file.

11.3 Object Kinds
=================

The CMake file-based API reports semantic information about the build
system using the following kinds of JSON objects.  Each kind of object
is versioned independently using semantic versioning with major and
minor components.  Every kind of object has the form:

     {
       "kind": "<kind>",
       "version": { "major": 1, "minor": 0 },
       "...": {}
     }

The ‘kind’ member is a string specifying the object kind name.  The
‘version’ member is a JSON object with ‘major’ and ‘minor’ members
specifying integer components of the object kind’s version.  Additional
top-level members are specific to each object kind.

11.3.1 Object Kind “codemodel”
------------------------------

The ‘codemodel’ object kind describes the build system structure as
modeled by CMake.

There is only one ‘codemodel’ object major version, version 2.  Version
1 does not exist to avoid confusion with that from
cmake-server(7) mode.

11.3.1.1 “codemodel” version 2
..............................

‘codemodel’ object version 2 is a JSON object:

     {
       "kind": "codemodel",
       "version": { "major": 2, "minor": 2 },
       "paths": {
         "source": "/path/to/top-level-source-dir",
         "build": "/path/to/top-level-build-dir"
       },
       "configurations": [
         {
           "name": "Debug",
           "directories": [
             {
               "source": ".",
               "build": ".",
               "childIndexes": [ 1 ],
               "projectIndex": 0,
               "targetIndexes": [ 0 ],
               "hasInstallRule": true,
               "minimumCMakeVersion": {
                 "string": "3.14"
               }
             },
             {
               "source": "sub",
               "build": "sub",
               "parentIndex": 0,
               "projectIndex": 0,
               "targetIndexes": [ 1 ],
               "minimumCMakeVersion": {
                 "string": "3.14"
               }
             }
           ],
           "projects": [
             {
               "name": "MyProject",
               "directoryIndexes": [ 0, 1 ],
               "targetIndexes": [ 0, 1 ]
             }
           ],
           "targets": [
             {
               "name": "MyExecutable",
               "directoryIndex": 0,
               "projectIndex": 0,
               "jsonFile": "<file>"
             },
             {
               "name": "MyLibrary",
               "directoryIndex": 1,
               "projectIndex": 0,
               "jsonFile": "<file>"
             }
           ]
         }
       ]
     }

The members specific to ‘codemodel’ objects are:

‘paths’

     A JSON object containing members:

     ‘source’

          A string specifying the absolute path to the top-level source
          directory, represented with forward slashes.

     ‘build’

          A string specifying the absolute path to the top-level build
          directory, represented with forward slashes.

‘configurations’

     A JSON array of entries corresponding to available build
     configurations.  On single-configuration generators there is one
     entry for the value of the CMAKE_BUILD_TYPE variable.
     For multi-configuration generators there is an entry for each
     configuration listed in the CMAKE_CONFIGURATION_TYPES.
     variable.  Each entry is a JSON object containing members:

     ‘name’

          A string specifying the name of the configuration, e.g.
          ‘Debug’.

     ‘directories’

          A JSON array of entries each corresponding to a build system
          directory whose source directory contains a ‘CMakeLists.txt’
          file.  The first entry corresponds to the top-level directory.
          Each entry is a JSON object containing members:

          ‘source’

               A string specifying the path to the source directory,
               represented with forward slashes.  If the directory is
               inside the top-level source directory then the path is
               specified relative to that directory (with ‘.’ for the
               top-level source directory itself).  Otherwise the path
               is absolute.

          ‘build’

               A string specifying the path to the build directory,
               represented with forward slashes.  If the directory is
               inside the top-level build directory then the path is
               specified relative to that directory (with ‘.’ for the
               top-level build directory itself).  Otherwise the path is
               absolute.

          ‘parentIndex’

               Optional member that is present when the directory is not
               top-level.  The value is an unsigned integer 0-based
               index of another entry in the main ‘directories’ array
               that corresponds to the parent directory that added this
               directory as a subdirectory.

          ‘childIndexes’

               Optional member that is present when the directory has
               subdirectories.  The value is a JSON array of entries
               corresponding to child directories created by the
               add_subdirectory() or subdirs().
               command.  Each entry is an unsigned integer 0-based index
               of another entry in the main ‘directories’ array.

          ‘projectIndex’

               An unsigned integer 0-based index into the main
               ‘projects’ array indicating the build system project to
               which the this directory belongs.

          ‘targetIndexes’

               Optional member that is present when the directory itself
               has targets, excluding those belonging to subdirectories.
               The value is a JSON array of entries corresponding to the
               targets.  Each entry is an unsigned integer 0-based index
               into the main ‘targets’ array.

          ‘minimumCMakeVersion’

               Optional member present when a minimum required version
               of CMake is known for the directory.  This is the ‘<min>’
               version given to the most local call to the
               cmake_minimum_required(VERSION) command in the
               directory itself or one of its ancestors.  The value is a
               JSON object with one member:

               ‘string’

                    A string specifying the minimum required version in
                    the format:

                         <major>.<minor>[.<patch>[.<tweak>]][<suffix>]

                    Each component is an unsigned integer and the suffix
                    may be an arbitrary string.

          ‘hasInstallRule’

               Optional member that is present with boolean value ‘true’
               when the directory or one of its subdirectories contains
               any install() rules, i.e.  whether a ‘make
               install’ or equivalent rule is available.

     ‘projects’

          A JSON array of entries corresponding to the top-level project
          and sub-projects defined in the build system.  Each
          (sub-)project corresponds to a source directory whose
          ‘CMakeLists.txt’ file calls the project() command
          with a project name different from its parent directory.  The
          first entry corresponds to the top-level project.

          Each entry is a JSON object containing members:

          ‘name’

               A string specifying the name given to the
               project() command.

          ‘parentIndex’

               Optional member that is present when the project is not
               top-level.  The value is an unsigned integer 0-based
               index of another entry in the main ‘projects’ array that
               corresponds to the parent project that added this project
               as a sub-project.

          ‘childIndexes’

               Optional member that is present when the project has
               sub-projects.  The value is a JSON array of entries
               corresponding to the sub-projects.  Each entry is an
               unsigned integer 0-based index of another entry in the
               main ‘projects’ array.

          ‘directoryIndexes’

               A JSON array of entries corresponding to build system
               directories that are part of the project.  The first
               entry corresponds to the top-level directory of the
               project.  Each entry is an unsigned integer 0-based index
               into the main ‘directories’ array.

          ‘targetIndexes’

               Optional member that is present when the project itself
               has targets, excluding those belonging to sub-projects.
               The value is a JSON array of entries corresponding to the
               targets.  Each entry is an unsigned integer 0-based index
               into the main ‘targets’ array.

     ‘targets’

          A JSON array of entries corresponding to the build system
          targets.  Such targets are created by calls to
          add_executable(), add_library(), and
          add_custom_target(), excluding imported targets and
          interface libraries (which do not generate any build rules).
          Each entry is a JSON object containing members:

          ‘name’

               A string specifying the target name.

          ‘id’

               A string uniquely identifying the target.  This matches
               the ‘id’ field in the file referenced by ‘jsonFile’.

          ‘directoryIndex’

               An unsigned integer 0-based index into the main
               ‘directories’ array indicating the build system directory
               in which the target is defined.

          ‘projectIndex’

               An unsigned integer 0-based index into the main
               ‘projects’ array indicating the build system project in
               which the target is defined.

          ‘jsonFile’

               A JSON string specifying a path relative to the codemodel
               file to another JSON file containing a "codemodel" version 2 "target" object.

11.3.1.2 “codemodel” version 2 “target” object
..............................................

A codemodel “target” object is referenced by a "codemodel" version 2
object’s ‘targets’ array.  Each “target” object is a JSON object
with members:

‘name’

     A string specifying the logical name of the target.

‘id’

     A string uniquely identifying the target.  The format is
     unspecified and should not be interpreted by clients.

‘type’

     A string specifying the type of the target.  The value is one of
     ‘EXECUTABLE’, ‘STATIC_LIBRARY’, ‘SHARED_LIBRARY’, ‘MODULE_LIBRARY’,
     ‘OBJECT_LIBRARY’, ‘INTERFACE_LIBRARY’, or ‘UTILITY’.

‘backtrace’

     Optional member that is present when a CMake language backtrace to
     the command in the source code that created the target is
     available.  The value is an unsigned integer 0-based index into the
     ‘backtraceGraph’ member’s ‘nodes’ array.

‘folder’

     Optional member that is present when the FOLDER target
     property is set.  The value is a JSON object with one member:

     ‘name’

          A string specifying the name of the target folder.

‘paths’

     A JSON object containing members:

     ‘source’

          A string specifying the path to the target’s source directory,
          represented with forward slashes.  If the directory is inside
          the top-level source directory then the path is specified
          relative to that directory (with ‘.’ for the top-level source
          directory itself).  Otherwise the path is absolute.

     ‘build’

          A string specifying the path to the target’s build directory,
          represented with forward slashes.  If the directory is inside
          the top-level build directory then the path is specified
          relative to that directory (with ‘.’ for the top-level build
          directory itself).  Otherwise the path is absolute.

‘nameOnDisk’

     Optional member that is present for executable and library targets
     that are linked or archived into a single primary artifact.  The
     value is a string specifying the file name of that artifact on
     disk.

‘artifacts’

     Optional member that is present for executable and library targets
     that produce artifacts on disk meant for consumption by dependents.
     The value is a JSON array of entries corresponding to the
     artifacts.  Each entry is a JSON object containing one member:

     ‘path’

          A string specifying the path to the file on disk, represented
          with forward slashes.  If the file is inside the top-level
          build directory then the path is specified relative to that
          directory.  Otherwise the path is absolute.

‘isGeneratorProvided’

     Optional member that is present with boolean value ‘true’ if the
     target is provided by CMake’s build system generator rather than by
     a command in the source code.

‘install’

     Optional member that is present when the target has an
     install() rule.  The value is a JSON object with members:

     ‘prefix’

          A JSON object specifying the installation prefix.  It has one
          member:

          ‘path’

               A string specifying the value of
               CMAKE_INSTALL_PREFIX.

     ‘destinations’

          A JSON array of entries specifying an install destination
          path.  Each entry is a JSON object with members:

          ‘path’

               A string specifying the install destination path.  The
               path may be absolute or relative to the install prefix.

          ‘backtrace’

               Optional member that is present when a CMake language
               backtrace to the install() command invocation
               that specified this destination is available.  The value
               is an unsigned integer 0-based index into the
               ‘backtraceGraph’ member’s ‘nodes’ array.

‘link’

     Optional member that is present for executables and shared library
     targets that link into a runtime binary.  The value is a JSON
     object with members describing the link step:

     ‘language’

          A string specifying the language (e.g.  ‘C’, ‘CXX’, ‘Fortran’)
          of the toolchain is used to invoke the linker.

     ‘commandFragments’

          Optional member that is present when fragments of the link
          command line invocation are available.  The value is a JSON
          array of entries specifying ordered fragments.  Each entry is
          a JSON object with members:

          ‘fragment’

               A string specifying a fragment of the link command line
               invocation.  The value is encoded in the build system’s
               native shell format.

          ‘role’

               A string specifying the role of the fragment’s content:

                  * ‘flags’: link flags.

                  * ‘libraries’: link library file paths or flags.

                  * ‘libraryPath’: library search path flags.

                  * ‘frameworkPath’: macOS framework search path flags.

     ‘lto’

          Optional member that is present with boolean value ‘true’ when
          link-time optimization (a.k.a.  interprocedural optimization
          or link-time code generation) is enabled.

     ‘sysroot’

          Optional member that is present when the
          CMAKE_SYSROOT_LINK or CMAKE_SYSROOT variable
          is defined.  The value is a JSON object with one member:

          ‘path’

               A string specifying the absolute path to the sysroot,
               represented with forward slashes.

‘archive’

     Optional member that is present for static library targets.  The
     value is a JSON object with members describing the archive step:

     ‘commandFragments’

          Optional member that is present when fragments of the archiver
          command line invocation are available.  The value is a JSON
          array of entries specifying the fragments.  Each entry is a
          JSON object with members:

          ‘fragment’

               A string specifying a fragment of the archiver command
               line invocation.  The value is encoded in the build
               system’s native shell format.

          ‘role’

               A string specifying the role of the fragment’s content:

                  * ‘flags’: archiver flags.

     ‘lto’

          Optional member that is present with boolean value ‘true’ when
          link-time optimization (a.k.a.  interprocedural optimization
          or link-time code generation) is enabled.

‘dependencies’

     Optional member that is present when the target depends on other
     targets.  The value is a JSON array of entries corresponding to the
     dependencies.  Each entry is a JSON object with members:

     ‘id’

          A string uniquely identifying the target on which this target
          depends.  This matches the main ‘id’ member of the other
          target.

     ‘backtrace’

          Optional member that is present when a CMake language
          backtrace to the add_dependencies(),
          target_link_libraries(), or other command invocation that
          created this dependency is available.  The value is an
          unsigned integer 0-based index into the ‘backtraceGraph’
          member’s ‘nodes’ array.

‘sources’

     A JSON array of entries corresponding to the target’s source files.
     Each entry is a JSON object with members:

     ‘path’

          A string specifying the path to the source file on disk,
          represented with forward slashes.  If the file is inside the
          top-level source directory then the path is specified relative
          to that directory.  Otherwise the path is absolute.

     ‘compileGroupIndex’

          Optional member that is present when the source is compiled.
          The value is an unsigned integer 0-based index into the
          ‘compileGroups’ array.

     ‘sourceGroupIndex’

          Optional member that is present when the source is part of a
          source group either via the source_group() command
          or by default.  The value is an unsigned integer 0-based index
          into the ‘sourceGroups’ array.

     ‘isGenerated’

          Optional member that is present with boolean value ‘true’ if
          the source is GENERATED.

     ‘backtrace’

          Optional member that is present when a CMake language
          backtrace to the target_sources(),
          add_executable(), add_library(),
          add_custom_target(), or other command invocation that
          added this source to the target is available.  The value is an
          unsigned integer 0-based index into the ‘backtraceGraph’
          member’s ‘nodes’ array.

‘sourceGroups’

     Optional member that is present when sources are grouped together
     by the source_group() command or by default.  The value
     is a JSON array of entries corresponding to the groups.  Each entry
     is a JSON object with members:

     ‘name’

          A string specifying the name of the source group.

     ‘sourceIndexes’

          A JSON array listing the sources belonging to the group.  Each
          entry is an unsigned integer 0-based index into the main
          ‘sources’ array for the target.

‘compileGroups’

     Optional member that is present when the target has sources that
     compile.  The value is a JSON array of entries corresponding to
     groups of sources that all compile with the same settings.  Each
     entry is a JSON object with members:

     ‘sourceIndexes’

          A JSON array listing the sources belonging to the group.  Each
          entry is an unsigned integer 0-based index into the main
          ‘sources’ array for the target.

     ‘language’

          A string specifying the language (e.g.  ‘C’, ‘CXX’, ‘Fortran’)
          of the toolchain is used to compile the source file.

     ‘languageStandard’

          Optional member that is present when the language standard is
          set explicitly (e.g.  via CXX_STANDARD) or
          implicitly by compile features.  Each entry is a JSON object
          with two members:

          ‘backtraces’

               Optional member that is present when a CMake language
               backtrace to the ‘<LANG>_STANDARD’ setting is available.
               If the language standard was set implicitly by compile
               features those are used as the backtrace(s).  It’s
               possible for multiple compile features to require the
               same language standard so there could be multiple
               backtraces.  The value is a JSON array with each entry
               being an unsigned integer 0-based index into the
               ‘backtraceGraph’ member’s ‘nodes’ array.

          ‘standard’

               String representing the language standard.

          This field was added in codemodel version 2.2.

     ‘compileCommandFragments’

          Optional member that is present when fragments of the compiler
          command line invocation are available.  The value is a JSON
          array of entries specifying ordered fragments.  Each entry is
          a JSON object with one member:

          ‘fragment’

               A string specifying a fragment of the compile command
               line invocation.  The value is encoded in the build
               system’s native shell format.

     ‘includes’

          Optional member that is present when there are include
          directories.  The value is a JSON array with an entry for each
          directory.  Each entry is a JSON object with members:

          ‘path’

               A string specifying the path to the include directory,
               represented with forward slashes.

          ‘isSystem’

               Optional member that is present with boolean value ‘true’
               if the include directory is marked as a system include
               directory.

          ‘backtrace’

               Optional member that is present when a CMake language
               backtrace to the target_include_directories().
               or other command invocation that added this include
               directory is available.  The value is an unsigned integer
               0-based index into the ‘backtraceGraph’ member’s ‘nodes’
               array.

     ‘precompileHeaders’

          Optional member that is present when
          target_precompile_headers() or other command invocations
          set PRECOMPILE_HEADERS on the target.  The value
          is a JSON array with an entry for each header.  Each entry is
          a JSON object with members:

          ‘header’

               Full path to the precompile header file.

          ‘backtrace’

               Optional member that is present when a CMake language
               backtrace to the target_precompile_headers().
               or other command invocation that added this precompiled
               header is available.  The value is an unsigned integer
               0-based index into the ‘backtraceGraph’ member’s ‘nodes’
               array.

          This field was added in codemodel version 2.1.

     ‘defines’

          Optional member that is present when there are preprocessor
          definitions.  The value is a JSON array with an entry for each
          definition.  Each entry is a JSON object with members:

          ‘define’

               A string specifying the preprocessor definition in the
               format ‘<name>[=<value>]’, e.g.  ‘DEF’ or ‘DEF=1’.

          ‘backtrace’

               Optional member that is present when a CMake language
               backtrace to the target_compile_definitions().
               or other command invocation that added this preprocessor
               definition is available.  The value is an unsigned
               integer 0-based index into the ‘backtraceGraph’ member’s
               ‘nodes’ array.

     ‘sysroot’

          Optional member that is present when the
          CMAKE_SYSROOT_COMPILE or CMAKE_SYSROOT.
          variable is defined.  The value is a JSON object with one
          member:

          ‘path’

               A string specifying the absolute path to the sysroot,
               represented with forward slashes.

‘backtraceGraph’

     A JSON object describing the graph of backtraces whose nodes are
     referenced from ‘backtrace’ members elsewhere.  The members are:

     ‘nodes’

          A JSON array listing nodes in the backtrace graph.  Each entry
          is a JSON object with members:

          ‘file’

               An unsigned integer 0-based index into the backtrace
               ‘files’ array.

          ‘line’

               An optional member present when the node represents a
               line within the file.  The value is an unsigned integer
               1-based line number.

          ‘command’

               An optional member present when the node represents a
               command invocation within the file.  The value is an
               unsigned integer 0-based index into the backtrace
               ‘commands’ array.

          ‘parent’

               An optional member present when the node is not the
               bottom of the call stack.  The value is an unsigned
               integer 0-based index of another entry in the backtrace
               ‘nodes’ array.

     ‘commands’

          A JSON array listing command names referenced by backtrace
          nodes.  Each entry is a string specifying a command name.

     ‘files’

          A JSON array listing CMake language files referenced by
          backtrace nodes.  Each entry is a string specifying the path
          to a file, represented with forward slashes.  If the file is
          inside the top-level source directory then the path is
          specified relative to that directory.  Otherwise the path is
          absolute.

11.3.2 Object Kind “cache”
--------------------------

The ‘cache’ object kind lists cache entries.  These are the
Variables stored in the persistent cache (‘CMakeCache.txt’) for
the build tree.

There is only one ‘cache’ object major version, version 2.  Version 1
does not exist to avoid confusion with that from cmake-server(7)
mode.

11.3.2.1 “cache” version 2
..........................

‘cache’ object version 2 is a JSON object:

     {
       "kind": "cache",
       "version": { "major": 2, "minor": 0 },
       "entries": [
         {
           "name": "BUILD_SHARED_LIBS",
           "value": "ON",
           "type": "BOOL",
           "properties": [
             {
               "name": "HELPSTRING",
               "value": "Build shared libraries"
             }
           ]
         },
         {
           "name": "CMAKE_GENERATOR",
           "value": "Unix Makefiles",
           "type": "INTERNAL",
           "properties": [
             {
               "name": "HELPSTRING",
               "value": "Name of generator."
             }
           ]
         }
       ]
     }

The members specific to ‘cache’ objects are:

‘entries’

     A JSON array whose entries are each a JSON object specifying a
     cache entry.  The members of each entry are:

     ‘name’

          A string specifying the name of the entry.

     ‘value’

          A string specifying the value of the entry.

     ‘type’

          A string specifying the type of the entry used by
          cmake-gui(1) to choose a widget for editing.

     ‘properties’

          A JSON array of entries specifying associated cache entry properties.
          Each entry is a JSON object containing
          members:

          ‘name’

               A string specifying the name of the cache entry property.

          ‘value’

               A string specifying the value of the cache entry
               property.

11.3.3 Object Kind “cmakeFiles”
-------------------------------

The ‘cmakeFiles’ object kind lists files used by CMake while configuring
and generating the build system.  These include the ‘CMakeLists.txt’
files as well as included ‘.cmake’ files.

There is only one ‘cmakeFiles’ object major version, version 1.

11.3.3.1 “cmakeFiles” version 1
...............................

‘cmakeFiles’ object version 1 is a JSON object:

     {
       "kind": "cmakeFiles",
       "version": { "major": 1, "minor": 0 },
       "paths": {
         "build": "/path/to/top-level-build-dir",
         "source": "/path/to/top-level-source-dir"
       },
       "inputs": [
         {
           "path": "CMakeLists.txt"
         },
         {
           "isGenerated": true,
           "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
         },
         {
           "isExternal": true,
           "path": "/path/to/external/third-party/module.cmake"
         },
         {
           "isCMake": true,
           "isExternal": true,
           "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
         }
       ]
     }

The members specific to ‘cmakeFiles’ objects are:

‘paths’

     A JSON object containing members:

     ‘source’

          A string specifying the absolute path to the top-level source
          directory, represented with forward slashes.

     ‘build’

          A string specifying the absolute path to the top-level build
          directory, represented with forward slashes.

‘inputs’

     A JSON array whose entries are each a JSON object specifying an
     input file used by CMake when configuring and generating the build
     system.  The members of each entry are:

     ‘path’

          A string specifying the path to an input file to CMake,
          represented with forward slashes.  If the file is inside the
          top-level source directory then the path is specified relative
          to that directory.  Otherwise the path is absolute.

     ‘isGenerated’

          Optional member that is present with boolean value ‘true’ if
          the path specifies a file that is under the top-level build
          directory and the build is out-of-source.  This member is not
          available on in-source builds.

     ‘isExternal’

          Optional member that is present with boolean value ‘true’ if
          the path specifies a file that is not under the top-level
          source or build directories.

     ‘isCMake’

          Optional member that is present with boolean value ‘true’ if
          the path specifies a file in the CMake installation.

12 cmake-generator-expressions(7)
*********************************

12.1 Introduction
=================

Generator expressions are evaluated during build system generation to
produce information specific to each build configuration.

Generator expressions are allowed in the context of many target
properties, such as LINK_LIBRARIES,
INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and others.
They may also be used when using commands to populate those properties,
such as target_link_libraries(),
target_include_directories(), target_compile_definitions()
and others.

They enable conditional linking, conditional definitions used when
compiling, conditional include directories, and more.  The conditions
may be based on the build configuration, target properties, platform
information or any other queryable information.

Generator expressions have the form ‘$<...>’.  To avoid confusion, this
page deviates from most of the CMake documentation in that it omits
angular brackets ‘<...>’ around placeholders like ‘condition’, ‘string’,
‘target’, among others.

Generator expressions can be nested, as shown in most of the examples
below.

12.2 Boolean Generator Expressions
==================================

Boolean expressions evaluate to either ‘0’ or ‘1’.  They are typically
used to construct the condition in a conditional generator expression.

Available boolean expressions are:

12.2.1 Logical Operators
------------------------

‘$<BOOL:string>’

     Converts ‘string’ to ‘0’ or ‘1’.  Evaluates to ‘0’ if any of the
     following is true:

        * ‘string’ is empty,

        * ‘string’ is a case-insensitive equal of ‘0’, ‘FALSE’, ‘OFF’,
          ‘N’, ‘NO’, ‘IGNORE’, or ‘NOTFOUND’, or

        * ‘string’ ends in the suffix ‘-NOTFOUND’ (case-sensitive).

     Otherwise evaluates to ‘1’.

‘$<AND:conditions>’

     where ‘conditions’ is a comma-separated list of boolean
     expressions.  Evaluates to ‘1’ if all conditions are ‘1’.
     Otherwise evaluates to ‘0’.

‘$<OR:conditions>’

     where ‘conditions’ is a comma-separated list of boolean
     expressions.  Evaluates to ‘1’ if at least one of the conditions is
     ‘1’.  Otherwise evaluates to ‘0’.

‘$<NOT:condition>’

     ‘0’ if ‘condition’ is ‘1’, else ‘1’.

12.2.2 String Comparisons
-------------------------

‘$<STREQUAL:string1,string2>’

     ‘1’ if ‘string1’ and ‘string2’ are equal, else ‘0’.  The comparison
     is case-sensitive.  For a case-insensitive comparison, combine with
     a string transforming generator expression,

          $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...

‘$<EQUAL:value1,value2>’

     ‘1’ if ‘value1’ and ‘value2’ are numerically equal, else ‘0’.

‘$<IN_LIST:string,list>’

     ‘1’ if ‘string’ is member of the semicolon-separated ‘list’, else
     ‘0’.  Uses case-sensitive comparisons.

‘$<VERSION_LESS:v1,v2>’

     ‘1’ if ‘v1’ is a version less than ‘v2’, else ‘0’.

‘$<VERSION_GREATER:v1,v2>’

     ‘1’ if ‘v1’ is a version greater than ‘v2’, else ‘0’.

‘$<VERSION_EQUAL:v1,v2>’

     ‘1’ if ‘v1’ is the same version as ‘v2’, else ‘0’.

‘$<VERSION_LESS_EQUAL:v1,v2>’

     ‘1’ if ‘v1’ is a version less than or equal to ‘v2’, else ‘0’.

‘$<VERSION_GREATER_EQUAL:v1,v2>’

     ‘1’ if ‘v1’ is a version greater than or equal to ‘v2’, else ‘0’.

12.2.3 Variable Queries
-----------------------

‘$<TARGET_EXISTS:target>’

     ‘1’ if ‘target’ exists, else ‘0’.

‘$<CONFIG:cfgs>’

     ‘1’ if config is any one of the entries in ‘cfgs’, else ‘0’.  This
     is a case-insensitive comparison.  The mapping in
     MAP_IMPORTED_CONFIG_<CONFIG> is also considered by this
     expression when it is evaluated on a property on an IMPORTED
     target.

‘$<PLATFORM_ID:platform_ids>’

     where ‘platform_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     platform id matches any one of the entries in ‘platform_ids’,
     otherwise ‘0’.  See also the CMAKE_SYSTEM_NAME.
     variable.

‘$<C_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the C compiler matches any one of the entries in
     ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<CXX_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the CXX compiler matches any one of the entries in
     ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<CUDA_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the CUDA compiler matches any one of the entries in
     ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<OBJC_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the Objective-C compiler matches any one of the
     entries in ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<OBJCXX_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the Objective-C++ compiler matches any one of the
     entries in ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<Fortran_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the Fortran compiler matches any one of the entries
     in ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<ISPC_COMPILER_ID:compiler_ids>’

     where ‘compiler_ids’ is a comma-separated list.  ‘1’ if the CMake’s
     compiler id of the ISPC compiler matches any one of the entries in
     ‘compiler_ids’, otherwise ‘0’.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<C_COMPILER_VERSION:version>’

     ‘1’ if the version of the C compiler matches ‘version’, otherwise
     ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION.
     variable.

‘$<CXX_COMPILER_VERSION:version>’

     ‘1’ if the version of the CXX compiler matches ‘version’, otherwise
     ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION.
     variable.

‘$<CUDA_COMPILER_VERSION:version>’

     ‘1’ if the version of the CXX compiler matches ‘version’, otherwise
     ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION.
     variable.

‘$<OBJC_COMPILER_VERSION:version>’

     ‘1’ if the version of the OBJC compiler matches ‘version’,
     otherwise ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION
     variable.

‘$<OBJCXX_COMPILER_VERSION:version>’

     ‘1’ if the version of the OBJCXX compiler matches ‘version’,
     otherwise ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION
     variable.

‘$<Fortran_COMPILER_VERSION:version>’

     ‘1’ if the version of the Fortran compiler matches ‘version’,
     otherwise ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION
     variable.

‘$<ISPC_COMPILER_VERSION:version>’

     ‘1’ if the version of the ISPC compiler matches ‘version’,
     otherwise ‘0’.  See also the CMAKE_<LANG>_COMPILER_VERSION
     variable.

‘$<TARGET_POLICY:policy>’

     ‘1’ if the ‘policy’ was NEW when the ‘head’ target was created,
     else ‘0’.  If the ‘policy’ was not set, the warning message for the
     policy will be emitted.  This generator expression only works for a
     subset of policies.

‘$<COMPILE_FEATURES:features>’

     where ‘features’ is a comma-spearated list.  Evaluates to ‘1’ if
     all of the ‘features’ are available for the ‘head’ target, and ‘0’
     otherwise.  If this expression is used while evaluating the link
     implementation of a target and if any dependency transitively
     increases the required C_STANDARD or
     CXX_STANDARD for the ‘head’ target, an error is reported.
     See the cmake-compile-features(7) manual for
     information on compile features and a list of supported compilers.

‘$<COMPILE_LANG_AND_ID:language,compiler_ids>’

     ‘1’ when the language used for compilation unit matches ‘language’
     and the CMake’s compiler id of the language compiler matches any
     one of the entries in ‘compiler_ids’, otherwise ‘0’.  This
     expression is a short form for the combination of
     ‘$<COMPILE_LANGUAGE:language>’ and
     ‘$<LANG_COMPILER_ID:compiler_ids>’.  This expression may be used to
     specify compile options, compile definitions, and include
     directories for source files of a particular language and compiler
     combination in a target.  For example:

          add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
          target_compile_definitions(myapp
            PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
                    $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
                    $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
          )

     This specifies the use of different compile definitions based on
     both the compiler id and compilation language.  This example will
     have a ‘COMPILING_CXX_WITH_CLANG’ compile definition when Clang is
     the CXX compiler, and ‘COMPILING_CXX_WITH_INTEL’ when Intel is the
     CXX compiler.  Likewise when the C compiler is Clang it will only
     see the ‘COMPILING_C_WITH_CLANG’ definition.

     Without the ‘COMPILE_LANG_AND_ID’ generator expression the same
     logic would be expressed as:

          target_compile_definitions(myapp
            PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
                    $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
                    $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
          )

‘$<COMPILE_LANGUAGE:languages>’

     ‘1’ when the language used for compilation unit matches any of the
     entries in ‘languages’, otherwise ‘0’.  This expression may be used
     to specify compile options, compile definitions, and include
     directories for source files of a particular language in a target.
     For example:

          add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
          target_compile_options(myapp
            PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
          )
          target_compile_definitions(myapp
            PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
                    $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
          )
          target_include_directories(myapp
            PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
          )

     This specifies the use of the ‘-fno-exceptions’ compile option,
     ‘COMPILING_CXX’ compile definition, and ‘cxx_headers’ include
     directory for C++ only (compiler id checks elided).  It also
     specifies a ‘COMPILING_CUDA’ compile definition for CUDA.

     Note that with Visual Studio Generators and
     Xcode there is no way to represent target-wide compile
     definitions or include directories separately for ‘C’ and ‘CXX’
     languages.  Also, with Visual Studio Generators there
     is no way to represent target-wide flags separately for ‘C’ and
     ‘CXX’ languages.  Under these generators, expressions for both C
     and C++ sources will be evaluated using ‘CXX’ if there are any C++
     sources and otherwise using ‘C’.  A workaround is to create
     separate libraries for each source file language instead:

          add_library(myapp_c foo.c)
          add_library(myapp_cxx bar.cpp)
          target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
          add_executable(myapp main.cpp)
          target_link_libraries(myapp myapp_c myapp_cxx)

‘$<LINK_LANG_AND_ID:language,compiler_ids>’

     ‘1’ when the language used for link step matches ‘language’ and the
     CMake’s compiler id of the language linker matches any one of the
     entries in ‘compiler_ids’, otherwise ‘0’.  This expression is a
     short form for the combination of ‘$<LINK_LANGUAGE:language>’ and
     ‘$<LANG_COMPILER_ID:compiler_ids>’.  This expression may be used to
     specify link libraries, link options, link directories and link
     dependencies of a particular language and linker combination in a
     target.  For example:

          add_library(libC_Clang ...)
          add_library(libCXX_Clang ...)
          add_library(libC_Intel ...)
          add_library(libCXX_Intel ...)

          add_executable(myapp main.c)
          if (CXX_CONFIG)
            target_sources(myapp PRIVATE file.cxx)
          endif()
          target_link_libraries(myapp
            PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
                    $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
                    $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
                    $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)

     This specifies the use of different link libraries based on both
     the compiler id and link language.  This example will have target
     ‘libCXX_Clang’ as link dependency when ‘Clang’ or ‘AppleClang’ is
     the ‘CXX’ linker, and ‘libCXX_Intel’ when ‘Intel’ is the ‘CXX’
     linker.  Likewise when the ‘C’ linker is ‘Clang’ or ‘AppleClang’,
     target ‘libC_Clang’ will be added as link dependency and
     ‘libC_Intel’ when ‘Intel’ is the ‘C’ linker.

     See the note related to. ‘$<LINK_LANGUAGE:language>’ for
     constraints about the usage of this generator expression.

‘$<LINK_LANGUAGE:languages>’

     ‘1’ when the language used for link step matches any of the entries
     in ‘languages’, otherwise ‘0’.  This expression may be used to
     specify link libraries, link options, link directories and link
     dependencies of a particular language in a target.  For example:

          add_library(api_C ...)
          add_library(api_CXX ...)
          add_library(api INTERFACE)
          target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
                                              $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
          target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
                                              $<$<LINK_LANGUAGE:CXX>:api_CXX>)

          add_executable(myapp1 main.c)
          target_link_options(myapp1 PRIVATE api)

          add_executable(myapp2 main.cpp)
          target_link_options(myapp2 PRIVATE api)

     This specifies to use the ‘api’ target for linking targets ‘myapp1’
     and ‘myapp2’.  In practice, ‘myapp1’ will link with target ‘api_C’
     and option ‘-opt_c’ because it will use ‘C’ as link language.  And
     ‘myapp2’ will link with ‘api_CXX’ and option ‘-opt_cxx’ because
     ‘CXX’ will be the link language.
          Note: To determine the link language of a target, it is
          required to collect, transitively, all the targets which will
          be linked to it.  So, for link libraries properties, a double
          evaluation will be done.  During the first evaluation,
          ‘$<LINK_LANGUAGE:..>’ expressions will always return ‘0’.  The
          link language computed after this first pass will be used to
          do the second pass.  To avoid inconsistency, it is required
          that the second pass do not change the link language.
          Moreover, to avoid unexpected side-effects, it is required to
          specify complete entities as part of the ‘$<LINK_LANGUAGE:..>’
          expression.  For example:

               add_library(lib STATIC file.cxx)
               add_library(libother STATIC file.c)

               # bad usage
               add_executable(myapp1 main.c)
               target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)

               # correct usage
               add_executable(myapp2 main.c)
               target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)

          In this example, for ‘myapp1’, the first pass will,
          unexpectedly, determine that the link language is ‘CXX’
          because the evaluation of the generator expression will be an
          empty string so ‘myapp1’ will depends on target ‘lib’ which is
          ‘C++’.  On the contrary, for ‘myapp2’, the first evaluation
          will give ‘C’ as link language, so the second pass will
          correctly add target ‘libother’ as link dependency.

‘$<DEVICE_LINK:list>’

     Returns the list if it is the device link step, an empty list
     otherwise.  The device link step is controlled by
     CUDA_SEPARABLE_COMPILATION and
     CUDA_RESOLVE_DEVICE_SYMBOLS properties and policy
     CMP0105.  This expression can only be used to specify link
     options.

‘$<HOST_LINK:list>’

     Returns the list if it is the normal link step, an empty list
     otherwise.  This expression is mainly useful when a device link
     step is also involved (see ‘$<DEVICE_LINK:list>’ generator
     expression).  This expression can only be used to specify link
     options.

12.3 String-Valued Generator Expressions
========================================

These expressions expand to some string.  For example,

     include_directories(/usr/include/$<CXX_COMPILER_ID>/)

expands to ‘/usr/include/GNU/’ or ‘/usr/include/Clang/’ etc, depending
on the compiler identifier.

String-valued expressions may also be combined with other expressions.
Here an example for a string-valued expression within a boolean
expressions within a conditional expression:

     $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>

expands to ‘OLD_COMPILER’ if the CMAKE_CXX_COMPILER_VERSION.
is less than 4.2.0.

And here two nested string-valued expressions:

     -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>

generates a string of the entries in the INCLUDE_DIRECTORIES.
target property with each entry preceded by ‘-I’.

Expanding on the previous example, if one first wants to check if the
‘INCLUDE_DIRECTORIES’ property is non-empty, then it is advisable to
introduce a helper variable to keep the code readable:

     set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
     $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>>

The following string-valued generator expressions are available:

12.3.1 Escaped Characters
-------------------------

String literals to escape the special meaning a character would
otherwise have:

‘$<ANGLE-R>’

     A literal ‘>’.  Used for example to compare strings that contain a
     ‘>’.

‘$<COMMA>’

     A literal ‘,’.  Used for example to compare strings which contain a
     ‘,’.

‘$<SEMICOLON>’

     A literal ‘;’.  Used to prevent list expansion on an argument with
     ‘;’.

12.3.2 Conditional Expressions
------------------------------

Conditional generator expressions depend on a boolean condition that
must be ‘0’ or ‘1’.

‘$<condition:true_string>’

     Evaluates to ‘true_string’ if ‘condition’ is ‘1’.  Otherwise
     evaluates to the empty string.

‘$<IF:condition,true_string,false_string>’

     Evaluates to ‘true_string’ if ‘condition’ is ‘1’.  Otherwise
     evaluates to ‘false_string’.

Typically, the ‘condition’ is a boolean generator expression.
For instance,

     $<$<CONFIG:Debug>:DEBUG_MODE>

expands to ‘DEBUG_MODE’ when the ‘Debug’ configuration is used, and
otherwise expands to the empty string.

12.3.3 String Transformations
-----------------------------

‘$<JOIN:list,string>’

     Joins the list with the content of ‘string’.

‘$<REMOVE_DUPLICATES:list>’

     Removes duplicated items in the given ‘list’.

‘$<FILTER:list,INCLUDE|EXCLUDE,regex>’

     Includes or removes items from ‘list’ that match the regular
     expression ‘regex’.

‘$<LOWER_CASE:string>’

     Content of ‘string’ converted to lower case.

‘$<UPPER_CASE:string>’

     Content of ‘string’ converted to upper case.

‘$<GENEX_EVAL:expr>’

     Content of ‘expr’ evaluated as a generator expression in the
     current context.  This enables consumption of generator expressions
     whose evaluation results itself in generator expressions.

‘$<TARGET_GENEX_EVAL:tgt,expr>’

     Content of ‘expr’ evaluated as a generator expression in the
     context of ‘tgt’ target.  This enables consumption of custom target
     properties that themselves contain generator expressions.

     Having the capability to evaluate generator expressions is very
     useful when you want to manage custom properties supporting
     generator expressions.  For example:

          add_library(foo ...)

          set_property(TARGET foo PROPERTY
            CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
          )

          add_custom_target(printFooKeys
            COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
          )

     This naive implementation of the ‘printFooKeys’ custom command is
     wrong because ‘CUSTOM_KEYS’ target property is not evaluated and
     the content is passed as is (i.e.
     ‘$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>’).

     To have the expected result (i.e.  ‘FOO_EXTRA_THINGS’ if config is
     ‘Debug’), it is required to evaluate the output of
     ‘$<TARGET_PROPERTY:foo,CUSTOM_KEYS>’:

          add_custom_target(printFooKeys
            COMMAND ${CMAKE_COMMAND} -E
              echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
          )

12.3.4 Variable Queries
-----------------------

‘$<CONFIG>’

     Configuration name.

‘$<CONFIGURATION>’

     Configuration name.  Deprecated since CMake 3.0.  Use ‘CONFIG’
     instead.

‘$<PLATFORM_ID>’

     The current system’s CMake platform id.  See also the
     CMAKE_SYSTEM_NAME variable.

‘$<C_COMPILER_ID>’

     The CMake’s compiler id of the C compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<CXX_COMPILER_ID>’

     The CMake’s compiler id of the CXX compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<CUDA_COMPILER_ID>’

     The CMake’s compiler id of the CUDA compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<OBJC_COMPILER_ID>’

     The CMake’s compiler id of the OBJC compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<OBJCXX_COMPILER_ID>’

     The CMake’s compiler id of the OBJCXX compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<Fortran_COMPILER_ID>’

     The CMake’s compiler id of the Fortran compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<ISPC_COMPILER_ID>’

     The CMake’s compiler id of the ISPC compiler used.  See also the
     CMAKE_<LANG>_COMPILER_ID variable.

‘$<C_COMPILER_VERSION>’

     The version of the C compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<CXX_COMPILER_VERSION>’

     The version of the CXX compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<CUDA_COMPILER_VERSION>’

     The version of the CUDA compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<OBJC_COMPILER_VERSION>’

     The version of the OBJC compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<OBJCXX_COMPILER_VERSION>’

     The version of the OBJCXX compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<Fortran_COMPILER_VERSION>’

     The version of the Fortran compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<ISPC_COMPILER_VERSION>’

     The version of the ISPC compiler used.  See also the
     CMAKE_<LANG>_COMPILER_VERSION variable.

‘$<COMPILE_LANGUAGE>’

     The compile language of source files when evaluating compile
     options.  See the related boolean expression.
     ‘$<COMPILE_LANGUAGE:language>’ for notes about the portability of
     this generator expression.

‘$<LINK_LANGUAGE>’

     The link language of target when evaluating link options.  See
     the related boolean expression.
     ‘$<LINK_LANGUAGE:language>’ for notes about the portability of this
     generator expression.

          Note: This generator expression is not supported by the link
          libraries properties to avoid side-effects due to the double
          evaluation of these properties.

12.3.5 Target-Dependent Queries
-------------------------------

These queries refer to a target ‘tgt’.  This can be any runtime
artifact, namely:

   * an executable target created by add_executable().

   * a shared library target (‘.so’, ‘.dll’ but not their ‘.lib’ import
     library) created by add_library().

   * a static library target created by add_library().

In the following, “the ‘tgt’ filename” means the name of the ‘tgt’
binary file.  This has to be distinguished from “the target name”, which
is just the string ‘tgt’.

‘$<TARGET_NAME_IF_EXISTS:tgt>’

     The target name ‘tgt’ if the target exists, an empty string
     otherwise.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_FILE:tgt>’

     Full path to the ‘tgt’ binary file.

‘$<TARGET_FILE_BASE_NAME:tgt>’

     Base name of ‘tgt’, i.e.  ‘$<TARGET_FILE_NAME:tgt>’ without prefix
     and suffix.  For example, if the ‘tgt’ filename is ‘libbase.so’,
     the base name is ‘base’.

     See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
     see LIBRARY_OUTPUT_NAME and RUNTIME_OUTPUT_NAME
     target properties and their configuration specific variants
     OUTPUT_NAME_<CONFIG>,
     ARCHIVE_OUTPUT_NAME_<CONFIG>,
     LIBRARY_OUTPUT_NAME_<CONFIG> and
     RUNTIME_OUTPUT_NAME_<CONFIG>.

     The <CONFIG>_POSTFIX and DEBUG_POSTFIX.
     target properties can also be considered.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_FILE_PREFIX:tgt>’

     Prefix of the ‘tgt’ filename (such as ‘lib’).

     See also the PREFIX target property.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_FILE_SUFFIX:tgt>’

     Suffix of the ‘tgt’ filename (extension such as ‘.so’ or ‘.exe’).

     See also the SUFFIX target property.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_FILE_NAME:tgt>’

     The ‘tgt’ filename.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_FILE_DIR:tgt>’

     Directory of the ‘tgt’ binary file.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_LINKER_FILE:tgt>’

     File used when linking to the ‘tgt’ target.  This will usually be
     the library that ‘tgt’ represents (‘.a’, ‘.lib’, ‘.so’), but for a
     shared library on DLL platforms, it would be the ‘.lib’ import
     library associated with the DLL.

‘$<TARGET_LINKER_FILE_BASE_NAME:tgt>’

     Base name of file used to link the target ‘tgt’, i.e.
     ‘$<TARGET_LINKER_FILE_NAME:tgt>’ without prefix and suffix.  For
     example, if target file name is ‘libbase.a’, the base name is
     ‘base’.

     See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
     and LIBRARY_OUTPUT_NAME target properties and
     their configuration specific variants OUTPUT_NAME_<CONFIG>,
     see ARCHIVE_OUTPUT_NAME_<CONFIG> and
     LIBRARY_OUTPUT_NAME_<CONFIG>.

     The <CONFIG>_POSTFIX and DEBUG_POSTFIX.
     target properties can also be considered.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_LINKER_FILE_PREFIX:tgt>’

     Prefix of file used to link target ‘tgt’.

     See also the PREFIX and IMPORT_PREFIX target
     properties.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_LINKER_FILE_SUFFIX:tgt>’

     Suffix of file used to link where ‘tgt’ is the name of a target.

     The suffix corresponds to the file extension (such as “.so” or
     “.lib”).

     See also the SUFFIX and IMPORT_SUFFIX target
     properties.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_LINKER_FILE_NAME:tgt>’

     Name of file used to link target ‘tgt’.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_LINKER_FILE_DIR:tgt>’

     Directory of file used to link target ‘tgt’.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_SONAME_FILE:tgt>’

     File with soname (‘.so.3’) where ‘tgt’ is the name of a target.

‘$<TARGET_SONAME_FILE_NAME:tgt>’

     Name of file with soname (‘.so.3’).

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_SONAME_FILE_DIR:tgt>’

     Directory of with soname (‘.so.3’).

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_PDB_FILE:tgt>’

     Full path to the linker generated program database file (.pdb)
     where ‘tgt’ is the name of a target.

     See also the PDB_NAME and PDB_OUTPUT_DIRECTORY
     target properties and their configuration specific variants
     PDB_NAME_<CONFIG> and
     PDB_OUTPUT_DIRECTORY_<CONFIG>.

‘$<TARGET_PDB_FILE_BASE_NAME:tgt>’

     Base name of the linker generated program database file (.pdb)
     where ‘tgt’ is the name of a target.

     The base name corresponds to the target PDB file name (see
     ‘$<TARGET_PDB_FILE_NAME:tgt>’) without prefix and suffix.  For
     example, if target file name is ‘base.pdb’, the base name is
     ‘base’.

     See also the PDB_NAME target property and its
     configuration specific variant PDB_NAME_<CONFIG>.

     The <CONFIG>_POSTFIX and DEBUG_POSTFIX.
     target properties can also be considered.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_PDB_FILE_NAME:tgt>’

     Name of the linker generated program database file (.pdb).

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_PDB_FILE_DIR:tgt>’

     Directory of the linker generated program database file (.pdb).

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_BUNDLE_DIR:tgt>’

     Full path to the bundle directory (‘my.app’, ‘my.framework’, or
     ‘my.bundle’) where ‘tgt’ is the name of a target.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_BUNDLE_CONTENT_DIR:tgt>’

     Full path to the bundle content directory where ‘tgt’ is the name
     of a target.  For the macOS SDK it leads to ‘my.app/Contents’,
     ‘my.framework’, or ‘my.bundle/Contents’.  For all other SDKs (e.g.
     iOS) it leads to ‘my.app’, ‘my.framework’, or ‘my.bundle’ due to
     the flat bundle structure.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on (see policy CMP0112).

‘$<TARGET_PROPERTY:tgt,prop>’

     Value of the property ‘prop’ on the target ‘tgt’.

     Note that ‘tgt’ is not added as a dependency of the target this
     expression is evaluated on.

‘$<TARGET_PROPERTY:prop>’

     Value of the property ‘prop’ on the target for which the expression
     is being evaluated.  Note that for generator expressions in
     Transitive Usage Requirements this is the consuming target
     rather than the target specifying the requirement.

‘$<INSTALL_PREFIX>’

     Content of the install prefix when the target is exported via
     install(EXPORT), or when evaluated in INSTALL_NAME_DIR,
     and empty otherwise.

12.3.6 Output-Related Expressions
---------------------------------

‘$<TARGET_NAME:...>’

     Marks ‘...’ as being the name of a target.  This is required if
     exporting targets to multiple dependent export sets.  The ‘...’
     must be a literal name of a target- it may not contain generator
     expressions.

‘$<LINK_ONLY:...>’

     Content of ‘...’ except when evaluated in a link interface while
     propagating Transitive Usage Requirements, in which case
     it is the empty string.  Intended for use only in an
     INTERFACE_LINK_LIBRARIES target property, perhaps via the
     target_link_libraries() command, to specify private link
     dependencies without other usage requirements.

‘$<INSTALL_INTERFACE:...>’

     Content of ‘...’ when the property is exported using
     install(EXPORT), and empty otherwise.

‘$<BUILD_INTERFACE:...>’

     Content of ‘...’ when the property is exported using
     export(), or when the target is used by another target in the
     same buildsystem.  Expands to the empty string otherwise.

‘$<MAKE_C_IDENTIFIER:...>’

     Content of ‘...’ converted to a C identifier.  The conversion
     follows the same behavior as string(MAKE_C_IDENTIFIER).

‘$<TARGET_OBJECTS:objLib>’

     List of objects resulting from build of ‘objLib’.

‘$<SHELL_PATH:...>’

     Content of ‘...’ converted to shell path style.  For example,
     slashes are converted to backslashes in Windows shells and drive
     letters are converted to posix paths in MSYS shells.  The ‘...’
     must be an absolute path.  The ‘...’ may be a
     semicolon-separated list of paths, in which case each path is
     converted individually and a result list is generated using the
     shell path separator (‘:’ on POSIX and ‘;’ on Windows).  Be sure to
     enclose the argument containing this genex in double quotes in
     CMake source code so that ‘;’ does not split arguments.

12.4 Debugging
==============

Since generator expressions are evaluated during generation of the
buildsystem, and not during processing of ‘CMakeLists.txt’ files, it is
not possible to inspect their result with the message().
command.

One possible way to generate debug messages is to add a custom target,

     add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")

The shell command ‘make genexdebug’ (invoked after execution of ‘cmake’)
would then print the result of ‘$<...>’.

Another way is to write debug messages to a file:

     file(GENERATE OUTPUT filename CONTENT "$<...>")

13 cmake-generators(7)
**********************

13.1 Introduction
=================

A `CMake Generator' is responsible for writing the input files for a
native build system.  Exactly one of the CMake Generators.
must be selected for a build tree to determine what native build system
is to be used.  Optionally one of the Extra Generators may
be selected as a variant of some of the Command-Line Build Tool Generators
to produce project files for an auxiliary IDE.

CMake Generators are platform-specific so each may be available only on
certain platforms.  The cmake(1) command-line tool ‘--help’
output lists available generators on the current platform.  Use its ‘-G’
option to specify the generator for a new build tree.  The
cmake-gui(1) offers interactive selection of a generator when
creating a new build tree.

13.2 CMake Generators
=====================

13.2.1 Command-Line Build Tool Generators
-----------------------------------------

These generators support command-line build tools.  In order to use
them, one must launch CMake from a command-line prompt whose environment
is already configured for the chosen compiler and build tool.

13.2.1.1 Makefile Generators
............................

13.2.1.2 Borland Makefiles
..........................

Generates Borland makefiles.

13.2.1.3 MSYS Makefiles
.......................

Generates makefiles for use with MSYS (Minimal SYStem) ‘make’ under the
MSYS shell.

Use this generator in a MSYS shell prompt and using ‘make’ as the build
tool.  The generated makefiles use ‘/bin/sh’ as the shell to launch
build rules.  They are not compatible with a Windows command prompt.

To build under a Windows command prompt, use the MinGW Makefiles
generator.

13.2.1.4 MinGW Makefiles
........................

Generates makefiles for use with ‘mingw32-make’ under a Windows command
prompt.

Use this generator under a Windows command prompt with MinGW (Minimalist
GNU for Windows) in the ‘PATH’ and using ‘mingw32-make’ as the build
tool.  The generated makefiles use ‘cmd.exe’ as the shell to launch
build rules.  They are not compatible with MSYS or a unix shell.

To build under the MSYS shell, use the MSYS Makefiles.
generator.

13.2.1.5 NMake Makefiles
........................

Generates NMake makefiles.

13.2.1.6 NMake Makefiles JOM
............................

Generates JOM makefiles.

13.2.1.7 Unix Makefiles
.......................

Generates standard UNIX makefiles.

A hierarchy of UNIX makefiles is generated into the build tree.  Use any
standard UNIX-style make program to build the project through the ‘all’
target and install the project through the ‘install’ (or
‘install/strip’) target.

For each subdirectory ‘sub/dir’ of the project a UNIX makefile will be
created, containing the following targets:

‘all’

     Depends on all targets required by the subdirectory.

‘install’

     Runs the install step in the subdirectory, if any.

‘install/strip’

     Runs the install step in the subdirectory followed by a
     ‘CMAKE_STRIP’ command, if any.

     The ‘CMAKE_STRIP’ variable will contain the platform’s ‘strip’
     utility, which removes symbols information from generated binaries.

‘test’

     Runs the test step in the subdirectory, if any.

‘package’

     Runs the package step in the subdirectory, if any.

13.2.1.8 Watcom WMake
.....................

Generates Watcom WMake makefiles.

13.2.1.9 Ninja Generators
.........................

13.2.1.10 Ninja
...............

Generates ‘build.ninja’ files.

A ‘build.ninja’ file is generated into the build tree.  Use the ninja
program to build the project through the ‘all’ target and install the
project through the ‘install’ (or ‘install/strip’) target.

For each subdirectory ‘sub/dir’ of the project, additional targets are
generated:

‘sub/dir/all’

     Depends on all targets required by the subdirectory.

‘sub/dir/install’

     Runs the install step in the subdirectory, if any.

‘sub/dir/install/strip’

     Runs the install step in the subdirectory followed by a
     ‘CMAKE_STRIP’ command, if any.

     The ‘CMAKE_STRIP’ variable will contain the platform’s ‘strip’
     utility, which removes symbols information from generated binaries.

‘sub/dir/test’

     Runs the test step in the subdirectory, if any.

‘sub/dir/package’

     Runs the package step in the subdirectory, if any.

13.2.1.11 Fortran Support
.........................

The ‘Ninja’ generator conditionally supports Fortran when the ‘ninja’
tool is at least version 1.10 (which has the required features).

13.2.1.12 See Also
..................

The Ninja Multi-Config generator is similar to the ‘Ninja’
generator, but generates multiple configurations at once.

13.2.1.13 Ninja Multi-Config
............................

New in version 3.17.

Generates multiple ‘build-<Config>.ninja’ files.

This generator is very much like the Ninja generator, but
with some key differences.  Only these differences will be discussed in
this document.

Unlike the Ninja generator, ‘Ninja Multi-Config’ generates
multiple configurations at once with CMAKE_CONFIGURATION_TYPES
instead of only one configuration with CMAKE_BUILD_TYPE.
One ‘build-<Config>.ninja’ file will be generated for each of these
configurations (with ‘<Config>’ being the configuration name.)  These
files are intended to be run with ‘ninja -f build-<Config>.ninja’.  A
‘build.ninja’ file is also generated, using the configuration from
either CMAKE_DEFAULT_BUILD_TYPE or the first item from
CMAKE_CONFIGURATION_TYPES.

‘cmake --build . --config <Config>’ will always use
‘build-<Config>.ninja’ to build.  If no ‘--config’ argument is
specified, ‘cmake --build .’ will use ‘build.ninja’.

Each ‘build-<Config>.ninja’ file contains ‘<target>’ targets as well as
‘<target>:<Config>’ targets, where ‘<Config>’ is the same as the
configuration specified in ‘build-<Config>.ninja’ Additionally, if
cross-config mode is enabled, ‘build-<Config>.ninja’ may contain
‘<target>:<OtherConfig>’ targets, where ‘<OtherConfig>’ is a
cross-config, as well as ‘<target>:all’, which builds the target in all
cross-configs.  See below for how to enable cross-config mode.

The ‘Ninja Multi-Config’ generator recognizes the following variables:

CMAKE_CONFIGURATION_TYPES.

     Specifies the total set of configurations to build.

See CMAKE_CROSS_CONFIGS.

     Specifies a semicolon-separated list of configurations
     available from all ‘build-<Config>.ninja’ files.

See CMAKE_DEFAULT_BUILD_TYPE.

     Specifies the configuration to use by default in a ‘build.ninja’
     file.

See CMAKE_DEFAULT_CONFIGS.

     Specifies a semicolon-separated list of configurations
     to build for a target in ‘build.ninja’ if no ‘:<Config>’ suffix is
     specified.

Consider the following example:

     cmake_minimum_required(VERSION 3.16)
     project(MultiConfigNinja C)

     add_executable(generator generator.c)
     add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
     add_library(generated ${CMAKE_BINARY_DIR}/generated.c)

Now assume you configure the project with ‘Ninja Multi-Config’ and run
one of the following commands:

     ninja -f build-Debug.ninja generated
     # OR
     cmake --build . --config Debug --target generated

This would build the ‘Debug’ configuration of ‘generator’, which would
be used to generate ‘generated.c’, which would be used to build the
‘Debug’ configuration of ‘generated’.

But if CMAKE_CROSS_CONFIGS is set to ‘all’, and you run the
following instead:

     ninja -f build-Release.ninja generated:Debug
     # OR
     cmake --build . --config Release --target generated:Debug

This would build the ‘Release’ configuration of ‘generator’, which would
be used to generate ‘generated.c’, which would be used to build the
‘Debug’ configuration of ‘generated’.  This is useful for running a
release-optimized version of a generator utility while still building
the debug version of the targets built with the generated code.

13.2.2 IDE Build Tool Generators
--------------------------------

These generators support Integrated Development Environment (IDE)
project files.  Since the IDEs configure their own environment one may
launch CMake from any environment.

13.2.2.1 Visual Studio Generators
.................................

13.2.2.2 Visual Studio 6
........................

Removed.  This once generated Visual Studio 6 project files, but the
generator has been removed since CMake 3.6.  It is still possible to
build with VS 6 tools using the NMake Makefiles generator.

13.2.2.3 Visual Studio 7
........................

Removed.  This once generated Visual Studio .NET 2002 project files, but
the generator has been removed since CMake 3.6.  It is still possible to
build with VS 7.0 tools using the NMake Makefiles generator.

13.2.2.4 Visual Studio 7 .NET 2003
..................................

Removed.  This once generated Visual Studio .NET 2003 project files, but
the generator has been removed since CMake 3.9.  It is still possible to
build with VS 7.1 tools using the NMake Makefiles generator.

13.2.2.5 Visual Studio 8 2005
.............................

Removed.  This once generated Visual Studio 8 2005 project files, but
the generator has been removed since CMake 3.12.  It is still possible
to build with VS 2005 tools using the NMake Makefiles.
generator.

13.2.2.6 Visual Studio 9 2008
.............................

Generates Visual Studio 9 2008 project files.

13.2.2.7 Platform Selection
...........................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 9 2008" -A Win32’

   * ‘cmake -G "Visual Studio 9 2008" -A x64’

   * ‘cmake -G "Visual Studio 9 2008" -A Itanium’

   * ‘cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>’ (Specify a target
     platform matching a Windows CE SDK name.)

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 9 2008 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 9 2008 IA64’

     Specify target platform ‘Itanium’.

‘Visual Studio 9 2008 <WinCE-SDK>’

     Specify target platform matching a Windows CE SDK name.

13.2.2.8 Visual Studio 10 2010
..............................

Generates Visual Studio 10 (VS 2010) project files.

For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name ‘Visual Studio 10’ without the year component.

13.2.2.9 Project Types
......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (Database, Website, etc.)  are not supported.

13.2.2.10 Platform Selection
............................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 10 2010" -A Win32’

   * ‘cmake -G "Visual Studio 10 2010" -A x64’

   * ‘cmake -G "Visual Studio 10 2010" -A Itanium’

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 10 2010 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 10 2010 IA64’

     Specify target platform ‘Itanium’.

13.2.2.11 Toolset Selection
...........................

The ‘v100’ toolset that comes with Visual Studio 10 2010 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

13.2.2.12 Visual Studio 11 2012
...............................

Generates Visual Studio 11 (VS 2012) project files.

For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name “Visual Studio 11” without the year component.

13.2.2.13 Project Types
.......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (JavaScript, Database, Website, etc.)  are not supported.

13.2.2.14 Platform Selection
............................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 11 2012" -A Win32’

   * ‘cmake -G "Visual Studio 11 2012" -A x64’

   * ‘cmake -G "Visual Studio 11 2012" -A ARM’

   * ‘cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>’ (Specify a target
     platform matching a Windows CE SDK name.)

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 11 2012 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 11 2012 ARM’

     Specify target platform ‘ARM’.

‘Visual Studio 11 2012 <WinCE-SDK>’

     Specify target platform matching a Windows CE SDK name.

13.2.2.15 Toolset Selection
...........................

The ‘v110’ toolset that comes with Visual Studio 11 2012 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

13.2.2.16 Visual Studio 12 2013
...............................

Generates Visual Studio 12 (VS 2013) project files.

For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name “Visual Studio 12” without the year component.

13.2.2.17 Project Types
.......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (JavaScript, Powershell, Python, etc.)  are not supported.

13.2.2.18 Platform Selection
............................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 12 2013" -A Win32’

   * ‘cmake -G "Visual Studio 12 2013" -A x64’

   * ‘cmake -G "Visual Studio 12 2013" -A ARM’

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 12 2013 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 12 2013 ARM’

     Specify target platform ‘ARM’.

13.2.2.19 Toolset Selection
...........................

The ‘v120’ toolset that comes with Visual Studio 12 2013 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

For each toolset that comes with this version of Visual Studio, there
are variants that are themselves compiled for 32-bit (‘x86’) and 64-bit
(‘x64’) hosts (independent of the architecture they target).  By default
this generator uses the 32-bit variant even on a 64-bit host.  One may
explicitly request use of either the 32-bit or 64-bit host tools by
adding either ‘host=x86’ or ‘host=x64’ to the toolset specification.
See the CMAKE_GENERATOR_TOOLSET variable for details.

13.2.2.20 Visual Studio 14 2015
...............................

New in version 3.1.

Generates Visual Studio 14 (VS 2015) project files.

13.2.2.21 Project Types
.......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (JavaScript, Powershell, Python, etc.)  are not supported.

13.2.2.22 Platform Selection
............................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 14 2015" -A Win32’

   * ‘cmake -G "Visual Studio 14 2015" -A x64’

   * ‘cmake -G "Visual Studio 14 2015" -A ARM’

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 14 2015 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 14 2015 ARM’

     Specify target platform ‘ARM’.

13.2.2.23 Toolset Selection
...........................

The ‘v140’ toolset that comes with Visual Studio 14 2015 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

For each toolset that comes with this version of Visual Studio, there
are variants that are themselves compiled for 32-bit (‘x86’) and 64-bit
(‘x64’) hosts (independent of the architecture they target).  By default
this generator uses the 32-bit variant even on a 64-bit host.  One may
explicitly request use of either the 32-bit or 64-bit host tools by
adding either ‘host=x86’ or ‘host=x64’ to the toolset specification.
See the CMAKE_GENERATOR_TOOLSET variable for details.

13.2.2.24 Windows 10 SDK Maximum Version for VS 2015
....................................................

Microsoft stated in a “Windows 10 October 2018 Update” blog post that
Windows 10 SDK versions (15063, 16299, 17134, 17763) are not supported
by VS 2015 and are only supported by VS 2017 and later.  Therefore by
default CMake automatically ignores Windows 10 SDKs beyond
‘10.0.14393.0’.

However, there are other recommendations for certain driver/Win32 builds
that indicate otherwise.  A user can override this behavior by either
setting the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.
to a false value or setting the
CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM to the string
value of the required maximum (e.g.  ‘10.0.15063.0’).

13.2.2.25 Visual Studio 15 2017
...............................

New in version 3.7.1.

Generates Visual Studio 15 (VS 2017) project files.

13.2.2.26 Project Types
.......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (JavaScript, Powershell, Python, etc.)  are not supported.

13.2.2.27 Instance Selection
............................

VS 2017 supports multiple installations on the same machine.  The
CMAKE_GENERATOR_INSTANCE variable may be set as a cache entry
containing the absolute path to a Visual Studio instance.  If the value
is not specified explicitly by the user or a toolchain file, CMake
queries the Visual Studio Installer to locate VS instances, chooses one,
and sets the variable as a cache entry to hold the value persistently.

When CMake first chooses an instance, if the ‘VS150COMNTOOLS’
environment variable is set and points to the ‘Common7/Tools’ directory
within one of the instances, that instance will be used.  Otherwise, if
more than one instance is installed we do not define which one is chosen
by default.

13.2.2.28 Platform Selection
............................

The default target platform name (architecture) is ‘Win32’.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 15 2017" -A Win32’

   * ‘cmake -G "Visual Studio 15 2017" -A x64’

   * ‘cmake -G "Visual Studio 15 2017" -A ARM’

   * ‘cmake -G "Visual Studio 15 2017" -A ARM64’

For compatibility with CMake versions prior to 3.1, one may specify a
target platform name optionally at the end of the generator name.  This
is supported only for:

‘Visual Studio 15 2017 Win64’

     Specify target platform ‘x64’.

‘Visual Studio 15 2017 ARM’

     Specify target platform ‘ARM’.

13.2.2.29 Toolset Selection
...........................

The ‘v141’ toolset that comes with Visual Studio 15 2017 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

For each toolset that comes with this version of Visual Studio, there
are variants that are themselves compiled for 32-bit (‘x86’) and 64-bit
(‘x64’) hosts (independent of the architecture they target).  By default
this generator uses the 32-bit variant even on a 64-bit host.  One may
explicitly request use of either the 32-bit or 64-bit host tools by
adding either ‘host=x86’ or ‘host=x64’ to the toolset specification.
See the CMAKE_GENERATOR_TOOLSET variable for details.

13.2.2.30 Visual Studio 16 2019
...............................

New in version 3.14.

Generates Visual Studio 16 (VS 2019) project files.

13.2.2.31 Project Types
.......................

Only Visual C++ and C# projects may be generated.  Other types of
projects (JavaScript, Powershell, Python, etc.)  are not supported.

13.2.2.32 Instance Selection
............................

VS 2019 supports multiple installations on the same machine.  The
CMAKE_GENERATOR_INSTANCE variable may be set as a cache entry
containing the absolute path to a Visual Studio instance.  If the value
is not specified explicitly by the user or a toolchain file, CMake
queries the Visual Studio Installer to locate VS instances, chooses one,
and sets the variable as a cache entry to hold the value persistently.

When CMake first chooses an instance, if the ‘VS160COMNTOOLS’
environment variable is set and points to the ‘Common7/Tools’ directory
within one of the instances, that instance will be used.  Otherwise, if
more than one instance is installed we do not define which one is chosen
by default.

13.2.2.33 Platform Selection
............................

The default target platform name (architecture) is that of the host and
is provided in the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.

The CMAKE_GENERATOR_PLATFORM variable may be set, perhaps via
the cmake(1). ‘-A’ option, to specify a target platform name
(architecture).  For example:

   * ‘cmake -G "Visual Studio 16 2019" -A Win32’

   * ‘cmake -G "Visual Studio 16 2019" -A x64’

   * ‘cmake -G "Visual Studio 16 2019" -A ARM’

   * ‘cmake -G "Visual Studio 16 2019" -A ARM64’

13.2.2.34 Toolset Selection
...........................

The ‘v142’ toolset that comes with Visual Studio 16 2019 is selected by
default.  The CMAKE_GENERATOR_TOOLSET option may be set,
perhaps via the cmake(1). ‘-T’ option, to specify another
toolset.

For each toolset that comes with this version of Visual Studio, there
are variants that are themselves compiled for 32-bit (‘x86’) and 64-bit
(‘x64’) hosts (independent of the architecture they target).  By default
this generator uses the 64-bit variant on x64 hosts and the 32-bit
variant otherwise.  One may explicitly request use of either the 32-bit
or 64-bit host tools by adding either ‘host=x86’ or ‘host=x64’ to the
toolset specification.  See the CMAKE_GENERATOR_TOOLSET.
variable for details.

13.2.2.35 Other Generators
..........................

13.2.2.36 Green Hills MULTI
...........................

New in version 3.3.

Generates Green Hills MULTI project files (experimental,
work-in-progress).

The buildsystem has predetermined build-configuration settings that can
be controlled via the CMAKE_BUILD_TYPE variable.

Customizations that are used to pick toolset and target system:

The ‘-A <arch>’ can be supplied for setting the target architecture.
‘<arch>’ usually is one of ‘arm’, ‘ppc’, ‘86’, etcetera.  If the target
architecture is not specified then the default architecture of ‘arm’
will be used.

The ‘-T <toolset>’ option can be used to set the directory location of
the toolset.  Both absolute and relative paths are valid.  Relative
paths use ‘GHS_TOOLSET_ROOT’ as the root.  If the toolset is not
specified then the latest toolset found in ‘GHS_TOOLSET_ROOT’ will be
used.

Cache variables that are used for toolset and target system
customization:

   * ‘GHS_TARGET_PLATFORM’

          Defaults to ‘integrity’.
          Usual values are ‘integrity’, ‘threadx’, ‘uvelosity’, ‘velosity’, ‘vxworks’, ‘standalone’.

   * ‘GHS_PRIMARY_TARGET’

          Sets ‘primaryTarget’ entry in project file.
          Defaults to ‘<arch>_<GHS_TARGET_PLATFORM>.tgt’.

   * ‘GHS_TOOLSET_ROOT’

          Root path for ‘toolset’ searches.
          Defaults to ‘C:/ghs’ in Windows or ‘/usr/ghs’ in Linux.

   * ‘GHS_OS_ROOT’

          Root path for RTOS searches.
          Defaults to ‘C:/ghs’ in Windows or ‘/usr/ghs’ in Linux.

   * ‘GHS_OS_DIR’ and ‘GHS_OS_DIR_OPTION’

          Sets ‘-os_dir’ entry in project file.
          Defaults to latest platform OS installation at ‘GHS_OS_ROOT’.  Set this value if a specific RTOS is to be used.
          ‘GHS_OS_DIR_OPTION’ default value is ‘-os_dir’.

   * ‘GHS_BSP_NAME’

          Sets ‘-bsp’ entry in project file.
          Defaults to ‘sim<arch>’ for ‘integrity’ platforms.

Customizations are available through the following cache variables:

   * ‘GHS_CUSTOMIZATION’

   * ‘GHS_GPJ_MACROS’

The following properties are available:

   * GHS_INTEGRITY_APP.

   * GHS_NO_SOURCE_GROUP_FILE.

     Note: This generator is deemed experimental as of CMake 3.19.2 and
     is still a work in progress.  Future versions of CMake may make
     breaking changes as the generator matures.

13.2.2.37 Xcode
...............

Generate Xcode project files.

This supports Xcode 5.0 and above.

13.2.2.38 Toolset and Build System Selection
............................................

By default Xcode is allowed to select its own default toolchain.  The
CMAKE_GENERATOR_TOOLSET option may be set, perhaps via the
cmake(1). ‘-T’ option, to specify another toolset.

This generator supports toolset specification using one of these forms:

   * ‘toolset’

   * ‘toolset[,key=value]*’

   * ‘key=value[,key=value]*’

The ‘toolset’ specifies the toolset name.  The selected toolset name is
provided in the CMAKE_XCODE_PLATFORM_TOOLSET variable.

The ‘key=value’ pairs form a comma-separated list of options to specify
generator-specific details of the toolset selection.  Supported pairs
are:

‘buildsystem=<variant>’

     Specify the buildsystem variant to use.  See the
     CMAKE_XCODE_BUILD_SYSTEM variable for allowed values.

     For example, to select the original build system under Xcode 12,
     run cmake(1) with the option ‘-T buildsystem=1’.

13.3 Extra Generators
=====================

Some of the CMake Generators listed in the cmake(1)
command-line tool ‘--help’ output may have variants that specify an
extra generator for an auxiliary IDE tool.  Such generator names have
the form ‘<extra-generator> - <main-generator>’.  The following extra
generators are known to CMake.

13.3.1 CodeBlocks
-----------------

Generates CodeBlocks project files.

Project files for CodeBlocks will be created in the top directory and in
every subdirectory which features a ‘CMakeLists.txt’ file containing a
project() call.  Additionally a hierarchy of makefiles is
generated into the build tree.  The
CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES variable may be set to
‘ON’ to exclude any files which are located outside of the project root
directory.  The appropriate make program can build the project through
the default ‘all’ target.  An ‘install’ target is also provided.

This “extra” generator may be specified as:

‘CodeBlocks - MinGW Makefiles’

     Generate with MinGW Makefiles.

‘CodeBlocks - NMake Makefiles’

     Generate with NMake Makefiles.

‘CodeBlocks - NMake Makefiles JOM’

     Generate with NMake Makefiles JOM.

‘CodeBlocks - Ninja’

     Generate with Ninja.

‘CodeBlocks - Unix Makefiles’

     Generate with Unix Makefiles.

13.3.2 CodeLite
---------------

Generates CodeLite project files.

Project files for CodeLite will be created in the top directory and in
every subdirectory which features a CMakeLists.txt file containing a
project() call.  The CMAKE_CODELITE_USE_TARGETS.
variable may be set to ‘ON’ to change the default behavior from projects
to targets as the basis for project files.  The appropriate make program
can build the project through the default ‘all’ target.  An ‘install’
target is also provided.

This “extra” generator may be specified as:

‘CodeLite - MinGW Makefiles’

     Generate with MinGW Makefiles.

‘CodeLite - NMake Makefiles’

     Generate with NMake Makefiles.

‘CodeLite - Ninja’

     Generate with Ninja.

‘CodeLite - Unix Makefiles’

     Generate with Unix Makefiles.

13.3.3 Eclipse CDT4
-------------------

Generates Eclipse CDT 4.0 project files.

Project files for Eclipse will be created in the top directory.  In out
of source builds, a linked resource to the top level source directory
will be created.  Additionally a hierarchy of makefiles is generated
into the build tree.  The appropriate make program can build the project
through the default ‘all’ target.  An ‘install’ target is also provided.

This “extra” generator may be specified as:

‘Eclipse CDT4 - MinGW Makefiles’

     Generate with MinGW Makefiles.

‘Eclipse CDT4 - NMake Makefiles’

     Generate with NMake Makefiles.

‘Eclipse CDT4 - Ninja’

     Generate with Ninja.

‘Eclipse CDT4 - Unix Makefiles’

     Generate with Unix Makefiles.

13.3.4 Kate
-----------

Generates Kate project files.

A project file for Kate will be created in the top directory in the top
level build directory.  To use it in Kate, the Project plugin must be
enabled.  The project file is loaded in Kate by opening the
‘ProjectName.kateproject’ file in the editor.  If the Kate Build-plugin
is enabled, all targets generated by CMake are available for building.

This “extra” generator may be specified as:

‘Kate - MinGW Makefiles’

     Generate with MinGW Makefiles.

‘Kate - NMake Makefiles’

     Generate with NMake Makefiles.

‘Kate - Ninja’

     Generate with Ninja.

‘Kate - Unix Makefiles’

     Generate with Unix Makefiles.

13.3.5 Sublime Text 2
---------------------

Generates Sublime Text 2 project files.

Project files for Sublime Text 2 will be created in the top directory
and in every subdirectory which features a ‘CMakeLists.txt’ file
containing a project() call.  Additionally ‘Makefiles’ (or
‘build.ninja’ files) are generated into the build tree.  The appropriate
make program can build the project through the default ‘all’ target.  An
‘install’ target is also provided.

This “extra” generator may be specified as:

‘Sublime Text 2 - MinGW Makefiles’

     Generate with MinGW Makefiles.

‘Sublime Text 2 - NMake Makefiles’

     Generate with NMake Makefiles.

‘Sublime Text 2 - Ninja’

     Generate with Ninja.

‘Sublime Text 2 - Unix Makefiles’

     Generate with Unix Makefiles.

14 cmake-language(7)
********************

14.1 Organization
=================

CMake input files are written in the “CMake Language” in source files
named ‘CMakeLists.txt’ or ending in a ‘.cmake’ file name extension.

CMake Language source files in a project are organized into:

   * Directories. (‘CMakeLists.txt’),

   * Scripts. (‘<script>.cmake’), and

   * Modules. (‘<module>.cmake’).

14.1.1 Directories
------------------

When CMake processes a project source tree, the entry point is a source
file called ‘CMakeLists.txt’ in the top-level source directory.  This
file may contain the entire build specification or use the
add_subdirectory() command to add subdirectories to the build.
Each subdirectory added by the command must also contain a
‘CMakeLists.txt’ file as the entry point to that directory.  For each
source directory whose ‘CMakeLists.txt’ file is processed CMake
generates a corresponding directory in the build tree to act as the
default working and output directory.

14.1.2 Scripts
--------------

An individual ‘<script>.cmake’ source file may be processed in `script
mode' by using the cmake(1) command-line tool with the ‘-P’
option.  Script mode simply runs the commands in the given CMake
Language source file and does not generate a build system.  It does not
allow CMake commands that define build targets or actions.

14.1.3 Modules
--------------

CMake Language code in either Directories or Scripts
may use the include() command to load a
‘<module>.cmake’ source file in the scope of the including context.  See
the cmake-modules(7) manual page for documentation of modules
included with the CMake distribution.  Project source trees may also
provide their own modules and specify their location(s) in the
CMAKE_MODULE_PATH variable.

14.2 Syntax
===========

14.2.1 Encoding
---------------

A CMake Language source file may be written in 7-bit ASCII text for
maximum portability across all supported platforms.  Newlines may be
encoded as either ‘\n’ or ‘\r\n’ but will be converted to ‘\n’ as input
files are read.

Note that the implementation is 8-bit clean so source files may be
encoded as UTF-8 on platforms with system APIs supporting this encoding.
In addition, CMake 3.2 and above support source files encoded in UTF-8
on Windows (using UTF-16 to call system APIs).  Furthermore, CMake 3.0
and above allow a leading UTF-8 Byte-Order Mark(1) in source files.

   ---------- Footnotes ----------

   (1) http://en.wikipedia.org/wiki/Byte_order_mark

14.2.2 Source Files
-------------------

A CMake Language source file consists of zero or more Command Invocations
separated by newlines and optionally spaces and
Comments.:

     file         ::= file_element*
     file_element ::= command_invocation line_ending |
                      (bracket_comment|space)* line_ending
     line_ending  ::= line_comment? newline
     space        ::= <match '[ \t]+'>
     newline      ::= <match '\n'>

Note that any source file line not inside Command Arguments.
or a Bracket Comment can end in a Line Comment.

14.2.3 Command Invocations
--------------------------

A `command invocation' is a name followed by paren-enclosed arguments
separated by whitespace:

     command_invocation  ::= space* identifier space* '(' arguments ')'
     identifier          ::= <match '[A-Za-z_][A-Za-z0-9_]*'>
     arguments           ::= argument? separated_arguments*
     separated_arguments ::= separation+ argument? |
                             separation* '(' arguments ')'
     separation          ::= space | line_ending

For example:

     add_executable(hello world.c)

Command names are case-insensitive.  Nested unquoted parentheses in the
arguments must balance.  Each ‘(’ or ‘)’ is given to the command
invocation as a literal Unquoted Argument.  This may be used
in calls to the if() command to enclose conditions.  For
example:

     if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE

     Note: CMake versions prior to 3.0 require command name identifiers
     to be at least 2 characters.

     CMake versions prior to 2.8.12 silently accept an Unquoted Argument
     or a Quoted Argument immediately
     following a Quoted Argument and not separated by any
     whitespace.  For compatibility, CMake 2.8.12 and higher accept such
     code but produce a warning.

14.2.4 Command Arguments
------------------------

There are three types of arguments within Command Invocations.:

     argument ::= bracket_argument | quoted_argument | unquoted_argument

14.2.4.1 Bracket Argument
.........................

A `bracket argument', inspired by Lua(1) long bracket syntax, encloses
content between opening and closing “brackets” of the same length:

     bracket_argument ::= bracket_open bracket_content bracket_close
     bracket_open     ::= '[' '='* '['
     bracket_content  ::= <any text not containing a bracket_close with
                           the same number of '=' as the bracket_open>
     bracket_close    ::= ']' '='* ']'

An opening bracket is written ‘[’ followed by zero or more ‘=’ followed
by ‘[’.  The corresponding closing bracket is written ‘]’ followed by
the same number of ‘=’ followed by ‘]’.  Brackets do not nest.  A unique
length may always be chosen for the opening and closing brackets to
contain closing brackets of other lengths.

Bracket argument content consists of all text between the opening and
closing brackets, except that one newline immediately following the
opening bracket, if any, is ignored.  No evaluation of the enclosed
content, such as Escape Sequences or Variable References,
is performed.  A bracket argument is always given to
the command invocation as exactly one argument.

For example:

     message([=[
     This is the first line in a bracket argument with bracket length 1.
     No \-escape sequences or ${variable} references are evaluated.
     This is always one argument even though it contains a ; character.
     The text does not end on a closing bracket of length 0 like ]].
     It does end in a closing bracket of length 1.
     ]=])

     Note: CMake versions prior to 3.0 do not support bracket arguments.
     They interpret the opening bracket as the start of an
     Unquoted Argument.

   ---------- Footnotes ----------

   (1) http://www.lua.org/

14.2.4.2 Quoted Argument
........................

A `quoted argument' encloses content between opening and closing
double-quote characters:

     quoted_argument     ::= '"' quoted_element* '"'
     quoted_element      ::= <any character except '\' or '"'> |
                             escape_sequence |
                             quoted_continuation
     quoted_continuation ::= '\' newline

Quoted argument content consists of all text between opening and closing
quotes.  Both Escape Sequences and Variable References
are evaluated.  A quoted argument is always given to
the command invocation as exactly one argument.

For example:

     message("This is a quoted argument containing multiple lines.
     This is always one argument even though it contains a ; character.
     Both \\-escape sequences and ${variable} references are evaluated.
     The text does not end on an escaped double-quote like \".
     It does end in an unescaped double quote.
     ")

The final ‘\’ on any line ending in an odd number of backslashes is
treated as a line continuation and ignored along with the immediately
following newline character.  For example:

     message("\
     This is the first line of a quoted argument. \
     In fact it is the only line but since it is long \
     the source code uses line continuation.\
     ")

     Note: CMake versions prior to 3.0 do not support continuation with
     ‘\’.  They report errors in quoted arguments containing lines
     ending in an odd number of ‘\’ characters.

14.2.4.3 Unquoted Argument
..........................

An `unquoted argument' is not enclosed by any quoting syntax.  It may
not contain any whitespace, ‘(’, ‘)’, ‘#’, ‘"’, or ‘\’ except when
escaped by a backslash:

     unquoted_argument ::= unquoted_element+ | unquoted_legacy
     unquoted_element  ::= <any character except whitespace or one of '()#"\'> |
                           escape_sequence
     unquoted_legacy   ::= <see note in text>

Unquoted argument content consists of all text in a contiguous block of
allowed or escaped characters.  Both Escape Sequences and
Variable References are evaluated.  The resulting value is
divided in the same way Lists divide into elements.  Each
non-empty element is given to the command invocation as an argument.
Therefore an unquoted argument may be given to a command invocation as
zero or more arguments.

For example:

     foreach(arg
         NoSpace
         Escaped\ Space
         This;Divides;Into;Five;Arguments
         Escaped\;Semicolon
         )
       message("${arg}")
     endforeach()

     Note: To support legacy CMake code, unquoted arguments may also
     contain double-quoted strings (‘"..."’, possibly enclosing
     horizontal whitespace), and make-style variable references
     (‘$(MAKEVAR)’).

     Unescaped double-quotes must balance, may not appear at the
     beginning of an unquoted argument, and are treated as part of the
     content.  For example, the unquoted arguments ‘-Da="b c"’,
     ‘-Da=$(v)’, and ‘a" "b"c"d’ are each interpreted literally.  They
     may instead be written as quoted arguments ‘"-Da=\"b c\""’,
     ‘"-Da=$(v)"’, and ‘"a\" \"b\"c\"d"’, respectively.

     Make-style references are treated literally as part of the content
     and do not undergo variable expansion.  They are treated as part of
     a single argument (rather than as separate ‘$’, ‘(’, ‘MAKEVAR’, and
     ‘)’ arguments).

     The above “unquoted_legacy” production represents such arguments.
     We do not recommend using legacy unquoted arguments in new code.
     Instead use a Quoted Argument or a Bracket Argument
     to represent the content.

14.2.5 Escape Sequences
-----------------------

An `escape sequence' is a ‘\’ followed by one character:

     escape_sequence  ::= escape_identity | escape_encoded | escape_semicolon
     escape_identity  ::= '\' <match '[^A-Za-z0-9;]'>
     escape_encoded   ::= '\t' | '\r' | '\n'
     escape_semicolon ::= '\;'

A ‘\’ followed by a non-alphanumeric character simply encodes the
literal character without interpreting it as syntax.  A ‘\t’, ‘\r’, or
‘\n’ encodes a tab, carriage return, or newline character, respectively.
A ‘\;’ outside of any Variable References encodes itself but
may be used in an Unquoted Argument to encode the ‘;’
without dividing the argument value on it.  A ‘\;’ inside Variable References
encodes the literal ‘;’ character.  (See also policy
CMP0053 documentation for historical considerations.)

14.2.6 Variable References
--------------------------

A `variable reference' has the form ‘${<variable>}’ and is evaluated
inside a Quoted Argument or an Unquoted Argument.
A variable reference is replaced by the value of the variable, or by the
empty string if the variable is not set.  Variable references can nest
and are evaluated from the inside out, e.g.
‘${outer_${inner_variable}_variable}’.

Literal variable references may consist of alphanumeric characters, the
characters ‘/_.+-’, and Escape Sequences.  Nested references
may be used to evaluate variables of any name.  See also policy
CMP0053 documentation for historical considerations and reasons
why the ‘$’ is also technically permitted but is discouraged.

The Variables section documents the scope of variable names
and how their values are set.

An `environment variable reference' has the form ‘$ENV{<variable>}’.
See the Environment Variables section for more information.

A `cache variable reference' has the form ‘$CACHE{<variable>}’.  See
CACHE for more information.

The if() command has a special condition syntax that allows
for variable references in the short form ‘<variable>’ instead of
‘${<variable>}’.  However, environment and cache variables always need
to be referenced as ‘$ENV{<variable>}’ or ‘$CACHE{<variable>}’.

14.2.7 Comments
---------------

A comment starts with a ‘#’ character that is not inside a Bracket Argument,
see Quoted Argument, or escaped with ‘\’ as part
of an Unquoted Argument.  There are two types of comments: a
Bracket Comment and a Line Comment.

14.2.7.1 Bracket Comment
........................

A ‘#’ immediately followed by a bracket_open forms a
`bracket comment' consisting of the entire bracket enclosure:

     bracket_comment ::= '#' bracket_argument

For example:

     #[[This is a bracket comment.
     It runs until the close bracket.]]
     message("First Argument\n" #[[Bracket Comment]] "Second Argument")

     Note: CMake versions prior to 3.0 do not support bracket comments.
     They interpret the opening ‘#’ as the start of a Line Comment.

14.2.7.2 Line Comment
.....................

A ‘#’ not immediately followed by a bracket_open forms a
`line comment' that runs until the end of the line:

     line_comment ::= '#' <any text not starting in a bracket_open
                           and not containing a newline>

For example:

     # This is a line comment.
     message("First Argument\n" # This is a line comment :)
             "Second Argument") # This is a line comment.

14.3 Control Structures
=======================

14.3.1 Conditional Blocks
-------------------------

The if()./ see elseif()./ see else()./ see
endif() commands delimit code blocks to be executed conditionally.

14.3.2 Loops
------------

The foreach()./ see endforeach() and while().
/ see endwhile() commands delimit code blocks to be executed
in a loop.  Inside such blocks the break() command may be
used to terminate the loop early whereas the continue().
command may be used to start with the next iteration immediately.

14.3.3 Command Definitions
--------------------------

The macro()./ see endmacro(), and function().
/ see endfunction() commands delimit code blocks to be
recorded for later invocation as commands.

14.4 Variables
==============

Variables are the basic unit of storage in the CMake Language.  Their
values are always of string type, though some commands may interpret the
strings as values of other types.  The set() and
unset() commands explicitly set or unset a variable, but other
commands have semantics that modify variables as well.  Variable names
are case-sensitive and may consist of almost any text, but we recommend
sticking to names consisting only of alphanumeric characters plus ‘_’
and ‘-’.

Variables have dynamic scope.  Each variable “set” or “unset” creates a
binding in the current scope:

Function Scope

     Command Definitions created by the function()
     command create commands that, when invoked, process the
     recorded commands in a new variable binding scope.  A variable
     “set” or “unset” binds in this scope and is visible for the current
     function and any nested calls within it, but not after the function
     returns.

Directory Scope

     Each of the Directories in a source tree has its own
     variable bindings.  Before processing the ‘CMakeLists.txt’ file for
     a directory, CMake copies all variable bindings currently defined
     in the parent directory, if any, to initialize the new directory
     scope.  CMake Scripts, when processed with ‘cmake -P’,
     bind variables in one “directory” scope.

     A variable “set” or “unset” not inside a function call binds to the
     current directory scope.

Persistent Cache

     CMake stores a separate set of “cache” variables, or “cache
     entries”, whose values persist across multiple runs within a
     project build tree.  Cache entries have an isolated binding scope
     modified only by explicit request, such as by the ‘CACHE’ option of
     the set() and unset() commands.

When evaluating Variable References, CMake first searches the
function call stack, if any, for a binding and then falls back to the
binding in the current directory scope, if any.  If a “set” binding is
found, its value is used.  If an “unset” binding is found, or no binding
is found, CMake then searches for a cache entry.  If a cache entry is
found, its value is used.  Otherwise, the variable reference evaluates
to an empty string.  The ‘$CACHE{VAR}’ syntax can be used to do direct
cache entry lookups.

The cmake-variables(7) manual documents the many variables
that are provided by CMake or have meaning to CMake when set by project
code.

     Note: CMake reserves identifiers that:

        * begin with ‘CMAKE_’ (upper-, lower-, or mixed-case), or

        * begin with ‘_CMAKE_’ (upper-, lower-, or mixed-case), or

        * begin with ‘_’ followed by the name of any CMake Command.

14.5 Environment Variables
==========================

Environment Variables are like ordinary Variables, with the
following differences:

Scope

     Environment variables have global scope in a CMake process.  They
     are never cached.

References

     Variable References have the form ‘$ENV{<variable>}’.

Initialization

     Initial values of the CMake environment variables are those of the
     calling process.  Values can be changed using the set().
     and unset() commands.  These commands only affect the
     running CMake process, not the system environment at large.
     Changed values are not written back to the calling process, and
     they are not seen by subsequent build or test processes.

The cmake-env-variables(7) manual documents environment
variables that have special meaning to CMake.

14.6 Lists
==========

Although all values in CMake are stored as strings, a string may be
treated as a list in certain contexts, such as during evaluation of an
Unquoted Argument.  In such contexts, a string is divided
into list elements by splitting on ‘;’ characters not following an
unequal number of ‘[’ and ‘]’ characters and not immediately preceded by
a ‘\’.  The sequence ‘\;’ does not divide a value but is replaced by ‘;’
in the resulting element.

A list of elements is represented as a string by concatenating the
elements separated by ‘;’.  For example, the set() command
stores multiple values into the destination variable as a list:

     set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"

Lists are meant for simple use cases such as a list of source files and
should not be used for complex data processing tasks.  Most commands
that construct lists do not escape ‘;’ characters in list elements, thus
flattening nested lists:

     set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"

15 cmake-modules(7)
*******************

The modules listed here are part of the CMake distribution.  Projects
may provide further modules; their location(s) can be specified in the
CMAKE_MODULE_PATH variable.

15.1 Utility Modules
====================

These modules are loaded using the include() command.

15.1.1 AddFileDependencies
--------------------------

Add dependencies to a source file.

     ADD_FILE_DEPENDENCIES(<source> <files>)

Adds the given ‘<files>’ to the dependencies of file ‘<source>’.

15.1.2 AndroidTestUtilities
---------------------------

New in version 3.7.

Create a test that automatically loads specified data onto an Android
device.

15.1.2.1 Introduction
.....................

Use this module to push data needed for testing an Android device
behavior onto a connected Android device.  The module will accept files
and libraries as well as separate destinations for each.  It will create
a test that loads the files into a device object store and link to them
from the specified destination.  The files are only uploaded if they are
not already in the object store.

For example:

     include(AndroidTestUtilities)
     android_add_test_data(
       example_setup_test
       FILES <files>...
       LIBS <libs>...
       DEVICE_TEST_DIR "/data/local/tests/example"
       DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
       )

At build time a test named “example_setup_test” will be created.  Run
this test on the command line with ctest(1) to load the data
onto the Android device.

15.1.2.2 Module Functions
.........................

 -- Command: android_add_test_data

          android_add_test_data(<test-name>
            [FILES <files>...] [FILES_DEST <device-dir>]
            [LIBS <libs>...]   [LIBS_DEST <device-dir>]
            [DEVICE_OBJECT_STORE <device-dir>]
            [DEVICE_TEST_DIR <device-dir>]
            [NO_LINK_REGEX <strings>...]
            )

     The ‘android_add_test_data’ function is used to copy files and
     libraries needed to run project-specific tests.  On the host
     operating system, this is done at build time.  For on-device
     testing, the files are loaded onto the device by the manufactured
     test at run time.

     This function accepts the following named parameters:

     ‘FILES <files>...’

          zero or more files needed for testing

     ‘LIBS <libs>...’

          zero or more libraries needed for testing

     ‘FILES_DEST <device-dir>’

          absolute path where the data files are expected to be

     ‘LIBS_DEST <device-dir>’

          absolute path where the libraries are expected to be

     ‘DEVICE_OBJECT_STORE <device-dir>’

          absolute path to the location where the data is stored
          on-device

     ‘DEVICE_TEST_DIR <device-dir>’

          absolute path to the root directory of the on-device test
          location

     ‘NO_LINK_REGEX <strings>...’

          list of regex strings matching the names of files that should
          be copied from the object store to the testing directory

15.1.3 BundleUtilities
----------------------

Functions to help assemble a standalone bundle application.

A collection of CMake utility functions useful for dealing with ‘.app’
bundles on the Mac and bundle-like directories on any OS.

The following functions are provided by this module:

     fixup_bundle
     copy_and_fixup_bundle
     verify_app
     get_bundle_main_executable
     get_dotapp_dir
     get_bundle_and_executable
     get_bundle_all_executables
     get_item_key
     get_item_rpaths
     clear_bundle_keys
     set_bundle_key_values
     get_bundle_keys
     copy_resolved_item_into_bundle
     copy_resolved_framework_into_bundle
     fixup_bundle_item
     verify_bundle_prerequisites
     verify_bundle_symlinks

Requires CMake 2.6 or greater because it uses function, break and
‘PARENT_SCOPE’.  Also depends on ‘GetPrerequisites.cmake’.

DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ‘CMakeLists.txt’)!
Instead, invoke them from an install(CODE) or
install(SCRIPT) rule.

     fixup_bundle(<app> <libs> <dirs>)

Fix up ‘<app>’ bundle in-place and make it standalone, such that it can
be drag-n-drop copied to another machine and run on that machine as long
as all of the system libraries are compatible.

If you pass plugins to ‘fixup_bundle’ as the libs parameter, you should
install them or copy them into the bundle before calling ‘fixup_bundle’.
The ‘<libs>’ parameter is a list of libraries that must be fixed up, but
that cannot be determined by ‘otool’ output analysis (i.e.  ‘plugins’).

Gather all the keys for all the executables and libraries in a bundle,
and then, for each key, copy each prerequisite into the bundle.  Then
fix each one up according to its own list of prerequisites.

Then clear all the keys and call ‘verify_app’ on the final bundle to
ensure that it is truly standalone.

As an optional parameter (‘IGNORE_ITEM’) a list of file names can be
passed, which are then ignored (e.g.  ‘IGNORE_ITEM
"vcredist_x86.exe;vcredist_x64.exe"’).

     copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)

Makes a copy of the bundle ‘<src>’ at location ‘<dst>’ and then fixes up
the new copied bundle in-place at ‘<dst>’.

     verify_app(<app>)

Verifies that an application ‘<app>’ appears valid based on running
analysis tools on it.  Calls message(FATAL_ERROR) if the
application is not verified.

As an optional parameter (‘IGNORE_ITEM’) a list of file names can be
passed, which are then ignored (e.g.  ‘IGNORE_ITEM
"vcredist_x86.exe;vcredist_x64.exe"’)

     get_bundle_main_executable(<bundle> <result_var>)

The result will be the full path name of the bundle’s main executable
file or an ‘error:’ prefixed string if it could not be determined.

     get_dotapp_dir(<exe> <dotapp_dir_var>)

Returns the nearest parent dir whose name ends with ‘.app’ given the
full path to an executable.  If there is no such parent dir, then simply
return the dir containing the executable.

The returned directory may or may not exist.

     get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)

Takes either a ‘.app’ directory name or the name of an executable nested
inside a ‘.app’ directory and returns the path to the ‘.app’ directory
in ‘<bundle_var>’ and the path to its main executable in
‘<executable_var>’.

     get_bundle_all_executables(<bundle> <exes_var>)

Scans ‘<bundle>’ bundle recursively for all ‘<exes_var>’ executable
files and accumulates them into a variable.

     get_item_key(<item> <key_var>)

Given ‘<item>’ file name, generate ‘<key_var>’ key that should be unique
considering the set of libraries that need copying or fixing up to make
a bundle standalone.  This is essentially the file name including
extension with ‘.’ replaced by ‘_’

This key is used as a prefix for CMake variables so that we can
associate a set of variables with a given item based on its key.

     clear_bundle_keys(<keys_var>)

Loop over the ‘<keys_var>’ list of keys, clearing all the variables
associated with each key.  After the loop, clear the list of keys
itself.

Caller of ‘get_bundle_keys’ should call ‘clear_bundle_keys’ when done
with list of keys.

     set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
                           <copyflag> [<rpaths>])

Add ‘<keys_var>’ key to the list (if necessary) for the given item.  If
added, also set all the variables associated with that key.

     get_bundle_keys(<app> <libs> <dirs> <keys_var>)

Loop over all the executable and library files within ‘<app>’ bundle
(and given as extra ‘<libs>’) and accumulate a list of keys representing
them.  Set values associated with each key such that we can loop over
all of them and copy prerequisite libs into the bundle and then do
appropriate ‘install_name_tool’ fixups.

As an optional parameter (‘IGNORE_ITEM’) a list of file names can be
passed, which are then ignored (e.g.  ‘IGNORE_ITEM
"vcredist_x86.exe;vcredist_x64.exe"’)

     copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)

Copy a resolved item into the bundle if necessary.  Copy is not
necessary, if the ‘<resolved_item>’ is “the same as” the
‘<resolved_embedded_item>’.

     copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)

Copy a resolved framework into the bundle if necessary.  Copy is not
necessary, if the ‘<resolved_item>’ is “the same as” the
‘<resolved_embedded_item>’.

By default, ‘BU_COPY_FULL_FRAMEWORK_CONTENTS’ is not set.  If you want
full frameworks embedded in your bundles, set
‘BU_COPY_FULL_FRAMEWORK_CONTENTS’ to ‘ON’ before calling fixup_bundle.
By default, ‘COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE’ copies the framework
dylib itself plus the framework ‘Resources’ directory.

     fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)

Get the direct/non-system prerequisites of the
‘<resolved_embedded_item>’.  For each prerequisite, change the way it is
referenced to the value of the ‘_EMBEDDED_ITEM’ keyed variable for that
prerequisite.  (Most likely changing to an ‘@executable_path’ style
reference.)

This function requires that the ‘<resolved_embedded_item>’ be ‘inside’
the bundle already.  In other words, if you pass plugins to
‘fixup_bundle’ as the libs parameter, you should install them or copy
them into the bundle before calling ‘fixup_bundle’.  The ‘libs’
parameter is a list of libraries that must be fixed up, but that cannot
be determined by otool output analysis.  (i.e., ‘plugins’)

Also, change the id of the item being fixed up to its own
‘_EMBEDDED_ITEM’ value.

Accumulate changes in a local variable and make `one' call to
‘install_name_tool’ at the end of the function with all the changes at
once.

If the ‘BU_CHMOD_BUNDLE_ITEMS’ variable is set then bundle items will be
marked writable before ‘install_name_tool’ tries to change them.

     verify_bundle_prerequisites(<bundle> <result_var> <info_var>)

Verifies that the sum of all prerequisites of all files inside the
bundle are contained within the bundle or are ‘system’ libraries,
presumed to exist everywhere.

As an optional parameter (‘IGNORE_ITEM’) a list of file names can be
passed, which are then ignored (e.g.  ‘IGNORE_ITEM
"vcredist_x86.exe;vcredist_x64.exe"’)

     verify_bundle_symlinks(<bundle> <result_var> <info_var>)

Verifies that any symlinks found in the ‘<bundle>’ bundle point to other
files that are already also in the bundle… Anything that points to an
external file causes this function to fail the verification.

15.1.4 CheckCCompilerFlag
-------------------------

Check whether the C compiler supports a given flag.

 -- Command: check_c_compiler_flag

          check_c_compiler_flag(<flag> <var>)

     Check that the ‘<flag>’ is accepted by the compiler without a
     diagnostic.  Stores the result in an internal cache entry named
     ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_c_source_compiles’ macro from the
CheckCSourceCompiles module.  See documentation of that module for
a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_C_FLAGS, unknown flags in such
     variables may cause a false negative for this check.

15.1.5 CheckCompilerFlag
------------------------

New in version 3.19.

Check whether the compiler supports a given flag.

 -- Command: check_compiler_flag

          check_compiler_flag(<lang> <flag> <var>)

Check that the ‘<flag>’ is accepted by the compiler without a
diagnostic.  Stores the result in an internal cache entry named ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_source_compiles(<LANG>)’ function from the
CheckSourceCompiles module.  See documentation of that module for
a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_<LANG>_FLAGS, unknown flags in
     such variables may cause a false negative for this check.

15.1.6 CheckCSourceCompiles
---------------------------

Check if given C source compiles and links into an executable.

 -- Command: check_c_source_compiles

          check_c_source_compiles(<code> <resultVar>
                                  [FAIL_REGEX <regex1> [<regex2>...]])

     Check that the source supplied in ‘<code>’ can be compiled as a C
     source file and linked as an executable (so it must contain at
     least a ‘main()’ function).  The result will be stored in the
     internal cache variable specified by ‘<resultVar>’, with a boolean
     true value for success and boolean false for failure.  If
     ‘FAIL_REGEX’ is provided, then failure is determined by checking if
     anything in the output matches any of the specified regular
     expressions.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_c_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_C_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.7 CheckCSourceRuns
-----------------------

Check if given C source compiles and links into an executable and can
subsequently be run.

 -- Command: check_c_source_runs

          check_c_source_runs(<code> <resultVar>)

     Check that the source supplied in ‘<code>’ can be compiled as a C
     source file, linked as an executable and then run.  The ‘<code>’
     must contain at least a ‘main()’ function.  If the ‘<code>’ could
     be built and run successfully, the internal cache variable
     specified by ‘<resultVar>’ will be set to 1, otherwise it will be
     set to an value that evaluates to boolean false (e.g.  an empty
     string or an error message).

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_c_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_C_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.8 CheckCXXCompilerFlag
---------------------------

Check whether the CXX compiler supports a given flag.

 -- Command: check_cxx_compiler_flag

          check_cxx_compiler_flag(<flag> <var>)

     Check that the ‘<flag>’ is accepted by the compiler without a
     diagnostic.  Stores the result in an internal cache entry named
     ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_cxx_source_compiles’ macro from the
CheckCXXSourceCompiles module.  See documentation of that module
for a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_CXX_FLAGS, unknown flags in
     such variables may cause a false negative for this check.

15.1.9 CheckCXXSourceCompiles
-----------------------------

Check if given C++ source compiles and links into an executable.

 -- Command: check_cxx_source_compiles

          check_cxx_source_compiles(<code> <resultVar>
                                    [FAIL_REGEX <regex1> [<regex2>...]])

     Check that the source supplied in ‘<code>’ can be compiled as a C++
     source file and linked as an executable (so it must contain at
     least a ‘main()’ function).  The result will be stored in the
     internal cache variable specified by ‘<resultVar>’, with a boolean
     true value for success and boolean false for failure.  If
     ‘FAIL_REGEX’ is provided, then failure is determined by checking if
     anything in the output matches any of the specified regular
     expressions.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_cxx_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_CXX_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.10 CheckCXXSourceRuns
--------------------------

Check if given C++ source compiles and links into an executable and can
subsequently be run.

 -- Command: check_cxx_source_runs

          check_cxx_source_runs(<code> <resultVar>)

     Check that the source supplied in ‘<code>’ can be compiled as a C++
     source file, linked as an executable and then run.  The ‘<code>’
     must contain at least a ‘main()’ function.  If the ‘<code>’ could
     be built and run successfully, the internal cache variable
     specified by ‘<resultVar>’ will be set to 1, otherwise it will be
     set to an value that evaluates to boolean false (e.g.  an empty
     string or an error message).

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_cxx_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_CXX_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.11 CheckCXXSymbolExists
----------------------------

Check if a symbol exists as a function, variable, or macro in ‘C++’.

 -- Command: check_cxx_symbol_exists

          check_cxx_symbol_exists(<symbol> <files> <variable>)

     Check that the ‘<symbol>’ is available after including given header
     ‘<files>’ and store the result in a ‘<variable>’.  Specify the list
     of files in one argument as a semicolon-separated list.
     ‘check_cxx_symbol_exists()’ can be used to check for symbols as
     seen by the C++ compiler, as opposed to
     check_symbol_exists(), which always uses the ‘C’ compiler.

     If the header files define the symbol as a macro it is considered
     available and assumed to work.  If the header files declare the
     symbol as a function or variable then the symbol must also be
     available for linking.  If the symbol is a type, enum value, or C++
     template it will not be recognized: consider using the
     CheckTypeSize or CheckCXXSourceCompiles module
     instead.

     Note: This command is unreliable when ‘<symbol>’ is (potentially)
     an overloaded function.  Since there is no reliable way to predict
     whether a given function in the system environment may be defined
     as an overloaded function or may be an overloaded function on other
     systems or will become so in the future, it is generally advised to
     use the CheckCXXSourceCompiles module for checking any
     function symbol (unless somehow you surely know the checked
     function is not overloaded on other systems or will not be so in
     the future).

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

For example:

     include(CheckCXXSymbolExists)

     # Check for macro SEEK_SET
     check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
     # Check for function std::fopen
     check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)

15.1.12 CheckFortranCompilerFlag
--------------------------------

New in version 3.3.

Check whether the Fortran compiler supports a given flag.

 -- Command: check_fortran_compiler_flag

          check_fortran_compiler_flag(<flag> <var>)

     Check that the ‘<flag>’ is accepted by the compiler without a
     diagnostic.  Stores the result in an internal cache entry named
     ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_fortran_source_compiles’ macro from the
CheckFortranSourceCompiles module.  See documentation of that
module for a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_Fortran_FLAGS, unknown flags
     in such variables may cause a false negative for this check.

15.1.13 CheckFortranFunctionExists
----------------------------------

Check if a Fortran function exists.

 -- Command: CHECK_FORTRAN_FUNCTION_EXISTS

          CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)

     where

     ‘<function>’

          the name of the Fortran function

     ‘<result>’

          variable to store the result; will be created as an internal
          cache variable.

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_LINK_OPTIONS’

     A ;-list of options to add to the link command (see
     try_compile() for further details).

‘CMAKE_REQUIRED_LIBRARIES’

     A ;-list of libraries to add to the link command.  These
     can be the name of system libraries or they can be Imported Targets.
     (see try_compile() for further details).

15.1.14 CheckFortranSourceCompiles
----------------------------------

New in version 3.1.

Check if given Fortran source compiles and links into an executable.

 -- Command: check_fortran_source_compiles

          check_fortran_source_compiles(<code> <resultVar>
              [FAIL_REGEX <regex>...]
              [SRC_EXT <extension>]
          )

     Checks that the source supplied in ‘<code>’ can be compiled as a
     Fortran source file and linked as an executable.  The ‘<code>’ must
     be a Fortran program containing at least an ‘end’ statement–for
     example:

          check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)

     This command can help avoid costly build processes when a compiler
     lacks support for a necessary feature, or a particular vendor
     library is not compatible with the Fortran compiler version being
     used.  This generate-time check may advise the user of such before
     the main build process.  See also the
     check_fortran_source_runs() command to actually run the
     compiled code.

     The result will be stored in the internal cache variable
     ‘<resultVar>’, with a boolean true value for success and boolean
     false for failure.

     If ‘FAIL_REGEX’ is provided, then failure is determined by checking
     if anything in the output matches any of the specified regular
     expressions.

     By default, the test source file will be given a ‘.F’ file
     extension.  The ‘SRC_EXT’ option can be used to override this with
     ‘.<extension>’ instead– ‘.F90’ is a typical choice.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_fortran_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_Fortran_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.15 CheckFortranSourceRuns
------------------------------

New in version 3.14.

Check if given Fortran source compiles and links into an executable and
can subsequently be run.

 -- Command: check_fortran_source_runs

          check_fortran_source_runs(<code> <resultVar>
              [SRC_EXT <extension>])

     Check that the source supplied in ‘<code>’ can be compiled as a
     Fortran source file, linked as an executable and then run.  The
     ‘<code>’ must be a Fortran program containing at least an ‘end’
     statement–for example:

          check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)

     This command can help avoid costly build processes when a compiler
     lacks support for a necessary feature, or a particular vendor
     library is not compatible with the Fortran compiler version being
     used.  Some of these failures only occur at runtime instead of
     linktime, and a trivial runtime example can catch the issue before
     the main build process.

     If the ‘<code>’ could be built and run successfully, the internal
     cache variable specified by ‘<resultVar>’ will be set to 1,
     otherwise it will be set to an value that evaluates to boolean
     false (e.g.  an empty string or an error message).

     By default, the test source file will be given a ‘.F90’ file
     extension.  The ‘SRC_EXT’ option can be used to override this with
     ‘.<extension>’ instead.

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_fortran_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_Fortran_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.16 CheckFunctionExists
---------------------------

Check if a C function can be linked

 -- Command: check_function_exists

          check_function_exists(<function> <variable>)

     Checks that the ‘<function>’ is provided by libraries on the system
     and store the result in a ‘<variable>’, which will be created as an
     internal cache variable.

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

     Note: Prefer using CheckSymbolExists instead of this
     module, for the following reasons:

        * ‘check_function_exists()’ can’t detect functions that are
          inlined in headers or specified as a macro.

        * ‘check_function_exists()’ can’t detect anything in the 32-bit
          versions of the Win32 API, because of a mismatch in calling
          conventions.

        * ‘check_function_exists()’ only verifies linking, it does not
          verify that the function is declared in system headers.

15.1.17 CheckIncludeFileCXX
---------------------------

Provides a macro to check if a header file can be included in ‘CXX’.

 -- Command: CHECK_INCLUDE_FILE_CXX

          CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])

     Check if the given ‘<include>’ file may be included in a ‘CXX’
     source file and store the result in an internal cache entry named
     ‘<variable>’.  The optional third argument may be used to add
     compilation flags to the check (or use ‘CMAKE_REQUIRED_FLAGS’
     below).

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

See modules CheckIncludeFile and CheckIncludeFiles
to check for one or more ‘C’ headers.

15.1.18 CheckIncludeFile
------------------------

Provides a macro to check if a header file can be included in ‘C’.

 -- Command: CHECK_INCLUDE_FILE

          CHECK_INCLUDE_FILE(<include> <variable> [<flags>])

     Check if the given ‘<include>’ file may be included in a ‘C’ source
     file and store the result in an internal cache entry named
     ‘<variable>’.  The optional third argument may be used to add
     compilation flags to the check (or use ‘CMAKE_REQUIRED_FLAGS’
     below).

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

See the CheckIncludeFiles module to check for multiple
headers at once.  See the CheckIncludeFileCXX module to
check for headers using the ‘CXX’ language.

15.1.19 CheckIncludeFiles
-------------------------

Provides a macro to check if a list of one or more header files can be
included together.

 -- Command: CHECK_INCLUDE_FILES

          CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])

     Check if the given ‘<includes>’ list may be included together in a
     source file and store the result in an internal cache entry named
     ‘<variable>’.  Specify the ‘<includes>’ argument as a ;-list
     of header file names.

     If ‘LANGUAGE’ is set, the specified compiler will be used to
     perform the check.  Acceptable values are ‘C’ and ‘CXX’.  If not
     set, the C compiler will be used if enabled.  If the C compiler is
     not enabled, the C++ compiler will be used if enabled.

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

See modules CheckIncludeFile and CheckIncludeFileCXX
to check for a single header file in ‘C’ or ‘CXX’ languages.

15.1.20 CheckIPOSupported
-------------------------

New in version 3.9.

Check whether the compiler supports an interprocedural optimization
(IPO/LTO). Use this before enabling the
INTERPROCEDURAL_OPTIMIZATION target property.

 -- Command: check_ipo_supported

          check_ipo_supported([RESULT <result>] [OUTPUT <output>]
                              [LANGUAGES <lang>...])

     Options are:

     ‘RESULT <result>’

          Set ‘<result>’ variable to ‘YES’ if IPO is supported by the
          compiler and ‘NO’ otherwise.  If this option is not given then
          the command will issue a fatal error if IPO is not supported.

     ‘OUTPUT <output>’

          Set ‘<output>’ variable with details about any error.

     ‘LANGUAGES <lang>...’

          Specify languages whose compilers to check.  Languages ‘C’,
          ‘CXX’, and ‘Fortran’ are supported.

It makes no sense to use this module when CMP0069 is set to
‘OLD’ so module will return error in this case.  See policy
CMP0069 for details.

15.1.20.1 Examples
..................

     check_ipo_supported() # fatal error if IPO is not supported
     set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)

     # Optional IPO. Do not use IPO if it's not supported by compiler.
     check_ipo_supported(RESULT result OUTPUT output)
     if(result)
       set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
     else()
       message(WARNING "IPO is not supported: ${output}")
     endif()

15.1.21 CheckLanguage
---------------------

Check if a language can be enabled

Usage:

     check_language(<lang>)

where ‘<lang>’ is a language that may be passed to
enable_language() such as ‘Fortran’.  If
CMAKE_<LANG>_COMPILER is already defined the check does nothing.
Otherwise it tries enabling the language in a test project.  The result
is cached in CMAKE_<LANG>_COMPILER as the compiler that was
found, or ‘NOTFOUND’ if the language cannot be enabled.  For CUDA which
can have an explicit host compiler, the cache
CMAKE_CUDA_HOST_COMPILER variable will be set if it was required
for compilation (and cleared if it was not).

Example:

     check_language(Fortran)
     if(CMAKE_Fortran_COMPILER)
       enable_language(Fortran)
     else()
       message(STATUS "No Fortran support")
     endif()

15.1.22 CheckLibraryExists
--------------------------

Check if the function exists.

 -- Command: CHECK_LIBRARY_EXISTS

          CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)

          LIBRARY  - the name of the library you are looking for
          FUNCTION - the name of the function
          LOCATION - location where the library should be found
          VARIABLE - variable to store the result
                     Will be created as an internal cache variable.

The following variables may be set before calling this macro to modify
the way the check is run:

     CMAKE_REQUIRED_FLAGS = string of compile command line flags
     CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
     CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
     CMAKE_REQUIRED_LIBRARIES = list of libraries to link
     CMAKE_REQUIRED_QUIET = execute quietly without messages

15.1.23 CheckLinkerFlag
-----------------------

New in version 3.18.

Check whether the compiler supports a given link flag.

 -- Command: check_linker_flag

          check_linker_flag(<lang> <flag> <var>)

Check that the link ‘<flag>’ is accepted by the ‘<lang>’ compiler
without a diagnostic.  Stores the result in an internal cache entry
named ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_LINK_OPTIONS’ variable
and calls the check_source_compiles() command from the
CheckSourceCompiles module.  See that module’s documentation for a
listing of variables that can otherwise modify the build.

The underlying implementation relies on the LINK_OPTIONS.
property to check the specified flag.  The ‘LINKER:’ prefix, as
described in the target_link_options() command, can be used
as well.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the link flag.  Whether the
flag has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_<LANG>_FLAGS, unknown flags in
     such variables may cause a false negative for this check.

15.1.24 CheckOBJCCompilerFlag
-----------------------------

New in version 3.16.

Check whether the Objective-C compiler supports a given flag.

 -- Command: check_objc_compiler_flag

          check_objc_compiler_flag(<flag> <var>)

     Check that the ‘<flag>’ is accepted by the compiler without a
     diagnostic.  Stores the result in an internal cache entry named
     ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_objc_source_compiles’ macro from the
CheckOBJCSourceCompiles module.  See documentation of that module
for a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_OBJC_FLAGS, unknown flags in
     such variables may cause a false negative for this check.

15.1.25 CheckOBJCSourceCompiles
-------------------------------

New in version 3.16.

Check if given Objective-C source compiles and links into an executable.

 -- Command: check_objc_source_compiles

          check_objc_source_compiles(<code> <resultVar>
                                     [FAIL_REGEX <regex1> [<regex2>...]])

     Check that the source supplied in ‘<code>’ can be compiled as a
     Objectie-C source file and linked as an executable (so it must
     contain at least a ‘main()’ function).  The result will be stored
     in the internal cache variable specified by ‘<resultVar>’, with a
     boolean true value for success and boolean false for failure.  If
     ‘FAIL_REGEX’ is provided, then failure is determined by checking if
     anything in the output matches any of the specified regular
     expressions.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_objc_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_OBJC_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.26 CheckOBJCSourceRuns
---------------------------

New in version 3.16.

Check if given Objective-C source compiles and links into an executable
and can subsequently be run.

 -- Command: check_objc_source_runs

          check_objc_source_runs(<code> <resultVar>)

     Check that the source supplied in ‘<code>’ can be compiled as a
     Objective-C source file, linked as an executable and then run.  The
     ‘<code>’ must contain at least a ‘main()’ function.  If the
     ‘<code>’ could be built and run successfully, the internal cache
     variable specified by ‘<resultVar>’ will be set to 1, otherwise it
     will be set to an value that evaluates to boolean false (e.g.  an
     empty string or an error message).

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_objc_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_OBJC_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.27 CheckOBJCXXCompilerFlag
-------------------------------

New in version 3.16.

Check whether the Objective-C++ compiler supports a given flag.

 -- Command: check_objcxx_compiler_flag

          check_objcxx_compiler_flag(<flag> <var>)

     Check that the ‘<flag>’ is accepted by the compiler without a
     diagnostic.  Stores the result in an internal cache entry named
     ‘<var>’.

This command temporarily sets the ‘CMAKE_REQUIRED_DEFINITIONS’ variable
and calls the ‘check_objcxx_source_compiles’ macro from the
CheckOBJCXXSourceCompiles module.  See documentation of that
module for a listing of variables that can otherwise modify the build.

A positive result from this check indicates only that the compiler did
not issue a diagnostic message when given the flag.  Whether the flag
has any effect or even a specific one is beyond the scope of this
module.

     Note: Since the try_compile() command forwards flags
     from variables like CMAKE_OBJCXX_FLAGS, unknown flags in
     such variables may cause a false negative for this check.

15.1.28 CheckOBJCXXSourceCompiles
---------------------------------

New in version 3.16.

Check if given Objective-C++ source compiles and links into an
executable.

 -- Command: check_objcxx_source_compiles

          check_objcxx_source_compiles(<code> <resultVar>
                                       [FAIL_REGEX <regex1> [<regex2>...]])

     Check that the source supplied in ‘<code>’ can be compiled as a
     Objective-C++ source file and linked as an executable (so it must
     contain at least a ‘main()’ function).  The result will be stored
     in the internal cache variable specified by ‘<resultVar>’, with a
     boolean true value for success and boolean false for failure.  If
     ‘FAIL_REGEX’ is provided, then failure is determined by checking if
     anything in the output matches any of the specified regular
     expressions.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_objcxx_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_OBJCXX_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.29 CheckOBJCXXSourceRuns
-----------------------------

New in version 3.16.

Check if given Objective-C++ source compiles and links into an
executable and can subsequently be run.

 -- Command: check_objcxx_source_runs

          check_objcxx_source_runs(<code> <resultVar>)

     Check that the source supplied in ‘<code>’ can be compiled as a
     Objective-C++ source file, linked as an executable and then run.
     The ‘<code>’ must contain at least a ‘main()’ function.  If the
     ‘<code>’ could be built and run successfully, the internal cache
     variable specified by ‘<resultVar>’ will be set to 1, otherwise it
     will be set to an value that evaluates to boolean false (e.g.  an
     empty string or an error message).

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_objcxx_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_OBJCXX_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.30 CheckPIESupported
-------------------------

New in version 3.14.

Check whether the linker supports Position Independent Code (PIE) or No
Position Independent Code (NO_PIE) for executables.  Use this to ensure
that the POSITION_INDEPENDENT_CODE target property for
executables will be honored at link time.

 -- Command: check_pie_supported

          check_pie_supported([OUTPUT_VARIABLE <output>]
                              [LANGUAGES <lang>...])

     Options are:

     ‘OUTPUT_VARIABLE <output>’

          Set ‘<output>’ variable with details about any error.

     ‘LANGUAGES <lang>...’

          Check the linkers used for each of the specified languages.
          Supported languages are ‘C’, ‘CXX’, and ‘Fortran’.

It makes no sense to use this module when CMP0083 is set to
‘OLD’, so the command will return an error in this case.  See policy
CMP0083 for details.

15.1.30.1 Variables
...................

For each language checked, two boolean cache variables are defined.

     ‘CMAKE_<lang>_LINK_PIE_SUPPORTED’

          Set to ‘YES’ if ‘PIE’ is supported by the linker and ‘NO’
          otherwise.

     ‘CMAKE_<lang>_LINK_NO_PIE_SUPPORTED’

          Set to ‘YES’ if ‘NO_PIE’ is supported by the linker and ‘NO’
          otherwise.

15.1.30.2 Examples
..................

     check_pie_supported()
     set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

     # Retrieve any error message.
     check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
     set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
     if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
       message(WARNING "PIE is not supported at link time: ${output}.\n"
                       "PIE link options will not be passed to linker.")
     endif()

15.1.31 CheckPrototypeDefinition
--------------------------------

Check if the prototype we expect is correct.

 -- Command: check_prototype_definition

          check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)

          FUNCTION - The name of the function (used to check if prototype exists)
          PROTOTYPE- The prototype to check.
          RETURN - The return value of the function.
          HEADER - The header files required.
          VARIABLE - The variable to store the result.
                     Will be created as an internal cache variable.

     Example:

          check_prototype_definition(getpwent_r
           "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
           "NULL"
           "unistd.h;pwd.h"
           SOLARIS_GETPWENT_R)

The following variables may be set before calling this function to
modify the way the check is run:

     CMAKE_REQUIRED_FLAGS = string of compile command line flags
     CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
     CMAKE_REQUIRED_INCLUDES = list of include directories
     CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
     CMAKE_REQUIRED_LIBRARIES = list of libraries to link
     CMAKE_REQUIRED_QUIET = execute quietly without messages

15.1.32 CheckSourceCompiles
---------------------------

New in version 3.19.

Check if given source compiles and links into an executable.

 -- Command: check_source_compiles

          check_source_compiles(<lang> <code> <resultVar>
                                [FAIL_REGEX <regex1> [<regex2>...]]
                                [SRC_EXT <extension>])

     Check that the source supplied in ‘<code>’ can be compiled as a
     source file for the requested language and linked as an executable
     (so it must contain at least a ‘main()’ function).  The result will
     be stored in the internal cache variable specified by
     ‘<resultVar>’, with a boolean true value for success and boolean
     false for failure.  If ‘FAIL_REGEX’ is provided, then failure is
     determined by checking if anything in the output matches any of the
     specified regular expressions.

     By default, the test source file will be given a file extension
     that matches the requested language.  The ‘SRC_EXT’ option can be
     used to override this with ‘.<extension>’ instead.

     The underlying check is performed by the try_compile().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_source_compiles()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_<LANG>_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_compile()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_compile() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_compile() for
          further details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.33 CheckSourceRuns
-----------------------

New in version 3.19.

Check if given source compiles and links into an executable and can
subsequently be run.

 -- Command: check_source_runs

          check_source_runs(<lang> <code> <resultVar>
                            [SRC_EXT <extension>])

     Check that the source supplied in ‘<code>’ can be compiled as a
     source file for the requested language, linked as an executable and
     then run.  The ‘<code>’ must contain at least a ‘main()’ function.
     If the ‘<code>’ could be built and run successfully, the internal
     cache variable specified by ‘<resultVar>’ will be set to 1,
     otherwise it will be set to an value that evaluates to boolean
     false (e.g.  an empty string or an error message).

     By default, the test source file will be given a file extension
     that matches the requested language.  The ‘SRC_EXT’ option can be
     used to override this with ‘.<extension>’ instead.

     The underlying check is performed by the try_run().
     command.  The compile and link commands can be influenced by
     setting any of the following variables prior to calling
     ‘check_objc_source_runs()’:

     ‘CMAKE_REQUIRED_FLAGS’

          Additional flags to pass to the compiler.  Note that the
          contents of CMAKE_OBJC_FLAGS and its associated
          configuration-specific variable are automatically added to the
          compiler command before the contents of
          ‘CMAKE_REQUIRED_FLAGS’.

     ‘CMAKE_REQUIRED_DEFINITIONS’

          A ;-list of compiler definitions of the form
          ‘-DFOO’ or ‘-DFOO=bar’.  A definition for the name specified
          by ‘<resultVar>’ will also be added automatically.

     ‘CMAKE_REQUIRED_INCLUDES’

          A ;-list of header search paths to pass to the
          compiler.  These will be the only header search paths used by
          ‘try_run()’, i.e.  the contents of the
          INCLUDE_DIRECTORIES directory property will be ignored.

     ‘CMAKE_REQUIRED_LINK_OPTIONS’

          A ;-list of options to add to the link command (see
          try_run() for further details).

     ‘CMAKE_REQUIRED_LIBRARIES’

          A ;-list of libraries to add to the link command.
          These can be the name of system libraries or they can be
          Imported Targets. (see try_run() for further
          details).

     ‘CMAKE_REQUIRED_QUIET’

          If this variable evaluates to a boolean true value, all status
          messages associated with the check will be suppressed.

     The check is only performed once, with the result cached in the
     variable named by ‘<resultVar>’.  Every subsequent CMake run will
     re-use this cached value rather than performing the check again,
     even if the ‘<code>’ changes.  In order to force the check to be
     re-evaluated, the variable named by ‘<resultVar>’ must be manually
     removed from the cache.

15.1.34 CheckStructHasMember
----------------------------

Check if the given struct or class has the specified member variable

 -- Command: CHECK_STRUCT_HAS_MEMBER

          CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
                                  [LANGUAGE <language>])

          <struct> - the name of the struct or class you are interested in
          <member> - the member which existence you want to check
          <header> - the header(s) where the prototype should be declared
          <variable> - variable to store the result
          <language> - the compiler to use (C or CXX)

The following variables may be set before calling this macro to modify
the way the check is run:

     CMAKE_REQUIRED_FLAGS = string of compile command line flags
     CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
     CMAKE_REQUIRED_INCLUDES = list of include directories
     CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
     CMAKE_REQUIRED_LIBRARIES = list of libraries to link
     CMAKE_REQUIRED_QUIET = execute quietly without messages

Example:

     CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
                             HAVE_TIMEVAL_TV_SEC LANGUAGE C)

15.1.35 CheckSymbolExists
-------------------------

Provides a macro to check if a symbol exists as a function, variable, or
macro in ‘C’.

 -- Command: check_symbol_exists

          check_symbol_exists(<symbol> <files> <variable>)

     Check that the ‘<symbol>’ is available after including given header
     ‘<files>’ and store the result in a ‘<variable>’.  Specify the list
     of files in one argument as a semicolon-separated list.
     ‘<variable>’ will be created as an internal cache variable.

If the header files define the symbol as a macro it is considered
available and assumed to work.  If the header files declare the symbol
as a function or variable then the symbol must also be available for
linking (so intrinsics may not be detected).  If the symbol is a type,
enum value, or intrinsic it will not be recognized (consider using
CheckTypeSize or CheckCSourceCompiles).  If the check
needs to be done in C++, consider using CheckCXXSymbolExists.
instead.

The following variables may be set before calling this macro to modify
the way the check is run:

‘CMAKE_REQUIRED_FLAGS’

     string of compile command line flags.

‘CMAKE_REQUIRED_DEFINITIONS’

     a ;-list of macros to define (-DFOO=bar).

‘CMAKE_REQUIRED_INCLUDES’

     a ;-list of header search paths to pass to the compiler.

‘CMAKE_REQUIRED_LINK_OPTIONS’

     a ;-list of options to add to the link command.

‘CMAKE_REQUIRED_LIBRARIES’

     a ;-list of libraries to add to the link command.  See
     policy CMP0075.

‘CMAKE_REQUIRED_QUIET’

     execute quietly without messages.

For example:

     include(CheckSymbolExists)

     # Check for macro SEEK_SET
     check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
     # Check for function fopen
     check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)

15.1.36 CheckTypeSize
---------------------

Check sizeof a type

 -- Command: CHECK_TYPE_SIZE

          CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
                                        [LANGUAGE <language>])

     Check if the type exists and determine its size.  On return,
     ‘HAVE_${VARIABLE}’ holds the existence of the type, and
     ‘${VARIABLE}’ holds one of the following:

          <size> = type has non-zero size <size>
          "0"    = type has arch-dependent size (see below)
          ""     = type does not exist

     Both ‘HAVE_${VARIABLE}’ and ‘${VARIABLE}’ will be created as
     internal cache variables.

     Furthermore, the variable ‘${VARIABLE}_CODE’ holds C preprocessor
     code to define the macro ‘${VARIABLE}’ to the size of the type, or
     leave the macro undefined if the type does not exist.

     The variable ‘${VARIABLE}’ may be ‘0’ when
     CMAKE_OSX_ARCHITECTURES has multiple architectures for
     building OS X universal binaries.  This indicates that the type
     size varies across architectures.  In this case ‘${VARIABLE}_CODE’
     contains C preprocessor tests mapping from each architecture macro
     to the corresponding type size.  The list of architecture macros is
     stored in ‘${VARIABLE}_KEYS’, and the value for each key is stored
     in ‘${VARIABLE}-${KEY}’.

     If the ‘BUILTIN_TYPES_ONLY’ option is not given, the macro checks
     for headers ‘<sys/types.h>’, ‘<stdint.h>’, and ‘<stddef.h>’, and
     saves results in ‘HAVE_SYS_TYPES_H’, ‘HAVE_STDINT_H’, and
     ‘HAVE_STDDEF_H’.  The type size check automatically includes the
     available headers, thus supporting checks of types defined in the
     headers.

     If ‘LANGUAGE’ is set, the specified compiler will be used to
     perform the check.  Acceptable values are ‘C’ and ‘CXX’.

Despite the name of the macro you may use it to check the size of more
complex expressions, too.  To check e.g.  for the size of a struct
member you can do something like this:

     check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)

The following variables may be set before calling this macro to modify
the way the check is run:

     CMAKE_REQUIRED_FLAGS = string of compile command line flags
     CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
     CMAKE_REQUIRED_INCLUDES = list of include directories
     CMAKE_REQUIRED_LINK_OPTIONS  = list of options to pass to link command
     CMAKE_REQUIRED_LIBRARIES = list of libraries to link
     CMAKE_REQUIRED_QUIET = execute quietly without messages
     CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include

15.1.37 CheckVariableExists
---------------------------

Check if the variable exists.

 -- Command: CHECK_VARIABLE_EXISTS

          CHECK_VARIABLE_EXISTS(VAR VARIABLE)

          VAR      - the name of the variable
          VARIABLE - variable to store the result
                     Will be created as an internal cache variable.

     This macro is only for ‘C’ variables.

The following variables may be set before calling this macro to modify
the way the check is run:

     CMAKE_REQUIRED_FLAGS = string of compile command line flags
     CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
     CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
     CMAKE_REQUIRED_LIBRARIES = list of libraries to link
     CMAKE_REQUIRED_QUIET = execute quietly without messages

15.1.38 CMakeAddFortranSubdirectory
-----------------------------------

Add a fortran-only subdirectory, find a fortran compiler, and build.

The ‘cmake_add_fortran_subdirectory’ function adds a subdirectory to a
project that contains a fortran-only subproject.  The module will check
the current compiler and see if it can support fortran.  If no fortran
compiler is found and the compiler is MSVC, then this module will find
the MinGW gfortran.  It will then use an external project to build with
the MinGW tools.  It will also create imported targets for the libraries
created.  This will only work if the fortran code is built into a dll,
so BUILD_SHARED_LIBS is turned on in the project.  In
addition the CMAKE_GNUtoMS option is set to on, so that
Microsoft ‘.lib’ files are created.  Usage is as follows:

     cmake_add_fortran_subdirectory(
      <subdir>                # name of subdirectory
      PROJECT <project_name>  # project name in subdir top CMakeLists.txt
      ARCHIVE_DIR <dir>       # dir where project places .lib files
      RUNTIME_DIR <dir>       # dir where project places .dll files
      LIBRARIES <lib>...      # names of library targets to import
      LINK_LIBRARIES          # link interface libraries for LIBRARIES
       [LINK_LIBS <lib> <dep>...]...
      CMAKE_COMMAND_LINE ...  # extra command line flags to pass to cmake
      NO_EXTERNAL_INSTALL     # skip installation of external project
      )

Relative paths in ‘ARCHIVE_DIR’ and ‘RUNTIME_DIR’ are interpreted with
respect to the build directory corresponding to the source directory in
which the function is invoked.

Limitations:

‘NO_EXTERNAL_INSTALL’ is required for forward compatibility with a
future version that supports installation of the external project
binaries during ‘make install’.

15.1.39 CMakeBackwardCompatibilityCXX
-------------------------------------

define a bunch of backwards compatibility variables

     CMAKE_ANSI_CXXFLAGS - flag for ansi c++
     CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
     include(TestForANSIStreamHeaders)
     include(CheckIncludeFileCXX)
     include(TestForSTDNamespace)
     include(TestForANSIForScope)

15.1.40 CMakeDependentOption
----------------------------

Macro to provide an option dependent on other options.

This macro presents an option to the user only if a set of other
conditions are true.

Usage:

     cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)

Where ‘<option>’ is available to the user if ‘<depends>’ is true.  When
‘<option>’ is available, the given ‘<help_text>’ and initial ‘<value>’
are used.  If the ‘<depends>’ condition is not true, ‘<option>’ will not
be presented and will always have the value given by ‘<force>’.  Any
value set by the user is preserved for when the option is presented
again.  Each element in the fourth parameter is evaluated as an
if-condition, so Condition Syntax can be used.

Example invocation:

     cmake_dependent_option(USE_FOO "Use Foo" ON
                            "USE_BAR;NOT USE_ZOT" OFF)

If ‘USE_BAR’ is true and ‘USE_ZOT’ is false, this provides an option
called ‘USE_FOO’ that defaults to ON. Otherwise, it sets ‘USE_FOO’ to
OFF and hides the option from the user.  If the status of ‘USE_BAR’ or
‘USE_ZOT’ ever changes, any value for the ‘USE_FOO’ option is saved so
that when the option is re-enabled it retains its old value.

15.1.41 CMakeFindDependencyMacro
--------------------------------

 -- Command: find_dependency

     The ‘find_dependency()’ macro wraps a find_package().
     call for a package dependency:

          find_dependency(<dep> [...])

     It is designed to be used in a Package Configuration File.
     (‘<PackageName>Config.cmake’).  ‘find_dependency’ forwards the
     correct parameters for ‘QUIET’ and ‘REQUIRED’ which were passed to
     the original find_package() call.  Any additional
     arguments specified are forwarded to find_package().

     If the dependency could not be found it sets an informative
     diagnostic message and calls return() to end processing
     of the calling package configuration file and return to the
     find_package() command that loaded it.

          Note: The call to return() makes this macro
          unsuitable to call from Find Modules.

15.1.42 CMakeFindFrameworks
---------------------------

helper module to find OSX frameworks

This module reads hints about search locations from variables:

     CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories

15.1.43 CMakeFindPackageMode
----------------------------

This file is executed by cmake when invoked with –find-package.  It
expects that the following variables are set using -D:

‘NAME’

     name of the package

‘COMPILER_ID’

     the CMake compiler ID for which the result is, i.e.
     GNU/Intel/Clang/MSVC, etc.

‘LANGUAGE’

     language for which the result will be used, i.e.  C/CXX/Fortran/ASM

‘MODE’

     ‘EXIST’

          only check for existence of the given package

     ‘COMPILE’

          print the flags needed for compiling an object file which uses
          the given package

     ‘LINK’

          print the flags needed for linking when using the given
          package

‘QUIET’

     if TRUE, don’t print anything

15.1.44 CMakeGraphVizOptions
----------------------------

The builtin Graphviz support of CMake.

15.1.44.1 Generating Graphviz files
...................................

CMake can generate Graphviz(1) files showing the dependencies between
the targets in a project, as well as external libraries which are linked
against.

When running CMake with the ‘--graphviz=foo.dot’ option, it produces:

   * a ‘foo.dot’ file, showing all dependencies in the project

   * a ‘foo.dot.<target>’ file for each target, showing on which other
     targets it depends

   * a ‘foo.dot.<target>.dependers’ file for each target, showing which
     other targets depend on it

Those .dot files can be converted to images using the `dot' command from
the Graphviz package:

     dot -Tpng -o foo.png foo.dot

The different dependency types ‘PUBLIC’, ‘INTERFACE’ and ‘PRIVATE’ are
represented as solid, dashed and dotted edges.

   ---------- Footnotes ----------

   (1) https://www.graphviz.org/

15.1.44.2 Variables specific to the Graphviz support
....................................................

The resulting graphs can be huge.  The look and content of the generated
graphs can be controlled using the file ‘CMakeGraphVizOptions.cmake’.
This file is first searched in CMAKE_BINARY_DIR, and then in
CMAKE_SOURCE_DIR.  If found, the variables set in it are used
to adjust options for the generated Graphviz files.

 -- Variable: GRAPHVIZ_GRAPH_NAME

     The graph name.

        * Mandatory: NO

        * Default: value of CMAKE_PROJECT_NAME.

 -- Variable: GRAPHVIZ_GRAPH_HEADER

     The header written at the top of the Graphviz files.

        * Mandatory: NO

        * Default: “node [ fontsize = “12” ];”

 -- Variable: GRAPHVIZ_NODE_PREFIX

     The prefix for each node in the Graphviz files.

        * Mandatory: NO

        * Default: “node”

 -- Variable: GRAPHVIZ_EXECUTABLES

     Set to FALSE to exclude executables from the generated graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_STATIC_LIBS

     Set to FALSE to exclude static libraries from the generated graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_SHARED_LIBS

     Set to FALSE to exclude shared libraries from the generated graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_MODULE_LIBS

     Set to FALSE to exclude module libraries from the generated graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_INTERFACE_LIBS

     Set to FALSE to exclude interface libraries from the generated
     graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_OBJECT_LIBS

     Set to FALSE to exclude object libraries from the generated graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_UNKNOWN_LIBS

     Set to FALSE to exclude unknown libraries from the generated
     graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_EXTERNAL_LIBS

     Set to FALSE to exclude external libraries from the generated
     graphs.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_CUSTOM_TARGETS

     Set to TRUE to include custom targets in the generated graphs.

        * Mandatory: NO

        * Default: FALSE

 -- Variable: GRAPHVIZ_IGNORE_TARGETS

     A list of regular expressions for names of targets to exclude from
     the generated graphs.

        * Mandatory: NO

        * Default: empty

 -- Variable: GRAPHVIZ_GENERATE_PER_TARGET

     Set to FALSE to not generate per-target graphs ‘foo.dot.<target>’.

        * Mandatory: NO

        * Default: TRUE

 -- Variable: GRAPHVIZ_GENERATE_DEPENDERS

     Set to FALSE to not generate depender graphs
     ‘foo.dot.<target>.dependers’.

        * Mandatory: NO

        * Default: TRUE

15.1.45 CMakePackageConfigHelpers
---------------------------------

Helpers functions for creating config files that can be included by
other projects to find and use a package.

Adds the configure_package_config_file() and
write_basic_package_version_file() commands.

15.1.45.1 Generating a Package Configuration File
.................................................

 -- Command: configure_package_config_file

     Create a config file for a project:

          configure_package_config_file(<input> <output>
            INSTALL_DESTINATION <path>
            [PATH_VARS <var1> <var2> ... <varN>]
            [NO_SET_AND_CHECK_MACRO]
            [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
            [INSTALL_PREFIX <path>]
            )

‘configure_package_config_file()’ should be used instead of the plain
configure_file() command when creating the
‘<PackageName>Config.cmake’ or ‘<PackageName>-config.cmake’ file for
installing a project or library.  It helps making the resulting package
relocatable by avoiding hardcoded paths in the installed ‘Config.cmake’
file.

In a ‘FooConfig.cmake’ file there may be code like this to make the
install destinations know to the using project:

     set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
     set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
     set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
     #...logic to determine installedPrefix from the own location...
     set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )

All 4 options shown above are not sufficient, since the first 3 hardcode
the absolute directory locations, and the 4th case works only if the
logic to determine the ‘installedPrefix’ is correct, and if
‘CONFIG_INSTALL_DIR’ contains a relative path, which in general cannot
be guaranteed.  This has the effect that the resulting ‘FooConfig.cmake’
file would work poorly under Windows and OSX, where users are used to
choose the install location of a binary package at install time,
independent from how CMAKE_INSTALL_PREFIX was set at
build/cmake time.

Using ‘configure_package_config_file’ helps.  If used correctly, it
makes the resulting ‘FooConfig.cmake’ file relocatable.  Usage:

  1. write a ‘FooConfig.cmake.in’ file as you are used to

  2. insert a line containing only the string ‘@PACKAGE_INIT@’

  3. instead of ‘set(FOO_DIR "@SOME_INSTALL_DIR@")’, use ‘set(FOO_DIR
     "@PACKAGE_SOME_INSTALL_DIR@")’ (this must be after the
     ‘@PACKAGE_INIT@’ line)

  4. instead of using the normal configure_file(), use
     ‘configure_package_config_file()’

The ‘<input>’ and ‘<output>’ arguments are the input and output file,
the same way as in configure_file().

The ‘<path>’ given to ‘INSTALL_DESTINATION’ must be the destination
where the ‘FooConfig.cmake’ file will be installed to.  This path can
either be absolute, or relative to the ‘INSTALL_PREFIX’ path.

The variables ‘<var1>’ to ‘<varN>’ given as ‘PATH_VARS’ are the
variables which contain install destinations.  For each of them the
macro will create a helper variable ‘PACKAGE_<var...>’.  These helper
variables must be used in the ‘FooConfig.cmake.in’ file for setting the
installed location.  They are calculated by
‘configure_package_config_file’ so that they are always relative to the
installed location of the package.  This works both for relative and
also for absolute locations.  For absolute locations it works only if
the absolute location is a subdirectory of ‘INSTALL_PREFIX’.

If the ‘INSTALL_PREFIX’ argument is passed, this is used as base path to
calculate all the relative paths.  The ‘<path>’ argument must be an
absolute path.  If this argument is not passed, the
CMAKE_INSTALL_PREFIX variable will be used instead.  The default
value is good when generating a FooConfig.cmake file to use your package
from the install tree.  When generating a FooConfig.cmake file to use
your package from the build tree this option should be used.

By default ‘configure_package_config_file’ also generates two helper
macros, ‘set_and_check()’ and ‘check_required_components()’ into the
‘FooConfig.cmake’ file.

‘set_and_check()’ should be used instead of the normal ‘set()’ command
for setting directories and file locations.  Additionally to setting the
variable it also checks that the referenced file or directory actually
exists and fails with a ‘FATAL_ERROR’ otherwise.  This makes sure that
the created ‘FooConfig.cmake’ file does not contain wrong references.
When using the ‘NO_SET_AND_CHECK_MACRO’, this macro is not generated
into the ‘FooConfig.cmake’ file.

‘check_required_components(<PackageName>)’ should be called at the end
of the ‘FooConfig.cmake’ file.  This macro checks whether all requested,
non-optional components have been found, and if this is not the case,
sets the ‘Foo_FOUND’ variable to ‘FALSE’, so that the package is
considered to be not found.  It does that by testing the
‘Foo_<Component>_FOUND’ variables for all requested required components.
This macro should be called even if the package doesn’t provide any
components to make sure users are not specifying components erroneously.
When using the ‘NO_CHECK_REQUIRED_COMPONENTS_MACRO’ option, this macro
is not generated into the ‘FooConfig.cmake’ file.

For an example see below the documentation for
write_basic_package_version_file().

15.1.45.2 Generating a Package Version File
...........................................

 -- Command: write_basic_package_version_file

     Create a version file for a project:

          write_basic_package_version_file(<filename>
            [VERSION <major.minor.patch>]
            COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
            [ARCH_INDEPENDENT] )

Writes a file for use as ‘<PackageName>ConfigVersion.cmake’ file to
‘<filename>’.  See the documentation of find_package() for
details on this.

‘<filename>’ is the output filename, it should be in the build tree.
‘<major.minor.patch>’ is the version number of the project to be
installed.

If no ‘VERSION’ is given, the PROJECT_VERSION variable is
used.  If this hasn’t been set, it errors out.

The ‘COMPATIBILITY’ mode ‘AnyNewerVersion’ means that the installed
package version will be considered compatible if it is newer or exactly
the same as the requested version.  This mode should be used for
packages which are fully backward compatible, also across major
versions.  If ‘SameMajorVersion’ is used instead, then the behaviour
differs from ‘AnyNewerVersion’ in that the major version number must be
the same as requested, e.g.  version 2.0 will not be considered
compatible if 1.0 is requested.  This mode should be used for packages
which guarantee backward compatibility within the same major version.
If ‘SameMinorVersion’ is used, the behaviour is the same as
‘SameMajorVersion’, but both major and minor version must be the same as
requested, e.g version 0.2 will not be compatible if 0.1 is requested.
If ‘ExactVersion’ is used, then the package is only considered
compatible if the requested version matches exactly its own version
number (not considering the tweak version).  For example, version 1.2.3
of a package is only considered compatible to requested version 1.2.3.
This mode is for packages without compatibility guarantees.  If your
project has more elaborated version matching rules, you will need to
write your own custom ‘ConfigVersion.cmake’ file instead of using this
macro.

     Note: ‘COMPATIBILITY_MODE’ ‘AnyNewerVersion’, ‘SameMajorVersion’
     and ‘SameMinorVersion’ handle the version range if any is specified
     (see find_package() command for the details).
     ‘ExactVersion’ is incompatible with version ranges and will display
     an author warning if one is specified.

If ‘ARCH_INDEPENDENT’ is given, the installed package version will be
considered compatible even if it was built for a different architecture
than the requested architecture.  Otherwise, an architecture check will
be performed, and the package will be considered compatible only if the
architecture matches exactly.  For example, if the package is built for
a 32-bit architecture, the package is only considered compatible if it
is used on a 32-bit architecture, unless ‘ARCH_INDEPENDENT’ is given, in
which case the package is considered compatible on any architecture.

     Note: ‘ARCH_INDEPENDENT’ is intended for header-only libraries or
     similar packages with no binaries.

Internally, this macro executes configure_file() to create
the resulting version file.  Depending on the ‘COMPATIBILITY’, the
corresponding ‘BasicConfigVersion-<COMPATIBILITY>.cmake.in’ file is
used.  Please note that these files are internal to CMake and you should
not call configure_file() on them yourself, but they can be
used as starting point to create more sophisticted custom
‘ConfigVersion.cmake’ files.

15.1.45.3 Example Generating Package Files
..........................................

Example using both configure_package_config_file() and
‘write_basic_package_version_file()’:

‘CMakeLists.txt’:

     set(INCLUDE_INSTALL_DIR include/ ... CACHE )
     set(LIB_INSTALL_DIR lib/ ... CACHE )
     set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
     #...
     include(CMakePackageConfigHelpers)
     configure_package_config_file(FooConfig.cmake.in
       ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
       INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
       PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
     write_basic_package_version_file(
       ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
       VERSION 1.2.3
       COMPATIBILITY SameMajorVersion )
     install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
                   ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
             DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )

‘FooConfig.cmake.in’:

     set(FOO_VERSION x.y.z)
     ...
     @PACKAGE_INIT@
     ...
     set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
     set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")

     check_required_components(Foo)

15.1.46 CMakePrintHelpers
-------------------------

Convenience functions for printing properties and variables, useful e.g.
for debugging.

     cmake_print_properties([TARGETS target1 ..  targetN]
                           [SOURCES source1 .. sourceN]
                           [DIRECTORIES dir1 .. dirN]
                           [TESTS test1 .. testN]
                           [CACHE_ENTRIES entry1 .. entryN]
                           PROPERTIES prop1 .. propN )

This function prints the values of the properties of the given targets,
source files, directories, tests or cache entries.  Exactly one of the
scope keywords must be used.  Example:

     cmake_print_properties(TARGETS foo bar PROPERTIES
                            LOCATION INTERFACE_INCLUDE_DIRECTORIES)

This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES
properties for both targets foo and bar.

     cmake_print_variables(var1 var2 ..  varN)

This function will print the name of each variable followed by its
value.  Example:

     cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)

Gives:

     -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""

15.1.47 CMakePrintSystemInformation
-----------------------------------

Print system information.

This module serves diagnostic purposes.  Just include it in a project to
see various internal CMake variables.

15.1.48 CMakePushCheckState
---------------------------

This module defines three macros: ‘CMAKE_PUSH_CHECK_STATE()’
‘CMAKE_POP_CHECK_STATE()’ and ‘CMAKE_RESET_CHECK_STATE()’ These macros
can be used to save, restore and reset (i.e., clear contents) the state
of the variables ‘CMAKE_REQUIRED_FLAGS’, ‘CMAKE_REQUIRED_DEFINITIONS’,
‘CMAKE_REQUIRED_LINK_OPTIONS’, ‘CMAKE_REQUIRED_LIBRARIES’,
‘CMAKE_REQUIRED_INCLUDES’ and ‘CMAKE_EXTRA_INCLUDE_FILES’ used by the
various Check-files coming with CMake, like e.g.
‘check_function_exists()’ etc.  The variable contents are pushed on a
stack, pushing multiple times is supported.  This is useful e.g.  when
executing such tests in a Find-module, where they have to be set, but
after the Find-module has been executed they should have the same value
as they had before.

‘CMAKE_PUSH_CHECK_STATE()’ macro receives optional argument ‘RESET’.
Whether it’s specified, ‘CMAKE_PUSH_CHECK_STATE()’ will set all
‘CMAKE_REQUIRED_*’ variables to empty values, same as
‘CMAKE_RESET_CHECK_STATE()’ call will do.

Usage:

     cmake_push_check_state(RESET)
     set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
     check_function_exists(...)
     cmake_reset_check_state()
     set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
     check_function_exists(...)
     cmake_pop_check_state()

15.1.49 CMakeVerifyManifest
---------------------------

CMakeVerifyManifest.cmake

This script is used to verify that embedded manifests and side by side
manifests for a project match.  To run this script, cd to a directory
and run the script with cmake -P. On the command line you can pass in
versions that are OK even if not found in the .manifest files.  For
example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
could be used to allow an embedded manifest of 8.0.50608.0 to be used in
a project even if that version was not found in the .manifest file.

15.1.50 CPack
-------------

Configure generators for binary installers and source packages.

15.1.50.1 Introduction
......................

The CPack module generates the configuration files ‘CPackConfig.cmake’
and ‘CPackSourceConfig.cmake’.  They are intended for use in a
subsequent run of the cpack program where they steer the
generation of installers or/and source packages.

Depending on the CMake generator, the CPack module may also add two new
build targets, ‘package’ and ‘package_source’.  See the packaging targets
section below for details.

The generated binary installers will contain all files that have been
installed via CMake’s install() command (and the deprecated
commands install_files(), install_programs(), and
install_targets()).  Note that the ‘DESTINATION’ option of
the install() command must be a relative path; otherwise
installed files are ignored by CPack.

Certain kinds of binary installers can be configured such that users can
select individual application components to install.  See the
CPackComponent module for further details.

Source packages (configured through ‘CPackSourceConfig.cmake’ and
generated by the CPack Archive Generator) will contain all
source files in the project directory except those specified in
CPACK_SOURCE_IGNORE_FILES.

15.1.50.2 CPack Generators
..........................

The CPACK_GENERATOR variable has different meanings in
different contexts.  In a ‘CMakeLists.txt’ file, see CPACK_GENERATOR
is a `list of generators': and when cpack is run with no
other arguments, it will iterate over that list and produce one package
for each generator.  In a CPACK_PROJECT_CONFIG_FILE,
CPACK_GENERATOR is a `string naming a single generator'.  If you
need per-cpack-generator logic to control `other' cpack settings, then
you need a CPACK_PROJECT_CONFIG_FILE.  If set, the
CPACK_PROJECT_CONFIG_FILE is included automatically on a
per-generator basis.  It only need contain overrides.

Here’s how it works:

   * cpack runs

   * it includes ‘CPackConfig.cmake’

   * it iterates over the generators given by the ‘-G’ command line
     option, or if no such option was specified, over the list of
     generators given by the CPACK_GENERATOR variable set in
     the ‘CPackConfig.cmake’ input file.

   * foreach generator, it then

        - sets CPACK_GENERATOR to the one currently being
          iterated

        - includes the CPACK_PROJECT_CONFIG_FILE.

        - produces the package for that generator

This is the key: For each generator listed in CPACK_GENERATOR.
in ‘CPackConfig.cmake’, cpack will `reset' CPACK_GENERATOR.
internally to `the one currently being used' and then include the
CPACK_PROJECT_CONFIG_FILE.

For a list of available generators, see cpack-generators(7).

15.1.50.3 Targets package and package_source
............................................

If CMake is run with the Makefile, Ninja, or Xcode generator, then
‘include(CPack)’ generates a target ‘package’.  This makes it possible
to build a binary installer from CMake, Make, or Ninja: Instead of
‘cpack’, one may call ‘cmake --build . --target package’ or ‘make
package’ or ‘ninja package’.  The VS generator creates an uppercase
target ‘PACKAGE’.

If CMake is run with the Makefile or Ninja generator, then
‘include(CPack)’ also generates a target ‘package_source’.  To build a
source package, instead of ‘cpack -G TGZ --config
CPackSourceConfig.cmake’ one may call ‘cmake --build . --target
package_source’, ‘make package_source’, or ‘ninja package_source’.

15.1.50.4 Variables common to all CPack Generators
..................................................

Before including this CPack module in your ‘CMakeLists.txt’ file, there
are a variety of variables that can be set to customize the resulting
installers.  The most commonly-used variables are:

 -- Variable: CPACK_PACKAGE_NAME

     The name of the package (or application).  If not specified, it
     defaults to the project name.

 -- Variable: CPACK_PACKAGE_VENDOR

     The name of the package vendor.  (e.g., “Kitware”).  The default is
     “Humanity”.

 -- Variable: CPACK_PACKAGE_DIRECTORY

     The directory in which CPack is doing its packaging.  If it is not
     set then this will default (internally) to the build dir.  This
     variable may be defined in a CPack config file or from the
     cpack command line option ‘-B’.  If set, the command line
     option overrides the value found in the config file.

 -- Variable: CPACK_PACKAGE_VERSION_MAJOR

     Package major version.  This variable will always be set, but its
     default value depends on whether or not version details were given
     to the project() command in the top level
     CMakeLists.txt file.  If version details were given, the default
     value will be CMAKE_PROJECT_VERSION_MAJOR.  If no
     version details were given, a default version of 0.1.1 will be
     assumed, leading to ‘CPACK_PACKAGE_VERSION_MAJOR’ having a default
     value of 0.

 -- Variable: CPACK_PACKAGE_VERSION_MINOR

     Package minor version.  The default value is determined based on
     whether or not version details were given to the project()
     command in the top level CMakeLists.txt file.  If version
     details were given, the default value will be
     CMAKE_PROJECT_VERSION_MINOR, but if no minor version component
     was specified then ‘CPACK_PACKAGE_VERSION_MINOR’ will be left
     unset.  If no project version was given at all, a default version
     of 0.1.1 will be assumed, leading to ‘CPACK_PACKAGE_VERSION_MINOR’
     having a default value of 1.

 -- Variable: CPACK_PACKAGE_VERSION_PATCH

     Package patch version.  The default value is determined based on
     whether or not version details were given to the project()
     command in the top level CMakeLists.txt file.  If version
     details were given, the default value will be
     CMAKE_PROJECT_VERSION_PATCH, but if no patch version component
     was specified then ‘CPACK_PACKAGE_VERSION_PATCH’ will be left
     unset.  If no project version was given at all, a default version
     of 0.1.1 will be assumed, leading to ‘CPACK_PACKAGE_VERSION_PATCH’
     having a default value of 1.

 -- Variable: CPACK_PACKAGE_DESCRIPTION

     A description of the project, used in places such as the
     introduction screen of CPack-generated Windows installers.  If not
     set, the value of this variable is populated from the file named by
     CPACK_PACKAGE_DESCRIPTION_FILE.

 -- Variable: CPACK_PACKAGE_DESCRIPTION_FILE

     A text file used to describe the project when
     CPACK_PACKAGE_DESCRIPTION is not explicitly set.  The default
     value for ‘CPACK_PACKAGE_DESCRIPTION_FILE’ points to a built-in
     template file ‘Templates/CPack.GenericDescription.txt’.

 -- Variable: CPACK_PACKAGE_DESCRIPTION_SUMMARY

     Short description of the project (only a few words).  If the
     CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
     default value, otherwise the default will be a string generated by
     CMake based on CMAKE_PROJECT_NAME.

 -- Variable: CPACK_PACKAGE_HOMEPAGE_URL

     Project homepage URL. The default value is taken from the
     CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
     level project() command, or else the default will be
     empty if no URL was provided to project().

 -- Variable: CPACK_PACKAGE_FILE_NAME

     The name of the package file to generate, not including the
     extension.  For example, ‘cmake-2.6.1-Linux-i686’.  The default
     value is:

          ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}

 -- Variable: CPACK_PACKAGE_INSTALL_DIRECTORY

     Installation directory on the target system.  This may be used by
     some CPack generators like NSIS to create an installation directory
     e.g., “CMake 2.5” below the installation prefix.  All installed
     elements will be put inside this directory.

 -- Variable: CPACK_PACKAGE_ICON

     A branding image that will be displayed inside the installer (used
     by GUI installers).

 -- Variable: CPACK_PACKAGE_CHECKSUM

     An algorithm that will be used to generate an additional file with
     the checksum of the package.  The output file name will be:

          ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

     Supported algorithms are those listed by the string(<HASH>)
     command.

 -- Variable: CPACK_PROJECT_CONFIG_FILE

     CPack-time project CPack configuration file.  This file is included
     at cpack time, once per generator after CPack has set
     CPACK_GENERATOR to the actual generator being used.  It allows
     per-generator setting of ‘CPACK_*’ variables at cpack time.

 -- Variable: CPACK_RESOURCE_FILE_LICENSE

     License to be embedded in the installer.  It will typically be
     displayed to the user by the produced installer (often with an
     explicit “Accept” button, for graphical installers) prior to
     installation.  This license file is NOT added to the installed
     files but is used by some CPack generators like NSIS. If you want
     to install a license file (may be the same as this one) along with
     your project, you must add an appropriate CMake install()
     command in your ‘CMakeLists.txt’.

 -- Variable: CPACK_RESOURCE_FILE_README

     ReadMe file to be embedded in the installer.  It typically
     describes in some detail the purpose of the project during the
     installation.  Not all CPack generators use this file.

 -- Variable: CPACK_RESOURCE_FILE_WELCOME

     Welcome file to be embedded in the installer.  It welcomes users to
     this installer.  Typically used in the graphical installers on
     Windows and Mac OS X.

 -- Variable: CPACK_MONOLITHIC_INSTALL

     Disables the component-based installation mechanism.  When set, the
     component specification is ignored and all installed items are put
     in a single “MONOLITHIC” package.  Some CPack generators do
     monolithic packaging by default and may be asked to do component
     packaging by setting ‘CPACK_<GENNAME>_COMPONENT_INSTALL’ to ‘TRUE’.

 -- Variable: CPACK_GENERATOR

     List of CPack generators to use.  If not specified, CPack will
     create a set of options following the naming pattern
     CPACK_BINARY_<GENNAME>. (e.g.  ‘CPACK_BINARY_NSIS’) allowing
     the user to enable/disable individual generators.  If the ‘-G’
     option is given on the cpack command line, it will
     override this variable and any ‘CPACK_BINARY_<GENNAME>’ options.

 -- Variable: CPACK_OUTPUT_CONFIG_FILE

     The name of the CPack binary configuration file.  This file is the
     CPack configuration generated by the CPack module for binary
     installers.  Defaults to ‘CPackConfig.cmake’.

 -- Variable: CPACK_PACKAGE_EXECUTABLES

     Lists each of the executables and associated text label to be used
     to create Start Menu shortcuts.  For example, setting this to the
     list ‘ccmake;CMake’ will create a shortcut named “CMake” that will
     execute the installed executable ‘ccmake’.  Not all CPack
     generators use it (at least NSIS, WIX and OSXX11 do).

 -- Variable: CPACK_STRIP_FILES

     List of files to be stripped.  Starting with CMake 2.6.0,
     ‘CPACK_STRIP_FILES’ will be a boolean variable which enables
     stripping of all files (a list of files evaluates to ‘TRUE’ in
     CMake, so this change is compatible).

 -- Variable: CPACK_VERBATIM_VARIABLES

     If set to ‘TRUE’, values of variables prefixed with ‘CPACK_’ will
     be escaped before being written to the configuration files, so that
     the cpack program receives them exactly as they were specified.  If
     not, characters like quotes and backslashes can cause parsing
     errors or alter the value received by the cpack program.  Defaults
     to ‘FALSE’ for backwards compatibility.

15.1.50.5 Variables for Source Package Generators
.................................................

The following CPack variables are specific to source packages, and will
not affect binary packages:

 -- Variable: CPACK_SOURCE_PACKAGE_FILE_NAME

     The name of the source package.  For example ‘cmake-2.6.1’.

 -- Variable: CPACK_SOURCE_STRIP_FILES

     List of files in the source tree that will be stripped.  Starting
     with CMake 2.6.0, ‘CPACK_SOURCE_STRIP_FILES’ will be a boolean
     variable which enables stripping of all files (a list of files
     evaluates to ‘TRUE’ in CMake, so this change is compatible).

 -- Variable: CPACK_SOURCE_GENERATOR

     List of generators used for the source packages.  As with
     CPACK_GENERATOR, if this is not specified then CPack will
     create a set of options (e.g.  ‘CPACK_SOURCE_ZIP’) allowing users
     to select which packages will be generated.

 -- Variable: CPACK_SOURCE_OUTPUT_CONFIG_FILE

     The name of the CPack source configuration file.  This file is the
     CPack configuration generated by the CPack module for source
     installers.  Defaults to ‘CPackSourceConfig.cmake’.

 -- Variable: CPACK_SOURCE_IGNORE_FILES

     Pattern of files in the source tree that won’t be packaged when
     building a source package.  This is a list of regular expression
     patterns (that must be properly escaped), e.g.,
     ‘/CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*’

15.1.50.6 Variables for Advanced Use
....................................

The following variables are for advanced uses of CPack:

 -- Variable: CPACK_CMAKE_GENERATOR

     What CMake generator should be used if the project is a CMake
     project.  Defaults to the value of CMAKE_GENERATOR.  Few
     users will want to change this setting.

 -- Variable: CPACK_INSTALL_CMAKE_PROJECTS

     List of four values that specify what project to install.  The four
     values are: Build directory, Project Name, Project Component,
     Directory.  If omitted, CPack will build an installer that installs
     everything.

 -- Variable: CPACK_SYSTEM_NAME

     System name, defaults to the value of CMAKE_SYSTEM_NAME,
     except on Windows where it will be ‘win32’ or ‘win64’.

 -- Variable: CPACK_PACKAGE_VERSION

     Package full version, used internally.  By default, this is built
     from CPACK_PACKAGE_VERSION_MAJOR,
     CPACK_PACKAGE_VERSION_MINOR, and
     CPACK_PACKAGE_VERSION_PATCH.

 -- Variable: CPACK_TOPLEVEL_TAG

     Directory for the installed files.

 -- Variable: CPACK_INSTALL_COMMANDS

     Extra commands to install components.  The environment variable
     ‘CMAKE_INSTALL_PREFIX’ is set to the temporary install directory
     during execution.

 -- Variable: CPACK_INSTALL_SCRIPTS

     Extra CMake scripts executed by CPack during its local staging
     installation.  They are executed before installing the files to be
     packaged.  The scripts are not called by a standalone install
     (e.g.: ‘make install’).  For every script, the following variables
     will be set: CMAKE_CURRENT_SOURCE_DIR,
     CMAKE_CURRENT_BINARY_DIR and CMAKE_INSTALL_PREFIX.
     (which is set to the staging install directory).  The singular form
     ‘CMAKE_INSTALL_SCRIPT’ is supported as an alternative variable for
     historical reasons, but its value is ignored if
     ‘CMAKE_INSTALL_SCRIPTS’ is set and a warning will be issued.

     See also CPACK_PRE_BUILD_SCRIPTS and
     CPACK_POST_BUILD_SCRIPTS which can be used to specify scripts
     to be executed later in the packaging process.

 -- Variable: CPACK_PRE_BUILD_SCRIPTS

     List of CMake scripts to execute after CPack has installed the
     files to be packaged into a staging directory and before producing
     the package(s) from those files.  See also
     CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.

 -- Variable: CPACK_POST_BUILD_SCRIPTS

     List of CMake scripts to execute after CPack has produced the
     resultant packages and before copying them back to the build
     directory.  See also CPACK_INSTALL_SCRIPTS,
     CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.

 -- Variable: CPACK_PACKAGE_FILES

     List of package files created in the staging directory, with each
     file provided as a full absolute path.  This variable is populated
     by CPack just before invoking the post-build scripts listed in
     CPACK_POST_BUILD_SCRIPTS.  It is the preferred way for
     the post-build scripts to know the set of package files to operate
     on.  Projects should not try to set this variable themselves.

 -- Variable: CPACK_INSTALLED_DIRECTORIES

     Extra directories to install.

 -- Variable: CPACK_PACKAGE_INSTALL_REGISTRY_KEY

     Registry key used when installing this project.  This is only used
     by installers for Windows.  The default value is based on the
     installation directory.

 -- Variable: CPACK_CREATE_DESKTOP_LINKS

     List of desktop links to create.  Each desktop link requires a
     corresponding start menu shortcut as created by
     CPACK_PACKAGE_EXECUTABLES.

 -- Variable: CPACK_BINARY_<GENNAME>

     CPack generated options for binary generators.  The ‘CPack.cmake’
     module generates (when CPACK_GENERATOR is not set) a set
     of CMake options (see CMake option() command) which may
     then be used to select the CPack generator(s) to be used when
     building the ‘package’ target or when running cpack.
     without the ‘-G’ option.

15.1.51 CPackComponent
----------------------

Configure components for binary installers and source packages.

15.1.51.1 Introduction
......................

This module is automatically included by CPack.

Certain binary installers (especially the graphical installers)
generated by CPack allow users to select individual application
`components' to install.  This module allows developers to configure the
packaging of such components.

Contents is assigned to components by the ‘COMPONENT’ argument of
CMake’s install() command.  Components can be annotated with
user-friendly names and descriptions, inter-component dependencies,
etc., and grouped in various ways to customize the resulting installer,
using the commands described below.

To specify different groupings for different CPack generators use a
CPACK_PROJECT_CONFIG_FILE.

15.1.51.2 Variables
...................

The following variables influence the component-specific packaging:

 -- Variable: CPACK_COMPONENTS_ALL

     The list of component to install.

     The default value of this variable is computed by CPack and
     contains all components defined by the project.  The user may set
     it to only include the specified components.

     Instead of specifying all the desired components, it is possible to
     obtain a list of all defined components and then remove the
     unwanted ones from the list.  The get_cmake_property().
     command can be used to obtain the ‘COMPONENTS’ property, then the
     list(REMOVE_ITEM) command can be used to remove the
     unwanted ones.  For example, to use all defined components except
     ‘foo’ and ‘bar’:

          get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
          list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")

 -- Variable: CPACK_<GENNAME>_COMPONENT_INSTALL

     Enable/Disable component install for CPack generator <GENNAME>.

     Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
     legacy default behavior.  e.g.  RPM builds monolithic whereas NSIS
     builds component.  One can change the default behavior by setting
     this variable to 0/1 or OFF/ON.

 -- Variable: CPACK_COMPONENTS_GROUPING

     Specify how components are grouped for multi-package
     component-aware CPack generators.

     Some generators like RPM or ARCHIVE (TGZ, ZIP, …) may generate
     several packages files when there are components, depending on the
     value of this variable:

        * ONE_PER_GROUP (default): create one package per component
          group

        * IGNORE : create one package per component (ignore the groups)

        * ALL_COMPONENTS_IN_ONE : create a single package with all
          requested components

 -- Variable: CPACK_COMPONENT_<compName>_DISPLAY_NAME

     The name to be displayed for a component.

 -- Variable: CPACK_COMPONENT_<compName>_DESCRIPTION

     The description of a component.

 -- Variable: CPACK_COMPONENT_<compName>_GROUP

     The group of a component.

 -- Variable: CPACK_COMPONENT_<compName>_DEPENDS

     The dependencies (list of components) on which this component
     depends.

 -- Variable: CPACK_COMPONENT_<compName>_HIDDEN

     True if this component is hidden from the user.

 -- Variable: CPACK_COMPONENT_<compName>_REQUIRED

     True if this component is required.

 -- Variable: CPACK_COMPONENT_<compName>_DISABLED

     True if this component is not selected to be installed by default.

15.1.51.3 Commands
..................

15.1.51.4 Add component
.......................

 -- Command: cpack_add_component

Describe an installation component.

     cpack_add_component(compname
                         [DISPLAY_NAME name]
                         [DESCRIPTION description]
                         [HIDDEN | REQUIRED | DISABLED ]
                         [GROUP group]
                         [DEPENDS comp1 comp2 ... ]
                         [INSTALL_TYPES type1 type2 ... ]
                         [DOWNLOADED]
                         [ARCHIVE_FILE filename]
                         [PLIST filename])

‘compname’ is the name of an installation component, as defined by the
‘COMPONENT’ argument of one or more CMake install().
commands.  With the ‘cpack_add_component’ command one can set a name, a
description, and other attributes of an installation component.  One can
also assign a component to a component group.

DISPLAY_NAME is the displayed name of the component, used in graphical
installers to display the component name.  This value can be any string.

DESCRIPTION is an extended description of the component, used in
graphical installers to give the user additional information about the
component.  Descriptions can span multiple lines using ‘\n’ as the line
separator.  Typically, these descriptions should be no more than a few
lines long.

HIDDEN indicates that this component will be hidden in the graphical
installer, so that the user cannot directly change whether it is
installed or not.

REQUIRED indicates that this component is required, and therefore will
always be installed.  It will be visible in the graphical installer, but
it cannot be unselected.  (Typically, required components are shown
greyed out).

DISABLED indicates that this component should be disabled (unselected)
by default.  The user is free to select this component for installation,
unless it is also HIDDEN.

DEPENDS lists the components on which this component depends.  If this
component is selected, then each of the components listed must also be
selected.  The dependency information is encoded within the installer
itself, so that users cannot install inconsistent sets of components.

GROUP names the component group of which this component is a part.  If
not provided, the component will be a standalone component, not part of
any component group.  Component groups are described with the
cpack_add_component_group command, detailed below.

INSTALL_TYPES lists the installation types of which this component is a
part.  When one of these installations types is selected, this component
will automatically be selected.  Installation types are described with
the cpack_add_install_type command, detailed below.

DOWNLOADED indicates that this component should be downloaded on-the-fly
by the installer, rather than packaged in with the installer itself.
For more information, see the cpack_configure_downloads command.

ARCHIVE_FILE provides a name for the archive file created by CPack to be
used for downloaded components.  If not supplied, CPack will create a
file with some name based on CPACK_PACKAGE_FILE_NAME and the name of the
component.  See cpack_configure_downloads for more information.

PLIST gives a filename that is passed to pkgbuild with the
‘--component-plist’ argument when using the productbuild generator.

15.1.51.5 Add component group
.............................

 -- Command: cpack_add_component_group

Describes a group of related CPack installation components.

     cpack_add_component_group(groupname
                              [DISPLAY_NAME name]
                              [DESCRIPTION description]
                              [PARENT_GROUP parent]
                              [EXPANDED]
                              [BOLD_TITLE])

The cpack_add_component_group describes a group of installation
components, which will be placed together within the listing of options.
Typically, component groups allow the user to select/deselect all of the
components within a single group via a single group-level option.  Use
component groups to reduce the complexity of installers with many
options.  groupname is an arbitrary name used to identify the group in
the GROUP argument of the cpack_add_component command, which is used to
place a component in a group.  The name of the group must not conflict
with the name of any component.

DISPLAY_NAME is the displayed name of the component group, used in
graphical installers to display the component group name.  This value
can be any string.

DESCRIPTION is an extended description of the component group, used in
graphical installers to give the user additional information about the
components within that group.  Descriptions can span multiple lines
using ‘\n’ as the line separator.  Typically, these descriptions should
be no more than a few lines long.

PARENT_GROUP, if supplied, names the parent group of this group.  Parent
groups are used to establish a hierarchy of groups, providing an
arbitrary hierarchy of groups.

EXPANDED indicates that, by default, the group should show up as
“expanded”, so that the user immediately sees all of the components
within the group.  Otherwise, the group will initially show up as a
single entry.

BOLD_TITLE indicates that the group title should appear in bold, to call
the user’s attention to the group.

15.1.51.6 Add installation type
...............................

 -- Command: cpack_add_install_type

Add a new installation type containing a set of predefined component
selections to the graphical installer.

     cpack_add_install_type(typename
                            [DISPLAY_NAME name])

The cpack_add_install_type command identifies a set of preselected
components that represents a common use case for an application.  For
example, a “Developer” install type might include an application along
with its header and library files, while an “End user” install type
might just include the application’s executable.  Each component
identifies itself with one or more install types via the INSTALL_TYPES
argument to cpack_add_component.

DISPLAY_NAME is the displayed name of the install type, which will
typically show up in a drop-down box within a graphical installer.  This
value can be any string.

15.1.51.7 Configure downloads
.............................

 -- Command: cpack_configure_downloads

Configure CPack to download selected components on-the-fly as part of
the installation process.

     cpack_configure_downloads(site
                               [UPLOAD_DIRECTORY dirname]
                               [ALL]
                               [ADD_REMOVE|NO_ADD_REMOVE])

The cpack_configure_downloads command configures installation-time
downloads of selected components.  For each downloadable component,
CPack will create an archive containing the contents of that component,
which should be uploaded to the given site.  When the user selects that
component for installation, the installer will download and extract the
component in place.  This feature is useful for creating small
installers that only download the requested components, saving
bandwidth.  Additionally, the installers are small enough that they will
be installed as part of the normal installation process, and the
“Change” button in Windows Add/Remove Programs control panel will allow
one to add or remove parts of the application after the original
installation.  On Windows, the downloaded-components functionality
requires the ZipDLL plug-in for NSIS, available at:

     http://nsis.sourceforge.net/ZipDLL_plug-in

On macOS, installers that download components on-the-fly can only be
built and installed on system using macOS 10.5 or later.

The site argument is a URL where the archives for downloadable
components will reside, e.g., ‘https://cmake.org/files/2.6.1/installer/’
All of the archives produced by CPack should be uploaded to that
location.

UPLOAD_DIRECTORY is the local directory where CPack will create the
various archives for each of the components.  The contents of this
directory should be uploaded to a location accessible by the URL given
in the site argument.  If omitted, CPack will use the directory
CPackUploads inside the CMake binary directory to store the generated
archives.

The ALL flag indicates that all components be downloaded.  Otherwise,
only those components explicitly marked as DOWNLOADED or that have a
specified ARCHIVE_FILE will be downloaded.  Additionally, the ALL option
implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).

ADD_REMOVE indicates that CPack should install a copy of the installer
that can be called from Windows’ Add/Remove Programs dialog (via the
“Modify” button) to change the set of installed components.
NO_ADD_REMOVE turns off this behavior.  This option is ignored on Mac OS
X.

15.1.52 CPackIFW
----------------

New in version 3.1.

This module looks for the location of the command-line utilities
supplied with the Qt Installer Framework(1) (QtIFW).

The module also defines several commands to control the behavior of the
CPack IFW Generator.

   ---------- Footnotes ----------

   (1) http://doc.qt.io/qtinstallerframework/index.html

15.1.52.1 Commands
..................

The module defines the following commands:

 -- Command: cpack_ifw_configure_component

     Sets the arguments specific to the CPack IFW generator.

          cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
                              [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
                              [NAME <name>]
                              [DISPLAY_NAME <display_name>] # Note: Internationalization supported
                              [DESCRIPTION <description>] # Note: Internationalization supported
                              [UPDATE_TEXT <update_text>]
                              [VERSION <version>]
                              [RELEASE_DATE <release_date>]
                              [SCRIPT <script>]
                              [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
                              [DEPENDS|DEPENDENCIES <com_id> ...]
                              [AUTO_DEPEND_ON <comp_id> ...]
                              [LICENSES <display_name> <file_path> ...]
                              [DEFAULT <value>]
                              [USER_INTERFACES <file_path> <file_path> ...]
                              [TRANSLATIONS <file_path> <file_path> ...]
                              [REPLACES <comp_id> ...]
                              [CHECKABLE <value>])

     This command should be called after cpack_add_component()
     command.

     ‘COMMON’

          if set, then the component will be packaged and installed as
          part of a group to which it belongs.

     ‘ESSENTIAL’

          if set, then the package manager stays disabled until that
          component is updated.

     ‘VIRTUAL’

          if set, then the component will be hidden from the installer.
          It is a equivalent of the ‘HIDDEN’ option from the
          cpack_add_component() command.

     ‘FORCED_INSTALLATION’

          if set, then the component must always be installed.  It is a
          equivalent of the ‘REQUIRED’ option from the
          cpack_add_component() command.

     ‘REQUIRES_ADMIN_RIGHTS’

          set it if the component needs to be installed with elevated
          permissions.

     ‘NAME’

          is used to create domain-like identification for this
          component.  By default used origin component name.

     ‘DISPLAY_NAME’

          set to rewrite original name configured by
          cpack_add_component() command.

     ‘DESCRIPTION’

          set to rewrite original description configured by
          cpack_add_component() command.

     ‘UPDATE_TEXT’

          will be added to the component description if this is an
          update to the component.

     ‘VERSION’

          is version of component.  By default used
          CPACK_PACKAGE_VERSION.

     ‘RELEASE_DATE’

          keep empty to auto generate.

     ‘SCRIPT’

          is a relative or absolute path to operations script for this
          component.

     ‘PRIORITY’ | ‘SORTING_PRIORITY’

          is priority of the component in the tree.  The ‘PRIORITY’
          option is deprecated and will be removed in a future version
          of CMake.  Please use ‘SORTING_PRIORITY’ option instead.

     ‘DEPENDS’ | ‘DEPENDENCIES’

          list of dependency component or component group identifiers in
          QtIFW style.

     ‘AUTO_DEPEND_ON’

          list of identifiers of component or component group in QtIFW
          style that this component has an automatic dependency on.

     ‘LICENSES’

          pair of <display_name> and <file_path> of license text for
          this component.  You can specify more then one license.

     ‘DEFAULT’

          Possible values are: TRUE, FALSE, and SCRIPT. Set to FALSE to
          disable the component in the installer or to SCRIPT to
          resolved during runtime (don’t forget add the file of the
          script as a value of the ‘SCRIPT’ option).

     ‘USER_INTERFACES’

          is a list of <file_path> (‘.ui’ files) representing pages to
          load.

     ‘TRANSLATIONS’

          is a list of <file_path> (‘.qm’ files) representing
          translations to load.

     ‘REPLACES’

          list of identifiers of component or component group to
          replace.

     ‘CHECKABLE’

          Possible values are: TRUE, FALSE. Set to FALSE if you want to
          hide the checkbox for an item.  This is useful when only a few
          subcomponents should be selected instead of all.

 -- Command: cpack_ifw_configure_component_group

     Sets the arguments specific to the CPack IFW generator.

          cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
                              [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
                              [NAME <name>]
                              [DISPLAY_NAME <display_name>] # Note: Internationalization supported
                              [DESCRIPTION <description>] # Note: Internationalization supported
                              [UPDATE_TEXT <update_text>]
                              [VERSION <version>]
                              [RELEASE_DATE <release_date>]
                              [SCRIPT <script>]
                              [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
                              [DEPENDS|DEPENDENCIES <com_id> ...]
                              [AUTO_DEPEND_ON <comp_id> ...]
                              [LICENSES <display_name> <file_path> ...]
                              [DEFAULT <value>]
                              [USER_INTERFACES <file_path> <file_path> ...]
                              [TRANSLATIONS <file_path> <file_path> ...]
                              [REPLACES <comp_id> ...]
                              [CHECKABLE <value>])

     This command should be called after
     cpack_add_component_group() command.

     ‘VIRTUAL’

          if set, then the group will be hidden from the installer.
          Note that setting this on a root component does not work.

     ‘FORCED_INSTALLATION’

          if set, then the group must always be installed.

     ‘REQUIRES_ADMIN_RIGHTS’

          set it if the component group needs to be installed with
          elevated permissions.

     ‘NAME’

          is used to create domain-like identification for this
          component group.  By default used origin component group name.

     ‘DISPLAY_NAME’

          set to rewrite original name configured by
          cpack_add_component_group() command.

     ‘DESCRIPTION’

          set to rewrite original description configured by
          cpack_add_component_group() command.

     ‘UPDATE_TEXT’

          will be added to the component group description if this is an
          update to the component group.

     ‘VERSION’

          is version of component group.  By default used
          CPACK_PACKAGE_VERSION.

     ‘RELEASE_DATE’

          keep empty to auto generate.

     ‘SCRIPT’

          is a relative or absolute path to operations script for this
          component group.

     ‘PRIORITY’ | ‘SORTING_PRIORITY’

          is priority of the component group in the tree.  The
          ‘PRIORITY’ option is deprecated and will be removed in a
          future version of CMake.  Please use ‘SORTING_PRIORITY’ option
          instead.

     ‘DEPENDS’ | ‘DEPENDENCIES’

          list of dependency component or component group identifiers in
          QtIFW style.

     ‘AUTO_DEPEND_ON’

          list of identifiers of component or component group in QtIFW
          style that this component group has an automatic dependency
          on.

     ‘LICENSES’

          pair of <display_name> and <file_path> of license text for
          this component group.  You can specify more then one license.

     ‘DEFAULT’

          Possible values are: TRUE, FALSE, and SCRIPT. Set to TRUE to
          preselect the group in the installer (this takes effect only
          on groups that have no visible child components) or to SCRIPT
          to resolved during runtime (don’t forget add the file of the
          script as a value of the ‘SCRIPT’ option).

     ‘USER_INTERFACES’

          is a list of <file_path> (‘.ui’ files) representing pages to
          load.

     ‘TRANSLATIONS’

          is a list of <file_path> (‘.qm’ files) representing
          translations to load.

     ‘REPLACES’

          list of identifiers of component or component group to
          replace.

     ‘CHECKABLE’

          Possible values are: TRUE, FALSE. Set to FALSE if you want to
          hide the checkbox for an item.  This is useful when only a few
          subcomponents should be selected instead of all.

 -- Command: cpack_ifw_add_repository

     Add QtIFW specific remote repository to binary installer.

          cpack_ifw_add_repository(<reponame> [DISABLED]
                              URL <url>
                              [USERNAME <username>]
                              [PASSWORD <password>]
                              [DISPLAY_NAME <display_name>])

     This command will also add the <reponame> repository to a variable
     CPACK_IFW_REPOSITORIES_ALL.

     ‘DISABLED’

          if set, then the repository will be disabled by default.

     ‘URL’

          is points to a list of available components.

     ‘USERNAME’

          is used as user on a protected repository.

     ‘PASSWORD’

          is password to use on a protected repository.

     ‘DISPLAY_NAME’

          is string to display instead of the URL.

 -- Command: cpack_ifw_update_repository

     Update QtIFW specific repository from remote repository.

          cpack_ifw_update_repository(<reponame>
                              [[ADD|REMOVE] URL <url>]|
                               [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
                              [USERNAME <username>]
                              [PASSWORD <password>]
                              [DISPLAY_NAME <display_name>])

     This command will also add the <reponame> repository to a variable
     CPACK_IFW_REPOSITORIES_ALL.

     ‘URL’

          is points to a list of available components.

     ‘OLD_URL’

          is points to a list that will replaced.

     ‘NEW_URL’

          is points to a list that will replace to.

     ‘USERNAME’

          is used as user on a protected repository.

     ‘PASSWORD’

          is password to use on a protected repository.

     ‘DISPLAY_NAME’

          is string to display instead of the URL.

 -- Command: cpack_ifw_add_package_resources

     Add additional resources in the installer binary.

          cpack_ifw_add_package_resources(<file_path> <file_path> ...)

     This command will also add the specified files to a variable
     CPACK_IFW_PACKAGE_RESOURCES.

15.1.53 CPackIFWConfigureFile
-----------------------------

New in version 3.8.

The module defines configure_file() similar command to
configure file templates prepared in QtIFW/SDK/Creator style.

15.1.53.1 Commands
..................

The module defines the following commands:

 -- Command: cpack_ifw_configure_file

     Copy a file to another location and modify its contents.

          cpack_ifw_configure_file(<input> <output>)

     Copies an ‘<input>’ file to an ‘<output>’ file and substitutes
     variable values referenced as ‘%{VAR}’ or ‘%VAR%’ in the input file
     content.  Each variable reference will be replaced with the current
     value of the variable, or the empty string if the variable is not
     defined.

15.1.54 CSharpUtilities
-----------------------

New in version 3.8.

Functions to make configuration of CSharp/.NET targets easier.

A collection of CMake utility functions useful for dealing with CSharp
targets for Visual Studio generators from version 2010 and later.

The following functions are provided by this module:

`Main functions'

   - csharp_set_windows_forms_properties().

   - csharp_set_designer_cs_properties().

   - csharp_set_xaml_cs_properties().

`Helper functions'

   - csharp_get_filename_keys().

   - csharp_get_filename_key_base().

   - csharp_get_dependentupon_name().

15.1.54.1 Main functions provided by the module
...............................................

 -- Command: csharp_set_windows_forms_properties

     Sets source file properties for use of Windows Forms.  Use this, if
     your CSharp target uses Windows Forms:

          csharp_set_windows_forms_properties([<file1> [<file2> [...]]])

     ‘<fileN>’

          List of all source files which are relevant for setting the
          VS_CSHARP_<tagname> properties (including ‘.cs’,
          ‘.resx’ and ‘.Designer.cs’ extensions).

     In the list of all given files for all files ending with
     ‘.Designer.cs’ and ‘.resx’ is searched.  For every `designer' or
     `resource' file a file with the same base name but only ‘.cs’ as
     extension is searched.  If this is found, the
     VS_CSHARP_<tagname> properties are set as follows:

     for the `.cs' file:

             - VS_CSHARP_SubType “Form”

     for the `.Designer.cs' file (if it exists):

             - VS_CSHARP_DependentUpon <cs-filename>

             - VS_CSHARP_DesignTime “” (delete tag if previously
               defined)

             - VS_CSHARP_AutoGen “”(delete tag if previously defined)

     for the `.resx' file (if it exists):

             - VS_RESOURCE_GENERATOR “” (delete tag if previously
               defined)

             - VS_CSHARP_DependentUpon <cs-filename>

             - VS_CSHARP_SubType “Designer”

 -- Command: csharp_set_designer_cs_properties

     Sets source file properties of ‘.Designer.cs’ files depending on
     sibling filenames.  Use this, if your CSharp target does `not' use
     Windows Forms (for Windows Forms use
     csharp_set_designer_cs_properties() instead):

          csharp_set_designer_cs_properties([<file1> [<file2> [...]]])

     ‘<fileN>’

          List of all source files which are relevant for setting the
          VS_CSHARP_<tagname> properties (including ‘.cs’,
          ‘.resx’, ‘.settings’ and ‘.Designer.cs’ extensions).

     In the list of all given files for all files ending with
     ‘.Designer.cs’ is searched.  For every `designer' file all files
     with the same base name but different extensions are searched.  If
     a match is found, the source file properties of the `designer' file
     are set depending on the extension of the matched file:

     if match is `.resx' file:

             - VS_CSHARP_AutoGen “True”

             - VS_CSHARP_DesignTime “True”

             - VS_CSHARP_DependentUpon <resx-filename>

     if match is `.cs' file:

             - VS_CSHARP_DependentUpon <cs-filename>

     if match is `.settings' file:

             - VS_CSHARP_AutoGen “True”

             - VS_CSHARP_DesignTimeSharedInput “True”

             - VS_CSHARP_DependentUpon <settings-filename>

     Note: Because the source file properties of the ‘.Designer.cs’ file
     are set according to the found matches and every match sets the
     `VS_CSHARP_DependentUpon' property, there should only be one match
     for each ‘Designer.cs’ file.

 -- Command: csharp_set_xaml_cs_properties

     Sets source file properties for use of Windows Presentation
     Foundation (WPF) and XAML. Use this, if your CSharp target uses
     WPF/XAML:

          csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])

     ‘<fileN>’

          List of all source files which are relevant for setting the
          VS_CSHARP_<tagname> properties (including ‘.cs’,
          ‘.xaml’, and ‘.xaml.cs’ extensions).

     In the list of all given files for all files ending with ‘.xaml.cs’
     is searched.  For every `xaml-cs' file, a file with the same base
     name but extension ‘.xaml’ is searched.  If a match is found, the
     source file properties of the ‘.xaml.cs’ file are set:

             - VS_CSHARP_DependentUpon <xaml-filename>

15.1.54.2 Helper functions which are used by the above ones
...........................................................

 -- Command: csharp_get_filename_keys

     Helper function which computes a list of key values to identify
     source files independently of relative/absolute paths given in
     cmake and eliminates case sensitivity:

          csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])

     ‘OUT’

          Name of the variable in which the list of keys is stored

     ‘<fileN>’

          filename(s) as given to to CSharp target using
          add_library() or add_executable().

     In some way the function applies a canonicalization to the source
     names.  This is necessary to find file matches if the files have
     been added to the target with different directory prefixes:

          add_library(lib
            myfile.cs
            ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)

          set_source_files_properties(myfile.Designer.cs PROPERTIES
            VS_CSHARP_DependentUpon myfile.cs)

          # this will fail, because in cmake
          #  - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
          #  - myfile.Designer.cs
          # are not the same source file. The source file property is not set.

 -- Command: csharp_get_filename_key_base

     Returns the full filepath and name `without' extension of a key.
     KEY is expected to be a key from csharp_get_filename_keys.  In BASE
     the value of KEY without the file extension is returned:

          csharp_get_filename_key_base(BASE KEY)

     ‘BASE’

          Name of the variable with the computed “base” of ‘KEY’.

     ‘KEY’

          The key of which the base will be computed.  Expected to be a
          upper case full filename.

 -- Command: csharp_get_dependentupon_name

     Computes a string which can be used as value for the source file
     property VS_CSHARP_<tagname> with `target' being
     ‘DependentUpon’:

          csharp_get_dependentupon_name(NAME FILE)

     ‘NAME’

          Name of the variable with the result value

     ‘FILE’

          Filename to convert to ‘<DependentUpon>’ value

     Actually this is only the filename without any path given at the
     moment.

15.1.55 CTest
-------------

Configure a project for testing with CTest/CDash

Include this module in the top CMakeLists.txt file of a project to
enable testing with CTest and dashboard submissions to CDash:

     project(MyProject)
     ...
     include(CTest)

The module automatically creates a ‘BUILD_TESTING’ option that selects
whether to enable testing support (‘ON’ by default).  After including
the module, use code like:

     if(BUILD_TESTING)
       # ... CMake code to create tests ...
     endif()

to creating tests when testing is enabled.

To enable submissions to a CDash server, create a ‘CTestConfig.cmake’
file at the top of the project with content such as:

     set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
     set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")

(the CDash server can provide the file to a project administrator who
configures ‘MyProject’).  Settings in the config file are shared by both
this ‘CTest’ module and the ctest(1) command-line
Dashboard Client mode (‘ctest -S’).

While building a project for submission to CDash, CTest scans the build
output for errors and warnings and reports them with surrounding context
from the build log.  This generic approach works for all build tools,
but does not give details about the command invocation that produced a
given problem.  One may get more detailed reports by setting the
CTEST_USE_LAUNCHERS variable:

     set(CTEST_USE_LAUNCHERS 1)

in the ‘CTestConfig.cmake’ file.

15.1.56 CTestCoverageCollectGCOV
--------------------------------

New in version 3.2.

This module provides the ‘ctest_coverage_collect_gcov’ function.

This function runs gcov on all .gcda files found in the binary tree and
packages the resulting .gcov files into a tar file.  This tarball also
contains the following:

   * `data.json' defines the source and build directories for use by
     CDash.

   * `Labels.json' indicates any LABELS that have been set
     on the source files.

   * The `uncovered' directory holds any uncovered files found by
     CTEST_EXTRA_COVERAGE_GLOB.

After generating this tar file, it can be sent to CDash for display with
the ctest_submit(CDASH_UPLOAD) command.

 -- Command: ctest_coverage_collect_gcov

          ctest_coverage_collect_gcov(TARBALL <tarfile>
            [SOURCE <source_dir>][BUILD <build_dir>]
            [GCOV_COMMAND <gcov_command>]
            [GCOV_OPTIONS <options>...]
            )

     Run gcov and package a tar file for CDash.  The options are:

     ‘TARBALL <tarfile>’

          Specify the location of the ‘.tar’ file to be created for
          later upload to CDash.  Relative paths will be interpreted
          with respect to the top-level build directory.

     ‘TARBALL_COMPRESSION <option>’ Specify a compression algorithm for the

          ‘TARBALL’ data file.  Using this option reduces the size of
          the data file before it is submitted to CDash.  ‘<option>’
          must be one of ‘GZIP’, ‘BZIP2’, ‘XZ’, ‘ZSTD’, ‘FROM_EXT’, or
          an expression that CMake evaluates as ‘FALSE’.  The default
          value is ‘BZIP2’.

          If ‘FROM_EXT’ is specified, the resulting file will be
          compressed based on the file extension of the ‘<tarfile>’
          (i.e.  ‘.tar.gz’ will use ‘GZIP’ compression).  File
          extensions that will produce compressed output include
          ‘.tar.gz’, ‘.tgz’, ‘.tar.bzip2’, ‘.tbz’, ‘.tar.xz’, and
          ‘.txz’.

     ‘SOURCE <source_dir>’

          Specify the top-level source directory for the build.  Default
          is the value of CTEST_SOURCE_DIRECTORY.

     ‘BUILD <build_dir>’

          Specify the top-level build directory for the build.  Default
          is the value of CTEST_BINARY_DIRECTORY.

     ‘GCOV_COMMAND <gcov_command>’

          Specify the full path to the ‘gcov’ command on the machine.
          Default is the value of CTEST_COVERAGE_COMMAND.

     ‘GCOV_OPTIONS <options>...’

          Specify options to be passed to gcov.  The ‘gcov’ command is
          run as ‘gcov <options>... -o <gcov-dir> <file>.gcda’.  If not
          specified, the default option is just ‘-b -x’.

     ‘GLOB’

          Recursively search for .gcda files in build_dir rather than
          determining search locations by reading TargetDirectories.txt.

     ‘DELETE’

          Delete coverage files after they’ve been packaged into the
          .tar.

     ‘QUIET’

          Suppress non-error messages that otherwise would have been
          printed out by this function.

15.1.57 CTestScriptMode
-----------------------

This file is read by ctest in script mode (-S)

15.1.58 CTestUseLaunchers
-------------------------

Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.

CTestUseLaunchers is automatically included when you include(CTest).
However, it is split out into its own module file so projects can use
the CTEST_USE_LAUNCHERS functionality independently.

To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
script, and then also set it in the cache of the configured project.
Both cmake and ctest need to know the value of it for the launchers to
work properly.  CMake needs to know in order to generate proper build
rules, and ctest, in order to produce the proper error and warning
analysis.

For convenience, you may set the ENV variable
CTEST_USE_LAUNCHERS_DEFAULT in your ctest -S script, too.  Then, as long
as your CMakeLists uses include(CTest) or include(CTestUseLaunchers), it
will use the value of the ENV variable to initialize a
CTEST_USE_LAUNCHERS cache variable.  This cache variable initialization
only occurs if CTEST_USE_LAUNCHERS is not already defined.  If
CTEST_USE_LAUNCHERS is on in a ctest -S script the ctest_configure
command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command
used to configure the project.

15.1.59 Dart
------------

Configure a project for testing with CTest or old Dart Tcl Client

This file is the backwards-compatibility version of the CTest module.
It supports using the old Dart 1 Tcl client for driving dashboard
submissions as well as testing with CTest.  This module should be
included in the CMakeLists.txt file at the top of a project.  Typical
usage:

     include(Dart)
     if(BUILD_TESTING)
       # ... testing related CMake code ...
     endif()

The BUILD_TESTING option is created by the Dart module to determine
whether testing support should be enabled.  The default is ON.

15.1.60 DeployQt4
-----------------

Functions to help assemble a standalone Qt4 executable.

A collection of CMake utility functions useful for deploying Qt4
executables.

The following functions are provided by this module:

     write_qt4_conf
     resolve_qt4_paths
     fixup_qt4_executable
     install_qt4_plugin_path
     install_qt4_plugin
     install_qt4_executable

Requires CMake 2.6 or greater because it uses function and PARENT_SCOPE.
Also depends on BundleUtilities.cmake.

     write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)

Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.

     resolve_qt4_paths(<paths_var> [<executable_path>])

Loop through <paths_var> list and if any don’t exist resolve them
relative to the <executable_path> (if supplied) or the
CMAKE_INSTALL_PREFIX.

     fixup_qt4_executable(<executable>
       [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])

Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
up a Qt4 executable using BundleUtilities so it is standalone and can be
drag-and-drop copied to another machine as long as all of the system
libraries are compatible.

<executable> should point to the executable to be fixed-up.

<qtplugins> should contain a list of the names or paths of any Qt
plugins to be installed.

<libs> will be passed to BundleUtilities and should be a list of any
already installed plugins, libraries or executables to also be fixed-up.

<dirs> will be passed to BundleUtilities and should contain and
directories to be searched to find library dependencies.

<plugins_dir> allows an custom plugins directory to be used.

<request_qt_conf> will force a qt.conf file to be written even if not
needed.

     install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
                             <plugins_dir> <component> <configurations>)

Install (or copy) a resolved <plugin> to the default plugins directory
(or <plugins_dir>) relative to <executable> and store the result in
<installed_plugin_path_var>.

If <copy> is set to TRUE then the plugins will be copied rather than
installed.  This is to allow this module to be used at CMake time rather
than install time.

If <component> is set then anything installed will use this COMPONENT.

     install_qt4_plugin(plugin executable copy installed_plugin_path_var
                        <plugins_dir> <component>)

Install (or copy) an unresolved <plugin> to the default plugins
directory (or <plugins_dir>) relative to <executable> and store the
result in <installed_plugin_path_var>.  See documentation of
INSTALL_QT4_PLUGIN_PATH.

     install_qt4_executable(<executable>
       [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])

Installs Qt plugins, writes a Qt configuration file (if needed) and
fixes up a Qt4 executable using BundleUtilities so it is standalone and
can be drag-and-drop copied to another machine as long as all of the
system libraries are compatible.  The executable will be fixed-up at
install time.  <component> is the COMPONENT used for bundle fixup and
plugin installation.  See documentation of FIXUP_QT4_BUNDLE.

15.1.61 Documentation
---------------------

This module provides support for the VTK documentation framework.  It
relies on several tools (Doxygen, Perl, etc).

15.1.62 ExternalData
--------------------

Manage data files stored outside source tree

15.1.62.1 Introduction
......................

Use this module to unambiguously reference data files stored outside the
source tree and fetch them at build time from arbitrary local and remote
content-addressed locations.  Functions provided by this module
recognize arguments with the syntax ‘DATA{<name>}’ as references to
external data, replace them with full paths to local copies of those
data, and create build rules to fetch and update the local copies.

For example:

     include(ExternalData)
     set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
                                    "file:////host/share/%(algo)/%(hash)"
                                    "http://data.org/%(algo)/%(hash)")
     ExternalData_Add_Test(MyData
       NAME MyTest
       COMMAND MyExe DATA{MyInput.png}
       )
     ExternalData_Add_Target(MyData)

When test ‘MyTest’ runs the ‘DATA{MyInput.png}’ argument will be
replaced by the full path to a real instance of the data file
‘MyInput.png’ on disk.  If the source tree contains a content link such
as ‘MyInput.png.md5’ then the ‘MyData’ target creates a real
‘MyInput.png’ in the build tree.

15.1.62.2 Module Functions
..........................

 -- Command: ExternalData_Expand_Arguments

     The ‘ExternalData_Expand_Arguments’ function evaluates ‘DATA{}’
     references in its arguments and constructs a new list of arguments:

          ExternalData_Expand_Arguments(
            <target>   # Name of data management target
            <outVar>   # Output variable
            [args...]  # Input arguments, DATA{} allowed
            )

     It replaces each ‘DATA{}’ reference in an argument with the full
     path of a real data file on disk that will exist after the
     ‘<target>’ builds.

 -- Command: ExternalData_Add_Test

     The ‘ExternalData_Add_Test’ function wraps around the CMake
     add_test() command but supports ‘DATA{}’ references in its
     arguments:

          ExternalData_Add_Test(
            <target>   # Name of data management target
            ...        # Arguments of add_test(), DATA{} allowed
            )

     It passes its arguments through ‘ExternalData_Expand_Arguments’ and
     then invokes the add_test() command using the results.

 -- Command: ExternalData_Add_Target

     The ‘ExternalData_Add_Target’ function creates a custom target to
     manage local instances of data files stored externally:

          ExternalData_Add_Target(
            <target>   # Name of data management target
            )

     It creates custom commands in the target as necessary to make data
     files available for each ‘DATA{}’ reference previously evaluated by
     other functions provided by this module.  Data files may be fetched
     from one of the URL templates specified in the
     ‘ExternalData_URL_TEMPLATES’ variable, or may be found locally in
     one of the paths specified in the ‘ExternalData_OBJECT_STORES’
     variable.

     Typically only one target is needed to manage all external data
     within a project.  Call this function once at the end of
     configuration after all data references have been processed.

15.1.62.3 Module Variables
..........................

The following variables configure behavior.  They should be set before
calling any of the functions provided by this module.

 -- Variable: ExternalData_BINARY_ROOT

     The ‘ExternalData_BINARY_ROOT’ variable may be set to the directory
     to hold the real data files named by expanded ‘DATA{}’ references.
     The default is ‘CMAKE_BINARY_DIR’.  The directory layout will
     mirror that of content links under ‘ExternalData_SOURCE_ROOT’.

 -- Variable: ExternalData_CUSTOM_SCRIPT_<key>

     Specify a full path to a ‘.cmake’ custom fetch script identified by
     ‘<key>’ in entries of the ‘ExternalData_URL_TEMPLATES’ list.  See
     Custom Fetch Scripts.

 -- Variable: ExternalData_LINK_CONTENT

     The ‘ExternalData_LINK_CONTENT’ variable may be set to the name of
     a supported hash algorithm to enable automatic conversion of real
     data files referenced by the ‘DATA{}’ syntax into content links.
     For each such ‘<file>’ a content link named ‘<file><ext>’ is
     created.  The original file is renamed to the form
     ‘.ExternalData_<algo>_<hash>’ to stage it for future transmission
     to one of the locations in the list of URL templates (by means
     outside the scope of this module).  The data fetch rule created for
     the content link will use the staged object if it cannot be found
     using any URL template.

 -- Variable: ExternalData_NO_SYMLINKS

     The real data files named by expanded ‘DATA{}’ references may be
     made available under ‘ExternalData_BINARY_ROOT’ using symbolic
     links on some platforms.  The ‘ExternalData_NO_SYMLINKS’ variable
     may be set to disable use of symbolic links and enable use of
     copies instead.

 -- Variable: ExternalData_OBJECT_STORES

     The ‘ExternalData_OBJECT_STORES’ variable may be set to a list of
     local directories that store objects using the layout
     ‘<dir>/%(algo)/%(hash)’.  These directories will be searched first
     for a needed object.  If the object is not available in any store
     then it will be fetched remotely using the URL templates and added
     to the first local store listed.  If no stores are specified the
     default is a location inside the build tree.

 -- Variable: ExternalData_SERIES_PARSE
 -- Variable: ExternalData_SERIES_PARSE_PREFIX
 -- Variable: ExternalData_SERIES_PARSE_NUMBER
 -- Variable: ExternalData_SERIES_PARSE_SUFFIX
 -- Variable: ExternalData_SERIES_MATCH

     See Referencing File Series.

 -- Variable: ExternalData_SOURCE_ROOT

     The ‘ExternalData_SOURCE_ROOT’ variable may be set to the highest
     source directory containing any path named by a ‘DATA{}’ reference.
     The default is ‘CMAKE_SOURCE_DIR’.  ‘ExternalData_SOURCE_ROOT’ and
     ‘CMAKE_SOURCE_DIR’ must refer to directories within a single source
     distribution (e.g.  they come together in one tarball).

 -- Variable: ExternalData_TIMEOUT_ABSOLUTE

     The ‘ExternalData_TIMEOUT_ABSOLUTE’ variable sets the download
     absolute timeout, in seconds, with a default of ‘300’ seconds.  Set
     to ‘0’ to disable enforcement.

 -- Variable: ExternalData_TIMEOUT_INACTIVITY

     The ‘ExternalData_TIMEOUT_INACTIVITY’ variable sets the download
     inactivity timeout, in seconds, with a default of ‘60’ seconds.
     Set to ‘0’ to disable enforcement.

 -- Variable: ExternalData_URL_ALGO_<algo>_<key>

     Specify a custom URL component to be substituted for URL template
     placeholders of the form ‘%(algo:<key>)’, where ‘<key>’ is a valid
     C identifier, when fetching an object referenced via hash algorithm
     ‘<algo>’.  If not defined, the default URL component is just
     ‘<algo>’ for any ‘<key>’.

 -- Variable: ExternalData_URL_TEMPLATES

     The ‘ExternalData_URL_TEMPLATES’ may be set to provide a list of
     URL templates using the placeholders ‘%(algo)’ and ‘%(hash)’ in
     each template.  Data fetch rules try each URL template in order by
     substituting the hash algorithm name for ‘%(algo)’ and the hash
     value for ‘%(hash)’.  Alternatively one may use ‘%(algo:<key>)’
     with ‘ExternalData_URL_ALGO_<algo>_<key>’ variables to gain more
     flexibility in remote URLs.

15.1.62.4 Referencing Files
...........................

15.1.62.5 Referencing Single Files
..................................

The ‘DATA{}’ syntax is literal and the ‘<name>’ is a full or relative
path within the source tree.  The source tree must contain either a real
data file at ‘<name>’ or a “content link” at ‘<name><ext>’ containing a
hash of the real file using a hash algorithm corresponding to ‘<ext>’.
For example, the argument ‘DATA{img.png}’ may be satisfied by either a
real ‘img.png’ file in the current source directory or a ‘img.png.md5’
file containing its MD5 sum.

Multiple content links of the same name with different hash algorithms
are supported (e.g.  ‘img.png.sha256’ and ‘img.png.sha1’) so long as
they all correspond to the same real file.  This allows objects to be
fetched from sources indexed by different hash algorithms.

15.1.62.6 Referencing File Series
.................................

The ‘DATA{}’ syntax can be told to fetch a file series using the form
‘DATA{<name>,:}’, where the ‘:’ is literal.  If the source tree contains
a group of files or content links named like a series then a reference
to one member adds rules to fetch all of them.  Although all members of
a series are fetched, only the file originally named by the ‘DATA{}’
argument is substituted for it.  The default configuration recognizes
file series names ending with ‘#.ext’, ‘_#.ext’, ‘.#.ext’, or ‘-#.ext’
where ‘#’ is a sequence of decimal digits and ‘.ext’ is any single
extension.  Configure it with a regex that parses ‘<number>’ and
‘<suffix>’ parts from the end of ‘<name>’:

     ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$

For more complicated cases set:

     ExternalData_SERIES_PARSE = regex with at least two () groups
     ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
     ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
     ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number

Configure series number matching with a regex that matches the
‘<number>’ part of series members named ‘<prefix><number><suffix>’:

     ExternalData_SERIES_MATCH = regex matching <number> in all series members

Note that the ‘<suffix>’ of a series does not include a hash-algorithm
extension.

15.1.62.7 Referencing Associated Files
......................................

The ‘DATA{}’ syntax can alternatively match files associated with the
named file and contained in the same directory.  Associated files may be
specified by options using the syntax ‘DATA{<name>,<opt1>,<opt2>,...}’.
Each option may specify one file by name or specify a regular expression
to match file names using the syntax ‘REGEX:<regex>’.  For example, the
arguments:

     DATA{MyData/MyInput.mhd,MyInput.img}                   # File pair
     DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series

will pass ‘MyInput.mha’ and ‘MyFrames00.png’ on the command line but
ensure that the associated files are present next to them.

15.1.62.8 Referencing Directories
.................................

The ‘DATA{}’ syntax may reference a directory using a trailing slash and
a list of associated files.  The form ‘DATA{<name>/,<opt1>,<opt2>,...}’
adds rules to fetch any files in the directory that match one of the
associated file options.  For example, the argument
‘DATA{MyDataDir/,REGEX:.*}’ will pass the full path to a ‘MyDataDir’
directory on the command line and ensure that the directory contains
files corresponding to every file or content link in the ‘MyDataDir’
source directory.  In order to match associated files in subdirectories,
specify a ‘RECURSE:’ option, e.g.  ‘DATA{MyDataDir/,RECURSE:,REGEX:.*}’.

15.1.62.9 Hash Algorithms
.........................

The following hash algorithms are supported:

     %(algo)     <ext>     Description
     -------     -----     -----------
     MD5         .md5      Message-Digest Algorithm 5, RFC 1321
     SHA1        .sha1     US Secure Hash Algorithm 1, RFC 3174
     SHA224      .sha224   US Secure Hash Algorithms, RFC 4634
     SHA256      .sha256   US Secure Hash Algorithms, RFC 4634
     SHA384      .sha384   US Secure Hash Algorithms, RFC 4634
     SHA512      .sha512   US Secure Hash Algorithms, RFC 4634
     SHA3_224    .sha3-224 Keccak SHA-3
     SHA3_256    .sha3-256 Keccak SHA-3
     SHA3_384    .sha3-384 Keccak SHA-3
     SHA3_512    .sha3-512 Keccak SHA-3

Note that the hashes are used only for unique data identification and
download verification.

15.1.62.10 Custom Fetch Scripts
...............................

When a data file must be fetched from one of the URL templates specified
in the ‘ExternalData_URL_TEMPLATES’ variable, it is normally downloaded
using the file(DOWNLOAD) command.  One may specify usage of a
custom fetch script by using a URL template of the form
‘ExternalDataCustomScript://<key>/<loc>’.  The ‘<key>’ must be a C
identifier, and the ‘<loc>’ must contain the ‘%(algo)’ and ‘%(hash)’
placeholders.  A variable corresponding to the key,
‘ExternalData_CUSTOM_SCRIPT_<key>’, must be set to the full path to a
‘.cmake’ script file.  The script will be included to perform the actual
fetch, and provided with the following variables:

 -- Variable: ExternalData_CUSTOM_LOCATION

     When a custom fetch script is loaded, this variable is set to the
     location part of the URL, which will contain the substituted hash
     algorithm name and content hash value.

 -- Variable: ExternalData_CUSTOM_FILE

     When a custom fetch script is loaded, this variable is set to the
     full path to a file in which the script must store the fetched
     content.  The name of the file is unspecified and should not be
     interpreted in any way.

The custom fetch script is expected to store fetched content in the file
or set a variable:

 -- Variable: ExternalData_CUSTOM_ERROR

     When a custom fetch script fails to fetch the requested content, it
     must set this variable to a short one-line message describing the
     reason for failure.

15.1.63 ExternalProject
-----------------------

15.1.63.1 Commands
..................

15.1.63.2 External Project Definition
.....................................

 -- Command: ExternalProject_Add

     The ‘ExternalProject_Add()’ function creates a custom target to
     drive download, update/patch, configure, build, install and test
     steps of an external project:

          ExternalProject_Add(<name> [<option>...])

     The individual steps within the process can be driven independently
     if required (e.g.  for CDash submission) and extra custom steps can
     be defined, along with the ability to control the step
     dependencies.  The directory structure used for the management of
     the external project can also be customized.  The function supports
     a large number of options which can be used to tailor the external
     project behavior.

     `Directory Options:'

          Most of the time, the default directory layout is sufficient.
          It is largely an implementation detail that the main project
          usually doesn’t need to change.  In some circumstances,
          however, control over the directory layout can be useful or
          necessary.  The directory options are potentially more useful
          from the point of view that the main build can use the
          ExternalProject_Get_Property() command to retrieve their
          values, thereby allowing the main project to refer to build
          artifacts of the external project.

          ‘PREFIX <dir>’

               Root directory for the external project.  Unless
               otherwise noted below, all other directories associated
               with the external project will be created under here.

          ‘TMP_DIR <dir>’

               Directory in which to store temporary files.

          ‘STAMP_DIR <dir>’

               Directory in which to store the timestamps of each step.
               Log files from individual steps are also created in here
               unless overridden by LOG_DIR (see `Logging Options'
               below).

          ‘LOG_DIR <dir>’

               Directory in which to store the logs of each step.

          ‘DOWNLOAD_DIR <dir>’

               Directory in which to store downloaded files before
               unpacking them.  This directory is only used by the URL
               download method, all other download methods use
               ‘SOURCE_DIR’ directly instead.

          ‘SOURCE_DIR <dir>’

               Source directory into which downloaded contents will be
               unpacked, or for non-URL download methods, the directory
               in which the repository should be checked out, cloned,
               etc.  If no download method is specified, this must point
               to an existing directory where the external project has
               already been unpacked or cloned/checked out.

                    Note: If a download method is specified, any
                    existing contents of the source directory may be
                    deleted.  Only the URL download method checks
                    whether this directory is either missing or empty
                    before initiating the download, stopping with an
                    error if it is not empty.  All other download
                    methods silently discard any previous contents of
                    the source directory.

          ‘BINARY_DIR <dir>’

               Specify the build directory location.  This option is
               ignored if ‘BUILD_IN_SOURCE’ is enabled.

          ‘INSTALL_DIR <dir>’

               Installation prefix to be placed in the ‘<INSTALL_DIR>’
               placeholder.  This does not actually configure the
               external project to install to the given prefix.  That
               must be done by passing appropriate arguments to the
               external project configuration step, e.g.  using
               ‘<INSTALL_DIR>’.

          If any of the above ‘..._DIR’ options are not specified, their
          defaults are computed as follows.  If the ‘PREFIX’ option is
          given or the ‘EP_PREFIX’ directory property is set, then an
          external project is built and installed under the specified
          prefix:

               TMP_DIR      = <prefix>/tmp
               STAMP_DIR    = <prefix>/src/<name>-stamp
               DOWNLOAD_DIR = <prefix>/src
               SOURCE_DIR   = <prefix>/src/<name>
               BINARY_DIR   = <prefix>/src/<name>-build
               INSTALL_DIR  = <prefix>
               LOG_DIR      = <STAMP_DIR>

          Otherwise, if the ‘EP_BASE’ directory property is set then
          components of an external project are stored under the
          specified base:

               TMP_DIR      = <base>/tmp/<name>
               STAMP_DIR    = <base>/Stamp/<name>
               DOWNLOAD_DIR = <base>/Download/<name>
               SOURCE_DIR   = <base>/Source/<name>
               BINARY_DIR   = <base>/Build/<name>
               INSTALL_DIR  = <base>/Install/<name>
               LOG_DIR      = <STAMP_DIR>

          If no ‘PREFIX’, ‘EP_PREFIX’, or ‘EP_BASE’ is specified, then
          the default is to set ‘PREFIX’ to ‘<name>-prefix’.  Relative
          paths are interpreted with respect to
          CMAKE_CURRENT_BINARY_DIR at the point where
          ‘ExternalProject_Add()’ is called.

     `Download Step Options:'

          A download method can be omitted if the ‘SOURCE_DIR’ option is
          used to point to an existing non-empty directory.  Otherwise,
          one of the download methods below must be specified (multiple
          download methods should not be given) or a custom
          ‘DOWNLOAD_COMMAND’ provided.

          ‘DOWNLOAD_COMMAND <cmd>...’

               Overrides the command used for the download step ( see
               generator expressions are supported).  If this
               option is specified, all other download options will be
               ignored.  Providing an empty string for ‘<cmd>’
               effectively disables the download step.

          `URL Download'

               ‘URL <url1> [<url2>...]’

                    List of paths and/or URL(s) of the external
                    project’s source.  When more than one URL is given,
                    they are tried in turn until one succeeds.  A URL
                    may be an ordinary path in the local file system (in
                    which case it must be the only URL provided) or any
                    downloadable URL supported by the
                    file(DOWNLOAD) command.  A local filesystem
                    path may refer to either an existing directory or to
                    an archive file, whereas a URL is expected to point
                    to a file which can be treated as an archive.  When
                    an archive is used, it will be unpacked
                    automatically unless the ‘DOWNLOAD_NO_EXTRACT’
                    option is set to prevent it.  The archive type is
                    determined by inspecting the actual content rather
                    than using logic based on the file extension.

               ‘URL_HASH <algo>=<hashValue>’

                    Hash of the archive file to be downloaded.  The
                    argument should be of the form ‘<algo>=<hashValue>’
                    where ‘algo’ can be any of the hashing algorithms
                    supported by the file() command.
                    Specifying this option is strongly recommended for
                    URL downloads, as it ensures the integrity of the
                    downloaded content.  It is also used as a check for
                    a previously downloaded file, allowing connection to
                    the remote location to be avoided altogether if the
                    local directory already has a file from an earlier
                    download that matches the specified hash.

               ‘URL_MD5 <md5>’

                    Equivalent to ‘URL_HASH MD5=<md5>’.

               ‘DOWNLOAD_NAME <fname>’

                    File name to use for the downloaded file.  If not
                    given, the end of the URL is used to determine the
                    file name.  This option is rarely needed, the
                    default name is generally suitable and is not
                    normally used outside of code internal to the
                    ‘ExternalProject’ module.

               ‘DOWNLOAD_NO_EXTRACT <bool>’

                    Allows the extraction part of the download step to
                    be disabled by passing a boolean true value for this
                    option.  If this option is not given, the downloaded
                    contents will be unpacked automatically if required.
                    If extraction has been disabled, the full path to
                    the downloaded file is available as
                    ‘<DOWNLOADED_FILE>’ in subsequent steps or as the
                    property ‘DOWNLOADED_FILE’ with the
                    ExternalProject_Get_Property() command.

               ‘DOWNLOAD_NO_PROGRESS <bool>’

                    Can be used to disable logging the download
                    progress.  If this option is not given, download
                    progress messages will be logged.

               ‘TIMEOUT <seconds>’

                    Maximum time allowed for file download operations.

               ‘INACTIVITY_TIMEOUT <seconds>’

                    Terminate the operation after a period of
                    inactivity.

               ‘HTTP_USERNAME <username>’

                    Username for the download operation if
                    authentication is required.

               ‘HTTP_PASSWORD <password>’

                    Password for the download operation if
                    authentication is required.

               ‘HTTP_HEADER <header1> [<header2>...]’

                    Provides an arbitrary list of HTTP headers for the
                    download operation.  This can be useful for
                    accessing content in systems like AWS, etc.

               ‘TLS_VERIFY <bool>’

                    Specifies whether certificate verification should be
                    performed for https URLs.  If this option is not
                    provided, the default behavior is determined by the
                    ‘CMAKE_TLS_VERIFY’ variable (see
                    file(DOWNLOAD)).  If that is also not set,
                    certificate verification will not be performed.  In
                    situations where ‘URL_HASH’ cannot be provided, this
                    option can be an alternative verification measure.

               ‘TLS_CAINFO <file>’

                    Specify a custom certificate authority file to use
                    if ‘TLS_VERIFY’ is enabled.  If this option is not
                    specified, the value of the ‘CMAKE_TLS_CAINFO’
                    variable will be used instead (see
                    file(DOWNLOAD))

               ‘NETRC <level>’

                    Specify whether the ‘.netrc’ file is to be used for
                    operation.  If this option is not specified, the
                    value of the ‘CMAKE_NETRC’ variable will be used
                    instead (see file(DOWNLOAD)) Valid levels
                    are:

                    ‘IGNORED’

                         The ‘.netrc’ file is ignored.  This is the
                         default.

                    ‘OPTIONAL’

                         The ‘.netrc’ file is optional, and information
                         in the URL is preferred.  The file will be
                         scanned to find which ever information is not
                         specified in the URL.

                    ‘REQUIRED’

                         The ‘.netrc’ file is required, and information
                         in the URL is ignored.

               ‘NETRC_FILE <file>’

                    Specify an alternative ‘.netrc’ file to the one in
                    your home directory if the ‘NETRC’ level is
                    ‘OPTIONAL’ or ‘REQUIRED’.  If this option is not
                    specified, the value of the ‘CMAKE_NETRC_FILE’
                    variable will be used instead (see
                    file(DOWNLOAD))

          `Git'

               NOTE: A git version of 1.6.5 or later is required if this
               download method is used.

               ‘GIT_REPOSITORY <url>’

                    URL of the git repository.  Any URL understood by
                    the ‘git’ command may be used.

               ‘GIT_TAG <tag>’

                    Git branch name, tag or commit hash.  Note that
                    branch names and tags should generally be specified
                    as remote names (i.e.  ‘origin/myBranch’ rather than
                    simply ‘myBranch’).  This ensures that if the remote
                    end has its tag moved or branch rebased or history
                    rewritten, the local clone will still be updated
                    correctly.  In general, however, specifying a commit
                    hash should be preferred for a number of reasons:

                       - If the local clone already has the commit
                         corresponding to the hash, no ‘git fetch’ needs
                         to be performed to check for changes each time
                         CMake is re-run.  This can result in a
                         significant speed up if many external projects
                         are being used.

                       - Using a specific git hash ensures that the main
                         project’s own history is fully traceable to a
                         specific point in the external project’s
                         evolution.  If a branch or tag name is used
                         instead, then checking out a specific commit of
                         the main project doesn’t necessarily pin the
                         whole build to a specific point in the life of
                         the external project.  The lack of such
                         deterministic behavior makes the main project
                         lose traceability and repeatability.

                    If ‘GIT_SHALLOW’ is enabled then ‘GIT_TAG’ works
                    only with branch names and tags.  A commit hash is
                    not allowed.

               ‘GIT_REMOTE_NAME <name>’

                    The optional name of the remote.  If this option is
                    not specified, it defaults to ‘origin’.

               ‘GIT_SUBMODULES <module>...’

                    Specific git submodules that should also be updated.
                    If this option is not provided, all git submodules
                    will be updated.  When CMP0097 is set to
                    ‘NEW’ if this value is set to an empty string then
                    no submodules are initialized or updated.

               ‘GIT_SUBMODULES_RECURSE <bool>’

                    Specify whether git submodules (if any) should
                    update recursively by passing the ‘--recursive’ flag
                    to ‘git submodule update’.  If not specified, the
                    default is on.

               ‘GIT_SHALLOW <bool>’

                    When this option is enabled, the ‘git clone’
                    operation will be given the ‘--depth 1’ option.
                    This performs a shallow clone, which avoids
                    downloading the whole history and instead retrieves
                    just the commit denoted by the ‘GIT_TAG’ option.

               ‘GIT_PROGRESS <bool>’

                    When enabled, this option instructs the ‘git clone’
                    operation to report its progress by passing it the
                    ‘--progress’ option.  Without this option, the clone
                    step for large projects may appear to make the build
                    stall, since nothing will be logged until the clone
                    operation finishes.  While this option can be used
                    to provide progress to prevent the appearance of the
                    build having stalled, it may also make the build
                    overly noisy if lots of external projects are used.

               ‘GIT_CONFIG <option1> [<option2>...]’

                    Specify a list of config options to pass to ‘git
                    clone’.  Each option listed will be transformed into
                    its own ‘--config <option>’ on the ‘git clone’
                    command line, with each option required to be in the
                    form ‘key=value’.

               ‘GIT_REMOTE_UPDATE_STRATEGY <strategy>’

                    When ‘GIT_TAG’ refers to a remote branch, this
                    option can be used to specify how the update step
                    behaves.  The ‘<strategy>’ must be one of the
                    following:

                    ‘CHECKOUT’

                         Ignore the local branch and always checkout the
                         branch specified by ‘GIT_TAG’.

                    ‘REBASE’

                         Try to rebase the current branch to the one
                         specified by ‘GIT_TAG’.  If there are local
                         uncommitted changes, they will be stashed first
                         and popped again after rebasing.  If rebasing
                         or popping stashed changes fail, abort the
                         rebase and halt with an error.  When
                         ‘GIT_REMOTE_UPDATE_STRATEGY’ is not present,
                         this is the default strategy unless the default
                         has been overridden with
                         ‘CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY’ (see
                         below).

                    ‘REBASE_CHECKOUT’

                         Same as ‘REBASE’ except if the rebase fails, an
                         annotated tag will be created at the original
                         ‘HEAD’ position from before the rebase and then
                         checkout ‘GIT_TAG’ just like the ‘CHECKOUT’
                         strategy.  The message stored on the annotated
                         tag will give information about what was
                         attempted and the tag name will include a
                         timestamp so that each failed run will add a
                         new tag.  This strategy ensures no changes will
                         be lost, but updates should always succeed if
                         ‘GIT_TAG’ refers to a valid ref unless there
                         are uncommitted changes that cannot be popped
                         successfully.

                    The variable ‘CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY’
                    can be set to override the default strategy.  This
                    variable should not be set by a project, it is
                    intended for the user to set.  It is primarily
                    intended for use in continuous integration scripts
                    to ensure that when history is rewritten on a remote
                    branch, the build doesn’t end up with unintended
                    changes or failed builds resulting from conflicts
                    during rebase operations.

          `Subversion'

               ‘SVN_REPOSITORY <url>’

                    URL of the Subversion repository.

               ‘SVN_REVISION -r<rev>’

                    Revision to checkout from the Subversion repository.

               ‘SVN_USERNAME <username>’

                    Username for the Subversion checkout and update.

               ‘SVN_PASSWORD <password>’

                    Password for the Subversion checkout and update.

               ‘SVN_TRUST_CERT <bool>’

                    Specifies whether to trust the Subversion server
                    site certificate.  If enabled, the
                    ‘--trust-server-cert’ option is passed to the ‘svn’
                    checkout and update commands.

          `Mercurial'

               ‘HG_REPOSITORY <url>’

                    URL of the mercurial repository.

               ‘HG_TAG <tag>’

                    Mercurial branch name, tag or commit id.

          `CVS'

               ‘CVS_REPOSITORY <cvsroot>’

                    CVSROOT of the CVS repository.

               ‘CVS_MODULE <mod>’

                    Module to checkout from the CVS repository.

               ‘CVS_TAG <tag>’

                    Tag to checkout from the CVS repository.

     `Update/Patch Step Options:'

          Whenever CMake is re-run, by default the external project’s
          sources will be updated if the download method supports
          updates (e.g.  a git repository would be checked if the
          ‘GIT_TAG’ does not refer to a specific commit).

          ‘UPDATE_COMMAND <cmd>...’

               Overrides the download method’s update step with a custom
               command.  The command may use generator expressions.

          ‘UPDATE_DISCONNECTED <bool>’

               When enabled, this option causes the update step to be
               skipped.  It does not, however, prevent the download
               step.  The update step can still be added as a step
               target (see ExternalProject_Add_StepTargets())
               and called manually.  This is useful if you want to
               allow developers to build the project when disconnected
               from the network (the network may still be needed for the
               download step though).

               When this option is present, it is generally advisable to
               make the value a cache variable under the developer’s
               control rather than hard-coding it.  If this option is
               not present, the default value is taken from the
               ‘EP_UPDATE_DISCONNECTED’ directory property.  If that is
               also not defined, updates are performed as normal.  The
               ‘EP_UPDATE_DISCONNECTED’ directory property is intended
               as a convenience for controlling the
               ‘UPDATE_DISCONNECTED’ behavior for an entire section of a
               project’s directory hierarchy and may be a more
               convenient method of giving developers control over
               whether or not to perform updates (assuming the project
               also provides a cache variable or some other convenient
               method for setting the directory property).

               This may cause a step target to be created automatically
               for the ‘download’ step.  See policy CMP0114.

          ‘PATCH_COMMAND <cmd>...’

               Specifies a custom command to patch the sources after an
               update.  By default, no patch command is defined.  Note
               that it can be quite difficult to define an appropriate
               patch command that performs robustly, especially for
               download methods such as git where changing the ‘GIT_TAG’
               will not discard changes from a previous patch, but the
               patch command will be called again after updating to the
               new tag.

     `Configure Step Options:'

          The configure step is run after the download and update steps.
          By default, the external project is assumed to be a CMake
          project, but this can be overridden if required.

          ‘CONFIGURE_COMMAND <cmd>...’

               The default configure command runs CMake with options
               based on the main project.  For non-CMake external
               projects, the ‘CONFIGURE_COMMAND’ option must be used to
               override this behavior ( see generator expressions.
               are supported).  For projects that require no configure
               step, specify this option with an empty string as the
               command to execute.

          ‘CMAKE_COMMAND /.../cmake’

               Specify an alternative cmake executable for the configure
               step (use an absolute path).  This is generally not
               recommended, since it is usually desirable to use the
               same CMake version throughout the whole build.  This
               option is ignored if a custom configure command has been
               specified with ‘CONFIGURE_COMMAND’.

          ‘CMAKE_GENERATOR <gen>’

               Override the CMake generator used for the configure step.
               Without this option, the same generator as the main build
               will be used.  This option is ignored if a custom
               configure command has been specified with the
               ‘CONFIGURE_COMMAND’ option.

          ‘CMAKE_GENERATOR_PLATFORM <platform>’

               Pass a generator-specific platform name to the CMake
               command (see CMAKE_GENERATOR_PLATFORM).  It is
               an error to provide this option without the
               ‘CMAKE_GENERATOR’ option.

          ‘CMAKE_GENERATOR_TOOLSET <toolset>’

               Pass a generator-specific toolset name to the CMake
               command (see CMAKE_GENERATOR_TOOLSET).  It is
               an error to provide this option without the
               ‘CMAKE_GENERATOR’ option.

          ‘CMAKE_GENERATOR_INSTANCE <instance>’

               Pass a generator-specific instance selection to the CMake
               command (see CMAKE_GENERATOR_INSTANCE).  It
               is an error to provide this option without the
               ‘CMAKE_GENERATOR’ option.

          ‘CMAKE_ARGS <arg>...’

               The specified arguments are passed to the ‘cmake’ command
               line.  They can be any argument the ‘cmake’ command
               understands, not just cache values defined by ‘-D...’
               arguments (see also CMake Options).  In
               addition, arguments may use generator expressions.

          ‘CMAKE_CACHE_ARGS <arg>...’

               This is an alternate way of specifying cache variables
               where command line length issues may become a problem.
               The arguments are expected to be in the form
               ‘-Dvar:STRING=value’, which are then transformed into
               CMake set() commands with the ‘FORCE’ option
               used.  These ‘set()’ commands are written to a pre-load
               script which is then applied using the cmake -C.
               command line option.  Arguments may use generator expressions.

          ‘CMAKE_CACHE_DEFAULT_ARGS <arg>...’

               This is the same as the ‘CMAKE_CACHE_ARGS’ option except
               the ‘set()’ commands do not include the ‘FORCE’ keyword.
               This means the values act as initial defaults only and
               will not override any variables already set from a
               previous run.  Use this option with care, as it can lead
               to different behavior depending on whether the build
               starts from a fresh build directory or re-uses previous
               build contents.

               If the CMake generator is the ‘Green Hills MULTI’ and not
               overridden then the original project’s settings for the
               GHS toolset and target system customization cache
               variables are propagated into the external project.

          ‘SOURCE_SUBDIR <dir>’

               When no ‘CONFIGURE_COMMAND’ option is specified, the
               configure step assumes the external project has a
               ‘CMakeLists.txt’ file at the top of its source tree (i.e.
               in ‘SOURCE_DIR’).  The ‘SOURCE_SUBDIR’ option can be used
               to point to an alternative directory within the source
               tree to use as the top of the CMake source tree instead.
               This must be a relative path and it will be interpreted
               as being relative to ‘SOURCE_DIR’.  When ‘BUILD_IN_SOURCE
               1’ is specified, the ‘BUILD_COMMAND’ is used to point to
               an alternative directory within the source tree.

     `Build Step Options:'

          If the configure step assumed the external project uses CMake
          as its build system, the build step will also.  Otherwise, the
          build step will assume a Makefile-based build and simply run
          ‘make’ with no arguments as the default build step.  This can
          be overridden with custom build commands if required.

          ‘BUILD_COMMAND <cmd>...’

               Overrides the default build command ( see generator expressions
               are supported).  If this option is not
               given, the default build command will be chosen to
               integrate with the main build in the most appropriate way
               (e.g.  using recursive ‘make’ for Makefile generators or
               ‘cmake --build’ if the project uses a CMake build).  This
               option can be specified with an empty string as the
               command to make the build step do nothing.

          ‘BUILD_IN_SOURCE <bool>’

               When this option is enabled, the build will be done
               directly within the external project’s source tree.  This
               should generally be avoided, the use of a separate build
               directory is usually preferred, but it can be useful when
               the external project assumes an in-source build.  The
               ‘BINARY_DIR’ option should not be specified if building
               in-source.

          ‘BUILD_ALWAYS <bool>’

               Enabling this option forces the build step to always be
               run.  This can be the easiest way to robustly ensure that
               the external project’s own build dependencies are
               evaluated rather than relying on the default success
               timestamp-based method.  This option is not normally
               needed unless developers are expected to modify something
               the external project’s build depends on in a way that is
               not detectable via the step target dependencies (e.g.
               ‘SOURCE_DIR’ is used without a download method and
               developers might modify the sources in ‘SOURCE_DIR’).

          ‘BUILD_BYPRODUCTS <file>...’

               Specifies files that will be generated by the build
               command but which might or might not have their
               modification time updated by subsequent builds.  These
               ultimately get passed through as ‘BYPRODUCTS’ to the
               build step’s own underlying call to
               add_custom_command().

     `Install Step Options:'

          If the configure step assumed the external project uses CMake
          as its build system, the install step will also.  Otherwise,
          the install step will assume a Makefile-based build and simply
          run ‘make install’ as the default build step.  This can be
          overridden with custom install commands if required.

          ‘INSTALL_COMMAND <cmd>...’

               The external project’s own install step is invoked as
               part of the main project’s `build'.  It is done after the
               external project’s build step and may be before or after
               the external project’s test step (see the
               ‘TEST_BEFORE_INSTALL’ option below).  The external
               project’s install rules are not part of the main
               project’s install rules, so if anything from the external
               project should be installed as part of the main build,
               these need to be specified in the main build as
               additional install() commands.  The default
               install step builds the ‘install’ target of the external
               project, but this can be overridden with a custom command
               using this option ( see generator expressions are
               supported).  Passing an empty string as the ‘<cmd>’ makes
               the install step do nothing.

     `Test Step Options:'

          The test step is only defined if at least one of the following
          ‘TEST_...’ options are provided.

          ‘TEST_COMMAND <cmd>...’

               Overrides the default test command ( see generator expressions
               are supported).  If this option is not
               given, the default behavior of the test step is to build
               the external project’s own ‘test’ target.  This option
               can be specified with ‘<cmd>’ as an empty string, which
               allows the test step to still be defined, but it will do
               nothing.  Do not specify any of the other ‘TEST_...’
               options if providing an empty string as the test command,
               but prefer to omit all ‘TEST_...’ options altogether if
               the test step target is not needed.

          ‘TEST_BEFORE_INSTALL <bool>’

               When this option is enabled, the test step will be
               executed before the install step.  The default behavior
               is for the test step to run after the install step.

          ‘TEST_AFTER_INSTALL <bool>’

               This option is mainly useful as a way to indicate that
               the test step is desired but all default behavior is
               sufficient.  Specifying this option with a boolean true
               value ensures the test step is defined and that it comes
               after the install step.  If both ‘TEST_BEFORE_INSTALL’
               and ‘TEST_AFTER_INSTALL’ are enabled, the latter is
               silently ignored.

          ‘TEST_EXCLUDE_FROM_MAIN <bool>’

               If enabled, the main build’s default ALL target will not
               depend on the test step.  This can be a useful way of
               ensuring the test step is defined but only gets invoked
               when manually requested.  This may cause a step target to
               be created automatically for either the ‘install’ or
               ‘build’ step.  See policy CMP0114.

     `Output Logging Options:'

          Each of the following ‘LOG_...’ options can be used to wrap
          the relevant step in a script to capture its output to files.
          The log files will be created in ‘LOG_DIR’ if supplied or
          otherwise the ‘STAMP_DIR’ directory with step-specific file
          names.

          ‘LOG_DOWNLOAD <bool>’

               When enabled, the output of the download step is logged
               to files.

          ‘LOG_UPDATE <bool>’

               When enabled, the output of the update step is logged to
               files.

          ‘LOG_PATCH <bool>’

               When enabled, the output of the patch step is logged to
               files.

          ‘LOG_CONFIGURE <bool>’

               When enabled, the output of the configure step is logged
               to files.

          ‘LOG_BUILD <bool>’

               When enabled, the output of the build step is logged to
               files.

          ‘LOG_INSTALL <bool>’

               When enabled, the output of the install step is logged to
               files.

          ‘LOG_TEST <bool>’

               When enabled, the output of the test step is logged to
               files.

          ‘LOG_MERGED_STDOUTERR <bool>’

               When enabled, stdout and stderr will be merged for any
               step whose output is being logged to files.

          ‘LOG_OUTPUT_ON_FAILURE <bool>’

               This option only has an effect if at least one of the
               other ‘LOG_<step>’ options is enabled.  If an error
               occurs for a step which has logging to file enabled, that
               step’s output will be printed to the console if
               ‘LOG_OUTPUT_ON_FAILURE’ is set to true.  For cases where
               a large amount of output is recorded, just the end of
               that output may be printed to the console.

     `Terminal Access Options:'

          Steps can be given direct access to the terminal in some
          cases.  Giving a step access to the terminal may allow it to
          receive terminal input if required, such as for authentication
          details not provided by other options.  With the Ninja
          generator, these options place the steps in the ‘console’
          job pool.  Each step can be given access to the
          terminal individually via the following options:

          ‘USES_TERMINAL_DOWNLOAD <bool>’

               Give the download step access to the terminal.

          ‘USES_TERMINAL_UPDATE <bool>’

               Give the update step access to the terminal.

          ‘USES_TERMINAL_CONFIGURE <bool>’

               Give the configure step access to the terminal.

          ‘USES_TERMINAL_BUILD <bool>’

               Give the build step access to the terminal.

          ‘USES_TERMINAL_INSTALL <bool>’

               Give the install step access to the terminal.

          ‘USES_TERMINAL_TEST <bool>’

               Give the test step access to the terminal.

     `Target Options:'

          ‘DEPENDS <targets>...’

               Specify other targets on which the external project
               depends.  The other targets will be brought up to date
               before any of the external project’s steps are executed.
               Because the external project uses additional custom
               targets internally for each step, the ‘DEPENDS’ option is
               the most convenient way to ensure all of those steps
               depend on the other targets.  Simply doing
               add_dependencies(<name> <targets>) will not make
               any of the steps dependent on ‘<targets>’.

          ‘EXCLUDE_FROM_ALL <bool>’

               When enabled, this option excludes the external project
               from the default ALL target of the main build.

          ‘STEP_TARGETS <step-target>...’

               Generate custom targets for the specified steps.  This is
               required if the steps need to be triggered manually or if
               they need to be used as dependencies of other targets.
               If this option is not specified, the default value is
               taken from the ‘EP_STEP_TARGETS’ directory property.  See
               ExternalProject_Add_StepTargets() below for
               further discussion of the effects of this option.

          ‘INDEPENDENT_STEP_TARGETS <step-target>...’

               Deprecated.  This is allowed only if policy
               CMP0114 is not set to ‘NEW’.  Generates custom
               targets for the specified steps and prevent these targets
               from having the usual dependencies applied to them.  If
               this option is not specified, the default value is taken
               from the ‘EP_INDEPENDENT_STEP_TARGETS’ directory
               property.  This option is mostly useful for allowing
               individual steps to be driven independently, such as for
               a CDash setup where each step should be initiated and
               reported individually rather than as one whole build.
               See ExternalProject_Add_StepTargets() below
               for further discussion of the effects of this option.

     `Miscellaneous Options:'

          ‘LIST_SEPARATOR <sep>’

               For any of the various ‘..._COMMAND’ options, replace ‘;’
               with ‘<sep>’ in the specified command lines.  This can be
               useful where list variables may be given in commands
               where they should end up as space-separated arguments
               (‘<sep>’ would be a single space character string in this
               case).

          ‘COMMAND <cmd>...’

               Any of the other ‘..._COMMAND’ options can have
               additional commands appended to them by following them
               with as many ‘COMMAND ...’ options as needed ( see
               generator expressions are supported).  For example:

                    ExternalProject_Add(example
                      ... # Download options, etc.
                      BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
                      COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
                      COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
                    )

     It should also be noted that each build step is created via a call
     to ExternalProject_Add_Step().  See that command’s
     documentation for the automatic substitutions that are supported
     for some options.

15.1.63.3 Obtaining Project Properties
......................................

 -- Command: ExternalProject_Get_Property

     The ‘ExternalProject_Get_Property()’ function retrieves external
     project target properties:

          ExternalProject_Get_Property(<name> <prop1> [<prop2>...])

     The function stores property values in variables of the same name.
     Property names correspond to the keyword argument names of
     ‘ExternalProject_Add()’.  For example, the source directory might
     be retrieved like so:

          ExternalProject_Get_property(myExtProj SOURCE_DIR)
          message("Source dir of myExtProj = ${SOURCE_DIR}")

15.1.63.4 Explicit Step Management
..................................

The ‘ExternalProject_Add()’ function on its own is often sufficient for
incorporating an external project into the main build.  Certain
scenarios require additional work to implement desired behavior, such as
adding in a custom step or making steps available as manually
triggerable targets.  The ‘ExternalProject_Add_Step()’,
‘ExternalProject_Add_StepTargets()’ and
‘ExternalProject_Add_StepDependencies’ functions provide the lower level
control needed to implement such step-level capabilities.

 -- Command: ExternalProject_Add_Step

     The ‘ExternalProject_Add_Step()’ function specifies an additional
     custom step for an external project defined by an earlier call to
     ExternalProject_Add().:

          ExternalProject_Add_Step(<name> <step> [<option>...])

     ‘<name>’ is the same as the name passed to the original call to
     ExternalProject_Add().  The specified ‘<step>’ must not
     be one of the pre-defined steps (‘mkdir’, ‘download’, ‘update’,
     ‘patch’, ‘configure’, ‘build’, ‘install’ or ‘test’).  The supported
     options are:

     ‘COMMAND <cmd>...’

          The command line to be executed by this custom step ( see
          generator expressions are supported).  This option can be
          repeated multiple times to specify multiple commands to be
          executed in order.

     ‘COMMENT "<text>..."’

          Text to be printed when the custom step executes.

     ‘DEPENDEES <step>...’

          Other steps (custom or pre-defined) on which this step
          depends.

     ‘DEPENDERS <step>...’

          Other steps (custom or pre-defined) that depend on this new
          custom step.

     ‘DEPENDS <file>...’

          Files on which this custom step depends.

     ‘INDEPENDENT <bool>’

          Specifies whether this step is independent of the external
          dependencies specified by the ExternalProject_Add().
          ’s ‘DEPENDS’ option.  The default is ‘FALSE’.  Steps
          marked as independent may depend only on other steps marked
          independent.  See policy CMP0114.

          Note that this use of the term “independent” refers only to
          independence from external targets specified by the ‘DEPENDS’
          option and is orthogonal to a step’s dependencies on other
          steps.

          If a step target is created for an independent step by the
          ExternalProject_Add(). ‘STEP_TARGETS’ option or by
          the ExternalProject_Add_StepTargets() function, it
          will not depend on the external targets, but may depend on
          targets for other steps.

     ‘BYPRODUCTS <file>...’

          Files that will be generated by this custom step but which
          might or might not have their modification time updated by
          subsequent builds.  This list of files will ultimately be
          passed through as the ‘BYPRODUCTS’ option to the
          add_custom_command() used to implement the custom step
          internally.

     ‘ALWAYS <bool>’

          When enabled, this option specifies that the custom step
          should always be run (i.e.  that it is always considered out
          of date).

     ‘EXCLUDE_FROM_MAIN <bool>’

          When enabled, this option specifies that the external
          project’s main target does not depend on the custom step.
          This may cause step targets to be created automatically for
          the steps on which this step depends.  See policy
          CMP0114.

     ‘WORKING_DIRECTORY <dir>’

          Specifies the working directory to set before running the
          custom step’s command.  If this option is not specified, the
          directory will be the value of the
          CMAKE_CURRENT_BINARY_DIR at the point where
          ‘ExternalProject_Add_Step()’ was called.

     ‘LOG <bool>’

          If set, this causes the output from the custom step to be
          captured to files in the external project’s ‘LOG_DIR’ if
          supplied or ‘STAMP_DIR’.

     ‘USES_TERMINAL <bool>’

          If enabled, this gives the custom step direct access to the
          terminal if possible.

     The command line, comment, working directory and byproducts of
     every standard and custom step are processed to replace the tokens
     ‘<SOURCE_DIR>’, ‘<SOURCE_SUBDIR>’, ‘<BINARY_DIR>’, ‘<INSTALL_DIR>’
     ‘<TMP_DIR>’, ‘<DOWNLOAD_DIR>’ and ‘<DOWNLOADED_FILE>’ with their
     corresponding property values defined in the original call to
     ExternalProject_Add().

 -- Command: ExternalProject_Add_StepTargets

     The ‘ExternalProject_Add_StepTargets()’ function generates targets
     for the steps listed.  The name of each created target will be of
     the form ‘<name>-<step>’:

          ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])

     Creating a target for a step allows it to be used as a dependency
     of another target or to be triggered manually.  Having targets for
     specific steps also allows them to be driven independently of each
     other by specifying targets on build command lines.  For example,
     you may be submitting to a sub-project based dashboard where you
     want to drive the configure portion of the build, then submit to
     the dashboard, followed by the build portion, followed by tests.
     If you invoke a custom target that depends on a step halfway
     through the step dependency chain, then all the previous steps will
     also run to ensure everything is up to date.

     Internally, see ExternalProject_Add() calls
     ExternalProject_Add_Step() to create each step.  If any
     ‘STEP_TARGETS’ were specified, then
     ‘ExternalProject_Add_StepTargets()’ will also be called after
     ExternalProject_Add_Step().  Even if a step is not mentioned
     in the ‘STEP_TARGETS’ option, ‘ExternalProject_Add_StepTargets()’
     can still be called later to manually define a target for the step.

     The ‘STEP_TARGETS’ option for ExternalProject_Add() is
     generally the easiest way to ensure targets are created for
     specific steps of interest.  For custom steps,
     ‘ExternalProject_Add_StepTargets()’ must be called explicitly if a
     target should also be created for that custom step.  An alternative
     to these two options is to populate the ‘EP_STEP_TARGETS’ directory
     property.  It acts as a default for the step target options and can
     save having to repeatedly specify the same set of step targets when
     multiple external projects are being defined.

     If CMP0114 is set to ‘NEW’, step targets are fully
     responsible for holding the custom commands implementing their
     steps.  The primary target created by ‘ExternalProject_Add’ depends
     on the step targets, and the step targets depend on each other.
     The target-level dependencies match the file-level dependencies
     used by the custom commands for each step.  The targets for steps
     created with ExternalProject_Add_Step().’s ‘INDEPENDENT’
     option do not depend on the external targets specified by
     ExternalProject_Add().’s ‘DEPENDS’ option.  The predefined
     steps ‘mkdir’, ‘download’, ‘update’, and ‘patch’ are independent.

     If CMP0114 is not ‘NEW’, the following deprecated
     behavior is available:

        * A deprecated ‘NO_DEPENDS’ option may be specified immediately
          after the ‘<name>’ and before the first step.  If the
          ‘NO_DEPENDS’ option is specified, the step target will not
          depend on the dependencies of the external project (i.e.  on
          any dependencies of the ‘<name>’ custom target created by
          ExternalProject_Add()).  This is usually safe for
          the ‘download’, ‘update’ and ‘patch’ steps, since they do not
          typically require that the dependencies are updated and built.
          Using ‘NO_DEPENDS’ for any of the other pre-defined steps,
          however, may break parallel builds.  Only use ‘NO_DEPENDS’
          where it is certain that the named steps genuinely do not have
          dependencies.  For custom steps, consider whether or not the
          custom commands require the dependencies to be configured,
          built and installed.

        * The ‘INDEPENDENT_STEP_TARGETS’ option for
          ExternalProject_Add(), or the
          ‘EP_INDEPENDENT_STEP_TARGETS’ directory property, tells the
          function to call ‘ExternalProject_Add_StepTargets()’
          internally using the ‘NO_DEPENDS’ option for the specified
          steps.

 -- Command: ExternalProject_Add_StepDependencies

     The ‘ExternalProject_Add_StepDependencies()’ function can be used
     to add dependencies to a step.  The dependencies added must be
     targets CMake already knows about (these can be ordinary executable
     or library targets, custom targets or even step targets of another
     external project):

          ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])

     This function takes care to set both target and file level
     dependencies and will ensure that parallel builds will not break.
     It should be used instead of add_dependencies().
     whenever adding a dependency for some of the step targets generated
     by the ‘ExternalProject’ module.

15.1.63.5 Examples
..................

The following example shows how to download and build a hypothetical
project called `FooBar' from github:

     include(ExternalProject)
     ExternalProject_Add(foobar
       GIT_REPOSITORY    git@github.com:FooCo/FooBar.git
       GIT_TAG           origin/release/1.2.3
     )

For the sake of the example, also define a second hypothetical external
project called `SecretSauce', which is downloaded from a web server.
Two URLs are given to take advantage of a faster internal network if
available, with a fallback to a slower external server.  The project is
a typical ‘Makefile’ project with no configure step, so some of the
default commands are overridden.  The build is only required to build
the `sauce' target:

     find_program(MAKE_EXE NAMES gmake nmake make)
     ExternalProject_Add(secretsauce
       URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                         https://www.somecompany.com/downloads/sauce-2.7.zip
       URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
       CONFIGURE_COMMAND ""
       BUILD_COMMAND     ${MAKE_EXE} sauce
     )

Suppose the build step of ‘secretsauce’ requires that ‘foobar’ must
already be built.  This could be enforced like so:

     ExternalProject_Add_StepDependencies(secretsauce build foobar)

Another alternative would be to create a custom target for ‘foobar’’s
build step and make ‘secretsauce’ depend on that rather than the whole
‘foobar’ project.  This would mean ‘foobar’ only needs to be built, it
doesn’t need to run its install or test steps before ‘secretsauce’ can
be built.  The dependency can also be defined along with the
‘secretsauce’ project:

     ExternalProject_Add_StepTargets(foobar build)
     ExternalProject_Add(secretsauce
       URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                         https://www.somecompany.com/downloads/sauce-2.7.zip
       URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
       CONFIGURE_COMMAND ""
       BUILD_COMMAND     ${MAKE_EXE} sauce
       DEPENDS           foobar-build
     )

Instead of calling ExternalProject_Add_StepTargets(), the
target could be defined along with the ‘foobar’ project itself:

     ExternalProject_Add(foobar
       GIT_REPOSITORY git@github.com:FooCo/FooBar.git
       GIT_TAG        origin/release/1.2.3
       STEP_TARGETS   build
     )

If many external projects should have the same set of step targets,
setting a directory property may be more convenient.  The ‘build’ step
target could be created automatically by setting the ‘EP_STEP_TARGETS’
directory property before creating the external projects with
ExternalProject_Add().:

     set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

Lastly, suppose that ‘secretsauce’ provides a script called ‘makedoc’
which can be used to generate its own documentation.  Further suppose
that the script expects the output directory to be provided as the only
parameter and that it should be run from the ‘secretsauce’ source
directory.  A custom step and a custom target to trigger the script can
be defined like so:

     ExternalProject_Add_Step(secretsauce docs
       COMMAND           <SOURCE_DIR>/makedoc <BINARY_DIR>
       WORKING_DIRECTORY <SOURCE_DIR>
       COMMENT           "Building secretsauce docs"
       ALWAYS            TRUE
       EXCLUDE_FROM_MAIN TRUE
     )
     ExternalProject_Add_StepTargets(secretsauce docs)

The custom step could then be triggered from the main build like so:

     cmake --build . --target secretsauce-docs

15.1.64 FeatureSummary
----------------------

Functions for generating a summary of enabled/disabled features.

These functions can be used to generate a summary of enabled and
disabled packages and/or feature for a build tree such as:

     -- The following OPTIONAL packages have been found:
     LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
        * Enables HTML-import in MyWordProcessor
        * Enables odt-export in MyWordProcessor
     PNG, A PNG image library., <http://www.libpng.org/pub/png/>
        * Enables saving screenshots
     -- The following OPTIONAL packages have not been found:
     Lua51, The Lua scripting language., <http://www.lua.org>
        * Enables macros in MyWordProcessor
     Foo, Foo provides cool stuff.

15.1.64.1 Global Properties
...........................

 -- Variable: FeatureSummary_PKG_TYPES

The global property FeatureSummary_PKG_TYPES defines the
type of packages used by ‘FeatureSummary’.

The order in this list is important, the first package type in the list
is the least important, the last is the most important.  the of a
package can only be changed to higher types.

The default package types are , ‘RUNTIME’, ‘OPTIONAL’, ‘RECOMMENDED’ and
‘REQUIRED’, and their importance is ‘RUNTIME < OPTIONAL < RECOMMENDED <
REQUIRED’.

 -- Variable: FeatureSummary_REQUIRED_PKG_TYPES

The global property FeatureSummary_REQUIRED_PKG_TYPES.
defines which package types are required.

If one or more package in this categories has not been found, CMake will
abort when calling feature_summary() with the
‘FATAL_ON_MISSING_REQUIRED_PACKAGES’ option enabled.

The default value for this global property is ‘REQUIRED’.

 -- Variable: FeatureSummary_DEFAULT_PKG_TYPE

The global property FeatureSummary_DEFAULT_PKG_TYPE defines
which package type is the default one.  When calling
feature_summary(), if the user did not set the package type
explicitly, the package will be assigned to this category.

This value must be one of the types defined in the
FeatureSummary_PKG_TYPES global property unless the package type
is set for all the packages.

The default value for this global property is ‘OPTIONAL’.

 -- Variable: FeatureSummary_<TYPE>_DESCRIPTION

The global property FeatureSummary_<TYPE>_DESCRIPTION can be
defined for each type to replace the type name with the specified string
whenever the package type is used in an output string.

If not set, the string “‘<TYPE>’ packages” is used.

15.1.64.2 Functions
...................

 -- Command: feature_summary

          feature_summary( [FILENAME <file>]
                           [APPEND]
                           [VAR <variable_name>]
                           [INCLUDE_QUIET_PACKAGES]
                           [FATAL_ON_MISSING_REQUIRED_PACKAGES]
                           [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
                           [QUIET_ON_EMPTY]
                           WHAT (ALL
                                | PACKAGES_FOUND | PACKAGES_NOT_FOUND
                                | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
                                | ENABLED_FEATURES | DISABLED_FEATURES)
                         )

     The ‘feature_summary()’ macro can be used to print information
     about enabled or disabled packages or features of a project.  By
     default, only the names of the features/packages will be printed
     and their required version when one was specified.  Use
     ‘set_package_properties()’ to add more useful information, like
     e.g.  a download URL for the respective package or their purpose in
     the project.

     The ‘WHAT’ option is the only mandatory option.  Here you specify
     what information will be printed:

     ‘ALL’

          print everything

     ‘ENABLED_FEATURES’

          the list of all features which are enabled

     ‘DISABLED_FEATURES’

          the list of all features which are disabled

     ‘PACKAGES_FOUND’

          the list of all packages which have been found

     ‘PACKAGES_NOT_FOUND’

          the list of all packages which have not been found

     For each package type ‘<TYPE>’ defined by the
     FeatureSummary_PKG_TYPES global property, the following
     information can also be used:

     ‘<TYPE>_PACKAGES_FOUND’

          only those packages which have been found which have the type
          <TYPE>

     ‘<TYPE>_PACKAGES_NOT_FOUND’

          only those packages which have not been found which have the
          type <TYPE>

     With the exception of the ‘ALL’ value, these values can be combined
     in order to customize the output.  For example:

          feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

     If a ‘FILENAME’ is given, the information is printed into this
     file.  If ‘APPEND’ is used, it is appended to this file, otherwise
     the file is overwritten if it already existed.  If the VAR option
     is used, the information is “printed” into the specified variable.
     If ‘FILENAME’ is not used, the information is printed to the
     terminal.  Using the ‘DESCRIPTION’ option a description or headline
     can be set which will be printed above the actual content.  If only
     one type of package was requested, no title is printed, unless it
     is explicitly set using either ‘DESCRIPTION’ to use a custom
     string, or ‘DEFAULT_DESCRIPTION’ to use a default title for the
     requested type.  If ‘INCLUDE_QUIET_PACKAGES’ is given, packages
     which have been searched with ‘find_package(... QUIET)’ will also
     be listed.  By default they are skipped.  If
     ‘FATAL_ON_MISSING_REQUIRED_PACKAGES’ is given, CMake will abort if
     a package which is marked as one of the package types listed in the
     FeatureSummary_REQUIRED_PKG_TYPES global property has
     not been found.  The default value for the
     FeatureSummary_REQUIRED_PKG_TYPES global property is
     ‘REQUIRED’.

     The FeatureSummary_DEFAULT_PKG_TYPE global property can
     be modified to change the default package type assigned when not
     explicitly assigned by the user.

     If the ‘QUIET_ON_EMPTY’ option is used, if only one type of package
     was requested, and no packages belonging to that category were
     found, then no output (including the ‘DESCRIPTION’) is printed or
     added to the ‘VAR’ variable.

     Example 1, append everything to a file:

          include(FeatureSummary)
          feature_summary(WHAT ALL
                          FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)

     Example 2, print the enabled features into the variable
     enabledFeaturesText, including QUIET packages:

          include(FeatureSummary)
          feature_summary(WHAT ENABLED_FEATURES
                          INCLUDE_QUIET_PACKAGES
                          DESCRIPTION "Enabled Features:"
                          VAR enabledFeaturesText)
          message(STATUS "${enabledFeaturesText}")

     Example 3, change default package types and print only the
     categories that are not empty:

          include(FeatureSummary)
          set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
          find_package(FOO)
          set_package_properties(FOO PROPERTIES TYPE BUILD)
          feature_summary(WHAT BUILD_PACKAGES_FOUND
                          Description "Build tools found:"
                          QUIET_ON_EMPTY)
          feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
                          Description "Build tools not found:"
                          QUIET_ON_EMPTY)

 -- Command: set_package_properties

          set_package_properties(<name> PROPERTIES
                                 [ URL <url> ]
                                 [ DESCRIPTION <description> ]
                                 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
                                 [ PURPOSE <purpose> ]
                                )

     Use this macro to set up information about the named package, which
     can then be displayed via FEATURE_SUMMARY().  This can be done
     either directly in the Find-module or in the project which uses the
     module after the find_package() call.  The features for which
     information can be set are added automatically by the
     find_package() command.

     ‘URL <url>’

          This should be the homepage of the package, or something
          similar.  Ideally this is set already directly in the
          Find-module.

     ‘DESCRIPTION <description>’

          A short description what that package is, at most one
          sentence.  Ideally this is set already directly in the
          Find-module.

     ‘TYPE <type>’

          What type of dependency has the using project on that package.
          Default is ‘OPTIONAL’.  In this case it is a package which can
          be used by the project when available at buildtime, but it
          also work without.  ‘RECOMMENDED’ is similar to ‘OPTIONAL’,
          i.e.  the project will build if the package is not present,
          but the functionality of the resulting binaries will be
          severely limited.  If a ‘REQUIRED’ package is not available at
          buildtime, the project may not even build.  This can be
          combined with the ‘FATAL_ON_MISSING_REQUIRED_PACKAGES’
          argument for ‘feature_summary()’.  Last, a ‘RUNTIME’ package
          is a package which is actually not used at all during the
          build, but which is required for actually running the
          resulting binaries.  So if such a package is missing, the
          project can still be built, but it may not work later on.  If
          ‘set_package_properties()’ is called multiple times for the
          same package with different TYPEs, the ‘TYPE’ is only changed
          to higher TYPEs (‘RUNTIME < OPTIONAL < RECOMMENDED <
          REQUIRED’), lower TYPEs are ignored.  The ‘TYPE’ property is
          project-specific, so it cannot be set by the Find-module, but
          must be set in the project.  Type accepted can be changed by
          setting the FeatureSummary_PKG_TYPES global
          property.

     ‘PURPOSE <purpose>’

          This describes which features this package enables in the
          project, i.e.  it tells the user what functionality he gets in
          the resulting binaries.  If set_package_properties() is called
          multiple times for a package, all PURPOSE properties are
          appended to a list of purposes of the package in the project.
          As the TYPE property, also the PURPOSE property is
          project-specific, so it cannot be set by the Find-module, but
          must be set in the project.

     Example for setting the info for a package:

          find_package(LibXml2)
          set_package_properties(LibXml2 PROPERTIES
                                 DESCRIPTION "A XML processing library."
                                 URL "http://xmlsoft.org/")
          # or
          set_package_properties(LibXml2 PROPERTIES
                                 TYPE RECOMMENDED
                                 PURPOSE "Enables HTML-import in MyWordProcessor")
          # or
          set_package_properties(LibXml2 PROPERTIES
                                 TYPE OPTIONAL
                                 PURPOSE "Enables odt-export in MyWordProcessor")

          find_package(DBUS)
          set_package_properties(DBUS PROPERTIES
            TYPE RUNTIME
            PURPOSE "Necessary to disable the screensaver during a presentation")

 -- Command: add_feature_info

          add_feature_info(<name> <enabled> <description>)

     Use this macro to add information about a feature with the given
     ‘<name>’.  ‘<enabled>’ contains whether this feature is enabled or
     not.  It can be a variable or a list of conditions.
     ‘<description>’ is a text describing the feature.  The information
     can be displayed using ‘feature_summary()’ for ‘ENABLED_FEATURES’
     and ‘DISABLED_FEATURES’ respectively.

     Example for setting the info for a feature:

          option(WITH_FOO "Help for foo" ON)
          add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")

15.1.64.3 Legacy Macros
.......................

The following macros are provided for compatibility with previous CMake
versions:

 -- Command: set_package_info

          set_package_info(<name> <description> [ <url> [<purpose>] ])

     Use this macro to set up information about the named package, which
     can then be displayed via ‘feature_summary()’.  This can be done
     either directly in the Find-module or in the project which uses the
     module after the find_package() call.  The features for
     which information can be set are added automatically by the
     ‘find_package()’ command.

 -- Command: set_feature_info

          set_feature_info(<name> <description> [<url>])

     Does the same as:

          set_package_info(<name> <description> <url>)

 -- Command: print_enabled_features

          print_enabled_features()

     Does the same as

          feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")

 -- Command: print_disabled_features

          print_disabled_features()

     Does the same as

          feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")

15.1.65 FetchContent
--------------------

New in version 3.11.

15.1.65.1 Overview
..................

This module enables populating content at configure time via any method
supported by the ExternalProject module.  Whereas
ExternalProject_Add() downloads at build time, the ‘FetchContent’
module makes content available immediately, allowing the configure step
to use the content in commands like add_subdirectory(),
include() or file() operations.

Content population details would normally be defined separately from the
command that performs the actual population.  This separation ensures
that all of the dependency details are defined before anything may try
to use those details to populate content.  This is particularly
important in more complex project hierarchies where dependencies may be
shared between multiple projects.

The following shows a typical example of declaring content details:

     FetchContent_Declare(
       googletest
       GIT_REPOSITORY https://github.com/google/googletest.git
       GIT_TAG        release-1.8.0
     )

For most typical cases, populating the content can then be done with a
single command like so:

     FetchContent_MakeAvailable(googletest)

The above command not only populates the content, it also adds it to the
main build (if possible) so that the main build can use the populated
project’s targets, etc.  In some cases, the main project may need to
have more precise control over the population or may be required to
explicitly define the population steps (e.g.  if CMake versions earlier
than 3.14 need to be supported).  The typical pattern of such custom
steps looks like this:

     FetchContent_GetProperties(googletest)
     if(NOT googletest_POPULATED)
       FetchContent_Populate(googletest)
       add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
     endif()

Regardless of which population method is used, when using the
declare-populate pattern with a hierarchical project arrangement,
projects at higher levels in the hierarchy are able to override the
population details of content specified anywhere lower in the project
hierarchy.  The ability to detect whether content has already been
populated ensures that even if multiple child projects want certain
content to be available, the first one to populate it wins.  The other
child project can simply make use of the already available content
instead of repeating the population for itself.  See the Examples
section which demonstrates this scenario.

The ‘FetchContent’ module also supports defining and populating content
in a single call, with no check for whether the content has been
populated elsewhere in the project already.  This is a more low level
operation and would not normally be the way the module is used, but it
is sometimes useful as part of implementing some higher level feature or
to populate some content in CMake’s script mode.

15.1.65.2 Commands
..................

15.1.65.3 Declaring Content Details
...................................

 -- Command: FetchContent_Declare

          FetchContent_Declare(<name> <contentOptions>...)

     The ‘FetchContent_Declare()’ function records the options that
     describe how to populate the specified content, but if such details
     have already been recorded earlier in this project (regardless of
     where in the project hierarchy), this and all later calls for the
     same content ‘<name>’ are ignored.  This “first to record, wins”
     approach is what allows hierarchical projects to have parent
     projects override content details of child projects.

     The content ‘<name>’ can be any string without spaces, but good
     practice would be to use only letters, numbers and underscores.
     The name will be treated case-insensitively and it should be
     obvious for the content it represents, often being the name of the
     child project or the value given to its top level project()
     command (if it is a CMake project).  For well-known public
     projects, the name should generally be the official name of the
     project.  Choosing an unusual name makes it unlikely that other
     projects needing that same content will use the same name, leading
     to the content being populated multiple times.

     The ‘<contentOptions>’ can be any of the download or update/patch
     options that the ExternalProject_Add() command
     understands.  The configure, build, install and test steps are
     explicitly disabled and therefore options related to them will be
     ignored.  The ‘SOURCE_SUBDIR’ option is an exception, see
     FetchContent_MakeAvailable() for details on how that affects
     behavior.

     In most cases, ‘<contentOptions>’ will just be a couple of options
     defining the download method and method-specific details like a
     commit tag or archive hash.  For example:

          FetchContent_Declare(
            googletest
            GIT_REPOSITORY https://github.com/google/googletest.git
            GIT_TAG        release-1.8.0
          )

          FetchContent_Declare(
            myCompanyIcons
            URL      https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
            URL_HASH 5588a7b18261c20068beabfb4f530b87
          )

          FetchContent_Declare(
            myCompanyCertificates
            SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
            SVN_REVISION   -r12345
          )

15.1.65.4 Populating The Content
................................

For most common scenarios, population means making content available to
the main build according to previously declared details for that
dependency.  There are two main patterns for populating content, one
based on calling FetchContent_GetProperties() and
FetchContent_Populate() for more precise control and the other on
calling FetchContent_MakeAvailable() for a simpler, more
automated approach.  The former generally follows this canonical
pattern:
     # Check if population has already been performed
     FetchContent_GetProperties(<name>)
     string(TOLOWER "<name>" lcName)
     if(NOT ${lcName}_POPULATED)
       # Fetch the content using previously declared details
       FetchContent_Populate(<name>)

       # Set custom variables, policies, etc.
       # ...

       # Bring the populated content into the build
       add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
     endif()

The above is such a common pattern that, where no custom steps are
needed between the calls to FetchContent_Populate() and
add_subdirectory(), equivalent logic can be obtained by
calling FetchContent_MakeAvailable() instead.  Where it
meets the needs of the project, see FetchContent_MakeAvailable().
should be preferred, as it is simpler and provides additional features
over the pattern above.

 -- Command: FetchContent_Populate

          FetchContent_Populate( <name> )

     In most cases, the only argument given to ‘FetchContent_Populate()’
     is the ‘<name>’.  When used this way, the command assumes the
     content details have been recorded by an earlier call to
     FetchContent_Declare().  The details are stored in a global
     property, so they are unaffected by things like variable or
     directory scope.  Therefore, it doesn’t matter where in the project
     the details were previously declared, as long as they have been
     declared before the call to ‘FetchContent_Populate()’.  Those saved
     details are then used to construct a call to
     ExternalProject_Add() in a private sub-build to perform the
     content population immediately.  The implementation of
     ‘ExternalProject_Add()’ ensures that if the content has already
     been populated in a previous CMake run, that content will be reused
     rather than repopulating them again.  For the common case where
     population involves downloading content, the cost of the download
     is only paid once.

     An internal global property records when a particular content
     population request has been processed.  If
     ‘FetchContent_Populate()’ is called more than once for the same
     content name within a configure run, the second call will halt with
     an error.  Projects can and should check whether content population
     has already been processed with the
     FetchContent_GetProperties() command before calling
     ‘FetchContent_Populate()’.

     ‘FetchContent_Populate()’ will set three variables in the scope of
     the caller; ‘<lcName>_POPULATED’, ‘<lcName>_SOURCE_DIR’ and
     ‘<lcName>_BINARY_DIR’, where ‘<lcName>’ is the lowercased ‘<name>’.
     ‘<lcName>_POPULATED’ will always be set to ‘True’ by the call.
     ‘<lcName>_SOURCE_DIR’ is the location where the content can be
     found upon return (it will have already been populated), while
     ‘<lcName>_BINARY_DIR’ is a directory intended for use as a
     corresponding build directory.  The main use case for the two
     directory variables is to call add_subdirectory().
     immediately after population, i.e.:

          FetchContent_Populate(FooBar ...)
          add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})

     The values of the three variables can also be retrieved from
     anywhere in the project hierarchy using the
     FetchContent_GetProperties() command.

     A number of cache variables influence the behavior of all content
     population performed using details saved from a
     FetchContent_Declare() call:

     ‘FETCHCONTENT_BASE_DIR’

          In most cases, the saved details do not specify any options
          relating to the directories to use for the internal sub-build,
          final source and build areas.  It is generally best to leave
          these decisions up to the ‘FetchContent’ module to handle on
          the project’s behalf.  The ‘FETCHCONTENT_BASE_DIR’ cache
          variable controls the point under which all content population
          directories are collected, but in most cases developers would
          not need to change this.  The default location is
          ‘${CMAKE_BINARY_DIR}/_deps’, but if developers change this
          value, they should aim to keep the path short and just below
          the top level of the build tree to avoid running into path
          length problems on Windows.

     ‘FETCHCONTENT_QUIET’

          The logging output during population can be quite verbose,
          making the configure stage quite noisy.  This cache option
          (‘ON’ by default) hides all population output unless an error
          is encountered.  If experiencing problems with hung downloads,
          temporarily switching this option off may help diagnose which
          content population is causing the issue.

     ‘FETCHCONTENT_FULLY_DISCONNECTED’

          When this option is enabled, no attempt is made to download or
          update any content.  It is assumed that all content has
          already been populated in a previous run or the source
          directories have been pointed at existing contents the
          developer has provided manually (using options described
          further below).  When the developer knows that no changes have
          been made to any content details, turning this option ‘ON’ can
          significantly speed up the configure stage.  It is ‘OFF’ by
          default.

     ‘FETCHCONTENT_UPDATES_DISCONNECTED’

          This is a less severe download/update control compared to
          ‘FETCHCONTENT_FULLY_DISCONNECTED’.  Instead of bypassing all
          download and update logic, the
          ‘FETCHCONTENT_UPDATES_DISCONNECTED’ only disables the update
          stage.  Therefore, if content has not been downloaded
          previously, it will still be downloaded when this option is
          enabled.  This can speed up the configure stage, but not as
          much as ‘FETCHCONTENT_FULLY_DISCONNECTED’.  It is ‘OFF’ by
          default.

     In addition to the above cache variables, the following cache
     variables are also defined for each content name (‘<ucName>’ is the
     uppercased value of ‘<name>’):

     ‘FETCHCONTENT_SOURCE_DIR_<ucName>’

          If this is set, no download or update steps are performed for
          the specified content and the ‘<lcName>_SOURCE_DIR’ variable
          returned to the caller is pointed at this location.  This
          gives developers a way to have a separate checkout of the
          content that they can modify freely without interference from
          the build.  The build simply uses that existing source, but it
          still defines ‘<lcName>_BINARY_DIR’ to point inside its own
          build area.  Developers are strongly encouraged to use this
          mechanism rather than editing the sources populated in the
          default location, as changes to sources in the default
          location can be lost when content population details are
          changed by the project.

     ‘FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>’

          This is the per-content equivalent of
          ‘FETCHCONTENT_UPDATES_DISCONNECTED’.  If the global option or
          this option is ‘ON’, then updates will be disabled for the
          named content.  Disabling updates for individual content can
          be useful for content whose details rarely change, while still
          leaving other frequently changing content with updates
          enabled.

     The ‘FetchContent_Populate()’ command also supports a syntax
     allowing the content details to be specified directly rather than
     using any saved details.  This is more low-level and use of this
     form is generally to be avoided in favour of using saved content
     details as outlined above.  Nevertheless, in certain situations it
     can be useful to invoke the content population as an isolated
     operation (typically as part of implementing some other higher
     level feature or when using CMake in script mode):

          FetchContent_Populate( <name>
            [QUIET]
            [SUBBUILD_DIR <subBuildDir>]
            [SOURCE_DIR <srcDir>]
            [BINARY_DIR <binDir>]
            ...
          )

     This form has a number of key differences to that where only
     ‘<name>’ is provided:

        - All required population details are assumed to have been
          provided directly in the call to ‘FetchContent_Populate()’.
          Any saved details for ‘<name>’ are ignored.

        - No check is made for whether content for ‘<name>’ has already
          been populated.

        - No global property is set to record that the population has
          occurred.

        - No global properties record the source or binary directories
          used for the populated content.

        - The ‘FETCHCONTENT_FULLY_DISCONNECTED’ and
          ‘FETCHCONTENT_UPDATES_DISCONNECTED’ cache variables are
          ignored.

     The ‘<lcName>_SOURCE_DIR’ and ‘<lcName>_BINARY_DIR’ variables are
     still returned to the caller, but since these locations are not
     stored as global properties when this form is used, they are only
     available to the calling scope and below rather than the entire
     project hierarchy.  No ‘<lcName>_POPULATED’ variable is set in the
     caller’s scope with this form.

     The supported options for ‘FetchContent_Populate()’ are the same as
     those for FetchContent_Declare().  Those few options
     shown just above are either specific to ‘FetchContent_Populate()’
     or their behavior is slightly modified from how
     ExternalProject_Add() treats them.

     ‘QUIET’

          The ‘QUIET’ option can be given to hide the output associated
          with populating the specified content.  If the population
          fails, the output will be shown regardless of whether this
          option was given or not so that the cause of the failure can
          be diagnosed.  The global ‘FETCHCONTENT_QUIET’ cache variable
          has no effect on ‘FetchContent_Populate()’ calls where the
          content details are provided directly.

     ‘SUBBUILD_DIR’

          The ‘SUBBUILD_DIR’ argument can be provided to change the
          location of the sub-build created to perform the population.
          The default value is
          ‘${CMAKE_CURRENT_BINARY_DIR}/<lcName>-subbuild’ and it would
          be unusual to need to override this default.  If a relative
          path is specified, it will be interpreted as relative to
          CMAKE_CURRENT_BINARY_DIR.  This option should not be
          confused with the ‘SOURCE_SUBDIR’ option which only affects
          the FetchContent_MakeAvailable() command.

     ‘SOURCE_DIR’, ‘BINARY_DIR’

          The ‘SOURCE_DIR’ and ‘BINARY_DIR’ arguments are supported by
          ExternalProject_Add(), but different default values
          are used by ‘FetchContent_Populate()’.  ‘SOURCE_DIR’ defaults
          to ‘${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src’ and ‘BINARY_DIR’
          defaults to ‘${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build’.  If
          a relative path is specified, it will be interpreted as
          relative to CMAKE_CURRENT_BINARY_DIR.

     In addition to the above explicit options, any other unrecognized
     options are passed through unmodified to
     ExternalProject_Add() to perform the download, patch and
     update steps.  The following options are explicitly prohibited
     (they are disabled by the ‘FetchContent_Populate()’ command):

        - ‘CONFIGURE_COMMAND’

        - ‘BUILD_COMMAND’

        - ‘INSTALL_COMMAND’

        - ‘TEST_COMMAND’

     If using ‘FetchContent_Populate()’ within CMake’s script mode, be
     aware that the implementation sets up a sub-build which therefore
     requires a CMake generator and build tool to be available.  If
     these cannot be found by default, then the CMAKE_GENERATOR
     and/or CMAKE_MAKE_PROGRAM variables will need to
     be set appropriately on the command line invoking the script.

 -- Command: FetchContent_GetProperties

     When using saved content details, a call to
     FetchContent_Populate() records information in global
     properties which can be queried at any time.  This information
     includes the source and binary directories associated with the
     content and also whether or not the content population has been
     processed during the current configure run.

          FetchContent_GetProperties( <name>
            [SOURCE_DIR <srcDirVar>]
            [BINARY_DIR <binDirVar>]
            [POPULATED <doneVar>]
          )

     The ‘SOURCE_DIR’, ‘BINARY_DIR’ and ‘POPULATED’ options can be used
     to specify which properties should be retrieved.  Each option
     accepts a value which is the name of the variable in which to store
     that property.  Most of the time though, only ‘<name>’ is given, in
     which case the call will then set the same variables as a call to
     FetchContent_Populate(name).  This allows the following
     canonical pattern to be used, which ensures that the relevant
     variables will always be defined regardless of whether or not the
     population has been performed elsewhere in the project already:

          FetchContent_GetProperties(foobar)
          if(NOT foobar_POPULATED)
            FetchContent_Populate(foobar)
            ...
          endif()

     The above pattern allows other parts of the overall project
     hierarchy to re-use the same content and ensure that it is only
     populated once.

 -- Command: FetchContent_MakeAvailable

          FetchContent_MakeAvailable( <name1> [<name2>...] )

     This command implements the common pattern typically needed for
     most dependencies.  It iterates over each of the named dependencies
     in turn and for each one it loosely follows the canonical pattern
     as presented at the beginning of this section.  An
     important difference is that add_subdirectory() will
     only be called on the populated content if there is a
     ‘CMakeLists.txt’ file in its top level source directory.  This
     allows the command to be used for dependencies that make downloaded
     content available at a known location but which do not need or
     support being added directly to the build.

     The ‘SOURCE_SUBDIR’ option can be given in the declared details to
     instruct ‘FetchContent_MakeAvailable()’ to look for a
     ‘CMakeLists.txt’ file in a subdirectory below the top level (i.e.
     the same way that ‘SOURCE_SUBDIR’ is used by the
     ExternalProject_Add() command).  ‘SOURCE_SUBDIR’ must always
     be a relative path.  See the next section for an example of this
     option.

15.1.65.5 Examples
..................

This first fairly straightforward example ensures that some popular
testing frameworks are available to the main build:

     include(FetchContent)
     FetchContent_Declare(
       googletest
       GIT_REPOSITORY https://github.com/google/googletest.git
       GIT_TAG        release-1.8.0
     )
     FetchContent_Declare(
       Catch2
       GIT_REPOSITORY https://github.com/catchorg/Catch2.git
       GIT_TAG        v2.5.0
     )

     # After the following call, the CMake targets defined by googletest and
     # Catch2 will be defined and available to the rest of the build
     FetchContent_MakeAvailable(googletest Catch2)

If the sub-project’s ‘CMakeLists.txt’ file is not at the top level of
its source tree, the ‘SOURCE_SUBDIR’ option can be used to tell
‘FetchContent’ where to find it.  The following example shows how to use
that option and it also sets a variable which is meaningful to the
subproject before pulling it into the main build:

     include(FetchContent)
     FetchContent_Declare(
       protobuf
       GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
       GIT_TAG        v3.12.0
       SOURCE_SUBDIR  cmake
     )
     set(protobuf_BUILD_TESTS OFF)
     FetchContent_MakeAvailable(protobuf)

In more complex project hierarchies, the dependency relationships can be
more complicated.  Consider a hierarchy where ‘projA’ is the top level
project and it depends directly on projects ‘projB’ and ‘projC’.  Both
‘projB’ and ‘projC’ can be built standalone and they also both depend on
another project ‘projD’.  ‘projB’ additionally depends on ‘projE’.  This
example assumes that all five projects are available on a company git
server.  The ‘CMakeLists.txt’ of each project might have sections like
the following:

`projA':

     include(FetchContent)
     FetchContent_Declare(
       projB
       GIT_REPOSITORY git@mycompany.com:git/projB.git
       GIT_TAG        4a89dc7e24ff212a7b5167bef7ab079d
     )
     FetchContent_Declare(
       projC
       GIT_REPOSITORY git@mycompany.com:git/projC.git
       GIT_TAG        4ad4016bd1d8d5412d135cf8ceea1bb9
     )
     FetchContent_Declare(
       projD
       GIT_REPOSITORY git@mycompany.com:git/projD.git
       GIT_TAG        origin/integrationBranch
     )
     FetchContent_Declare(
       projE
       GIT_REPOSITORY git@mycompany.com:git/projE.git
       GIT_TAG        origin/release/2.3-rc1
     )

     # Order is important, see notes in the discussion further below
     FetchContent_MakeAvailable(projD projB projC)

`projB':

     include(FetchContent)
     FetchContent_Declare(
       projD
       GIT_REPOSITORY git@mycompany.com:git/projD.git
       GIT_TAG        20b415f9034bbd2a2e8216e9a5c9e632
     )
     FetchContent_Declare(
       projE
       GIT_REPOSITORY git@mycompany.com:git/projE.git
       GIT_TAG        68e20f674a48be38d60e129f600faf7d
     )

     FetchContent_MakeAvailable(projD projE)

`projC':

     include(FetchContent)
     FetchContent_Declare(
       projD
       GIT_REPOSITORY git@mycompany.com:git/projD.git
       GIT_TAG        7d9a17ad2c962aa13e2fbb8043fb6b8a
     )

     # This particular version of projD requires workarounds
     FetchContent_GetProperties(projD)
     if(NOT projd_POPULATED)
       FetchContent_Populate(projD)

       # Copy an additional/replacement file into the populated source
       file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)

       add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
     endif()

A few key points should be noted in the above:

   - ‘projB’ and ‘projC’ define different content details for ‘projD’,
     but ‘projA’ also defines a set of content details for ‘projD’.
     Because ‘projA’ will define them first, the details from ‘projB’
     and ‘projC’ will not be used.  The override details defined by
     ‘projA’ are not required to match either of those from ‘projB’ or
     ‘projC’, but it is up to the higher level project to ensure that
     the details it does define still make sense for the child projects.

   - In the ‘projA’ call to FetchContent_MakeAvailable(),
     ‘projD’ is listed ahead of ‘projB’ and ‘projC’ to ensure that
     ‘projA’ is in control of how ‘projD’ is populated.

   - While ‘projA’ defines content details for ‘projE’, it does not need
     to explicitly call ‘FetchContent_MakeAvailable(projE)’ or
     ‘FetchContent_Populate(projD)’ itself.  Instead, it leaves that to
     the child ‘projB’.  For higher level projects, it is often enough
     to just define the override content details and leave the actual
     population to the child projects.  This saves repeating the same
     thing at each level of the project hierarchy unnecessarily.

Projects don’t always need to add the populated content to the build.
Sometimes the project just wants to make the downloaded content
available at a predictable location.  The next example ensures that a
set of standard company toolchain files (and potentially even the
toolchain binaries themselves) is available early enough to be used for
that same build.

     cmake_minimum_required(VERSION 3.14)

     include(FetchContent)
     FetchContent_Declare(
       mycom_toolchains
       URL  https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
     )
     FetchContent_MakeAvailable(mycom_toolchains)

     project(CrossCompileExample)

The project could be configured to use one of the downloaded toolchains
like so:

     cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src

When CMake processes the ‘CMakeLists.txt’ file, it will download and
unpack the tarball into ‘_deps/mycompany_toolchains-src’ relative to the
build directory.  The CMAKE_TOOLCHAIN_FILE variable is not
used until the project() command is reached, at which point
CMake looks for the named toolchain file relative to the build
directory.  Because the tarball has already been downloaded and unpacked
by then, the toolchain file will be in place, even the very first time
that ‘cmake’ is run in the build directory.

Lastly, the following example demonstrates how one might download and
unpack a firmware tarball using CMake’s script mode.  The call
to FetchContent_Populate() specifies all the content details
and the unpacked firmware will be placed in a ‘firmware’ directory below
the current working directory.

`getFirmware.cmake':

     # NOTE: Intended to be run in script mode with cmake -P
     include(FetchContent)
     FetchContent_Populate(
       firmware
       URL        https://mycompany.com/assets/firmware-1.23-arm.tar.gz
       URL_HASH   MD5=68247684da89b608d466253762b0ff11
       SOURCE_DIR firmware
     )

15.1.66 FindPackageHandleStandardArgs
-------------------------------------

This module provides functions intended to be used in Find Modules
implementing find_package(<PackageName>) calls.

 -- Command: find_package_handle_standard_args

     This command handles the ‘REQUIRED’, ‘QUIET’ and version-related
     arguments of find_package().  It also sets the
     ‘<PackageName>_FOUND’ variable.  The package is considered found if
     all variables listed contain valid results, e.g.  valid filepaths.

     There are two signatures:

          find_package_handle_standard_args(<PackageName>
            (DEFAULT_MSG|<custom-failure-message>)
            <required-var>...
            )

          find_package_handle_standard_args(<PackageName>
            [FOUND_VAR <result-var>]
            [REQUIRED_VARS <required-var>...]
            [VERSION_VAR <version-var>]
            [HANDLE_VERSION_RANGE]
            [HANDLE_COMPONENTS]
            [CONFIG_MODE]
            [NAME_MISMATCHED]
            [REASON_FAILURE_MESSAGE <reason-failure-message>]
            [FAIL_MESSAGE <custom-failure-message>]
            )

     The ‘<PackageName>_FOUND’ variable will be set to ‘TRUE’ if all the
     variables ‘<required-var>...’ are valid and any optional
     constraints are satisfied, and ‘FALSE’ otherwise.  A success or
     failure message may be displayed based on the results and on
     whether the ‘REQUIRED’ and/or ‘QUIET’ option was given to the
     find_package() call.

     The options are:

     ‘(DEFAULT_MSG|<custom-failure-message>)’

          In the simple signature this specifies the failure message.
          Use ‘DEFAULT_MSG’ to ask for a default message to be computed
          (recommended).  Not valid in the full signature.

     ‘FOUND_VAR <result-var>’

          Obsolete.  Specifies either ‘<PackageName>_FOUND’ or
          ‘<PACKAGENAME>_FOUND’ as the result variable.  This exists
          only for compatibility with older versions of CMake and is now
          ignored.  Result variables of both names are always set for
          compatibility.

     ‘REQUIRED_VARS <required-var>...’

          Specify the variables which are required for this package.
          These may be named in the generated failure message asking the
          user to set the missing variable values.  Therefore these
          should typically be cache entries such as ‘FOO_LIBRARY’ and
          not output variables like ‘FOO_LIBRARIES’.  This option is
          mandatory if ‘HANDLE_COMPONENTS’ is not specified.

     ‘VERSION_VAR <version-var>’

          Specify the name of a variable that holds the version of the
          package that has been found.  This version will be checked
          against the (potentially) specified required version given to
          the find_package() call, including its ‘EXACT’
          option.  The default messages include information about the
          required version and the version which has been actually
          found, both if the version is ok or not.

     ‘HANDLE_VERSION_RANGE’

          Enable handling of a version range, if one is specified.
          Without this option, a developer warning will be displayed if
          a version range is specified.

     ‘HANDLE_COMPONENTS’

          Enable handling of package components.  In this case, the
          command will report which components have been found and which
          are missing, and the ‘<PackageName>_FOUND’ variable will be
          set to ‘FALSE’ if any of the required components (i.e.  not
          the ones listed after the ‘OPTIONAL_COMPONENTS’ option of
          find_package()) are missing.

     ‘CONFIG_MODE’

          Specify that the calling find module is a wrapper around a
          call to ‘find_package(<PackageName> NO_MODULE)’.  This implies
          a ‘VERSION_VAR’ value of ‘<PackageName>_VERSION’.  The command
          will automatically check whether the package configuration
          file was found.

     ‘REASON_FAILURE_MESSAGE <reason-failure-message>’

          Specify a custom message of the reason for the failure which
          will be appended to the default generated message.

     ‘FAIL_MESSAGE <custom-failure-message>’

          Specify a custom failure message instead of using the default
          generated message.  Not recommended.

     ‘NAME_MISMATCHED’

          Indicate that the ‘<PackageName>’ does not match
          ‘${CMAKE_FIND_PACKAGE_NAME}’.  This is usually a mistake and
          raises a warning, but it may be intentional for usage of the
          command for components of a larger package.

Example for the simple signature:

     find_package_handle_standard_args(LibXml2 DEFAULT_MSG
       LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)

The ‘LibXml2’ package is considered to be found if both
‘LIBXML2_LIBRARY’ and ‘LIBXML2_INCLUDE_DIR’ are valid.  Then also
‘LibXml2_FOUND’ is set to ‘TRUE’.  If it is not found and ‘REQUIRED’ was
used, it fails with a message(FATAL_ERROR), independent
whether ‘QUIET’ was used or not.  If it is found, success will be
reported, including the content of the first ‘<required-var>’.  On
repeated CMake runs, the same message will not be printed again.

     Note: If ‘<PackageName>’ does not match ‘CMAKE_FIND_PACKAGE_NAME’
     for the calling module, a warning that there is a mismatch is
     given.  The ‘FPHSA_NAME_MISMATCHED’ variable may be set to bypass
     the warning if using the old signature and the ‘NAME_MISMATCHED’
     argument using the new signature.  To avoid forcing the caller to
     require newer versions of CMake for usage, the variable’s value
     will be used if defined when the ‘NAME_MISMATCHED’ argument is not
     passed for the new signature (but using both is an error)..

Example for the full signature:

     find_package_handle_standard_args(LibArchive
       REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
       VERSION_VAR LibArchive_VERSION)

In this case, the ‘LibArchive’ package is considered to be found if both
‘LibArchive_LIBRARY’ and ‘LibArchive_INCLUDE_DIR’ are valid.  Also the
version of ‘LibArchive’ will be checked by using the version contained
in ‘LibArchive_VERSION’.  Since no ‘FAIL_MESSAGE’ is given, the default
messages will be printed.

Another example for the full signature:

     find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
     find_package_handle_standard_args(Automoc4  CONFIG_MODE)

In this case, a ‘FindAutmoc4.cmake’ module wraps a call to
‘find_package(Automoc4 NO_MODULE)’ and adds an additional search
directory for ‘automoc4’.  Then the call to
‘find_package_handle_standard_args’ produces a proper success/failure
message.

 -- Command: find_package_check_version

     Helper function which can be used to check if a ‘<version>’ is
     valid against version-related arguments of find_package().

          find_package_check_version(<version> <result-var>
            [HANDLE_VERSION_RANGE]
            [RESULT_MESSAGE_VARIABLE <message-var>]
            )

     The ‘<result-var>’ will hold a boolean value giving the result of
     the check.

     The options are:

     ‘HANDLE_VERSION_RANGE’

          Enable handling of a version range, if one is specified.
          Without this option, a developer warning will be displayed if
          a version range is specified.

     ‘RESULT_MESSAGE_VARIABLE <message-var>’

          Specify a variable to get back a message describing the result
          of the check.

Example for the usage:

     find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
       RESULT_MESSAGE_VARIABLE reason)
     if (result)
       message (STATUS "${reason}")
     else()
       message (FATAL_ERROR "${reason}")
     endif()

15.1.67 FindPackageMessage
--------------------------

     find_package_message(<name> "message for user" "find result details")

This function is intended to be used in FindXXX.cmake modules files.  It
will print a message once for each unique find result.  This is useful
for telling the user where a package was found.  The first argument
specifies the name (XXX) of the package.  The second argument specifies
the message to display.  The third argument lists details about the find
result so that if they change the message will be displayed again.  The
macro also obeys the QUIET argument to the find_package command.

Example:

     if(X11_FOUND)
       find_package_message(X11 "Found X11: ${X11_X11_LIB}"
         "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
     else()
      ...
     endif()

15.1.68 FortranCInterface
-------------------------

Fortran/C Interface Detection

This module automatically detects the API by which C and Fortran
languages interact.

15.1.68.1 Module Variables
..........................

Variables that indicate if the mangling is found:

‘FortranCInterface_GLOBAL_FOUND’

     Global subroutines and functions.

‘FortranCInterface_MODULE_FOUND’

     Module subroutines and functions (declared by “MODULE PROCEDURE”).

This module also provides the following variables to specify the
detected mangling, though a typical use case does not need to reference
them and can use the Module Functions below.

‘FortranCInterface_GLOBAL_PREFIX’

     Prefix for a global symbol without an underscore.

‘FortranCInterface_GLOBAL_SUFFIX’

     Suffix for a global symbol without an underscore.

‘FortranCInterface_GLOBAL_CASE’

     The case for a global symbol without an underscore, either ‘UPPER’
     or ‘LOWER’.

‘FortranCInterface_GLOBAL__PREFIX’

     Prefix for a global symbol with an underscore.

‘FortranCInterface_GLOBAL__SUFFIX’

     Suffix for a global symbol with an underscore.

‘FortranCInterface_GLOBAL__CASE’

     The case for a global symbol with an underscore, either ‘UPPER’ or
     ‘LOWER’.

‘FortranCInterface_MODULE_PREFIX’

     Prefix for a module symbol without an underscore.

‘FortranCInterface_MODULE_MIDDLE’

     Middle of a module symbol without an underscore that appears
     between the name of the module and the name of the symbol.

‘FortranCInterface_MODULE_SUFFIX’

     Suffix for a module symbol without an underscore.

‘FortranCInterface_MODULE_CASE’

     The case for a module symbol without an underscore, either ‘UPPER’
     or ‘LOWER’.

‘FortranCInterface_MODULE__PREFIX’

     Prefix for a module symbol with an underscore.

‘FortranCInterface_MODULE__MIDDLE’

     Middle of a module symbol with an underscore that appears between
     the name of the module and the name of the symbol.

‘FortranCInterface_MODULE__SUFFIX’

     Suffix for a module symbol with an underscore.

‘FortranCInterface_MODULE__CASE’

     The case for a module symbol with an underscore, either ‘UPPER’ or
     ‘LOWER’.

15.1.68.2 Module Functions
..........................

 -- Command: FortranCInterface_HEADER

     The ‘FortranCInterface_HEADER’ function is provided to generate a C
     header file containing macros to mangle symbol names:

          FortranCInterface_HEADER(<file>
                                   [MACRO_NAMESPACE <macro-ns>]
                                   [SYMBOL_NAMESPACE <ns>]
                                   [SYMBOLS [<module>:]<function> ...])

     It generates in ‘<file>’ definitions of the following macros:

          #define FortranCInterface_GLOBAL (name,NAME) ...
          #define FortranCInterface_GLOBAL_(name,NAME) ...
          #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
          #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...

     These macros mangle four categories of Fortran symbols,
     respectively:

        * Global symbols without ‘_’: ‘call mysub()’

        * Global symbols with ‘_’ : ‘call my_sub()’

        * Module symbols without ‘_’: ‘use mymod; call mysub()’

        * Module symbols with ‘_’ : ‘use mymod; call my_sub()’

     If mangling for a category is not known, its macro is left
     undefined.  All macros require raw names in both lower case and
     upper case.

     The options are:

     ‘MACRO_NAMESPACE’

          Replace the default ‘FortranCInterface_’ prefix with a given
          namespace ‘<macro-ns>’.

     ‘SYMBOLS’

          List symbols to mangle automatically with C preprocessor
          definitions:

               <function>          ==> #define <ns><function> ...
               <module>:<function> ==> #define <ns><module>_<function> ...

          If the mangling for some symbol is not known then no
          preprocessor definition is created, and a warning is
          displayed.

     ‘SYMBOL_NAMESPACE’

          Prefix all preprocessor definitions generated by the ‘SYMBOLS’
          option with a given namespace ‘<ns>’.

 -- Command: FortranCInterface_VERIFY

     The ‘FortranCInterface_VERIFY’ function is provided to verify that
     the Fortran and C/C++ compilers work together:

          FortranCInterface_VERIFY([CXX] [QUIET])

     It tests whether a simple test executable using Fortran and C (and
     C++ when the CXX option is given) compiles and links successfully.
     The result is stored in the cache entry
     ‘FortranCInterface_VERIFIED_C’ (or ‘FortranCInterface_VERIFIED_CXX’
     if ‘CXX’ is given) as a boolean.  If the check fails and ‘QUIET’ is
     not given the function terminates with a fatal error message
     describing the problem.  The purpose of this check is to stop a
     build early for incompatible compiler combinations.  The test is
     built in the ‘Release’ configuration.

15.1.68.3 Example Usage
.......................

     include(FortranCInterface)
     FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")

This creates a “FC.h” header that defines mangling macros ‘FC_GLOBAL()’,
‘FC_GLOBAL_()’, ‘FC_MODULE()’, and ‘FC_MODULE_()’.

     include(FortranCInterface)
     FortranCInterface_HEADER(FCMangle.h
                              MACRO_NAMESPACE "FC_"
                              SYMBOL_NAMESPACE "FC_"
                              SYMBOLS mysub mymod:my_sub)

This creates a “FCMangle.h” header that defines the same ‘FC_*()’
mangling macros as the previous example plus preprocessor symbols
‘FC_mysub’ and ‘FC_mymod_my_sub’.

15.1.68.4 Additional Manglings
..............................

FortranCInterface is aware of possible ‘GLOBAL’ and ‘MODULE’ manglings
for many Fortran compilers, but it also provides an interface to specify
new possible manglings.  Set the variables:

     FortranCInterface_GLOBAL_SYMBOLS
     FortranCInterface_MODULE_SYMBOLS

before including FortranCInterface to specify manglings of the symbols
‘MySub’, ‘My_Sub’, ‘MyModule:MySub’, and ‘My_Module:My_Sub’.  For
example, the code:

     set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
       #                                  ^^^^^  ^^^^^^   ^^^^^
     set(FortranCInterface_MODULE_SYMBOLS
         __mymodule_MOD_mysub __my_module_MOD_my_sub)
       #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
     include(FortranCInterface)

tells FortranCInterface to try given ‘GLOBAL’ and ‘MODULE’ manglings.
(The carets point at raw symbol names for clarity in this example but
are not needed.)

15.1.69 GenerateExportHeader
----------------------------

Function for generation of export macros for libraries

This module provides the function ‘GENERATE_EXPORT_HEADER()’.

The ‘GENERATE_EXPORT_HEADER’ function can be used to generate a file
suitable for preprocessor inclusion which contains EXPORT macros to be
used in library classes:

     GENERATE_EXPORT_HEADER( LIBRARY_TARGET
               [BASE_NAME <base_name>]
               [EXPORT_MACRO_NAME <export_macro_name>]
               [EXPORT_FILE_NAME <export_file_name>]
               [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
               [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
               [INCLUDE_GUARD_NAME <include_guard_name>]
               [STATIC_DEFINE <static_define>]
               [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
               [DEFINE_NO_DEPRECATED]
               [PREFIX_NAME <prefix_name>]
               [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
     )

The target properties CXX_VISIBILITY_PRESET and
VISIBILITY_INLINES_HIDDEN can be used to add the appropriate
compile flags for targets.  See the documentation of those target
properties, and the convenience variables
CMAKE_CXX_VISIBILITY_PRESET and
CMAKE_VISIBILITY_INLINES_HIDDEN.

By default ‘GENERATE_EXPORT_HEADER()’ generates macro names in a file
name determined by the name of the library.  This means that in the
simplest case, users of ‘GenerateExportHeader’ will be equivalent to:

     set(CMAKE_CXX_VISIBILITY_PRESET hidden)
     set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
     add_library(somelib someclass.cpp)
     generate_export_header(somelib)
     install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
     install(FILES
      someclass.h
      ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
     )

And in the ABI header files:

     #include "somelib_export.h"
     class SOMELIB_EXPORT SomeClass {
       ...
     };

The CMake fragment will generate a file in the
‘${CMAKE_CURRENT_BINARY_DIR}’ called ‘somelib_export.h’ containing the
macros ‘SOMELIB_EXPORT’, ‘SOMELIB_NO_EXPORT’, ‘SOMELIB_DEPRECATED’,
‘SOMELIB_DEPRECATED_EXPORT’ and ‘SOMELIB_DEPRECATED_NO_EXPORT’.  They
will be followed by content taken from the variable specified by the
‘CUSTOM_CONTENT_FROM_VARIABLE’ option, if any.  The resulting file
should be installed with other headers in the library.

The ‘BASE_NAME’ argument can be used to override the file name and the
names used for the macros:

     add_library(somelib someclass.cpp)
     generate_export_header(somelib
       BASE_NAME other_name
     )

Generates a file called ‘other_name_export.h’ containing the macros
‘OTHER_NAME_EXPORT’, ‘OTHER_NAME_NO_EXPORT’ and ‘OTHER_NAME_DEPRECATED’
etc.

The ‘BASE_NAME’ may be overridden by specifying other options in the
function.  For example:

     add_library(somelib someclass.cpp)
     generate_export_header(somelib
       EXPORT_MACRO_NAME OTHER_NAME_EXPORT
     )

creates the macro ‘OTHER_NAME_EXPORT’ instead of ‘SOMELIB_EXPORT’, but
other macros and the generated file name is as default:

     add_library(somelib someclass.cpp)
     generate_export_header(somelib
       DEPRECATED_MACRO_NAME KDE_DEPRECATED
     )

creates the macro ‘KDE_DEPRECATED’ instead of ‘SOMELIB_DEPRECATED’.

If ‘LIBRARY_TARGET’ is a static library, macros are defined without
values.

If the same sources are used to create both a shared and a static
library, the uppercased symbol ‘${BASE_NAME}_STATIC_DEFINE’ should be
used when building the static library:

     add_library(shared_variant SHARED ${lib_SRCS})
     add_library(static_variant ${lib_SRCS})
     generate_export_header(shared_variant BASE_NAME libshared_and_static)
     set_target_properties(static_variant PROPERTIES
       COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)

This will cause the export macros to expand to nothing when building the
static library.

If ‘DEFINE_NO_DEPRECATED’ is specified, then a macro
‘${BASE_NAME}_NO_DEPRECATED’ will be defined This macro can be used to
remove deprecated code from preprocessor output:

     option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
     if (EXCLUDE_DEPRECATED)
       set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
     endif()
     generate_export_header(somelib ${NO_BUILD_DEPRECATED})

And then in somelib:

     class SOMELIB_EXPORT SomeClass
     {
     public:
     #ifndef SOMELIB_NO_DEPRECATED
       SOMELIB_DEPRECATED void oldMethod();
     #endif
     };

     #ifndef SOMELIB_NO_DEPRECATED
     void SomeClass::oldMethod() {  }
     #endif

If ‘PREFIX_NAME’ is specified, the argument will be used as a prefix to
all generated macros.

For example:

     generate_export_header(somelib PREFIX_NAME VTK_)

Generates the macros ‘VTK_SOMELIB_EXPORT’ etc.

     ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )

The ‘ADD_COMPILER_EXPORT_FLAGS’ function adds ‘-fvisibility=hidden’ to
CMAKE_CXX_FLAGS if supported, and is a no-op on Windows
which does not need extra compiler flags for exporting support.  You may
optionally pass a single argument to ‘ADD_COMPILER_EXPORT_FLAGS’ that
will be populated with the ‘CXX_FLAGS’ required to enable visibility
support for the compiler/architecture in use.

This function is deprecated.  Set the target properties
CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN.
instead.

15.1.70 GetPrerequisites
------------------------

Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES)
instead.

Functions to analyze and list executable file prerequisites.

This module provides functions to list the .dll, .dylib or .so files
that an executable or shared library file depends on.  (Its
prerequisites.)

It uses various tools to obtain the list of required shared library
files:

     dumpbin (Windows)
     objdump (MinGW on Windows)
     ldd (Linux/Unix)
     otool (Mac OSX)

The following functions are provided by this module:

     get_prerequisites
     list_prerequisites
     list_prerequisites_by_glob
     gp_append_unique
     is_file_executable
     gp_item_default_embedded_path
       (projects can override with gp_item_default_embedded_path_override)
     gp_resolve_item
       (projects can override with gp_resolve_item_override)
     gp_resolved_file_type
       (projects can override with gp_resolved_file_type_override)
     gp_file_type

Requires CMake 2.6 or greater because it uses function, break, return
and PARENT_SCOPE.

     GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
                       <exepath> <dirs> [<rpaths>])

Get the list of shared library files required by <target>.  The list in
the variable named <prerequisites_var> should be empty on first entry to
this function.  On exit, <prerequisites_var> will contain the list of
required shared library files.

<target> is the full path to an executable file.  <prerequisites_var> is
the name of a CMake variable to contain the results.  <exclude_system>
must be 0 or 1 indicating whether to include or exclude “system”
prerequisites.  If <recurse> is set to 1 all prerequisites will be found
recursively, if set to 0 only direct prerequisites are listed.
<exepath> is the path to the top level executable used for
@executable_path replacement on the Mac.  <dirs> is a list of paths
where libraries might be found: these paths are searched first when a
target without any path info is given.  Then standard system locations
are also searched: PATH, Framework locations, /usr/lib…

The variable GET_PREREQUISITES_VERBOSE can be set to true to enable
verbose output.

     LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])

Print a message listing the prerequisites of <target>.

<target> is the name of a shared library or executable target or the
full path to a shared library or executable file.  If <recurse> is set
to 1 all prerequisites will be found recursively, if set to 0 only
direct prerequisites are listed.  <exclude_system> must be 0 or 1
indicating whether to include or exclude “system” prerequisites.  With
<verbose> set to 0 only the full path names of the prerequisites are
printed, set to 1 extra informatin will be displayed.

     LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)

Print the prerequisites of shared library and executable files matching
a globbing pattern.  <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE” to
retrieve a list of matching files.  If a matching file is executable,
its prerequisites are listed.

Any additional (optional) arguments provided are passed along as the
optional arguments to the list_prerequisites calls.

     GP_APPEND_UNIQUE(<list_var> <value>)

Append <value> to the list variable <list_var> only if the value is not
already in the list.

     IS_FILE_EXECUTABLE(<file> <result_var>)

Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.

     GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)

Return the path that others should refer to the item by when the item is
embedded inside a bundle.

Override on a per-project basis by providing a project-specific
gp_item_default_embedded_path_override function.

     GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
                     [<rpaths>])

Resolve an item into an existing full path file.

Override on a per-project basis by providing a project-specific
gp_resolve_item_override function.

     GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
                           [<rpaths>])

Return the type of <file> with respect to <original_file>.  String
describing type of prerequisite is returned in variable named
<type_var>.

Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
values – but only for non-embedded items.

Possible types are:

     system
     local
     embedded
     other

Override on a per-project basis by providing a project-specific
gp_resolved_file_type_override function.

     GP_FILE_TYPE(<original_file> <file> <type_var>)

Return the type of <file> with respect to <original_file>.  String
describing type of prerequisite is returned in variable named
<type_var>.

Possible types are:

     system
     local
     embedded
     other

15.1.71 GNUInstallDirs
----------------------

Define GNU standard installation directories

Provides install directory variables as defined by the GNU Coding
Standards(1).

   ---------- Footnotes ----------

   (1)
https://www.gnu.org/prep/standards/html_node/Directory-Variables.html

15.1.71.1 Result Variables
..........................

Inclusion of this module defines the following variables:

‘CMAKE_INSTALL_<dir>’

     Destination for files of a given type.  This value may be passed to
     the ‘DESTINATION’ options of install() commands for the
     corresponding file type.

‘CMAKE_INSTALL_FULL_<dir>’

     The absolute path generated from the corresponding
     ‘CMAKE_INSTALL_<dir>’ value.  If the value is not already an
     absolute path, an absolute path is constructed typically by
     prepending the value of the CMAKE_INSTALL_PREFIX.
     variable.  However, there are some special cases as
     documented below.

where ‘<dir>’ is one of:

‘BINDIR’

     user executables (‘bin’)

‘SBINDIR’

     system admin executables (‘sbin’)

‘LIBEXECDIR’

     program executables (‘libexec’)

‘SYSCONFDIR’

     read-only single-machine data (‘etc’)

‘SHAREDSTATEDIR’

     modifiable architecture-independent data (‘com’)

‘LOCALSTATEDIR’

     modifiable single-machine data (‘var’)

‘RUNSTATEDIR’

     run-time variable data (‘LOCALSTATEDIR/run’)

‘LIBDIR’

     object code libraries (‘lib’ or ‘lib64’ or ‘lib/<multiarch-tuple>’
     on Debian)

‘INCLUDEDIR’

     C header files (‘include’)

‘OLDINCLUDEDIR’

     C header files for non-gcc (‘/usr/include’)

‘DATAROOTDIR’

     read-only architecture-independent data root (‘share’)

‘DATADIR’

     read-only architecture-independent data (‘DATAROOTDIR’)

‘INFODIR’

     info documentation (‘DATAROOTDIR/info’)

‘LOCALEDIR’

     locale-dependent data (‘DATAROOTDIR/locale’)

‘MANDIR’

     man documentation (‘DATAROOTDIR/man’)

‘DOCDIR’

     documentation root (‘DATAROOTDIR/doc/PROJECT_NAME’)

If the includer does not define a value the above-shown default will be
used and the value will appear in the cache for editing by the user.

15.1.71.2 Special Cases
.......................

The following values of CMAKE_INSTALL_PREFIX are special:

‘/’

     For ‘<dir>’ other than the ‘SYSCONFDIR’, ‘LOCALSTATEDIR’ and
     ‘RUNSTATEDIR’, the value of ‘CMAKE_INSTALL_<dir>’ is prefixed with
     ‘usr/’ if it is not user-specified as an absolute path.  For
     example, the ‘INCLUDEDIR’ value ‘include’ becomes ‘usr/include’.
     This is required by the GNU Coding Standards(1), which state:

          When building the complete GNU system, the prefix will be
          empty and ‘/usr’ will be a symbolic link to ‘/’.

‘/usr’

     For ‘<dir>’ equal to ‘SYSCONFDIR’, ‘LOCALSTATEDIR’ or
     ‘RUNSTATEDIR’, the ‘CMAKE_INSTALL_FULL_<dir>’ is computed by
     prepending just ‘/’ to the value of ‘CMAKE_INSTALL_<dir>’ if it is
     not user-specified as an absolute path.  For example, the
     ‘SYSCONFDIR’ value ‘etc’ becomes ‘/etc’.  This is required by the
     GNU Coding Standards(2).

‘/opt/...’

     For ‘<dir>’ equal to ‘SYSCONFDIR’, ‘LOCALSTATEDIR’ or
     ‘RUNSTATEDIR’, the ‘CMAKE_INSTALL_FULL_<dir>’ is computed by
     `appending' the prefix to the value of ‘CMAKE_INSTALL_<dir>’ if it
     is not user-specified as an absolute path.  For example, the
     ‘SYSCONFDIR’ value ‘etc’ becomes ‘/etc/opt/...’.  This is defined
     by the Filesystem Hierarchy Standard(3).

   ---------- Footnotes ----------

   (1)
https://www.gnu.org/prep/standards/html_node/Directory-Variables.html

   (2)
https://www.gnu.org/prep/standards/html_node/Directory-Variables.html

   (3) https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html

15.1.71.3 Macros
................

 -- Command: GNUInstallDirs_get_absolute_install_dir

          GNUInstallDirs_get_absolute_install_dir(absvar var)

     Set the given variable ‘absvar’ to the absolute path contained
     within the variable ‘var’.  This is to allow the computation of an
     absolute path, accounting for all the special cases documented
     above.  While this macro is used to compute the various
     ‘CMAKE_INSTALL_FULL_<dir>’ variables, it is exposed publicly to
     allow users who create additional path variables to also compute
     absolute paths where necessary, using the same logic.

15.1.72 GoogleTest
------------------

New in version 3.9.

This module defines functions to help use the Google Test
infrastructure.  Two mechanisms for adding tests are provided.
gtest_add_tests() has been around for some time, originally via
‘find_package(GTest)’.  gtest_discover_tests() was
introduced in CMake 3.10.

The (older) gtest_add_tests() scans source files to identify
tests.  This is usually effective, with some caveats, including in
cross-compiling environments, and makes setting additional properties on
tests more convenient.  However, its handling of parameterized tests is
less comprehensive, and it requires re-running CMake to detect changes
to the list of tests.

The (newer) gtest_discover_tests() discovers tests by asking
the compiled test executable to enumerate its tests.  This is more
robust and provides better handling of parameterized tests, and does not
require CMake to be re-run when tests change.  However, it may not work
in a cross-compiling environment, and setting test properties is less
convenient.

More details can be found in the documentation of the respective
functions.

Both commands are intended to replace use of add_test() to
register tests, and will create a separate CTest test for each Google
Test test case.  Note that this is in some cases less efficient, as
common set-up and tear-down logic cannot be shared by multiple test
cases executing in the same instance.  However, it provides more
fine-grained pass/fail information to CTest, which is usually considered
as more beneficial.  By default, the CTest test name is the same as the
Google Test name (i.e.  ‘suite.testcase’); see also ‘TEST_PREFIX’ and
‘TEST_SUFFIX’.

 -- Command: gtest_add_tests

     Automatically add tests with CTest by scanning source code for
     Google Test macros:

          gtest_add_tests(TARGET target
                          [SOURCES src1...]
                          [EXTRA_ARGS arg1...]
                          [WORKING_DIRECTORY dir]
                          [TEST_PREFIX prefix]
                          [TEST_SUFFIX suffix]
                          [SKIP_DEPENDENCY]
                          [TEST_LIST outVar]
          )

     ‘gtest_add_tests’ attempts to identify tests by scanning source
     files.  Although this is generally effective, it uses only a basic
     regular expression match, which can be defeated by atypical test
     declarations, and is unable to fully “split” parameterized tests.
     Additionally, it requires that CMake be re-run to discover any
     newly added, removed or renamed tests (by default, this means that
     CMake is re-run when any test source file is changed, but see
     ‘SKIP_DEPENDENCY’).  However, it has the advantage of declaring
     tests at CMake time, which somewhat simplifies setting additional
     properties on tests, and always works in a cross-compiling
     environment.

     The options are:

     ‘TARGET target’

          Specifies the Google Test executable, which must be a known
          CMake executable target.  CMake will substitute the location
          of the built executable when running the test.

     ‘SOURCES src1...’

          When provided, only the listed files will be scanned for test
          cases.  If this option is not given, the SOURCES.
          property of the specified ‘target’ will be used to obtain the
          list of sources.

     ‘EXTRA_ARGS arg1...’

          Any extra arguments to pass on the command line to each test
          case.

     ‘WORKING_DIRECTORY dir’

          Specifies the directory in which to run the discovered test
          cases.  If this option is not provided, the current binary
          directory is used.

     ‘TEST_PREFIX prefix’

          Specifies a ‘prefix’ to be prepended to the name of each
          discovered test case.  This can be useful when the same source
          files are being used in multiple calls to ‘gtest_add_test()’
          but with different ‘EXTRA_ARGS’.

     ‘TEST_SUFFIX suffix’

          Similar to ‘TEST_PREFIX’ except the ‘suffix’ is appended to
          the name of every discovered test case.  Both ‘TEST_PREFIX’
          and ‘TEST_SUFFIX’ may be specified.

     ‘SKIP_DEPENDENCY’

          Normally, the function creates a dependency which will cause
          CMake to be re-run if any of the sources being scanned are
          changed.  This is to ensure that the list of discovered tests
          is updated.  If this behavior is not desired (as may be the
          case while actually writing the test cases), this option can
          be used to prevent the dependency from being added.

     ‘TEST_LIST outVar’

          The variable named by ‘outVar’ will be populated in the
          calling scope with the list of discovered test cases.  This
          allows the caller to do things like manipulate test properties
          of the discovered tests.

          include(GoogleTest)
          add_executable(FooTest FooUnitTest.cxx)
          gtest_add_tests(TARGET      FooTest
                          TEST_SUFFIX .noArgs
                          TEST_LIST   noArgsTests
          )
          gtest_add_tests(TARGET      FooTest
                          EXTRA_ARGS  --someArg someValue
                          TEST_SUFFIX .withArgs
                          TEST_LIST   withArgsTests
          )
          set_tests_properties(${noArgsTests}   PROPERTIES TIMEOUT 10)
          set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)

     For backward compatibility, the following form is also supported:

          gtest_add_tests(exe args files...)

     ‘exe’

          The path to the test executable or the name of a CMake target.

     ‘args’

          A ;-list of extra arguments to be passed to executable.  The
          entire list must be passed as a single argument.  Enclose it
          in quotes, or pass ‘""’ for no arguments.

     ‘files...’

          A list of source files to search for tests and test fixtures.
          Alternatively, use ‘AUTO’ to specify that ‘exe’ is the name of
          a CMake executable target whose sources should be scanned.

          include(GoogleTest)
          set(FooTestArgs --foo 1 --bar 2)
          add_executable(FooTest FooUnitTest.cxx)
          gtest_add_tests(FooTest "${FooTestArgs}" AUTO)

 -- Command: gtest_discover_tests

     Automatically add tests with CTest by querying the compiled test
     executable for available tests:

          gtest_discover_tests(target
                               [EXTRA_ARGS arg1...]
                               [WORKING_DIRECTORY dir]
                               [TEST_PREFIX prefix]
                               [TEST_SUFFIX suffix]
                               [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
                               [PROPERTIES name1 value1...]
                               [TEST_LIST var]
                               [DISCOVERY_TIMEOUT seconds]
                               [XML_OUTPUT_DIR dir]
                               [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
          )

     ‘gtest_discover_tests()’ sets up a post-build command on the test
     executable that generates the list of tests by parsing the output
     from running the test with the ‘--gtest_list_tests’ argument.
     Compared to the source parsing approach of gtest_add_tests(),
     this ensures that the full list of tests, including
     instantiations of parameterized tests, is obtained.  Since test
     discovery occurs at build time, it is not necessary to re-run CMake
     when the list of tests changes.  However, it requires that
     CROSSCOMPILING_EMULATOR is properly set in order to function
     in a cross-compiling environment.

     Additionally, setting properties on tests is somewhat less
     convenient, since the tests are not available at CMake time.
     Additional test properties may be assigned to the set of tests as a
     whole using the ‘PROPERTIES’ option.  If more fine-grained test
     control is needed, custom content may be provided through an
     external CTest script using the TEST_INCLUDE_FILES.
     directory property.  The set of discovered tests is made accessible
     to such a script via the ‘<target>_TESTS’ variable.

     The options are:

     ‘target’

          Specifies the Google Test executable, which must be a known
          CMake executable target.  CMake will substitute the location
          of the built executable when running the test.

     ‘EXTRA_ARGS arg1...’

          Any extra arguments to pass on the command line to each test
          case.

     ‘WORKING_DIRECTORY dir’

          Specifies the directory in which to run the discovered test
          cases.  If this option is not provided, the current binary
          directory is used.

     ‘TEST_PREFIX prefix’

          Specifies a ‘prefix’ to be prepended to the name of each
          discovered test case.  This can be useful when the same test
          executable is being used in multiple calls to
          ‘gtest_discover_tests()’ but with different ‘EXTRA_ARGS’.

     ‘TEST_SUFFIX suffix’

          Similar to ‘TEST_PREFIX’ except the ‘suffix’ is appended to
          the name of every discovered test case.  Both ‘TEST_PREFIX’
          and ‘TEST_SUFFIX’ may be specified.

     ‘NO_PRETTY_TYPES’

          By default, the type index of type-parameterized tests is
          replaced by the actual type name in the CTest test name.  If
          this behavior is undesirable (e.g.  because the type names are
          unwieldy), this option will suppress this behavior.

     ‘NO_PRETTY_VALUES’

          By default, the value index of value-parameterized tests is
          replaced by the actual value in the CTest test name.  If this
          behavior is undesirable (e.g.  because the value strings are
          unwieldy), this option will suppress this behavior.

     ‘PROPERTIES name1 value1...’

          Specifies additional properties to be set on all tests
          discovered by this invocation of ‘gtest_discover_tests()’.

     ‘TEST_LIST var’

          Make the list of tests available in the variable ‘var’, rather
          than the default ‘<target>_TESTS’.  This can be useful when
          the same test executable is being used in multiple calls to
          ‘gtest_discover_tests()’.  Note that this variable is only
          available in CTest.

     ‘DISCOVERY_TIMEOUT num’

          Specifies how long (in seconds) CMake will wait for the test
          to enumerate available tests.  If the test takes longer than
          this, discovery (and your build) will fail.  Most test
          executables will enumerate their tests very quickly, but under
          some exceptional circumstances, a test may require a longer
          timeout.  The default is 5.  See also the ‘TIMEOUT’ option of
          execute_process().

               Note: In CMake versions 3.10.1 and 3.10.2, this option
               was called ‘TIMEOUT’.  This clashed with the ‘TIMEOUT’
               test property, which is one of the common properties that
               would be set with the ‘PROPERTIES’ keyword, usually
               leading to legal but unintended behavior.  The keyword
               was changed to ‘DISCOVERY_TIMEOUT’ in CMake 3.10.3 to
               address this problem.  The ambiguous behavior of the
               ‘TIMEOUT’ keyword in 3.10.1 and 3.10.2 has not been
               preserved.

     ‘XML_OUTPUT_DIR dir’

          If specified, the parameter is passed along with
          ‘--gtest_output=xml:’ to test executable.  The actual file
          name is the same as the test target, including prefix and
          suffix.  This should be used instead of ‘EXTRA_ARGS
          --gtest_output=xml’ to avoid race conditions writing the XML
          result output when using parallel test execution.

     ‘DISCOVERY_MODE’

          Provides greater control over when ‘gtest_discover_tests()’
          performs test discovery.  By default, ‘POST_BUILD’ sets up a
          post-build command to perform test discovery at build time.
          In certain scenarios, like cross-compiling, this ‘POST_BUILD’
          behavior is not desirable.  By contrast, ‘PRE_TEST’ delays
          test discovery until just prior to test execution.  This way
          test discovery occurs in the target environment where the test
          has a better chance at finding appropriate runtime
          dependencies.

          ‘DISCOVERY_MODE’ defaults to the value of the
          ‘CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE’ variable if it is
          not passed when calling ‘gtest_discover_tests()’.  This
          provides a mechanism for globally selecting a preferred test
          discovery behavior without having to modify each call site.

15.1.73 InstallRequiredSystemLibraries
--------------------------------------

Include this module to search for compiler-provided system runtime
libraries and add install rules for them.  Some optional variables may
be set prior to including the module to adjust behavior:

‘CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS’

     Specify additional runtime libraries that may not be detected.
     After inclusion any detected libraries will be appended to this.

‘CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP’

     Set to TRUE to skip calling the install(PROGRAMS).
     command to allow the includer to specify its own install rule,
     using the value of ‘CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS’ to get the
     list of libraries.

‘CMAKE_INSTALL_DEBUG_LIBRARIES’

     Set to TRUE to install the debug runtime libraries when available
     with MSVC tools.

‘CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY’

     Set to TRUE to install only the debug runtime libraries with MSVC
     tools even if the release runtime libraries are also available.

‘CMAKE_INSTALL_UCRT_LIBRARIES’

     Set to TRUE to install the Windows Universal CRT libraries for
     app-local deployment (e.g.  to Windows XP). This is meaningful only
     with MSVC from Visual Studio 2015 or higher.

     One may set a ‘CMAKE_WINDOWS_KITS_10_DIR’ `environment variable' to
     an absolute path to tell CMake to look for Windows 10 SDKs in a
     custom location.  The specified directory is expected to contain
     ‘Redist/ucrt/DLLs/*’ directories.

‘CMAKE_INSTALL_MFC_LIBRARIES’

     Set to TRUE to install the MSVC MFC runtime libraries.

‘CMAKE_INSTALL_OPENMP_LIBRARIES’

     Set to TRUE to install the MSVC OpenMP runtime libraries

‘CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION’

     Specify the install(PROGRAMS) command ‘DESTINATION’
     option.  If not specified, the default is ‘bin’ on Windows and
     ‘lib’ elsewhere.

‘CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS’

     Set to TRUE to disable warnings about required library files that
     do not exist.  (For example, Visual Studio Express editions may not
     provide the redistributable files.)

‘CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT’

     Specify the install(PROGRAMS) command ‘COMPONENT’
     option.  If not specified, no such option will be used.

15.1.74 ProcessorCount
----------------------

ProcessorCount(var)

Determine the number of processors/cores and save value in ${var}

Sets the variable named ${var} to the number of physical cores available
on the machine if the information can be determined.  Otherwise it is
set to 0.  Currently this functionality is implemented for AIX, cygwin,
FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.

This function is guaranteed to return a positive integer (>=1) if it
succeeds.  It returns 0 if there’s a problem determining the processor
count.

Example use, in a ctest -S dashboard script:

     include(ProcessorCount)
     ProcessorCount(N)
     if(NOT N EQUAL 0)
       set(CTEST_BUILD_FLAGS -j${N})
       set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
     endif()

This function is intended to offer an approximation of the value of the
number of compute cores available on the current machine, such that you
may use that value for parallel building and parallel testing.  It is
meant to help utilize as much of the machine as seems reasonable.  Of
course, knowledge of what else might be running on the machine
simultaneously should be used when deciding whether to request a
machine’s full capacity all for yourself.

15.1.75 SelectLibraryConfigurations
-----------------------------------

     select_library_configurations(basename)

This macro takes a library base name as an argument, and will choose
good values for the variables

     basename_LIBRARY
     basename_LIBRARIES
     basename_LIBRARY_DEBUG
     basename_LIBRARY_RELEASE

depending on what has been found and set.

If only ‘basename_LIBRARY_RELEASE’ is defined, ‘basename_LIBRARY’ will
be set to the release value, and ‘basename_LIBRARY_DEBUG’ will be set to
‘basename_LIBRARY_DEBUG-NOTFOUND’.  If only ‘basename_LIBRARY_DEBUG’ is
defined, then ‘basename_LIBRARY’ will take the debug value, and
‘basename_LIBRARY_RELEASE’ will be set to
‘basename_LIBRARY_RELEASE-NOTFOUND’.

If the generator supports configuration types, then ‘basename_LIBRARY’
and ‘basename_LIBRARIES’ will be set with debug and optimized flags
specifying the library to be used for the given configuration.  If no
build type has been set or the generator in use does not support
configuration types, then ‘basename_LIBRARY’ and ‘basename_LIBRARIES’
will take only the release value, or the debug value if the release one
is not set.

15.1.76 SquishTestScript
------------------------

This script launches a GUI test using Squish.  You should not call the
script directly; instead, you should access it via the SQUISH_ADD_TEST
macro that is defined in FindSquish.cmake.

This script starts the Squish server, launches the test on the client,
and finally stops the squish server.  If any of these steps fail
(including if the tests do not pass) then a fatal error is raised.

15.1.77 TestBigEndian
---------------------

Define macro to determine endian type

Check if the system is big endian or little endian

     TEST_BIG_ENDIAN(VARIABLE)
     VARIABLE - variable to store the result to

15.1.78 TestForANSIForScope
---------------------------

Check for ANSI for scope support

Check if the compiler restricts the scope of variables declared in a
for-init-statement to the loop body.

     CMAKE_NO_ANSI_FOR_SCOPE - holds result

15.1.79 TestForANSIStreamHeaders
--------------------------------

Test for compiler support of ANSI stream headers iostream, etc.

check if the compiler supports the standard ANSI iostream header
(without the .h)

     CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results

15.1.80 TestForSSTREAM
----------------------

Test for compiler support of ANSI sstream header

check if the compiler supports the standard ANSI sstream header

     CMAKE_NO_ANSI_STRING_STREAM - defined by the results

15.1.81 TestForSTDNamespace
---------------------------

Test for std:: namespace support

check if the compiler supports std:: on stl classes

     CMAKE_NO_STD_NAMESPACE - defined by the results

15.1.82 UseEcos
---------------

This module defines variables and macros required to build eCos
application.

This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
- add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN )
- create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 … sourceN
) - adjusts the path of the source files and puts the result into VAR

Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
the ARM ELF toolchain for the directory where it is called
ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
PowerPC toolchain for the directory where it is called

It contains the following variables: ECOS_DEFINITIONS
ECOSCONFIG_EXECUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your
eCos configuration file has a different name, adjust this variable for
internal use only:

     ECOS_ADD_TARGET_LIB

15.1.83 UseJava
---------------

Use Module for Java

This file provides functions for Java.  It is assumed that
FindJava has already been loaded.  See FindJava for
information on how to load Java into your CMake project.

15.1.83.1 Creating And Installing JARs
......................................

     add_jar(<target_name>
             [SOURCES] <source1> [<source2>...] [<resource1>...]
             [INCLUDE_JARS <jar1> [<jar2>...]]
             [ENTRY_POINT <entry>]
             [VERSION <version>]
             [OUTPUT_NAME <name>]
             [OUTPUT_DIR <dir>]
             [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]]
             )

This command creates a ‘<target_name>.jar’.  It compiles the given
‘<source>’ files and adds the given ‘<resource>’ files to the jar file.
Source files can be java files or listing files (prefixed by ‘@’).  If
only resource files are given then just a jar file is created.  The list
of ‘INCLUDE_JARS’ are added to the classpath when compiling the java
sources and also to the dependencies of the target.  ‘INCLUDE_JARS’ also
accepts other target names created by ‘add_jar()’.  For backwards
compatibility, jar files listed as sources are ignored (as they have
been since the first version of this module).

The default ‘OUTPUT_DIR’ can also be changed by setting the variable
‘CMAKE_JAVA_TARGET_OUTPUT_DIR’.

Optionally, using option ‘GENERATE_NATIVE_HEADERS’, native header files
can be generated for methods declared as native.  These files provide
the connective glue that allow your Java and C code to interact.  An
INTERFACE target will be created for an easy usage of generated files.
Sub-option ‘DESTINATION’ can be used to specify the output directory for
generated header files.

‘GENERATE_NATIVE_HEADERS’ option requires, at least, version 1.8 of the
JDK.

The ‘add_jar()’ function sets the following target properties on
‘<target_name>’:

‘INSTALL_FILES’

     The files which should be installed.  This is used by
     ‘install_jar()’.

‘JNI_SYMLINK’

     The JNI symlink which should be installed.  This is used by
     ‘install_jni_symlink()’.

‘JAR_FILE’

     The location of the jar file so that you can include it.

‘CLASSDIR’

     The directory where the class files can be found.  For example to
     use them with ‘javah’.

     install_jar(<target_name> <destination>)
     install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])

This command installs the ‘<target_name>’ files to the given
‘<destination>’.  It should be called in the same scope as ‘add_jar()’
or it will fail.

The ‘install_jar()’ function sets the ‘INSTALL_DESTINATION’ target
property on jars so installed.  This property holds the ‘<destination>’
as described above, and is used by ‘install_jar_exports()’.  You can get
this information with get_property() and the
‘INSTALL_DESTINATION’ property key.

     install_jni_symlink(<target_name> <destination>)
     install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])

This command installs the ‘<target_name>’ JNI symlinks to the given
‘<destination>’.  It should be called in the same scope as ‘add_jar()’
or it will fail.

     install_jar_exports(TARGETS <jars>...
                         [NAMESPACE <namespace>]
                         FILE <filename>
                         DESTINATION <destination> [COMPONENT <component>])

This command installs a target export file ‘<filename>’ for the named
jar targets to the given ‘<destination>’ directory.  Its function is
similar to that of install(EXPORTS).

     export_jars(TARGETS <jars>...
                 [NAMESPACE <namespace>]
                 FILE <filename>)

This command writes a target export file ‘<filename>’ for the named
‘<jars>’ targets.  Its function is similar to that of export().

15.1.83.2 Examples
..................

To add compile flags to the target you can set these flags with the
following variable:

     set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)

To add a path or a jar file to the class path you can do this with the
‘CMAKE_JAVA_INCLUDE_PATH’ variable.

     set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)

To use a different output name for the target you can set it with:

     add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)

To use a different output directory than ‘CMAKE_CURRENT_BINARY_DIR’ you
can set it with:

     add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)

To define an entry point in your jar you can set it with the
‘ENTRY_POINT’ named argument:

     add_jar(example ENTRY_POINT com/examples/MyProject/Main)

To define a custom manifest for the jar, you can set it with the
‘MANIFEST’ named argument:

     add_jar(example MANIFEST /path/to/manifest)

To add a version to the target output name you can set it using the
‘VERSION’ named argument to ‘add_jar()’.  The following example will
create a jar file with the name ‘shibboleet-1.0.0.jar’ and will create a
symlink ‘shibboleet.jar’ pointing to the jar with the version
information.

     add_jar(shibboleet shibbotleet.java VERSION 1.2.0)

If the target is a JNI library, utilize the following commands to create
a JNI symbolic link:

     set(CMAKE_JNI_TARGET TRUE)
     add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
     install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
     install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})

If a single target needs to produce more than one jar from its java
source code, to prevent the accumulation of duplicate class files in
subsequent jars, set/reset ‘CMAKE_JAR_CLASSES_PREFIX’ prior to calling
the ‘add_jar()’ function:

     set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
     add_jar(foo foo.java)

     set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
     add_jar(bar bar.java)

For an optimum usage of option ‘GENERATE_NATIVE_HEADERS’, it is
recommended to include module JNI before any call to ‘add_jar()’.  The
produced target for native headers can then be used to compile C/C++
sources with the target_link_libraries() command.

     find_package(JNI)
     add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
     add_library(bar bar.cpp)
     target_link_libraries(bar PRIVATE foo-native)

15.1.83.3 Finding JARs
......................

     find_jar(<VAR>
              <name> | NAMES <name1> [<name2>...]
              [PATHS <path1> [<path2>... ENV <var>]]
              [VERSIONS <version1> [<version2>]]
              [DOC "cache documentation string"]
             )

This command is used to find a full path to the named jar.  A cache
entry named by ‘<VAR>’ is created to store the result of this command.
If the full path to a jar is found the result is stored in the variable
and the search will not repeated unless the variable is cleared.  If
nothing is found, the result will be ‘<VAR>-NOTFOUND’, and the search
will be attempted again next time ‘find_jar()’ is invoked with the same
variable.  The name of the full path to a file that is searched for is
specified by the names listed after ‘NAMES’ argument.  Additional search
locations can be specified after the ‘PATHS’ argument.  If you require
special a version of a jar file you can specify it with the ‘VERSIONS’
argument.  The argument after ‘DOC’ will be used for the documentation
string in the cache.

15.1.83.4 Javadoc
.................

The ‘create_javadoc()’ command can be used to create java documentation
based on files or packages.  For more details please read the javadoc
manpage.

There are two main signatures for ‘create_javadoc()’.  The first
signature works with package names on a path with source files.

     create_javadoc(<VAR>
                    PACKAGES <pkg1> [<pkg2>...]
                    [SOURCEPATH <sourcepath>]
                    [CLASSPATH <classpath>]
                    [INSTALLPATH <install path>]
                    [DOCTITLE "the documentation title"]
                    [WINDOWTITLE "the title of the document"]
                    [AUTHOR TRUE|FALSE]
                    [USE TRUE|FALSE]
                    [VERSION TRUE|FALSE]
                    )

For example:

     create_javadoc(my_example_doc
       PACKAGES com.example.foo com.example.bar
       SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
       CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
       WINDOWTITLE "My example"
       DOCTITLE "<h1>My example</h1>"
       AUTHOR TRUE
       USE TRUE
       VERSION TRUE
     )

The second signature for ‘create_javadoc()’ works on a given list of
files.

     create_javadoc(<VAR>
                    FILES <file1> [<file2>...]
                    [CLASSPATH <classpath>]
                    [INSTALLPATH <install path>]
                    [DOCTITLE "the documentation title"]
                    [WINDOWTITLE "the title of the document"]
                    [AUTHOR TRUE|FALSE]
                    [USE TRUE|FALSE]
                    [VERSION TRUE|FALSE]
                   )

For example:

     create_javadoc(my_example_doc
       FILES ${example_SRCS}
       CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
       WINDOWTITLE "My example"
       DOCTITLE "<h1>My example</h1>"
       AUTHOR TRUE
       USE TRUE
       VERSION TRUE
     )

Both signatures share most of the options.  These options are the same
as what you can find in the javadoc manpage.  Please look at the manpage
for ‘CLASSPATH’, ‘DOCTITLE’, ‘WINDOWTITLE’, ‘AUTHOR’, ‘USE’ and
‘VERSION’.

If you don’t set the ‘INSTALLPATH’, then by default the documentation
will be installed to :

     ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>

15.1.83.5 Header Generation
...........................

     create_javah(TARGET <target> | GENERATED_FILES <VAR>
                  CLASSES <class>...
                  [CLASSPATH <classpath>...]
                  [DEPENDS <depend>...]
                  [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
                  )

Create C header files from java classes.  These files provide the
connective glue that allow your Java and C code to interact.

Deprecated since version 3.11.

     Note: This command will no longer be supported starting with
     version 10 of the JDK due to the suppression of javah tool(1).  The
     ‘add_jar(GENERATE_NATIVE_HEADERS)’ command should be used instead.

There are two main signatures for ‘create_javah()’.  The first signature
returns generated files through variable specified by the
‘GENERATED_FILES’ option.  For example:

     create_javah(GENERATED_FILES files_headers
       CLASSES org.cmake.HelloWorld
       CLASSPATH hello.jar
     )

The second signature for ‘create_javah()’ creates a target which
encapsulates header files generation.  E.g.

     create_javah(TARGET target_headers
       CLASSES org.cmake.HelloWorld
       CLASSPATH hello.jar
     )

Both signatures share same options.

‘CLASSES <class>...’

     Specifies Java classes used to generate headers.

‘CLASSPATH <classpath>...’

     Specifies various paths to look up classes.  Here .class files, jar
     files or targets created by command add_jar can be used.

‘DEPENDS <depend>...’

     Targets on which the javah target depends.

‘OUTPUT_NAME <path>’

     Concatenates the resulting header files for all the classes listed
     by option ‘CLASSES’ into ‘<path>’.  Same behavior as option ‘-o’ of
     javah tool.

‘OUTPUT_DIR <path>’

     Sets the directory where the header files will be generated.  Same
     behavior as option ‘-d’ of javah tool.  If not specified, see
     CMAKE_CURRENT_BINARY_DIR is used as the output directory.

   ---------- Footnotes ----------

   (1) http://openjdk.java.net/jeps/313

15.1.84 UseJavaClassFilelist
----------------------------

This script create a list of compiled Java class files to be added to a
jar file.  This avoids including cmake files which get created in the
binary directory.

15.1.85 UseJavaSymlinks
-----------------------

Helper script for UseJava.cmake

15.1.86 UseSWIG
---------------

This file provides support for ‘SWIG’.  It is assumed that
FindSWIG module has already been loaded.

Defines the following command for use with ‘SWIG’:

 -- Command: swig_add_library

     Define swig module with given name and specified language:

          swig_add_library(<name>
                           [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
                           LANGUAGE <language>
                           [NO_PROXY]
                           [OUTPUT_DIR <directory>]
                           [OUTFILE_DIR <directory>]
                           SOURCES <file>...
                          )

     Targets created with the ‘swig_add_library’ command have the same
     capabilities as targets created with the add_library().
     command, so those targets can be used with any command expecting a
     target (e.g.  see target_link_libraries()).

          Note: This command creates a target with the specified
          ‘<name>’ when policy CMP0078 is set to ‘NEW’.
          Otherwise, the legacy behavior will choose a different target
          name and store it in the ‘SWIG_MODULE_<name>_REAL_NAME’
          variable.

          Note: For multi-config generators, this module does not
          support configuration-specific files generated by ‘SWIG’.  All
          build configurations must result in the same generated source
          file.

          Note: For Make-based generators, ‘swig_add_library’ does not
          track file dependencies, so depending on the
          ‘<name>_swig_compilation’ custom target is required for
          targets which require the ‘swig’-generated files to exist.
          Other generators may depend on the source files that would be
          generated by SWIG.

     ‘TYPE’

          ‘SHARED’, ‘MODULE’ and ‘STATIC’ have the same semantic as for
          the add_library() command.  If
          ‘USE_BUILD_SHARED_LIBS’ is specified, the library type will be
          ‘STATIC’ or ‘SHARED’ based on whether the current value of the
          BUILD_SHARED_LIBS variable is ‘ON’.  If no type is
          specified, ‘MODULE’ will be used.

     ‘LANGUAGE’

          Specify the target language.

     ‘NO_PROXY’

          Prevent the generation of the wrapper layer (swig ‘-noproxy’
          option).

     ‘OUTPUT_DIR’

          Specify where to write the language specific files (swig
          ‘-outdir’ option).  If not given, the ‘CMAKE_SWIG_OUTDIR’
          variable will be used.  If neither is specified, the default
          depends on the value of the ‘UseSWIG_MODULE_VERSION’ variable
          as follows:

             * If ‘UseSWIG_MODULE_VERSION’ is 1 or is undefined, output
               is written to the CMAKE_CURRENT_BINARY_DIR.
               directory.

             * If ‘UseSWIG_MODULE_VERSION’ is 2, a dedicated directory
               will be used.  The path of this directory can be
               retrieved from the ‘SWIG_SUPPORT_FILES_DIRECTORY’ target
               property.

     ‘OUTFILE_DIR’

          Specify an output directory name where the generated source
          file will be placed (swig ‘-o’ option).  If not specified, the
          ‘SWIG_OUTFILE_DIR’ variable will be used.  If neither is
          specified, ‘OUTPUT_DIR’ or ‘CMAKE_SWIG_OUTDIR’ is used
          instead.

     ‘SOURCES’

          List of sources for the library.  Files with extension ‘.i’
          will be identified as sources for the ‘SWIG’ tool.  Other
          files will be handled in the standard way.  This behavior can
          be overridden by specifying the variable
          ‘SWIG_SOURCE_FILE_EXTENSIONS’.

          Note: If ‘UseSWIG_MODULE_VERSION’ is set to 2, it is
          `strongly' recommended to use a dedicated directory unique to
          the target when either the ‘OUTPUT_DIR’ option or the
          ‘CMAKE_SWIG_OUTDIR’ variable are specified.  The output
          directory contents are erased as part of the target build, so
          to prevent interference between targets or losing other
          important files, each target should have its own dedicated
          output directory.

 -- Command: swig_link_libraries

     Link libraries to swig module:

          swig_link_libraries(<name> <item>...)

     This command has same capabilities as
     target_link_libraries() command.

          Note: If variable ‘UseSWIG_TARGET_NAME_PREFERENCE’ is set to
          ‘STANDARD’, this command is deprecated and
          target_link_libraries() command must be used instead.

Source file properties on module files `must' be set before the
invocation of the ‘swig_add_library’ command to specify special behavior
of SWIG and ensure generated files will receive the required settings.

‘CPLUSPLUS’

     Call SWIG in c++ mode.  For example:

          set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
          swig_add_library(mymod LANGUAGE python SOURCES mymod.i)

‘INCLUDE_DIRECTORIES’, ‘COMPILE_DEFINITIONS’ and ‘COMPILE_OPTIONS’

     Add custom flags to SWIG compiler and have same semantic as
     properties INCLUDE_DIRECTORIES,
     COMPILE_DEFINITIONS and COMPILE_OPTIONS.

‘USE_TARGET_INCLUDE_DIRECTORIES’

     If set to ‘TRUE’, contents of target property
     INCLUDE_DIRECTORIES will be forwarded to ‘SWIG’ compiler.  If
     set to ‘FALSE’ target property INCLUDE_DIRECTORIES will
     be ignored.  If not set, target property
     ‘SWIG_USE_TARGET_INCLUDE_DIRECTORIES’ will be considered.

‘GENERATED_INCLUDE_DIRECTORIES’, ‘GENERATED_COMPILE_DEFINITIONS’ and ‘GENERATED_COMPILE_OPTIONS’

     Add custom flags to the C/C++ generated source.  They will fill,
     respectively, properties INCLUDE_DIRECTORIES,
     COMPILE_DEFINITIONS and COMPILE_OPTIONS of
     generated C/C++ file.

‘DEPENDS’

     Specify additional dependencies to the source file.

‘SWIG_MODULE_NAME’

     Specify the actual import name of the module in the target
     language.  This is required if it cannot be scanned automatically
     from source or different from the module file basename.  For
     example:

          set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)

          Note: If policy CMP0086 is set to ‘NEW’, ‘-module
          <module_name>’ is passed to ‘SWIG’ compiler.

‘OUTPUT_DIR’

     Specify where to write the language specific files (swig ‘-outdir’
     option) for the considered source file.  If not specified, the
     other ways to define the output directory applies (see ‘OUTPUT_DIR’
     option of ‘swig_add_library()’ command).

‘OUTFILE_DIR’

     Specify an output directory where the generated source file will be
     placed (swig ‘-o’ option) for the considered source file.  If not
     specified, ‘OUTPUT_DIR’ source property will be used.  If neither
     are specified, the other ways to define output file directory
     applies (see ‘OUTFILE_DIR’ option of ‘swig_add_library()’ command).

Target library properties can be set to apply same configuration to all
SWIG input files.

‘SWIG_INCLUDE_DIRECTORIES’, ‘SWIG_COMPILE_DEFINITIONS’ and ‘SWIG_COMPILE_OPTIONS’

     These properties will be applied to all SWIG input files and have
     same semantic as target properties INCLUDE_DIRECTORIES,
     COMPILE_DEFINITIONS and COMPILE_OPTIONS.

          set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
          swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
          set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
          set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)

‘SWIG_USE_TARGET_INCLUDE_DIRECTORIES’

     If set to ‘TRUE’, contents of target property
     INCLUDE_DIRECTORIES will be forwarded to ‘SWIG’ compiler.  If
     set to ‘FALSE’ or not defined, target property
     INCLUDE_DIRECTORIES will be ignored.  This behavior can be
     overridden by specifying source property
     ‘USE_TARGET_INCLUDE_DIRECTORIES’.

‘SWIG_GENERATED_INCLUDE_DIRECTORIES’, ‘SWIG_GENERATED_COMPILE_DEFINITIONS’ and ‘SWIG_GENERATED_COMPILE_OPTIONS’

     These properties will populate, respectively, properties
     INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and
     COMPILE_FLAGS of all generated C/C++ files.

‘SWIG_DEPENDS’

     Add dependencies to all SWIG input files.

The following target properties are output properties and can be used to
get information about support files generated by ‘SWIG’ interface
compilation.

‘SWIG_SUPPORT_FILES’

     This output property list of wrapper files generated during SWIG
     compilation.

          set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
          swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
          get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)

          Note: Only most principal support files are listed.  In case
          some advanced features of ‘SWIG’ are used (for example
          ‘%template’), associated support files may not be listed.
          Prefer to use the ‘SWIG_SUPPORT_FILES_DIRECTORY’ property to
          handle support files.

‘SWIG_SUPPORT_FILES_DIRECTORY’

     This output property specifies the directory where support files
     will be generated.

          Note: When source property ‘OUTPUT_DIR’ is defined, multiple
          directories can be specified as part of
          ‘SWIG_SUPPORT_FILES_DIRECTORY’.

Some variables can be set to customize the behavior of
‘swig_add_library’ as well as ‘SWIG’:

‘UseSWIG_MODULE_VERSION’

     Specify different behaviors for ‘UseSWIG’ module.

        * Set to 1 or undefined: Legacy behavior is applied.

        * Set to 2: A new strategy is applied regarding support files:
          the output directory of support files is erased before ‘SWIG’
          interface compilation.

‘CMAKE_SWIG_FLAGS’

     Add flags to all swig calls.

‘CMAKE_SWIG_OUTDIR’

     Specify where to write the language specific files (swig ‘-outdir’
     option).

‘SWIG_OUTFILE_DIR’

     Specify an output directory name where the generated source file
     will be placed.  If not specified, ‘CMAKE_SWIG_OUTDIR’ is used.

‘SWIG_MODULE_<name>_EXTRA_DEPS’

     Specify extra dependencies for the generated module for ‘<name>’.

‘SWIG_SOURCE_FILE_EXTENSIONS’

     Specify a list of source file extensions to override the default
     behavior of considering only ‘.i’ files as sources for the ‘SWIG’
     tool.  For example:

          set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")

15.1.87 UsewxWidgets
--------------------

Convenience include for using wxWidgets library.

Determines if wxWidgets was FOUND and sets the appropriate libs,
incdirs, flags, etc.  INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
called.

USAGE

     # Note that for MinGW users the order of libs is important!
     find_package(wxWidgets REQUIRED net gl core base)
     include(${wxWidgets_USE_FILE})
     # and for each of your dependent executable/library targets:
     target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})

DEPRECATED

     LINK_LIBRARIES is not called in favor of adding dependencies per target.

AUTHOR

     Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>

15.1.88 WriteCompilerDetectionHeader
------------------------------------

New in version 3.1.

This module provides the function ‘write_compiler_detection_header()’.

This function can be used to generate a file suitable for preprocessor
inclusion which contains macros to be used in source code:

     write_compiler_detection_header(
               FILE <file>
               PREFIX <prefix>
               [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
               COMPILERS <compiler> [...]
               FEATURES <feature> [...]
               [BARE_FEATURES <feature> [...]]
               [VERSION <version>]
               [PROLOG <prolog>]
               [EPILOG <epilog>]
               [ALLOW_UNKNOWN_COMPILERS]
               [ALLOW_UNKNOWN_COMPILER_VERSIONS]
     )

This generates the file ‘<file>’ with macros which all have the prefix
‘<prefix>’.

By default, all content is written directly to the ‘<file>’.  The
‘OUTPUT_FILES_VAR’ may be specified to cause the compiler-specific
content to be written to separate files.  The separate files are then
available in the ‘<output_files_var>’ and may be consumed by the caller
for installation for example.  The ‘OUTPUT_DIR’ specifies a relative
path from the main ‘<file>’ to the compiler-specific files.  For
example:

     write_compiler_detection_header(
       FILE climbingstats_compiler_detection.h
       PREFIX ClimbingStats
       OUTPUT_FILES_VAR support_files
       OUTPUT_DIR compilers
       COMPILERS GNU Clang MSVC Intel
       FEATURES cxx_variadic_templates
     )
     install(FILES
       ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
       DESTINATION include
     )
     install(FILES
       ${support_files}
       DESTINATION include/compilers
     )

‘VERSION’ may be used to specify the API version to be generated.
Future versions of CMake may introduce alternative APIs.  A given API is
selected by any ‘<version>’ value greater than or equal to the version
of CMake that introduced the given API and less than the version of
CMake that introduced its succeeding API. The value of the
CMAKE_MINIMUM_REQUIRED_VERSION variable is used if no explicit
version is specified.  (As of CMake version 3.19.2 there is only one API
version.)

‘PROLOG’ may be specified as text content to write at the start of the
header.  ‘EPILOG’ may be specified as text content to write at the end
of the header

At least one ‘<compiler>’ and one ‘<feature>’ must be listed.  Compilers
which are known to CMake, but not specified are detected and a
preprocessor ‘#error’ is generated for them.  A preprocessor macro
matching ‘<PREFIX>_COMPILER_IS_<compiler>’ is generated for each
compiler known to CMake to contain the value ‘0’ or ‘1’.

Possible compiler identifiers are documented with the
CMAKE_<LANG>_COMPILER_ID variable.  Available features in this
version of CMake are listed in the CMAKE_C_KNOWN_FEATURES.
and CMAKE_CXX_KNOWN_FEATURES global properties.  The
‘{c,cxx}_std_*’ meta-features are ignored if requested.

See the cmake-compile-features(7) manual for information on
compile features.

‘BARE_FEATURES’ will define the compatibility macros with the name used
in newer versions of the language standard, so the code can use the new
feature name unconditionally.

‘ALLOW_UNKNOWN_COMPILERS’ and ‘ALLOW_UNKNOWN_COMPILER_VERSIONS’ cause
the module to generate conditions that treat unknown compilers as simply
lacking all features.  Without these options the default behavior is to
generate a ‘#error’ for unknown compilers and versions.

15.1.88.1 Feature Test Macros
.............................

For each compiler, a preprocessor macro is generated matching
‘<PREFIX>_COMPILER_IS_<compiler>’ which has the content either ‘0’ or
‘1’, depending on the compiler in use.  Preprocessor macros for compiler
version components are generated matching
‘<PREFIX>_COMPILER_VERSION_MAJOR’ ‘<PREFIX>_COMPILER_VERSION_MINOR’ and
‘<PREFIX>_COMPILER_VERSION_PATCH’ containing decimal values for the
corresponding compiler version components, if defined.

A preprocessor test is generated based on the compiler version denoting
whether each feature is enabled.  A preprocessor macro matching
‘<PREFIX>_COMPILER_<FEATURE>’, where ‘<FEATURE>’ is the upper-case
‘<feature>’ name, is generated to contain the value ‘0’ or ‘1’ depending
on whether the compiler in use supports the feature:

     write_compiler_detection_header(
       FILE climbingstats_compiler_detection.h
       PREFIX ClimbingStats
       COMPILERS GNU Clang AppleClang MSVC Intel
       FEATURES cxx_variadic_templates
     )

     #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
     template<typename... T>
     void someInterface(T t...) { /* ... */ }
     #else
     // Compatibility versions
     template<typename T1>
     void someInterface(T1 t1) { /* ... */ }
     template<typename T1, typename T2>
     void someInterface(T1 t1, T2 t2) { /* ... */ }
     template<typename T1, typename T2, typename T3>
     void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
     #endif

15.1.88.2 Symbol Macros
.......................

Some additional symbol-defines are created for particular features for
use as symbols which may be conditionally defined empty:

     class MyClass ClimbingStats_FINAL
     {
         ClimbingStats_CONSTEXPR int someInterface() { return 42; }
     };

The ‘ClimbingStats_FINAL’ macro will expand to ‘final’ if the compiler
(and its flags) support the ‘cxx_final’ feature, and the
‘ClimbingStats_CONSTEXPR’ macro will expand to ‘constexpr’ if
‘cxx_constexpr’ is supported.

If ‘BARE_FEATURES cxx_final’ was given as argument the ‘final’ keyword
will be defined for old compilers, too.

The following features generate corresponding symbol defines and if they
are available as ‘BARE_FEATURES’:

Feature                        Define                                  Symbol                bare

--------------------------------------------------------------------------------------------------------

‘c_restrict’                   ‘<PREFIX>_RESTRICT’                     ‘restrict’            yes

‘cxx_constexpr’                ‘<PREFIX>_CONSTEXPR’                    ‘constexpr’           yes

‘cxx_deleted_functions’        ‘<PREFIX>_DELETED_FUNCTION’             ‘= delete’

‘cxx_extern_templates’         ‘<PREFIX>_EXTERN_TEMPLATE’              ‘extern’

‘cxx_final’                    ‘<PREFIX>_FINAL’                        ‘final’               yes

‘cxx_noexcept’                 ‘<PREFIX>_NOEXCEPT’                     ‘noexcept’            yes

‘cxx_noexcept’                 ‘<PREFIX>_NOEXCEPT_EXPR(X)’             ‘noexcept(X)’

‘cxx_override’                 ‘<PREFIX>_OVERRIDE’                     ‘override’            yes

15.1.88.3 Compatibility Implementation Macros
.............................................

Some features are suitable for wrapping in a macro with a backward
compatibility implementation if the compiler does not support the
feature.

When the ‘cxx_static_assert’ feature is not provided by the compiler, a
compatibility implementation is available via the
‘<PREFIX>_STATIC_ASSERT(COND)’ and ‘<PREFIX>_STATIC_ASSERT_MSG(COND,
MSG)’ function-like macros.  The macros expand to ‘static_assert’ where
that compiler feature is available, and to a compatibility
implementation otherwise.  In the first form, the condition is
stringified in the message field of ‘static_assert’.  In the second
form, the message ‘MSG’ is passed to the message field of
‘static_assert’, or ignored if using the backward compatibility
implementation.

The ‘cxx_attribute_deprecated’ feature provides a macro definition
‘<PREFIX>_DEPRECATED’, which expands to either the standard
‘[[deprecated]]’ attribute or a compiler-specific decorator such as
‘__attribute__((__deprecated__))’ used by GNU compilers.

The ‘cxx_alignas’ feature provides a macro definition ‘<PREFIX>_ALIGNAS’
which expands to either the standard ‘alignas’ decorator or a
compiler-specific decorator such as ‘__attribute__ ((__aligned__))’ used
by GNU compilers.

The ‘cxx_alignof’ feature provides a macro definition ‘<PREFIX>_ALIGNOF’
which expands to either the standard ‘alignof’ decorator or a
compiler-specific decorator such as ‘__alignof__’ used by GNU compilers.

Feature                           Define                               Symbol                    bare

------------------------------------------------------------------------------------------------------------

‘cxx_alignas’                     ‘<PREFIX>_ALIGNAS’                   ‘alignas’

‘cxx_alignof’                     ‘<PREFIX>_ALIGNOF’                   ‘alignof’

‘cxx_nullptr’                     ‘<PREFIX>_NULLPTR’                   ‘nullptr’                 yes

‘cxx_static_assert’               ‘<PREFIX>_STATIC_ASSERT’             ‘static_assert’

‘cxx_static_assert’               ‘<PREFIX>_STATIC_ASSERT_MSG’         ‘static_assert’

‘cxx_attribute_deprecated’        ‘<PREFIX>_DEPRECATED’                ‘[[deprecated]]’

‘cxx_attribute_deprecated’        ‘<PREFIX>_DEPRECATED_MSG’            ‘[[deprecated]]’

‘cxx_thread_local’                ‘<PREFIX>_THREAD_LOCAL’              ‘thread_local’

A use-case which arises with such deprecation macros is the deprecation
of an entire library.  In that case, all public API in the library may
be decorated with the ‘<PREFIX>_DEPRECATED’ macro.  This results in very
noisy build output when building the library itself, so the macro may be
may be defined to empty in that case when building the deprecated
library:

     add_library(compat_support ${srcs})
     target_compile_definitions(compat_support
       PRIVATE
         CompatSupport_DEPRECATED=
     )

15.2 Find Modules
=================

These modules search for third-party software.  They are normally called
through the find_package() command.

15.2.1 FindALSA
---------------

Find Advanced Linux Sound Architecture (ALSA)

Find the alsa libraries (‘asound’)

15.2.1.1 IMPORTED Targets
.........................

This module defines IMPORTED target ‘ALSA::ALSA’, if ALSA
has been found.

15.2.1.2 Result Variables
.........................

This module defines the following variables:

‘ALSA_FOUND’

     True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found

‘ALSA_LIBRARIES’

     List of libraries when using ALSA.

‘ALSA_INCLUDE_DIRS’

     Where to find the ALSA headers.

15.2.1.3 Cache variables
........................

The following cache variables may also be set:

‘ALSA_INCLUDE_DIR’

     the ALSA include directory

‘ALSA_LIBRARY’

     the absolute path of the asound library

15.2.2 FindArmadillo
--------------------

Find the Armadillo C++ library.  Armadillo is a library for linear
algebra & scientific computing.

Using Armadillo:

     find_package(Armadillo REQUIRED)
     include_directories(${ARMADILLO_INCLUDE_DIRS})
     add_executable(foo foo.cc)
     target_link_libraries(foo ${ARMADILLO_LIBRARIES})

This module sets the following variables:

     ARMADILLO_FOUND - set to true if the library is found
     ARMADILLO_INCLUDE_DIRS - list of required include directories
     ARMADILLO_LIBRARIES - list of libraries to be linked
     ARMADILLO_VERSION_MAJOR - major version number
     ARMADILLO_VERSION_MINOR - minor version number
     ARMADILLO_VERSION_PATCH - patch version number
     ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
     ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")

15.2.3 FindASPELL
-----------------

Try to find ASPELL

Once done this will define

     ASPELL_FOUND - system has ASPELL
     ASPELL_EXECUTABLE - the ASPELL executable
     ASPELL_INCLUDE_DIR - the ASPELL include directory
     ASPELL_LIBRARIES - The libraries needed to use ASPELL
     ASPELL_DEFINITIONS - Compiler switches required for using ASPELL

15.2.4 FindAVIFile
------------------

Locate AVIFILE library and include paths

AVIFILE (‘http://avifile.sourceforge.net/’) is a set of libraries for
i386 machines to use various AVI codecs.  Support is limited beyond
Linux.  Windows provides native AVI support, and so doesn’t need this
library.  This module defines

     AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
     AVIFILE_LIBRARIES, the libraries to link against
     AVIFILE_DEFINITIONS, definitions to use when compiling
     AVIFILE_FOUND, If false, don't try to use AVIFILE

15.2.5 FindBacktrace
--------------------

Find provider for backtrace(3)(1).

Checks if OS supports ‘backtrace(3)’ via either ‘libc’ or custom
library.  This module defines the following variables:

‘Backtrace_HEADER’

     The header file needed for ‘backtrace(3)’.  Cached.  Could be
     forcibly set by user.

‘Backtrace_INCLUDE_DIRS’

     The include directories needed to use ‘backtrace(3)’ header.

‘Backtrace_LIBRARIES’

     The libraries (linker flags) needed to use ‘backtrace(3)’, if any.

‘Backtrace_FOUND’

     Is set if and only if ‘backtrace(3)’ support detected.

The following cache variables are also available to set or use:

‘Backtrace_LIBRARY’

     The external library providing backtrace, if any.

‘Backtrace_INCLUDE_DIR’

     The directory holding the ‘backtrace(3)’ header.

Typical usage is to generate of header file using
configure_file() with the contents like the following:

     #cmakedefine01 Backtrace_FOUND
     #if Backtrace_FOUND
     # include <${Backtrace_HEADER}>
     #endif

And then reference that generated header file in actual source.

   ---------- Footnotes ----------

   (1) http://man7.org/linux/man-pages/man3/backtrace.3.html

15.2.6 FindBISON
----------------

Find ‘bison’ executable and provide a macro to generate custom build
rules.

The module defines the following variables:

‘BISON_EXECUTABLE’

     path to the ‘bison’ program

‘BISON_VERSION’

     version of ‘bison’

‘BISON_FOUND’

     “True” if the program was found

The minimum required version of ‘bison’ can be specified using the
standard CMake syntax, e.g.  see find_package(BISON 2.1.3).

If ‘bison’ is found, the module defines the macro:

     BISON_TARGET(<Name> <YaccInput> <CodeOutput>
                  [COMPILE_FLAGS <flags>]
                  [DEFINES_FILE <file>]
                  [VERBOSE [<file>]]
                  [REPORT_FILE <file>]
                  )

which will create a custom rule to generate a parser.  ‘<YaccInput>’ is
the path to a yacc file.  ‘<CodeOutput>’ is the name of the source file
generated by bison.  A header file is also be generated, and contains
the token list.

The options are:

‘COMPILE_FLAGS <flags>’

     Specify flags to be added to the ‘bison’ command line.

‘DEFINES_FILE <file>’

     Specify a non-default header ‘<file>’ to be generated by ‘bison’.

‘VERBOSE [<file>]’

     Tell ‘bison’ to write a report file of the grammar and parser.  If
     ‘<file>’ is given, it specifies path the report file is copied to.
     ‘[<file>]’ is left for backward compatibility of this module.  Use
     ‘VERBOSE REPORT_FILE <file>’.

‘REPORT_FILE <file>’

     Specify a non-default report ‘<file>’, if generated.

The macro defines the following variables:

‘BISON_<Name>_DEFINED’

     ‘True’ is the macro ran successfully

‘BISON_<Name>_INPUT’

     The input source file, an alias for <YaccInput>

‘BISON_<Name>_OUTPUT_SOURCE’

     The source file generated by bison

‘BISON_<Name>_OUTPUT_HEADER’

     The header file generated by bison

‘BISON_<Name>_OUTPUTS’

     All files generated by bison including the source, the header and
     the report

‘BISON_<Name>_COMPILE_FLAGS’

     Options used in the ‘bison’ command line

Example usage:

     find_package(BISON)
     BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
                  DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
     add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})

15.2.7 FindBLAS
---------------

Find Basic Linear Algebra Subprograms (BLAS) library

This module finds an installed Fortran library that implements the BLAS
linear-algebra interface (see ‘http://www.netlib.org/blas/’).

The approach follows that taken for the ‘autoconf’ macro file,
‘acx_blas.m4’ (distributed at
‘http://ac-archive.sourceforge.net/ac-archive/acx_blas.html’).

15.2.7.1 Input Variables
........................

The following variables may be set to influence this module’s behavior:

‘BLA_STATIC’

     if ‘ON’ use static linkage

‘BLA_VENDOR’

     If set, checks only the specified vendor, if not set checks all the
     possibilities.  List of vendors valid in this module:

        * ‘Goto’

        * ‘FlexiBLAS’

        * ‘OpenBLAS’

        * ‘FLAME’

        * ‘ATLAS PhiPACK’

        * ‘CXML’

        * ‘DXML’

        * ‘SunPerf’

        * ‘SCSL’

        * ‘SGIMATH’

        * ‘IBMESSL’

        * ‘Intel10_32’ (intel mkl v10 32 bit, threaded code)

        * ‘Intel10_64lp’ (intel mkl v10+ 64 bit, threaded code, lp64
          model)

        * ‘Intel10_64lp_seq’ (intel mkl v10+ 64 bit, sequential code,
          lp64 model)

        * ‘Intel10_64ilp’ (intel mkl v10+ 64 bit, threaded code, ilp64
          model)

        * ‘Intel10_64ilp_seq’ (intel mkl v10+ 64 bit, sequential code,
          ilp64 model)

        * ‘Intel10_64_dyn’ (intel mkl v10+ 64 bit, single dynamic
          library)

        * ‘Intel’ (obsolete versions of mkl 32 and 64 bit)

        * ‘ACML’

        * ‘ACML_MP’

        * ‘ACML_GPU’

        * ‘Apple’

        * ‘NAS’

        * ‘Arm’

        * ‘Arm_mp’

        * ‘Arm_ilp64’

        * ‘Arm_ilp64_mp’

        * ‘Generic’

‘BLA_F95’

     if ‘ON’ tries to find the BLAS95 interfaces

‘BLA_PREFER_PKGCONFIG’

     if set ‘pkg-config’ will be used to search for a BLAS library first
     and if one is found that is preferred

15.2.7.2 Imported targets
.........................

This module defines the following IMPORTED target:

‘BLAS::BLAS’

     The libraries to use for BLAS, if found.

15.2.7.3 Result Variables
.........................

This module defines the following variables:

‘BLAS_FOUND’

     library implementing the BLAS interface is found

‘BLAS_LINKER_FLAGS’

     uncached list of required linker flags (excluding ‘-l’ and ‘-L’).

‘BLAS_LIBRARIES’

     uncached list of libraries (using full path name) to link against
     to use BLAS (may be empty if compiler implicitly links BLAS)

‘BLAS95_LIBRARIES’

     uncached list of libraries (using full path name) to link against
     to use BLAS95 interface

‘BLAS95_FOUND’

     library implementing the BLAS95 interface is found

     Note: C, CXX or Fortran must be enabled to detect a BLAS library.
     C or CXX must be enabled to use Intel Math Kernel Library (MKL).

     For example, to use Intel MKL libraries and/or Intel compiler:

          set(BLA_VENDOR Intel10_64lp)
          find_package(BLAS)

15.2.7.4 Hints
..............

Set the ‘MKLROOT’ environment variable to a directory that contains an
MKL installation, or add the directory to the dynamic library loader
environment variable for your platform (‘LIB’, ‘DYLD_LIBRARY_PATH’ or
‘LD_LIBRARY_PATH’).

15.2.8 FindBoost
----------------

Find Boost include dirs and libraries

Use this module by invoking find_package with the form:

     find_package(Boost
       [version] [EXACT]      # Minimum or EXACT version e.g. 1.67.0
       [REQUIRED]             # Fail with error if Boost is not found
       [COMPONENTS <libs>...] # Boost libraries by their canonical name
                              # e.g. "date_time" for "libboost_date_time"
       [OPTIONAL_COMPONENTS <libs>...]
                              # Optional Boost libraries by their canonical name)
       )                      # e.g. "date_time" for "libboost_date_time"

This module finds headers and requested component libraries OR a CMake
package configuration file provided by a “Boost CMake” build.  For the
latter case skip to the “Boost CMake” section below.  For the former
case results are reported in variables:

     Boost_FOUND            - True if headers and requested libraries were found
     Boost_INCLUDE_DIRS     - Boost include directories
     Boost_LIBRARY_DIRS     - Link directories for Boost libraries
     Boost_LIBRARIES        - Boost component libraries to be linked
     Boost_<C>_FOUND        - True if component <C> was found (<C> is upper-case)
     Boost_<C>_LIBRARY      - Libraries to link for component <C> (may include
                              target_link_libraries debug/optimized keywords)
     Boost_VERSION_MACRO    - BOOST_VERSION value from boost/version.hpp
     Boost_VERSION_STRING   - Boost version number in x.y.z format
     Boost_VERSION          - if CMP0093 NEW => same as Boost_VERSION_STRING
                              if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
     Boost_LIB_VERSION      - Version string appended to library filenames
     Boost_VERSION_MAJOR    - Boost major version number (X in X.y.z)
                              alias: Boost_MAJOR_VERSION
     Boost_VERSION_MINOR    - Boost minor version number (Y in x.Y.z)
                              alias: Boost_MINOR_VERSION
     Boost_VERSION_PATCH    - Boost subminor version number (Z in x.y.Z)
                              alias: Boost_SUBMINOR_VERSION
     Boost_VERSION_COUNT    - Amount of version components (3)
     Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
                            - Pass to add_definitions() to have diagnostic
                              information about Boost's automatic linking
                              displayed during compilation

Note that Boost Python components require a Python version suffix (Boost
1.67 and later), e.g.  ‘python36’ or ‘python27’ for the versions built
against Python 3.6 and 2.7, respectively.  This also applies to
additional components using Python including ‘mpi_python’ and ‘numpy’.
Earlier Boost releases may use distribution-specific suffixes such as
‘2’, ‘3’ or ‘2.7’.  These may also be used as suffixes, but note that
they are not portable.

This module reads hints about search locations from variables:

     BOOST_ROOT             - Preferred installation prefix
      (or BOOSTROOT)
     BOOST_INCLUDEDIR       - Preferred include directory e.g. <prefix>/include
     BOOST_LIBRARYDIR       - Preferred library directory e.g. <prefix>/lib
     Boost_NO_SYSTEM_PATHS  - Set to ON to disable searching in locations not
                              specified by these hint variables. Default is OFF.
     Boost_ADDITIONAL_VERSIONS
                            - List of Boost versions not known to this module
                              (Boost install locations may contain the version)

and saves search results persistently in CMake cache entries:

     Boost_INCLUDE_DIR         - Directory containing Boost headers
     Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
     Boost_LIBRARY_DIR_DEBUG   - Directory containing debug Boost libraries
     Boost_<C>_LIBRARY_DEBUG   - Component <C> library debug variant
     Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant

The following IMPORTED targets are also defined:

     Boost::headers                - Target for header-only dependencies
                                     (Boost include directory)
                                     alias: Boost::boost
     Boost::<C>                    - Target for specific component dependency
                                     (shared or static library); <C> is lower-
                                     case
     Boost::diagnostic_definitions - interface target to enable diagnostic
                                     information about Boost's automatic linking
                                     during compilation (adds BOOST_LIB_DIAGNOSTIC)
     Boost::disable_autolinking    - interface target to disable automatic
                                     linking with MSVC (adds BOOST_ALL_NO_LIB)
     Boost::dynamic_linking        - interface target to enable dynamic linking
                                     linking with MSVC (adds BOOST_ALL_DYN_LINK)

Implicit dependencies such as ‘Boost::filesystem’ requiring
‘Boost::system’ will be automatically detected and satisfied, even if
system is not specified when using find_package() and if
‘Boost::system’ is not added to target_link_libraries().  If
using ‘Boost::thread’, then ‘Threads::Threads’ will also be added
automatically.

It is important to note that the imported targets behave differently
than variables created by this module: multiple calls to
find_package(Boost) in the same directory or sub-directories with
different options (e.g.  static or shared) will not override the values
of the targets created by the first call.

Users may set these hints or results as ‘CACHE’ entries.  Projects
should not read these entries directly but instead use the above result
variables.  Note that some hint names start in upper-case “BOOST”.  One
may specify these as environment variables if they are not specified as
CMake variables or cache entries.

This module first searches for the ‘Boost’ header files using the above
hint variables (excluding ‘BOOST_LIBRARYDIR’) and saves the result in
‘Boost_INCLUDE_DIR’.  Then it searches for requested component libraries
using the above hints (excluding ‘BOOST_INCLUDEDIR’ and
‘Boost_ADDITIONAL_VERSIONS’), “lib” directories near
‘Boost_INCLUDE_DIR’, and the library name configuration settings below.
It saves the library directories in ‘Boost_LIBRARY_DIR_DEBUG’ and
‘Boost_LIBRARY_DIR_RELEASE’ and individual library locations in
‘Boost_<C>_LIBRARY_DEBUG’ and ‘Boost_<C>_LIBRARY_RELEASE’.  When one
changes settings used by previous searches in the same build tree
(excluding environment variables) this module discards previous search
results affected by the changes and searches again.

Boost libraries come in many variants encoded in their file name.  Users
or projects may tell this module which variant to find by setting
variables:

     Boost_USE_DEBUG_LIBS     - Set to ON or OFF to specify whether to search
                                and use the debug libraries.  Default is ON.
     Boost_USE_RELEASE_LIBS   - Set to ON or OFF to specify whether to search
                                and use the release libraries.  Default is ON.
     Boost_USE_MULTITHREADED  - Set to OFF to use the non-multithreaded
                                libraries ('mt' tag).  Default is ON.
     Boost_USE_STATIC_LIBS    - Set to ON to force the use of the static
                                libraries.  Default is OFF.
     Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
                                libraries linked statically to the C++ runtime
                                ('s' tag).  Default is platform dependent.
     Boost_USE_DEBUG_RUNTIME  - Set to ON or OFF to specify whether to use
                                libraries linked to the MS debug C++ runtime
                                ('g' tag).  Default is ON.
     Boost_USE_DEBUG_PYTHON   - Set to ON to use libraries compiled with a
                                debug Python build ('y' tag). Default is OFF.
     Boost_USE_STLPORT        - Set to ON to use libraries compiled with
                                STLPort ('p' tag).  Default is OFF.
     Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
                              - Set to ON to use libraries compiled with
                                STLPort deprecated "native iostreams"
                                ('n' tag).  Default is OFF.
     Boost_COMPILER           - Set to the compiler-specific library suffix
                                (e.g. "-gcc43").  Default is auto-computed
                                for the C++ compiler in use.  A list may be
                                used if multiple compatible suffixes should
                                be tested for, in decreasing order of
                                preference.
     Boost_LIB_PREFIX         - Set to the platform-specific library name
                                prefix (e.g. "lib") used by Boost static libs.
                                This is needed only on platforms where CMake
                                does not know the prefix by default.
     Boost_ARCHITECTURE       - Set to the architecture-specific library suffix
                                (e.g. "-x64").  Default is auto-computed for the
                                C++ compiler in use.
     Boost_THREADAPI          - Suffix for "thread" component library name,
                                such as "pthread" or "win32".  Names with
                                and without this suffix will both be tried.
     Boost_NAMESPACE          - Alternate namespace used to build boost with
                                e.g. if set to "myboost", will search for
                                myboost_thread instead of boost_thread.

Other variables one may set to control this module are:

     Boost_DEBUG              - Set to ON to enable debug output from FindBoost.
                                Please enable this before filing any bug report.
     Boost_REALPATH           - Set to ON to resolve symlinks for discovered
                                libraries to assist with packaging.  For example,
                                the "system" component library may be resolved to
                                "/usr/lib/libboost_system.so.1.67.0" instead of
                                "/usr/lib/libboost_system.so".  This does not
                                affect linking and should not be enabled unless
                                the user needs this information.
     Boost_LIBRARY_DIR        - Default value for Boost_LIBRARY_DIR_RELEASE and
                                Boost_LIBRARY_DIR_DEBUG.

On Visual Studio and Borland compilers Boost headers request automatic
linking to corresponding libraries.  This requires matching libraries to
be linked explicitly or available in the link library search path.  In
this case setting ‘Boost_USE_STATIC_LIBS’ to ‘OFF’ may not achieve
dynamic linking.  Boost automatic linking typically requests static
libraries with a few exceptions (such as ‘Boost.Python’).  Use:

     add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})

to ask Boost to report information about automatic linking requests.

Example to find Boost headers only:

     find_package(Boost 1.36.0)
     if(Boost_FOUND)
       include_directories(${Boost_INCLUDE_DIRS})
       add_executable(foo foo.cc)
     endif()

Example to find Boost libraries and use imported targets:

     find_package(Boost 1.56 REQUIRED COMPONENTS
                  date_time filesystem iostreams)
     add_executable(foo foo.cc)
     target_link_libraries(foo Boost::date_time Boost::filesystem
                               Boost::iostreams)

Example to find Boost Python 3.6 libraries and use imported targets:

     find_package(Boost 1.67 REQUIRED COMPONENTS
                  python36 numpy36)
     add_executable(foo foo.cc)
     target_link_libraries(foo Boost::python36 Boost::numpy36)

Example to find Boost headers and some `static' (release only)
libraries:

     set(Boost_USE_STATIC_LIBS        ON)  # only find static libs
     set(Boost_USE_DEBUG_LIBS         OFF) # ignore debug libs and
     set(Boost_USE_RELEASE_LIBS       ON)  # only find release libs
     set(Boost_USE_MULTITHREADED      ON)
     set(Boost_USE_STATIC_RUNTIME    OFF)
     find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
     if(Boost_FOUND)
       include_directories(${Boost_INCLUDE_DIRS})
       add_executable(foo foo.cc)
       target_link_libraries(foo ${Boost_LIBRARIES})
     endif()

15.2.8.1 Boost CMake
....................

If Boost was built using the boost-cmake project or from Boost 1.70.0 on
it provides a package configuration file for use with find_package’s
config mode.  This module looks for the package configuration file
called ‘BoostConfig.cmake’ or ‘boost-config.cmake’ and stores the result
in ‘CACHE’ entry “Boost_DIR”.  If found, the package configuration file
is loaded and this module returns with no further action.  See
documentation of the Boost CMake package configuration for details on
what it provides.

Set ‘Boost_NO_BOOST_CMAKE’ to ‘ON’, to disable the search for
boost-cmake.

15.2.9 FindBullet
-----------------

Try to find the Bullet physics engine

     This module defines the following variables

     BULLET_FOUND - Was bullet found
     BULLET_INCLUDE_DIRS - the Bullet include directories
     BULLET_LIBRARIES - Link to this, by default it includes
                        all bullet components (Dynamics,
                        Collision, LinearMath, & SoftBody)

     This module accepts the following variables

     BULLET_ROOT - Can be set to bullet install path or Windows build path

15.2.10 FindBZip2
-----------------

Try to find BZip2

15.2.10.1 IMPORTED Targets
..........................

This module defines IMPORTED target ‘BZip2::BZip2’, if BZip2
has been found.

15.2.10.2 Result Variables
..........................

This module defines the following variables:

‘BZIP2_FOUND’

     system has BZip2

‘BZIP2_INCLUDE_DIRS’

     the BZip2 include directories

‘BZIP2_LIBRARIES’

     Link these to use BZip2

‘BZIP2_NEED_PREFIX’

     this is set if the functions are prefixed with ‘BZ2_’

‘BZIP2_VERSION_STRING’

     the version of BZip2 found

15.2.10.3 Cache variables
.........................

The following cache variables may also be set:

‘BZIP2_INCLUDE_DIR’

     the BZip2 include directory

15.2.11 FindCABLE
-----------------

Find CABLE

This module finds if CABLE is installed and determines where the include
files and libraries are.  This code sets the following variables:

     CABLE             the path to the cable executable
     CABLE_TCL_LIBRARY the path to the Tcl wrapper library
     CABLE_INCLUDE_DIR the path to the include directory

To build Tcl wrappers, you should add shared library and link it to
${CABLE_TCL_LIBRARY}.  You should also add ${CABLE_INCLUDE_DIR} as an
include directory.

15.2.12 FindCoin3D
------------------

Find Coin3D (Open Inventor)

Coin3D is an implementation of the Open Inventor API. It provides data
structures and algorithms for 3D visualization.

This module defines the following variables

     COIN3D_FOUND         - system has Coin3D - Open Inventor
     COIN3D_INCLUDE_DIRS  - where the Inventor include directory can be found
     COIN3D_LIBRARIES     - Link to this to use Coin3D

15.2.13 FindCUDAToolkit
-----------------------

New in version 3.17.

This script locates the NVIDIA CUDA toolkit and the associated
libraries, but does not require the ‘CUDA’ language be enabled for a
given project.  This module does not search for the NVIDIA CUDA Samples.

15.2.13.1 Search Behavior
.........................

The CUDA Toolkit search behavior uses the following order:

  1. If the ‘CUDA’ language has been enabled we will use the directory
     containing the compiler as the first search location for ‘nvcc’.

  2. If the ‘CUDAToolkit_ROOT’ cmake configuration variable (e.g.,
     ‘-DCUDAToolkit_ROOT=/some/path’) `or' environment variable is
     defined, it will be searched.  If both an environment variable
     `and' a configuration variable are specified, the `configuration'
     variable takes precedence.

     The directory specified here must be such that the executable
     ‘nvcc’ or the appropriate ‘version.txt’ file can be found
     underneath the specified directory.

  3. If the CUDA_PATH environment variable is defined, it will be
     searched for ‘nvcc’.

  4. The user’s path is searched for ‘nvcc’ using find_program().
     If this is found, no subsequent search attempts are
     performed.  Users are responsible for ensuring that the first
     ‘nvcc’ to show up in the path is the desired path in the event that
     multiple CUDA Toolkits are installed.

  5. On Unix systems, if the symbolic link ‘/usr/local/cuda’ exists,
     this is used.  No subsequent search attempts are performed.  No
     default symbolic link location exists for the Windows platform.

  6. The platform specific default install locations are searched.  If
     exactly one candidate is found, this is used.  The default CUDA
     Toolkit install locations searched are:

     Platform          Search Pattern

     ------------------------------------------------------------------------------------

     macOS             ‘/Developer/NVIDIA/CUDA-X.Y’

     Other Unix        ‘/usr/local/cuda-X.Y’

     Windows           ‘C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y’

     Where ‘X.Y’ would be a specific version of the CUDA Toolkit, such
     as ‘/usr/local/cuda-9.0’ or ‘C:\Program Files\NVIDIA GPU Computing
     Toolkit\CUDA\v9.0’

          Note: When multiple CUDA Toolkits are installed in the default
          location of a system (e.g., both ‘/usr/local/cuda-9.0’ and
          ‘/usr/local/cuda-10.0’ exist but the ‘/usr/local/cuda’
          symbolic link does `not' exist), this package is marked as
          `not' found.

          There are too many factors involved in making an automatic
          decision in the presence of multiple CUDA Toolkits being
          installed.  In this situation, users are encouraged to either
          (1) set ‘CUDAToolkit_ROOT’ or (2) ensure that the correct
          ‘nvcc’ executable shows up in ‘$PATH’ for
          find_program() to find.

15.2.13.2 Options
.................

‘VERSION’

     If specified, describes the version of the CUDA Toolkit to search
     for.

‘REQUIRED’

     If specified, configuration will error if a suitable CUDA Toolkit
     is not found.

‘QUIET’

     If specified, the search for a suitable CUDA Toolkit will not
     produce any messages.

‘EXACT’

     If specified, the CUDA Toolkit is considered found only if the
     exact ‘VERSION’ specified is recovered.

15.2.13.3 Imported targets
..........................

An imported target named ‘CUDA::toolkit’ is provided.

This module defines IMPORTED targets for each of the
following libraries that are part of the CUDAToolkit:

   - CUDA Runtime Library.

   - CUDA Driver Library.

   - cuBLAS.

   - cuFFT.

   - cuRAND.

   - cuSOLVER.

   - cuSPARSE.

   - cuPTI.

   - NPP.

   - nvBLAS.

   - nvGRAPH.

   - nvJPEG.

   - nvidia-ML.

   - nvRTC.

   - nvToolsExt.

   - OpenCL.

   - cuLIBOS.

15.2.13.4 CUDA Runtime Library
..............................

The CUDA Runtime library (cudart) are what most applications will
typically need to link against to make any calls such as ‘cudaMalloc’,
and ‘cudaFree’.

Targets Created:

   - ‘CUDA::cudart’

   - ‘CUDA::cudart_static’

15.2.13.5 CUDA Driver Library
.............................

The CUDA Driver library (cuda) are used by applications that use calls
such as ‘cuMemAlloc’, and ‘cuMemFree’.  This is generally used by
advanced

Targets Created:

   - ‘CUDA::cuda_driver’

   - ‘CUDA::cuda_driver’

15.2.13.6 cuBLAS
................

The cuBLAS(1) library.

Targets Created:

   - ‘CUDA::cublas’

   - ‘CUDA::cublas_static’

   - ‘CUDA::cublasLt’ starting in CUDA 10.1

   - ‘CUDA::cublasLt_static’ starting in CUDA 10.1

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/cublas/index.html

15.2.13.7 cuFFT
...............

The cuFFT(1) library.

Targets Created:

   - ‘CUDA::cufft’

   - ‘CUDA::cufftw’

   - ‘CUDA::cufft_static’

   - ‘CUDA::cufftw_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/cufft/index.html

15.2.13.8 cuRAND
................

The cuRAND(1) library.

Targets Created:

   - ‘CUDA::curand’

   - ‘CUDA::curand_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/curand/index.html

15.2.13.9 cuSOLVER
..................

The cuSOLVER(1) library.

Targets Created:

   - ‘CUDA::cusolver’

   - ‘CUDA::cusolver_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/cusolver/index.html

15.2.13.10 cuSPARSE
...................

The cuSPARSE(1) library.

Targets Created:

   - ‘CUDA::cusparse’

   - ‘CUDA::cusparse_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/cusparse/index.html

15.2.13.11 cupti
................

The NVIDIA CUDA Profiling Tools Interface(1).

Targets Created:

   - ‘CUDA::cupti’

   - ‘CUDA::cupti_static’

   ---------- Footnotes ----------

   (1) https://developer.nvidia.com/CUPTI

15.2.13.12 NPP
..............

The NPP(1) libraries.

Targets Created:

   - ‘nppc’:

        - ‘CUDA::nppc’

        - ‘CUDA::nppc_static’

   - ‘nppial’: Arithmetic and logical operation functions in
     ‘nppi_arithmetic_and_logical_operations.h’

        - ‘CUDA::nppial’

        - ‘CUDA::nppial_static’

   - ‘nppicc’: Color conversion and sampling functions in
     ‘nppi_color_conversion.h’

        - ‘CUDA::nppicc’

        - ‘CUDA::nppicc_static’

   - ‘nppicom’: JPEG compression and decompression functions in
     ‘nppi_compression_functions.h’ Removed starting in CUDA 11.0, use
     nvJPEG instead.

        - ‘CUDA::nppicom’

        - ‘CUDA::nppicom_static’

   - ‘nppidei’: Data exchange and initialization functions in
     ‘nppi_data_exchange_and_initialization.h’

        - ‘CUDA::nppidei’

        - ‘CUDA::nppidei_static’

   - ‘nppif’: Filtering and computer vision functions in
     ‘nppi_filter_functions.h’

        - ‘CUDA::nppif’

        - ‘CUDA::nppif_static’

   - ‘nppig’: Geometry transformation functions found in
     ‘nppi_geometry_transforms.h’

        - ‘CUDA::nppig’

        - ‘CUDA::nppig_static’

   - ‘nppim’: Morphological operation functions found in
     ‘nppi_morphological_operations.h’

        - ‘CUDA::nppim’

        - ‘CUDA::nppim_static’

   - ‘nppist’: Statistics and linear transform in
     ‘nppi_statistics_functions.h’ and ‘nppi_linear_transforms.h’

        - ‘CUDA::nppist’

        - ‘CUDA::nppist_static’

   - ‘nppisu’: Memory support functions in ‘nppi_support_functions.h’

        - ‘CUDA::nppisu’

        - ‘CUDA::nppisu_static’

   - ‘nppitc’: Threshold and compare operation functions in
     ‘nppi_threshold_and_compare_operations.h’

        - ‘CUDA::nppitc’

        - ‘CUDA::nppitc_static’

   - ‘npps’:

        - ‘CUDA::npps’

        - ‘CUDA::npps_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/npp/index.html

15.2.13.13 nvBLAS
.................

The nvBLAS(1) libraries.  This is a shared library only.

Targets Created:

   - ‘CUDA::nvblas’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/nvblas/index.html

15.2.13.14 nvGRAPH
..................

The nvGRAPH(1) library.  Removed starting in CUDA 11.0

Targets Created:

   - ‘CUDA::nvgraph’

   - ‘CUDA::nvgraph_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/nvgraph/index.html

15.2.13.15 nvJPEG
.................

The nvJPEG(1) library.  Introduced in CUDA 10.

Targets Created:

   - ‘CUDA::nvjpeg’

   - ‘CUDA::nvjpeg_static’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/nvjpeg/index.html

15.2.13.16 nvRTC
................

The nvRTC(1) (Runtime Compilation) library.  This is a shared library
only.

Targets Created:

   - ‘CUDA::nvrtc’

   ---------- Footnotes ----------

   (1) https://docs.nvidia.com/cuda/nvrtc/index.html

15.2.13.17 nvidia-ML
....................

The NVIDIA Management Library(1).  This is a shared library only.

Targets Created:

   - ‘CUDA::nvml’

   ---------- Footnotes ----------

   (1) https://developer.nvidia.com/nvidia-management-library-nvml

15.2.13.18 nvToolsExt
.....................

The NVIDIA Tools Extension(1).  This is a shared library only.

Targets Created:

   - ‘CUDA::nvToolsExt’

   ---------- Footnotes ----------

   (1)
https://docs.nvidia.com/gameworks/content/gameworkslibrary/nvtx/nvidia_tools_extension_library_nvtx.htm

15.2.13.19 OpenCL
.................

The NVIDIA OpenCL Library(1).  This is a shared library only.

Targets Created:

   - ‘CUDA::OpenCL’

   ---------- Footnotes ----------

   (1) https://developer.nvidia.com/opencl

15.2.13.20 cuLIBOS
..................

The cuLIBOS library is a backend thread abstraction layer library which
is static only.  The ‘CUDA::cublas_static’, ‘CUDA::cusparse_static’,
‘CUDA::cufft_static’, ‘CUDA::curand_static’, and (when implemented) NPP
libraries all automatically have this dependency linked.

Target Created:

   - ‘CUDA::culibos’

`Note': direct usage of this target by consumers should not be
necessary.

15.2.13.21 Result variables
...........................

‘CUDAToolkit_FOUND’

     A boolean specifying whether or not the CUDA Toolkit was found.

‘CUDAToolkit_VERSION’

     The exact version of the CUDA Toolkit found (as reported by ‘nvcc
     --version’ or ‘version.txt’).

‘CUDAToolkit_VERSION_MAJOR’

     The major version of the CUDA Toolkit.

‘CUDAToolkit_VERSION_MAJOR’

     The minor version of the CUDA Toolkit.

‘CUDAToolkit_VERSION_PATCH’

     The patch version of the CUDA Toolkit.

‘CUDAToolkit_BIN_DIR’

     The path to the CUDA Toolkit library directory that contains the
     CUDA executable ‘nvcc’.

‘CUDAToolkit_INCLUDE_DIRS’

     The path to the CUDA Toolkit ‘include’ folder containing the header
     files required to compile a project linking against CUDA.

‘CUDAToolkit_LIBRARY_DIR’

     The path to the CUDA Toolkit library directory that contains the
     CUDA Runtime library ‘cudart’.

‘CUDAToolkit_LIBRARY_ROOT’

     The path to the CUDA Toolkit directory containing the nvvm
     directory and version.txt.

‘CUDAToolkit_TARGET_DIR’

     The path to the CUDA Toolkit directory including the target
     architecture when cross-compiling.  When not cross-compiling this
     will be equivalent to the parent directory of
     ‘CUDAToolkit_BIN_DIR’.

‘CUDAToolkit_NVCC_EXECUTABLE’

     The path to the NVIDIA CUDA compiler ‘nvcc’.  Note that this path
     may `not' be the same as CMAKE_CUDA_COMPILER.  ‘nvcc’
     must be found to determine the CUDA Toolkit version as well as
     determining other features of the Toolkit.  This variable is set
     for the convenience of modules that depend on this one.

15.2.14 FindCups
----------------

Find the Common UNIX Printing System (CUPS).

Set ‘CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE’ to ‘TRUE’ if you need a version
which features this function (i.e.  at least ‘1.1.19’)

15.2.14.1 Imported targets
..........................

This module defines IMPORTED target ‘Cups::Cups’, if Cups
has been found.

15.2.14.2 Result variables
..........................

This module will set the following variables in your project:

‘CUPS_FOUND’

     true if CUPS headers and libraries were found

‘CUPS_INCLUDE_DIRS’

     the directory containing the Cups headers

‘CUPS_LIBRARIES’

     the libraries to link against to use CUPS.

‘CUPS_VERSION_STRING’

     the version of CUPS found (since CMake 2.8.8)

15.2.14.3 Cache variables
.........................

The following cache variables may also be set:

‘CUPS_INCLUDE_DIR’

     the directory containing the Cups headers

15.2.15 FindCURL
----------------

Find the native CURL headers and libraries.

This module accept optional COMPONENTS to check supported features and
protocols:

     PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
                POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
     FEATURES:  SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
                Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy

15.2.15.1 IMPORTED Targets
..........................

This module defines IMPORTED target ‘CURL::libcurl’, if curl
has been found.

15.2.15.2 Result Variables
..........................

This module defines the following variables:

‘CURL_FOUND’

     “True” if ‘curl’ found.

‘CURL_INCLUDE_DIRS’

     where to find ‘curl’/‘curl.h’, etc.

‘CURL_LIBRARIES’

     List of libraries when using ‘curl’.

‘CURL_VERSION_STRING’

     The version of ‘curl’ found.

15.2.15.3 CURL CMake
....................

If CURL was built using the CMake buildsystem then it provides its own
‘CURLConfig.cmake’ file for use with the find_package().
command’s config mode.  This module looks for this file and, if found,
returns its results with no further action.

Set ‘CURL_NO_CURL_CMAKE’ to ‘ON’ to disable this search.

15.2.16 FindCurses
------------------

Find the curses or ncurses include file and library.

15.2.16.1 Result Variables
..........................

This module defines the following variables:

‘CURSES_FOUND’

     True if Curses is found.

‘CURSES_INCLUDE_DIRS’

     The include directories needed to use Curses.

‘CURSES_LIBRARIES’

     The libraries needed to use Curses.

‘CURSES_CFLAGS’

     Parameters which ought be given to C/C++ compilers when using
     Curses.

‘CURSES_HAVE_CURSES_H’

     True if curses.h is available.

‘CURSES_HAVE_NCURSES_H’

     True if ncurses.h is available.

‘CURSES_HAVE_NCURSES_NCURSES_H’

     True if ‘ncurses/ncurses.h’ is available.

‘CURSES_HAVE_NCURSES_CURSES_H’

     True if ‘ncurses/curses.h’ is available.

Set ‘CURSES_NEED_NCURSES’ to ‘TRUE’ before the ‘find_package(Curses)’
call if NCurses functionality is required.  Set ‘CURSES_NEED_WIDE’ to
‘TRUE’ before the ‘find_package(Curses)’ call if unicode functionality
is required.

15.2.16.2 Backward Compatibility
................................

The following variable are provided for backward compatibility:

‘CURSES_INCLUDE_DIR’

     Path to Curses include.  Use ‘CURSES_INCLUDE_DIRS’ instead.

‘CURSES_LIBRARY’

     Path to Curses library.  Use ‘CURSES_LIBRARIES’ instead.

15.2.17 FindCVS
---------------

Find the Concurrent Versions System (CVS).

The module defines the following variables:

     CVS_EXECUTABLE - path to cvs command line client
     CVS_FOUND - true if the command line client was found

Example usage:

     find_package(CVS)
     if(CVS_FOUND)
       message("CVS found: ${CVS_EXECUTABLE}")
     endif()

15.2.18 FindCxxTest
-------------------

Find CxxTest unit testing framework.

Find the CxxTest suite and declare a helper macro for creating unit
tests and integrating them with CTest.  For more details on CxxTest see
‘http://cxxtest.tigris.org’

INPUT Variables

     CXXTEST_USE_PYTHON [deprecated since 1.3]
         Only used in the case both Python & Perl
         are detected on the system to control
         which CxxTest code generator is used.
         Valid only for CxxTest version 3.

     NOTE: In older versions of this Find Module,
     this variable controlled if the Python test
     generator was used instead of the Perl one,
     regardless of which scripting language the
     user had installed.

     CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
         Specify a list of options to pass to the CxxTest code
         generator.  If not defined, --error-printer is
         passed.

OUTPUT Variables

     CXXTEST_FOUND
         True if the CxxTest framework was found
     CXXTEST_INCLUDE_DIRS
         Where to find the CxxTest include directory
     CXXTEST_PERL_TESTGEN_EXECUTABLE
         The perl-based test generator
     CXXTEST_PYTHON_TESTGEN_EXECUTABLE
         The python-based test generator
     CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
         The test generator that is actually used (chosen using user preferences
         and interpreters found in the system)
     CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
         The full path to the Perl or Python executable on the system, on
         platforms where the script cannot be executed using its shebang line.

MACROS for optional use by CMake users:

     CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
        Creates a CxxTest runner and adds it to the CTest testing suite
        Parameters:
            test_name               The name of the test
            gen_source_file         The generated source filename to be
                                    generated by CxxTest
            input_files_to_testgen  The list of header files containing the
                                    CxxTest::TestSuite's to be included in
                                    this runner

     #==============
     Example Usage:

     find_package(CxxTest)
     if(CXXTEST_FOUND)
         include_directories(${CXXTEST_INCLUDE_DIR})
         enable_testing()

         CXXTEST_ADD_TEST(unittest_foo foo_test.cc
                           ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
         target_link_libraries(unittest_foo foo) # as needed
     endif()

     This will (if CxxTest is found):
     1. Invoke the testgen executable to autogenerate foo_test.cc in the
        binary tree from "foo_test.h" in the current source directory.
     2. Create an executable and test called unittest_foo.

     #=============
     Example foo_test.h:

     #include <cxxtest/TestSuite.h>

     class MyTestSuite : public CxxTest::TestSuite
     {
     public:
        void testAddition( void )
        {
           TS_ASSERT( 1 + 1 > 1 );
           TS_ASSERT_EQUALS( 1 + 1, 2 );
        }
     };

15.2.19 FindCygwin
------------------

Find Cygwin, a POSIX-compatible environment that runs natively on
Microsoft Windows

15.2.20 FindDart
----------------

Find DART

This module looks for the dart testing software and sets DART_ROOT to
point to where it found it.

15.2.21 FindDCMTK
-----------------

Find DICOM ToolKit (DCMTK) libraries and applications

The module defines the following variables:

     DCMTK_INCLUDE_DIRS  - Directories to include to use DCMTK
     DCMTK_LIBRARIES     - Files to link against to use DCMTK
     DCMTK_FOUND         - If false, don't try to use DCMTK
     DCMTK_DIR           - (optional) Source directory for DCMTK

15.2.21.1 Compatibility
.......................

This module is able to find a version of DCMTK that does or does not
export a `DCMTKConfig.cmake' file.  It applies a two step process:

   * Step 1: Attempt to find DCMTK version providing a
     `DCMTKConfig.cmake' file.

   * Step 2: If step 1 failed, rely on `FindDCMTK.cmake' to set
     ‘DCMTK_*’ variables details below.

Recent DCMTK(1) provides a `DCMTKConfig.cmake' package configuration file.
To exclusively use the package configuration
file (recommended when possible), pass the ‘NO_MODULE’ option to
find_package().  For example, ‘find_package(DCMTK NO_MODULE)’. This
requires official DCMTK snapshot `3.6.1_20140617' or newer.

Until all clients update to the more recent DCMTK, build systems will
need to support different versions of DCMTK.

On any given system, the following combinations of DCMTK versions could
be considered:

             SYSTEM DCMTK              LOCAL DCMTK                 Supported ?

Case A       NA                        [ ] DCMTKConfig             YES

Case B       NA                        [X] DCMTKConfig             YES

Case C       [ ] DCMTKConfig           NA                          YES

Case D       [X] DCMTKConfig           NA                          YES

Case E       [ ] DCMTKConfig           [ ] DCMTKConfig             YES (*)

Case F       [X] DCMTKConfig           [ ] DCMTKConfig             NO

Case G       [ ] DCMTKConfig           [X] DCMTKConfig             YES

Case H       [X] DCMTKConfig           [X] DCMTKConfig             YES

     (*) See Troubleshooting section.

Legend:

     NA ……………: Means that no System or Local DCMTK is available

     [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
     a DCMTKConfig.cmake file.

     [X] DCMTKConfig ..: Means that the version of DCMTK exports a
     DCMTKConfig.cmake file.

   ---------- Footnotes ----------

   (1)
http://git.dcmtk.org/web?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe

15.2.21.2 Troubleshooting
.........................

What to do if my project finds a different version of DCMTK?

Remove DCMTK entry from the CMake cache per find_package().
documentation.

15.2.22 FindDevIL
-----------------

This module locates the developer’s image library.
‘http://openil.sourceforge.net/’

This module sets:

     IL_LIBRARIES -   the name of the IL library. These include the full path to
                      the core DevIL library. This one has to be linked into the
                      application.
     ILU_LIBRARIES -  the name of the ILU library. Again, the full path. This
                      library is for filters and effects, not actual loading. It
                      doesn't have to be linked if the functionality it provides
                      is not used.
     ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
                      library interfaces with OpenGL. It is not strictly needed
                      in applications.
     IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
     DevIL_FOUND    - this is set to TRUE if all the above variables were set.
                      This will be set to false if ILU or ILUT are not found,
                      even if they are not needed. In most systems, if one
                      library is found all the others are as well. That's the
                      way the DevIL developers release it.

15.2.23 FindDoxygen
-------------------

Doxygen is a documentation generation tool (see
‘http://www.doxygen.org’).  This module looks for Doxygen and some
optional tools it supports.  These tools are enabled as components in
the find_package() command:

‘dot’

     Graphviz(1) ‘dot’ utility used to render various graphs.

‘mscgen’

     Message Chart Generator(2) utility used by Doxygen’s ‘\msc’ and
     ‘\mscfile’ commands.

‘dia’

     Dia(3) the diagram editor used by Doxygen’s ‘\diafile’ command.

Examples:

     # Require dot, treat the other components as optional
     find_package(Doxygen
                  REQUIRED dot
                  OPTIONAL_COMPONENTS mscgen dia)

The following variables are defined by this module:

 -- Variable: DOXYGEN_FOUND

     True if the ‘doxygen’ executable was found.

 -- Variable: DOXYGEN_VERSION

     The version reported by ‘doxygen --version’.

The module defines ‘IMPORTED’ targets for Doxygen and each component
found.  These can be used as part of custom commands, etc.  and should
be preferred over old-style (and now deprecated) variables like
‘DOXYGEN_EXECUTABLE’.  The following import targets are defined if their
corresponding executable could be found (the component import targets
will only be defined if that component was requested):

     Doxygen::doxygen
     Doxygen::dot
     Doxygen::mscgen
     Doxygen::dia

   ---------- Footnotes ----------

   (1) http://graphviz.org

   (2) http://www.mcternan.me.uk/mscgen/

   (3) https://wiki.gnome.org/Apps/Dia

15.2.23.1 Functions
...................

 -- Command: doxygen_add_docs

     This function is intended as a convenience for adding a target for
     generating documentation with Doxygen.  It aims to provide sensible
     defaults so that projects can generally just provide the input
     files and directories and that will be sufficient to give sensible
     results.  The function supports the ability to customize the
     Doxygen configuration used to build the documentation.

          doxygen_add_docs(targetName
              [filesOrDirs...]
              [ALL]
              [USE_STAMP_FILE]
              [WORKING_DIRECTORY dir]
              [COMMENT comment])

     The function constructs a ‘Doxyfile’ and defines a custom target
     that runs Doxygen on that generated file.  The listed files and
     directories are used as the ‘INPUT’ of the generated ‘Doxyfile’ and
     they can contain wildcards.  Any files that are listed explicitly
     will also be added as ‘SOURCES’ of the custom target so they will
     show up in an IDE project’s source list.

     So that relative input paths work as expected, by default the
     working directory of the Doxygen command will be the current source
     directory (i.e.  see CMAKE_CURRENT_SOURCE_DIR).  This can
     be overridden with the ‘WORKING_DIRECTORY’ option to change the
     directory used as the relative base point.  Note also that
     Doxygen’s default behavior is to strip the working directory from
     relative paths in the generated documentation (see the
     ‘STRIP_FROM_PATH’ Doxygen config option(1) for details).

     If provided, the optional ‘comment’ will be passed as the ‘COMMENT’
     for the add_custom_target() command used to create the
     custom target internally.

     If ‘ALL’ is set, the target will be added to the default build
     target.

     If ‘USE_STAMP_FILE’ is set, the custom command defined by this
     function will create a stamp file with the name
     ‘<targetName>.stamp’ in the current binary directory whenever
     doxygen is re-run.  With this option present, all items in
     ‘<filesOrDirs>’ must be files (i.e.  no directories, symlinks or
     wildcards) and each of the files must exist at the time
     ‘doxygen_add_docs()’ is called.  An error will be raised if any of
     the items listed is missing or is not a file when ‘USE_STAMP_FILE’
     is given.  A dependency will be created on each of the files so
     that doxygen will only be re-run if one of the files is updated.
     Without the ‘USE_STAMP_FILE’ option, doxygen will always be re-run
     if the ‘<targetName>’ target is built regardless of whether
     anything listed in ‘<filesOrDirs>’ has changed.

     The contents of the generated ‘Doxyfile’ can be customized by
     setting CMake variables before calling ‘doxygen_add_docs()’.  Any
     variable with a name of the form ‘DOXYGEN_<tag>’ will have its
     value substituted for the corresponding ‘<tag>’ configuration
     option in the ‘Doxyfile’.  See the Doxygen documentation(2) for the
     full list of supported configuration options.

     Some of Doxygen’s defaults are overridden to provide more
     appropriate behavior for a CMake project.  Each of the following
     will be explicitly set unless the variable already has a value
     before ‘doxygen_add_docs()’ is called (with some exceptions noted):

      -- Variable: DOXYGEN_HAVE_DOT

          Set to ‘YES’ if the ‘dot’ component was requested and it was
          found, ‘NO’ otherwise.  Any existing value of
          ‘DOXYGEN_HAVE_DOT’ is ignored.

      -- Variable: DOXYGEN_DOT_MULTI_TARGETS

          Set to ‘YES’ by this module (note that this requires a ‘dot’
          version newer than 1.8.10).  This option is only meaningful if
          ‘DOXYGEN_HAVE_DOT’ is also set to ‘YES’.

      -- Variable: DOXYGEN_GENERATE_LATEX

          Set to ‘NO’ by this module.

      -- Variable: DOXYGEN_WARN_FORMAT

          For Visual Studio based generators, this is set to the form
          recognized by the Visual Studio IDE: ‘$file($line) : $text’.
          For all other generators, Doxygen’s default value is not
          overridden.

      -- Variable: DOXYGEN_PROJECT_NAME

          Populated with the name of the current project (i.e.  see
          PROJECT_NAME).

      -- Variable: DOXYGEN_PROJECT_NUMBER

          Populated with the version of the current project (i.e.  see
          PROJECT_VERSION).

      -- Variable: DOXYGEN_PROJECT_BRIEF

          Populated with the description of the current project (i.e.
          see PROJECT_DESCRIPTION).

      -- Variable: DOXYGEN_INPUT

          Projects should not set this variable.  It will be populated
          with the set of files and directories passed to
          ‘doxygen_add_docs()’, thereby providing consistent behavior
          with the other built-in commands like add_executable(),
          see add_library() and add_custom_target().
          If a variable named ‘DOXYGEN_INPUT’ is set by the
          project, it will be ignored and a warning will be issued.

      -- Variable: DOXYGEN_RECURSIVE

          Set to ‘YES’ by this module.

      -- Variable: DOXYGEN_EXCLUDE_PATTERNS

          If the set of inputs includes directories, this variable will
          specify patterns used to exclude files from them.  The
          following patterns are added by ‘doxygen_add_docs()’ to ensure
          CMake-specific files and directories are not included in the
          input.  If the project sets ‘DOXYGEN_EXCLUDE_PATTERNS’, those
          contents are merged with these additional patterns rather than
          replacing them:

               */.git/*
               */.svn/*
               */.hg/*
               */CMakeFiles/*
               */_CPack_Packages/*
               DartConfiguration.tcl
               CMakeLists.txt
               CMakeCache.txt

      -- Variable: DOXYGEN_OUTPUT_DIRECTORY

          Set to CMAKE_CURRENT_BINARY_DIR by this module.
          Note that if the project provides its own value for this and
          it is a relative path, it will be converted to an absolute
          path relative to the current binary directory.  This is
          necessary because doxygen will normally be run from a
          directory within the source tree so that relative source paths
          work as expected.  If this directory does not exist, it will
          be recursively created prior to executing the doxygen
          commands.

To change any of these defaults or override any other Doxygen config
option, set relevant variables before calling ‘doxygen_add_docs()’.  For
example:

          set(DOXYGEN_GENERATE_HTML NO)
          set(DOXYGEN_GENERATE_MAN YES)

          doxygen_add_docs(
              doxygen
              ${PROJECT_SOURCE_DIR}
              COMMENT "Generate man pages"
          )

A number of Doxygen config options accept lists of values, but Doxygen
requires them to be separated by whitespace.  CMake variables hold lists
as a string with items separated by semi-colons, so a conversion needs
to be performed.  The ‘doxygen_add_docs()’ command specifically checks
the following Doxygen config options and will convert their associated
CMake variable’s contents into the required form if set.

     ABBREVIATE_BRIEF
     ALIASES
     CITE_BIB_FILES
     DIAFILE_DIRS
     DOTFILE_DIRS
     DOT_FONTPATH
     ENABLED_SECTIONS
     EXAMPLE_PATH
     EXAMPLE_PATTERNS
     EXCLUDE
     EXCLUDE_PATTERNS
     EXCLUDE_SYMBOLS
     EXPAND_AS_DEFINED
     EXTENSION_MAPPING
     EXTRA_PACKAGES
     EXTRA_SEARCH_MAPPINGS
     FILE_PATTERNS
     FILTER_PATTERNS
     FILTER_SOURCE_PATTERNS
     HTML_EXTRA_FILES
     HTML_EXTRA_STYLESHEET
     IGNORE_PREFIX
     IMAGE_PATH
     INCLUDE_FILE_PATTERNS
     INCLUDE_PATH
     INPUT
     LATEX_EXTRA_FILES
     LATEX_EXTRA_STYLESHEET
     MATHJAX_EXTENSIONS
     MSCFILE_DIRS
     PLANTUML_INCLUDE_PATH
     PREDEFINED
     QHP_CUST_FILTER_ATTRS
     QHP_SECT_FILTER_ATTRS
     STRIP_FROM_INC_PATH
     STRIP_FROM_PATH
     TAGFILES
     TCL_SUBST

The following single value Doxygen options will be quoted automatically
if they contain at least one space:

     CHM_FILE
     DIA_PATH
     DOCBOOK_OUTPUT
     DOCSET_FEEDNAME
     DOCSET_PUBLISHER_NAME
     DOT_FONTNAME
     DOT_PATH
     EXTERNAL_SEARCH_ID
     FILE_VERSION_FILTER
     GENERATE_TAGFILE
     HHC_LOCATION
     HTML_FOOTER
     HTML_HEADER
     HTML_OUTPUT
     HTML_STYLESHEET
     INPUT_FILTER
     LATEX_FOOTER
     LATEX_HEADER
     LATEX_OUTPUT
     LAYOUT_FILE
     MAN_OUTPUT
     MAN_SUBDIR
     MATHJAX_CODEFILE
     MSCGEN_PATH
     OUTPUT_DIRECTORY
     PERL_PATH
     PLANTUML_JAR_PATH
     PROJECT_BRIEF
     PROJECT_LOGO
     PROJECT_NAME
     QCH_FILE
     QHG_LOCATION
     QHP_CUST_FILTER_NAME
     QHP_VIRTUAL_FOLDER
     RTF_EXTENSIONS_FILE
     RTF_OUTPUT
     RTF_STYLESHEET_FILE
     SEARCHDATA_FILE
     USE_MDFILE_AS_MAINPAGE
     WARN_FORMAT
     WARN_LOGFILE
     XML_OUTPUT

There are situations where it may be undesirable for a particular config
option to be automatically quoted by ‘doxygen_add_docs()’, such as
‘ALIASES’ which may need to include its own embedded quoting.  The
‘DOXYGEN_VERBATIM_VARS’ variable can be used to specify a list of
Doxygen variables (including the leading ‘DOXYGEN_’ prefix) which should
not be quoted.  The project is then responsible for ensuring that those
variables’ values make sense when placed directly in the Doxygen input
file.  In the case of list variables, list items are still separated by
spaces, it is only the automatic quoting that is skipped.  For example,
the following allows ‘doxygen_add_docs()’ to apply quoting to
‘DOXYGEN_PROJECT_BRIEF’, but not each item in the ‘DOXYGEN_ALIASES’ list
(see bracket syntax can also be used to make working with
embedded quotes easier):

     set(DOXYGEN_PROJECT_BRIEF "String with spaces")
     set(DOXYGEN_ALIASES
         [[somealias="@some_command param"]]
         "anotherAlias=@foobar"
     )
     set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)

The resultant ‘Doxyfile’ will contain the following lines:

     PROJECT_BRIEF = "String with spaces"
     ALIASES       = somealias="@some_command param" anotherAlias=@foobar

   ---------- Footnotes ----------

   (1) http://www.doxygen.org/manual/config.html

   (2) http://www.doxygen.org/manual/config.html

15.2.23.2 Deprecated Result Variables
.....................................

For compatibility with previous versions of CMake, the following
variables are also defined but they are deprecated and should no longer
be used:

 -- Variable: DOXYGEN_EXECUTABLE

     The path to the ‘doxygen’ command.  If projects need to refer to
     the ‘doxygen’ executable directly, they should use the
     ‘Doxygen::doxygen’ import target instead.

 -- Variable: DOXYGEN_DOT_FOUND

     True if the ‘dot’ executable was found.

 -- Variable: DOXYGEN_DOT_EXECUTABLE

     The path to the ‘dot’ command.  If projects need to refer to the
     ‘dot’ executable directly, they should use the ‘Doxygen::dot’
     import target instead.

 -- Variable: DOXYGEN_DOT_PATH

     The path to the directory containing the ‘dot’ executable as
     reported in ‘DOXYGEN_DOT_EXECUTABLE’.  The path may have forward
     slashes even on Windows and is not suitable for direct substitution
     into a ‘Doxyfile.in’ template.  If you need this value, get the
     IMPORTED_LOCATION property of the ‘Doxygen::dot’ target
     and use get_filename_component() to extract the
     directory part of that path.  You may also want to consider using
     file(TO_NATIVE_PATH) to prepare the path for a Doxygen
     configuration file.

15.2.23.3 Deprecated Hint Variables
...................................

 -- Variable: DOXYGEN_SKIP_DOT

     This variable has no effect for the component form of
     ‘find_package’.  In backward compatibility mode (i.e.  without
     components list) it prevents the finder module from searching for
     Graphviz’s ‘dot’ utility.

15.2.24 FindEnvModules
----------------------

New in version 3.15.

Locate an environment module implementation and make commands available
to CMake scripts to use them.  This is compatible with both Lua-based
Lmod and TCL-based EnvironmentModules.

This module is intended for the use case of setting up the compiler and
library environment within a CTest Script. (‘ctest -S’).  It
can also be used in a CMake Script. (‘cmake -P’).

     Note: The loaded environment will not survive past the end of the
     calling process.  Do not use this module in project code
     (‘CMakeLists.txt’ files) to load a compiler environment; it will
     not be available during the build.  Instead load the environment
     manually before running CMake or using the generated build system.

15.2.24.1 Example Usage
.......................

     set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
     set(CTEST_BUILD_CONFIGURATION Release)
     set(CTEST_BUILD_FLAGS "-k -j8")
     set(CTEST_CMAKE_GENERATOR "Unix Makefiles")

     ...

     find_package(EnvModules REQUIRED)

     env_module(purge)
     env_module(load modules)
     env_module(load craype)
     env_module(load PrgEnv-cray)
     env_module(load craype-knl)
     env_module(load cray-mpich)
     env_module(load cray-libsci)

     set(ENV{CRAYPE_LINK_TYPE} dynamic)

     ...

15.2.24.2 Result Variables
..........................

This module will set the following variables in your project:

‘EnvModules_FOUND’

     True if a compatible environment modules framework was found.

15.2.24.3 Cache Variables
.........................

The following cache variable will be set:

‘EnvModules_COMMAND’

     The low level module command to use.  Currently supported
     implementations are the Lua based Lmod and TCL based
     EnvironmentModules.

15.2.24.4 Environment Variables
...............................

‘ENV{MODULESHOME}’

     Usually set by the module environment implementation, used as a
     hint to locate the module command to execute.

15.2.24.5 Provided Functions
............................

This defines the following CMake functions for interacting with
environment modules:

 -- Command: env_module

     Execute an aribitrary module command:

          env_module(cmd arg1 ... argN)
          env_module(
            COMMAND cmd arg1 ... argN
            [OUTPUT_VARIABLE <out-var>]
            [RESULT_VARIABLE <ret-var>]
          )

     The options are:

     ‘cmd arg1 ... argN’

          The module sub-command and arguments to execute as if they
          were passed directly to the module command in your shell
          environment.

     ‘OUTPUT_VARIABLE <out-var>’

          The standard output from executing the module command.

     ‘RESULT_VARIABLE <ret-var>’

          The return code from executing the module command.

 -- Command: env_module_swap

     Swap one module for another:

          env_module_swap(out_mod in_mod
            [OUTPUT_VARIABLE <out-var>]
            [RESULT_VARIABLE <ret-var>]
          )

     This is functionally equivalent to the ‘module swap out_mod in_mod’
     shell command.  The options are:

     ‘OUTPUT_VARIABLE <out-var>’

          The standard output from executing the module command.

     ‘RESULT_VARIABLE <ret-var>’

          The return code from executing the module command.

 -- Command: env_module_list

     Retrieve the list of currently loaded modules:

          env_module_list(<out-var>)

     This is functionally equivalent to the ‘module list’ shell command.
     The result is stored in ‘<out-var>’ as a properly formatted CMake
     semicolon-separated list variable.

 -- Command: env_module_avail

     Retrieve the list of available modules:

          env_module_avail([<mod-prefix>] <out-var>)

     This is functionally equivalent to the ‘module avail <mod-prefix>’
     shell command.  The result is stored in ‘<out-var>’ as a properly
     formatted CMake semicolon-separated list variable.

15.2.25 FindEXPAT
-----------------

Find the native Expat headers and library.  Expat is a stream-oriented
XML parser library written in C.

15.2.25.1 Imported Targets
..........................

This module defines the following IMPORTED targets:

‘EXPAT::EXPAT’

     The Expat ‘expat’ library, if found.

15.2.25.2 Result Variables
..........................

This module will set the following variables in your project:

‘EXPAT_INCLUDE_DIRS’

     where to find expat.h, etc.

‘EXPAT_LIBRARIES’

     the libraries to link against to use Expat.

‘EXPAT_FOUND’

     true if the Expat headers and libraries were found.

15.2.26 FindFLEX
----------------

Find Fast Lexical Analyzer (Flex) executable and provides a macro to
generate custom build rules

The module defines the following variables:

     FLEX_FOUND - True is flex executable is found
     FLEX_EXECUTABLE - the path to the flex executable
     FLEX_VERSION - the version of flex
     FLEX_LIBRARIES - The flex libraries
     FLEX_INCLUDE_DIRS - The path to the flex headers

The minimum required version of flex can be specified using the standard
syntax, e.g.  see find_package(FLEX 2.5.13).

If flex is found on the system, the module provides the macro:

     FLEX_TARGET(Name FlexInput FlexOutput
                 [COMPILE_FLAGS <string>]
                 [DEFINES_FILE <string>]
                 )

which creates a custom command to generate the ‘FlexOutput’ file from
the ‘FlexInput’ file.  If ‘COMPILE_FLAGS’ option is specified, the next
parameter is added to the flex command line.  If flex is configured to
output a header file, the ‘DEFINES_FILE’ option may be used to specify
its name.  Name is an alias used to get details of this custom command.
Indeed the macro defines the following variables:

     FLEX_${Name}_DEFINED - true is the macro ran successfully
     FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
     alias for FlexOutput
     FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
     FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.

Flex scanners often use tokens defined by Bison: the code generated by
Flex depends of the header generated by Bison.  This module also defines
a macro:

     ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)

which adds the required dependency between a scanner and a parser where
‘FlexTarget’ and ‘BisonTarget’ are the first parameters of respectively
‘FLEX_TARGET’ and ‘BISON_TARGET’ macros.

     ====================================================================
     Example:

     find_package(BISON)
     find_package(FLEX)

     BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
     FLEX_TARGET(MyScanner lexer.l  ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
     ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)

      include_directories(${CMAKE_CURRENT_BINARY_DIR})
      add_executable(Foo
         Foo.cc
         ${BISON_MyParser_OUTPUTS}
         ${FLEX_MyScanner_OUTPUTS}
      )
      target_link_libraries(Foo ${FLEX_LIBRARIES})
     ====================================================================

15.2.27 FindFLTK
----------------

Find the Fast Light Toolkit (FLTK) library

15.2.27.1 Input Variables
.........................

By default this module will search for all of the FLTK components and
add them to the ‘FLTK_LIBRARIES’ variable.  You can limit the components
which get placed in ‘FLTK_LIBRARIES’ by defining one or more of the
following three options:

‘FLTK_SKIP_OPENGL’

     Set to true to disable searching for the FLTK GL library

‘FLTK_SKIP_FORMS’

     Set to true to disable searching for the FLTK Forms library

‘FLTK_SKIP_IMAGES’

     Set to true to disable searching for the FLTK Images library

FLTK is composed also by a binary tool.  You can set the following
option:

‘FLTK_SKIP_FLUID’

     Set to true to not look for the FLUID binary

15.2.27.2 Result Variables
..........................

The following variables will be defined:

‘FLTK_FOUND’

     True if all components not skipped were found

‘FLTK_INCLUDE_DIR’

     Path to the include directory for FLTK header files

‘FLTK_LIBRARIES’

     List of the FLTK libraries found

‘FLTK_FLUID_EXECUTABLE’

     Path to the FLUID binary tool

‘FLTK_WRAP_UI’

     True if FLUID is found, used to enable the FLTK_WRAP_UI command

15.2.27.3 Cache Variables
.........................

The following cache variables are also available to set or use:

‘FLTK_BASE_LIBRARY_RELEASE’

     The FLTK base library (optimized)

‘FLTK_BASE_LIBRARY_DEBUG’

     The FLTK base library (debug)

‘FLTK_GL_LIBRARY_RELEASE’

     The FLTK GL library (optimized)

‘FLTK_GL_LIBRARY_DEBUG’

     The FLTK GL library (debug)

‘FLTK_FORMS_LIBRARY_RELEASE’

     The FLTK Forms library (optimized)

‘FLTK_FORMS_LIBRARY_DEBUG’

     The FLTK Forms library (debug)

‘FLTK_IMAGES_LIBRARY_RELEASE’

     The FLTK Images protobuf library (optimized)

‘FLTK_IMAGES_LIBRARY_DEBUG’

     The FLTK Images library (debug)

15.2.28 FindFLTK2
-----------------

Find the native FLTK 2.0 includes and library

The following settings are defined

     FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
     FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
     FLTK2_INCLUDE_DIR, where to find include files
     FLTK2_LIBRARIES, list of fltk2 libraries
     FLTK2_FOUND, Don't use FLTK2 if false.

The following settings should not be used in general.

     FLTK2_BASE_LIBRARY   = the full path to fltk2.lib
     FLTK2_GL_LIBRARY     = the full path to fltk2_gl.lib
     FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib

15.2.29 FindFontconfig
----------------------

New in version 3.14.

Find Fontconfig headers and library.

15.2.29.1 Imported Targets
..........................

‘Fontconfig::Fontconfig’

     The Fontconfig library, if found.

15.2.29.2 Result Variables
..........................

This will define the following variables in your project:

‘Fontconfig_FOUND’

     true if (the requested version of) Fontconfig is available.

‘Fontconfig_VERSION’

     the version of Fontconfig.

‘Fontconfig_LIBRARIES’

     the libraries to link against to use Fontconfig.

‘Fontconfig_INCLUDE_DIRS’

     where to find the Fontconfig headers.

‘Fontconfig_COMPILE_OPTIONS’

     this should be passed to target_compile_options(), if the target is
     not used for linking

15.2.30 FindFreetype
--------------------

Find the FreeType font renderer includes and library.

15.2.30.1 Imported Targets
..........................

This module defines the following IMPORTED target:

‘Freetype::Freetype’

     The Freetype ‘freetype’ library, if found

15.2.30.2 Result Variables
..........................

This module will set the following variables in your project:

‘FREETYPE_FOUND’

     true if the Freetype headers and libraries were found

‘FREETYPE_INCLUDE_DIRS’

     directories containing the Freetype headers.  This is the
     concatenation of the variables:

     ‘FREETYPE_INCLUDE_DIR_ft2build’

          directory holding the main Freetype API configuration header

     ‘FREETYPE_INCLUDE_DIR_freetype2’

          directory holding Freetype public headers

‘FREETYPE_LIBRARIES’

     the library to link against

‘FREETYPE_VERSION_STRING’

     the version of freetype found (since CMake 2.8.8)

15.2.30.3 Hints
...............

The user may set the environment variable ‘FREETYPE_DIR’ to the root
directory of a Freetype installation.

15.2.31 FindGCCXML
------------------

Find the GCC-XML front-end executable.

This module will define the following variables:

     GCCXML - the GCC-XML front-end executable.

15.2.32 FindGDAL
----------------

Find Geospatial Data Abstraction Library (GDAL).

15.2.32.1 IMPORTED Targets
..........................

This module defines IMPORTED target ‘GDAL::GDAL’ if GDAL has
been found.

15.2.32.2 Result Variables
..........................

This module will set the following variables in your project:

‘GDAL_FOUND’

     True if GDAL is found.

‘GDAL_INCLUDE_DIRS’

     Include directories for GDAL headers.

‘GDAL_LIBRARIES’

     Libraries to link to GDAL.

‘GDAL_VERSION’

     The version of GDAL found.

15.2.32.3 Cache variables
.........................

The following cache variables may also be set:

‘GDAL_LIBRARY’

     The libgdal library file.

‘GDAL_INCLUDE_DIR’

     The directory containing ‘gdal.h’.

15.2.32.4 Hints
...............

Set ‘GDAL_DIR’ or ‘GDAL_ROOT’ in the environment to specify the GDAL
installation prefix.

15.2.33 FindGettext
-------------------

Find GNU gettext tools

This module looks for the GNU gettext tools.  This module defines the
following values:

     GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
     GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
     GETTEXT_FOUND: True if gettext has been found.
     GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)

Additionally it provides the following macros:

GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )

     This will create a target "translations" which will convert the
     given input po files into the binary output mo file. If the
     ALL option is used, the translations will also be created when
     building the default target.

GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION
<destdir>] LANGUAGES <lang1> <lang2> … )

     Process the given pot file to mo files.
     If INSTALL_DESTINATION is given then automatically install rules will
     be created, the language subdirectory will be taken into account
     (by default use share/locale/).
     If ALL is specified, the pot file is processed when building the all traget.
     It creates a custom target "potfile".

GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
PO_FILES <po1> <po2> … )

     Process the given po files to mo files for the given language.
     If INSTALL_DESTINATION is given then automatically install rules will
     be created, the language subdirectory will be taken into account
     (by default use share/locale/).
     If ALL is specified, the po files are processed when building the all traget.
     It creates a custom target "pofiles".

     Note: If you wish to use the Gettext library (libintl), use
     FindIntl.

15.2.34 FindGIF
---------------

This finds the Graphics Interchange Format (GIF) library (‘giflib’)

15.2.34.1 Imported targets
..........................

This module defines the following IMPORTED target:

‘GIF::GIF’

     The ‘giflib’ library, if found.

15.2.34.2 Result variables
..........................

This module will set the following variables in your project:

‘GIF_FOUND’

     If false, do not try to use GIF.

‘GIF_INCLUDE_DIRS’

     where to find gif_lib.h, etc.

‘GIF_LIBRARIES’

     the libraries needed to use GIF.

‘GIF_VERSION’

     3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.

15.2.34.3 Cache variables
.........................

The following cache variables may also be set:

‘GIF_INCLUDE_DIR’

     where to find the GIF headers.

‘GIF_LIBRARY’

     where to find the GIF library.

15.2.34.4 Hints
...............

‘GIF_DIR’ is an environment variable that would correspond to the
‘./configure --prefix=$GIF_DIR’.

15.2.35 FindGit
---------------

The module defines the following ‘IMPORTED’ targets (when
CMAKE_ROLE is ‘PROJECT’):

‘Git::Git’

     Executable of the Git command-line client.

The module defines the following variables:

‘GIT_EXECUTABLE’

     Path to Git command-line client.

‘Git_FOUND’, ‘GIT_FOUND’

     True if the Git command-line client was found.

‘GIT_VERSION_STRING’

     The version of Git found.

Example usage:

     find_package(Git)
     if(Git_FOUND)
       message("Git found: ${GIT_EXECUTABLE}")
     endif()

15.2.36 FindGLEW
----------------

Find the OpenGL Extension Wrangler Library (GLEW)

15.2.36.1 Input Variables
.........................

The following variables may be set to influence this module’s behavior:

‘GLEW_USE_STATIC_LIBS’

     to find and create IMPORTED target for static linkage.

‘GLEW_VERBOSE’

     to output a detailed log of this module.

15.2.36.2 Imported Targets
..........................

This module defines the following Imported Targets.:

‘GLEW::glew’

     The GLEW shared library.

‘GLEW::glew_s’

     The GLEW static library, if ‘GLEW_USE_STATIC_LIBS’ is set to
     ‘TRUE’.

‘GLEW::GLEW’

     Duplicates either ‘GLEW::glew’ or ‘GLEW::glew_s’ based on
     availability.

15.2.36.3 Result Variables
..........................

This module defines the following variables:

‘GLEW_INCLUDE_DIRS’

     include directories for GLEW

‘GLEW_LIBRARIES’

     libraries to link against GLEW

‘GLEW_SHARED_LIBRARIES’

     libraries to link against shared GLEW

‘GLEW_STATIC_LIBRARIES’

     libraries to link against static GLEW

‘GLEW_FOUND’

     true if GLEW has been found and can be used

‘GLEW_VERSION’

     GLEW version

‘GLEW_VERSION_MAJOR’

     GLEW major version

‘GLEW_VERSION_MINOR’

     GLEW minor version

‘GLEW_VERSION_MICRO’

     GLEW micro version

15.2.37 FindGLUT
----------------

Find OpenGL Utility Toolkit (GLUT) library and include files.

15.2.37.1 IMPORTED Targets
..........................

This module defines the IMPORTED targets:

‘GLUT::GLUT’

     Defined if the system has GLUT.

15.2.37.2 Result Variables
..........................

This module sets the following variables:

     GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
     GLUT_LIBRARIES, the libraries to link against
     GLUT_FOUND, If false, do not try to use GLUT.

Also defined, but not for general use are:

     GLUT_glut_LIBRARY = the full path to the glut library.
     GLUT_Xmu_LIBRARY  = the full path to the Xmu library.
     GLUT_Xi_LIBRARY   = the full path to the Xi Library.

15.2.38 FindGnuplot
-------------------

this module looks for gnuplot

Once done this will define

     GNUPLOT_FOUND - system has Gnuplot
     GNUPLOT_EXECUTABLE - the Gnuplot executable
     GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)

GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.

15.2.39 FindGnuTLS
------------------

Find the GNU Transport Layer Security library (gnutls)

15.2.39.1 IMPORTED Targets
..........................

This module defines IMPORTED target ‘GnuTLS::GnuTLS’, if
gnutls has been found.

15.2.39.2 Result Variables
..........................

‘GNUTLS_FOUND’

     System has gnutls

‘GNUTLS_INCLUDE_DIR’

     The gnutls include directory

‘GNUTLS_LIBRARIES’

     The libraries needed to use gnutls

‘GNUTLS_DEFINITIONS’

     Compiler switches required for using gnutls

‘GNUTLS_VERSION’

     version of gnutls.

15.2.40 FindGSL
---------------

New in version 3.2.

Find the native GNU Scientific Library (GSL) includes and libraries.

The GNU Scientific Library (GSL) is a numerical library for C and C++
programmers.  It is free software under the GNU General Public License.

15.2.40.1 Imported Targets
..........................

If GSL is found, this module defines the following IMPORTED.
targets:

     GSL::gsl      - The main GSL library.
     GSL::gslcblas - The CBLAS support library used by GSL.

15.2.40.2 Result Variables
..........................

This module will set the following variables in your project:

     GSL_FOUND          - True if GSL found on the local system
     GSL_INCLUDE_DIRS   - Location of GSL header files.
     GSL_LIBRARIES      - The GSL libraries.
     GSL_VERSION        - The version of the discovered GSL install.

15.2.40.3 Hints
...............

Set ‘GSL_ROOT_DIR’ to a directory that contains a GSL installation.

This script expects to find libraries at ‘$GSL_ROOT_DIR/lib’ and the GSL
headers at ‘$GSL_ROOT_DIR/include/gsl’.  The library directory may
optionally provide Release and Debug folders.  If available, the
libraries named ‘gsld’, ‘gslblasd’ or ‘cblasd’ are recognized as debug
libraries.  For Unix-like systems, this script will use
‘$GSL_ROOT_DIR/bin/gsl-config’ (if found) to aid in the discovery of
GSL.

15.2.40.4 Cache Variables
.........................

This module may set the following variables depending on platform and
type of GSL installation discovered.  These variables may optionally be
set to help this module find the correct files:

     GSL_CBLAS_LIBRARY       - Location of the GSL CBLAS library.
     GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
     GSL_CONFIG_EXECUTABLE   - Location of the ``gsl-config`` script (if any).
     GSL_LIBRARY             - Location of the GSL library.
     GSL_LIBRARY_DEBUG       - Location of the debug GSL library (if any).

15.2.41 FindGTest
-----------------

Locate the Google C++ Testing Framework.

15.2.41.1 Imported targets
..........................

This module defines the following IMPORTED targets:

‘GTest::GTest’

     The Google Test ‘gtest’ library, if found; adds Thread::Thread
     automatically

‘GTest::Main’

     The Google Test ‘gtest_main’ library, if found

15.2.41.2 Result variables
..........................

This module will set the following variables in your project:

‘GTEST_FOUND’

     Found the Google Testing framework

‘GTEST_INCLUDE_DIRS’

     the directory containing the Google Test headers

The library variables below are set as normal variables.  These contain
debug/optimized keywords when a debugging library is found.

‘GTEST_LIBRARIES’

     The Google Test ‘gtest’ library; note it also requires linking with
     an appropriate thread library

‘GTEST_MAIN_LIBRARIES’

     The Google Test ‘gtest_main’ library

‘GTEST_BOTH_LIBRARIES’

     Both ‘gtest’ and ‘gtest_main’

15.2.41.3 Cache variables
.........................

The following cache variables may also be set:

‘GTEST_ROOT’

     The root directory of the Google Test installation (may also be set
     as an environment variable)

‘GTEST_MSVC_SEARCH’

     If compiling with MSVC, this variable can be set to ‘MT’ or ‘MD’
     (the default) to enable searching a GTest build tree

15.2.41.4 Example usage
.......................

     enable_testing()
     find_package(GTest REQUIRED)

     add_executable(foo foo.cc)
     target_link_libraries(foo GTest::GTest GTest::Main)

     add_test(AllTestsInFoo foo)

15.2.41.5 Deeper integration with CTest
.......................................

See GoogleTest for information on the
gtest_add_tests() and gtest_discover_tests() commands.

15.2.42 FindGTK
---------------

Find GTK, glib and GTKGLArea

     GTK_INCLUDE_DIR   - Directories to include to use GTK
     GTK_LIBRARIES     - Files to link against to use GTK
     GTK_FOUND         - GTK was found
     GTK_GL_FOUND      - GTK's GL features were found

15.2.43 FindGTK2
----------------

Find the GTK2 widget libraries and several of its other optional
components like ‘gtkmm’, ‘glade’, and ‘glademm’.

Specify one or more of the following components as you call this find
module.  See example below.

   * ‘gtk’

   * ‘gtkmm’

   * ‘glade’

   * ‘glademm’

15.2.43.1 Result Variables
..........................

The following variables will be defined for your use

‘GTK2_FOUND’

     Were all of your specified components found?

‘GTK2_INCLUDE_DIRS’

     All include directories

‘GTK2_LIBRARIES’

     All libraries

‘GTK2_TARGETS’

     All imported targets

‘GTK2_DEFINITIONS’

     Additional compiler flags

‘GTK2_VERSION’

     The version of GTK2 found (x.y.z)

‘GTK2_MAJOR_VERSION’

     The major version of GTK2

‘GTK2_MINOR_VERSION’

     The minor version of GTK2

‘GTK2_PATCH_VERSION’

     The patch version of GTK2

15.2.43.2 Input Variables
.........................

Optional variables you can define prior to calling this module:

‘GTK2_DEBUG’

     Enables verbose debugging of the module

‘GTK2_ADDITIONAL_SUFFIXES’

     Allows defining additional directories to search for include files

15.2.43.3 Example Usage
.......................

Call find_package() once.  Here are some examples to pick
from:

Require GTK 2.6 or later:

     find_package(GTK2 2.6 REQUIRED gtk)

Require GTK 2.10 or later and Glade:

     find_package(GTK2 2.10 REQUIRED gtk glade)

Search for GTK/GTKMM 2.8 or later:

     find_package(GTK2 2.8 COMPONENTS gtk gtkmm)

Use the results:

     if(GTK2_FOUND)
       include_directories(${GTK2_INCLUDE_DIRS})
       add_executable(mygui mygui.cc)
       target_link_libraries(mygui ${GTK2_LIBRARIES})
     endif()

15.2.44 FindHDF5
----------------

Find Hierarchical Data Format (HDF5), a library for reading and writing
self describing array data.

This module invokes the ‘HDF5’ wrapper compiler that should be installed
alongside ‘HDF5’.  Depending upon the ‘HDF5’ Configuration, the wrapper
compiler is called either ‘h5cc’ or ‘h5pcc’.  If this succeeds, the
module will then call the compiler with the show argument to see what
flags are used when compiling an ‘HDF5’ client application.

The module will optionally accept the ‘COMPONENTS’ argument.  If no
‘COMPONENTS’ are specified, then the find module will default to finding
only the ‘HDF5’ C library.  If one or more ‘COMPONENTS’ are specified,
the module will attempt to find the language bindings for the specified
components.  The valid components are ‘C’, ‘CXX’, ‘Fortran’, ‘HL’.  ‘HL’
refers to the “high-level” HDF5 functions for C and Fortran.  If the
‘COMPONENTS’ argument is not given, the module will attempt to find only
the C bindings.  For example, to use Fortran HDF5 and HDF5-HL functions,
do: ‘find_package(HDF5 COMPONENTS Fortran HL)’.

This module will read the variable ‘HDF5_USE_STATIC_LIBRARIES’ to
determine whether or not to prefer a static link to a dynamic link for
‘HDF5’ and all of it’s dependencies.  To use this feature, make sure
that the ‘HDF5_USE_STATIC_LIBRARIES’ variable is set before the call to
find_package.

Both the serial and parallel ‘HDF5’ wrappers are considered and the
first directory to contain either one will be used.  In the event that
both appear in the same directory the serial version is preferentially
selected.  This behavior can be reversed by setting the variable
‘HDF5_PREFER_PARALLEL’ to ‘TRUE’.

In addition to finding the includes and libraries required to compile an
‘HDF5’ client application, this module also makes an effort to find
tools that come with the ‘HDF5’ distribution that may be useful for
regression testing.

15.2.44.1 Result Variables
..........................

This module will set the following variables in your project:

‘HDF5_FOUND’

     HDF5 was found on the system

‘HDF5_VERSION’

     HDF5 library version

‘HDF5_INCLUDE_DIRS’

     Location of the HDF5 header files

‘HDF5_DEFINITIONS’

     Required compiler definitions for HDF5

‘HDF5_LIBRARIES’

     Required libraries for all requested bindings

‘HDF5_HL_LIBRARIES’

     Required libraries for the HDF5 high level API for all bindings, if
     the ‘HL’ component is enabled

Available components are: ‘C’ ‘CXX’ ‘Fortran’ and ‘HL’.  For each
enabled language binding, a corresponding ‘HDF5_${LANG}_LIBRARIES’
variable, and potentially ‘HDF5_${LANG}_DEFINITIONS’, will be defined.
If the ‘HL’ component is enabled, then an ‘HDF5_${LANG}_HL_LIBRARIES’
will also be defined.  With all components enabled, the following
variables will be defined:

‘HDF5_C_DEFINITIONS’

     Required compiler definitions for HDF5 C bindings

‘HDF5_CXX_DEFINITIONS’

     Required compiler definitions for HDF5 C++ bindings

‘HDF5_Fortran_DEFINITIONS’

     Required compiler definitions for HDF5 Fortran bindings

‘HDF5_C_INCLUDE_DIRS’

     Required include directories for HDF5 C bindings

‘HDF5_CXX_INCLUDE_DIRS’

     Required include directories for HDF5 C++ bindings

‘HDF5_Fortran_INCLUDE_DIRS’

     Required include directories for HDF5 Fortran bindings

‘HDF5_C_LIBRARIES’

     Required libraries for the HDF5 C bindings

‘HDF5_CXX_LIBRARIES’

     Required libraries for the HDF5 C++ bindings

‘HDF5_Fortran_LIBRARIES’

     Required libraries for the HDF5 Fortran bindings

‘HDF5_C_HL_LIBRARIES’

     Required libraries for the high level C bindings

‘HDF5_CXX_HL_LIBRARIES’

     Required libraries for the high level C++ bindings

‘HDF5_Fortran_HL_LIBRARIES’

     Required libraries for the high level Fortran bindings.

‘HDF5_IS_PARALLEL’

     HDF5 library has parallel IO support

‘HDF5_C_COMPILER_EXECUTABLE’

     path to the HDF5 C wrapper compiler

‘HDF5_CXX_COMPILER_EXECUTABLE’

     path to the HDF5 C++ wrapper compiler

‘HDF5_Fortran_COMPILER_EXECUTABLE’

     path to the HDF5 Fortran wrapper compiler

‘HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE’

     path to the primary C compiler which is also the HDF5 wrapper

‘HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE’

     path to the primary C++ compiler which is also the HDF5 wrapper

‘HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE’

     path to the primary Fortran compiler which is also the HDF5 wrapper

‘HDF5_DIFF_EXECUTABLE’

     path to the HDF5 dataset comparison tool

With all components enabled, the following targets will be defined:

     ``hdf5::hdf5``
     ``hdf5::hdf5_hl_cpp``
     ``hdf5::hdf5_fortran``
     ``hdf5::hdf5_hl``
     ``hdf5::hdf5_hl_cpp``
     ``hdf5::hdf5_hl_fortran``
     ``hdf5::h5diff``

15.2.44.2 Hints
...............

The following variables can be set to guide the search for HDF5
libraries and includes:

‘HDF5_PREFER_PARALLEL’

     set ‘true’ to prefer parallel HDF5 (by default, serial is
     preferred)

‘HDF5_FIND_DEBUG’

     Set ‘true’ to get extra debugging output.

‘HDF5_NO_FIND_PACKAGE_CONFIG_FILE’

     Set ‘true’ to skip trying to find ‘hdf5-config.cmake’.

15.2.45 FindHg
--------------

Extract information from a mercurial working copy.

The module defines the following variables:

     HG_EXECUTABLE - path to mercurial command line client (hg)
     HG_FOUND - true if the command line client was found
     HG_VERSION_STRING - the version of mercurial found

If the command line client executable is found the following macro is
defined:

     HG_WC_INFO(<dir> <var-prefix>)

Hg_WC_INFO extracts information of a mercurial working copy at a given
location.  This macro defines the following variables:

     <var-prefix>_WC_CHANGESET - current changeset
     <var-prefix>_WC_REVISION - current revision

Example usage:

     find_package(Hg)
     if(HG_FOUND)
       message("hg found: ${HG_EXECUTABLE}")
       HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
       message("Current revision is ${Project_WC_REVISION}")
       message("Current changeset is ${Project_WC_CHANGESET}")
     endif()

15.2.46 FindHSPELL
------------------

Try to find Hebrew spell-checker (Hspell) and morphology engine.

Once done this will define

     HSPELL_FOUND - system has Hspell
     HSPELL_INCLUDE_DIR - the Hspell include directory
     HSPELL_LIBRARIES - The libraries needed to use Hspell
     HSPELL_DEFINITIONS - Compiler switches required for using Hspell

     HSPELL_VERSION_STRING - The version of Hspell found (x.y)
     HSPELL_MAJOR_VERSION  - the major version of Hspell
     HSPELL_MINOR_VERSION  - The minor version of Hspell

15.2.47 FindHTMLHelp
--------------------

This module looks for Microsoft HTML Help Compiler

It defines:

     HTML_HELP_COMPILER     : full path to the Compiler (hhc.exe)
     HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
     HTML_HELP_LIBRARY      : full path to the library (htmlhelp.lib)

15.2.48 FindIce
---------------

New in version 3.1.

Find the ZeroC Internet Communication Engine (ICE) programs, libraries
and datafiles.

This module supports multiple components.  Components can include any
of: ‘Freeze’, ‘Glacier2’, ‘Ice’, ‘IceBox’, ‘IceDB’, ‘IceDiscovery’,
‘IceGrid’, ‘IceLocatorDiscovery’, ‘IcePatch’, ‘IceSSL’, ‘IceStorm’,
‘IceUtil’, ‘IceXML’, or ‘Slice’.

Ice 3.7 and later also include C++11-specific components:
‘Glacier2++11’, ‘Ice++11’, ‘IceBox++11’, ‘IceDiscovery++11’ ‘IceGrid’,
‘IceLocatorDiscovery++11’, ‘IceSSL++11’, ‘IceStorm++11’

Note that the set of supported components is Ice version-specific.

This module reports information about the Ice installation in several
variables.  General variables:

     Ice_VERSION - Ice release version
     Ice_FOUND - true if the main programs and libraries were found
     Ice_LIBRARIES - component libraries to be linked
     Ice_INCLUDE_DIRS - the directories containing the Ice headers
     Ice_SLICE_DIRS - the directories containing the Ice slice interface
                      definitions

Imported targets:

     Ice::<C>

Where ‘<C>’ is the name of an Ice component, for example ‘Ice::Glacier2’
or ‘Ice++11’.

Ice slice programs are reported in:

     Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
     Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
     Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
     Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
     Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
     Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
     Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
     Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
     Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
     Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
     Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
     Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
     Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable

Ice programs are reported in:

     Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
     Ice_ICEBOX_EXECUTABLE - path to icebox executable
     Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
     Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
     Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
     Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
     Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
     Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
     Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
     Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
     Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
     Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
     Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
     Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
     Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
     Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
     Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
     Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
     Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
     Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable

Ice db programs (Windows only; standard system versions on all other
platforms) are reported in:

     Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
     Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
     Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
     Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
     Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
     Ice_DB_LOAD_EXECUTABLE - path to db_load executable
     Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
     Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
     Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
     Ice_DB_STAT_EXECUTABLE - path to db_stat executable
     Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
     Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
     Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
     Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
     Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable

Ice component libraries are reported in:

     Ice_<C>_FOUND - ON if component was found
     Ice_<C>_LIBRARIES - libraries for component

Note that ‘<C>’ is the uppercased name of the component.

This module reads hints about search results from:

     Ice_HOME - the root of the Ice installation

The environment variable ‘ICE_HOME’ may also be used; the Ice_HOME
variable takes precedence.

     Note: On Windows, Ice 3.7.0 and later provide libraries via the
     NuGet package manager.  Appropriate NuGet packages will be searched
     for using ‘CMAKE_PREFIX_PATH’, or alternatively ‘Ice_HOME’ may be
     set to the location of a specific NuGet package to restrict the
     search.

The following cache variables may also be set:

     Ice_<P>_EXECUTABLE - the path to executable <P>
     Ice_INCLUDE_DIR - the directory containing the Ice headers
     Ice_SLICE_DIR - the directory containing the Ice slice interface
                     definitions
     Ice_<C>_LIBRARY - the library for component <C>

     Note: In most cases none of the above variables will require
     setting, unless multiple Ice versions are available and a specific
     version is required.  On Windows, the most recent version of Ice
     will be found through the registry.  On Unix, the programs, headers
     and libraries will usually be in standard locations, but
     Ice_SLICE_DIRS might not be automatically detected (commonly known
     locations are searched).  All the other variables are defaulted
     using Ice_HOME, if set.  It’s possible to set Ice_HOME and
     selectively specify alternative locations for the other components;
     this might be required for e.g.  newer versions of Visual Studio if
     the heuristics are not sufficient to identify the correct programs
     and libraries for the specific Visual Studio version.

Other variables one may set to control this module are:

     Ice_DEBUG - Set to ON to enable debug output from FindIce.

15.2.49 FindIconv
-----------------

New in version 3.11.

This module finds the ‘iconv()’ POSIX.1 functions on the system.  These
functions might be provided in the regular C library or externally in
the form of an additional library.

The following variables are provided to indicate iconv support:

 -- Variable: Iconv_FOUND

     Variable indicating if the iconv support was found.

 -- Variable: Iconv_INCLUDE_DIRS

     The directories containing the iconv headers.

 -- Variable: Iconv_LIBRARIES

     The iconv libraries to be linked.

 -- Variable: Iconv_IS_BUILT_IN

     A variable indicating whether iconv support is stemming from the C
     library or not.  Even if the C library provides ‘iconv()’, the
     presence of an external ‘libiconv’ implementation might lead to
     this being false.

Additionally, the following IMPORTED target is being
provided:

 -- Variable: Iconv::Iconv

     Imported target for using iconv.

The following cache variables may also be set:

 -- Variable: Iconv_INCLUDE_DIR

     The directory containing the iconv headers.

 -- Variable: Iconv_LIBRARY

     The iconv library (if not implicitly given in the C library).

     Note: On POSIX platforms, iconv might be part of the C library and
     the cache variables ‘Iconv_INCLUDE_DIR’ and ‘Iconv_LIBRARY’ might
     be empty.

15.2.50 FindIcotool
-------------------

Find icotool

This module looks for icotool.  Convert and create Win32 icon and cursor
files.  This module defines the following values:

     ICOTOOL_EXECUTABLE: the full path to the icotool tool.
     ICOTOOL_FOUND: True if icotool has been found.
     ICOTOOL_VERSION_STRING: the version of icotool found.

15.2.51 FindICU
---------------

New in version 3.7.

Find the International Components for Unicode (ICU) libraries and
programs.

This module supports multiple components.  Components can include any
of: ‘data’, ‘i18n’, ‘io’, ‘le’, ‘lx’, ‘test’, ‘tu’ and ‘uc’.

Note that on Windows ‘data’ is named ‘dt’ and ‘i18n’ is named ‘in’; any
of the names may be used, and the appropriate platform-specific library
name will be automatically selected.

This module reports information about the ICU installation in several
variables.  General variables:

     ICU_VERSION - ICU release version
     ICU_FOUND - true if the main programs and libraries were found
     ICU_LIBRARIES - component libraries to be linked
     ICU_INCLUDE_DIRS - the directories containing the ICU headers

Imported targets:

     ICU::<C>

Where ‘<C>’ is the name of an ICU component, for example ‘ICU::i18n’.

ICU programs are reported in:

     ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
     ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
     ICU_GENBRK_EXECUTABLE - path to genbrk executable
     ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
     ICU_GENRB_EXECUTABLE - path to genrb executable
     ICU_GENDICT_EXECUTABLE - path to gendict executable
     ICU_DERB_EXECUTABLE - path to derb executable
     ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
     ICU_UCONV_EXECUTABLE - path to uconv executable
     ICU_GENCFU_EXECUTABLE - path to gencfu executable
     ICU_MAKECONV_EXECUTABLE - path to makeconv executable
     ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
     ICU_GENCCODE_EXECUTABLE - path to genccode executable
     ICU_GENSPREP_EXECUTABLE - path to gensprep executable
     ICU_ICUPKG_EXECUTABLE - path to icupkg executable
     ICU_GENCMN_EXECUTABLE - path to gencmn executable

ICU component libraries are reported in:

     ICU_<C>_FOUND - ON if component was found
     ICU_<C>_LIBRARIES - libraries for component

ICU datafiles are reported in:

     ICU_MAKEFILE_INC - Makefile.inc
     ICU_PKGDATA_INC - pkgdata.inc

Note that ‘<C>’ is the uppercased name of the component.

This module reads hints about search results from:

     ICU_ROOT - the root of the ICU installation

The environment variable ‘ICU_ROOT’ may also be used; the ICU_ROOT
variable takes precedence.

The following cache variables may also be set:

     ICU_<P>_EXECUTABLE - the path to executable <P>
     ICU_INCLUDE_DIR - the directory containing the ICU headers
     ICU_<C>_LIBRARY - the library for component <C>

     Note: In most cases none of the above variables will require
     setting, unless multiple ICU versions are available and a specific
     version is required.

Other variables one may set to control this module are:

     ICU_DEBUG - Set to ON to enable debug output from FindICU.

15.2.52 FindImageMagick
-----------------------

Find ImageMagick binary suite.

This module will search for a set of ImageMagick tools specified as
components in the find_package() call.  Typical components
include, but are not limited to (future versions of ImageMagick might
have additional components not listed here):

     animate
     compare
     composite
     conjure
     convert
     display
     identify
     import
     mogrify
     montage
     stream

If no component is specified in the find_package() call, then
it only searches for the ImageMagick executable directory.  This code
defines the following variables:

     ImageMagick_FOUND                  - TRUE if all components are found.
     ImageMagick_EXECUTABLE_DIR         - Full path to executables directory.
     ImageMagick_<component>_FOUND      - TRUE if <component> is found.
     ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
     ImageMagick_VERSION_STRING         - the version of ImageMagick found
                                          (since CMake 2.8.8)

‘ImageMagick_VERSION_STRING’ will not work for old versions like 5.2.3.

There are also components for the following ImageMagick APIs:

     Magick++
     MagickWand
     MagickCore

For these components the following variables are set:

     ImageMagick_FOUND                    - TRUE if all components are found.
     ImageMagick_INCLUDE_DIRS             - Full paths to all include dirs.
     ImageMagick_LIBRARIES                - Full paths to all libraries.
     ImageMagick_<component>_FOUND        - TRUE if <component> is found.
     ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
     ImageMagick_<component>_LIBRARIES    - Full path to <component> libraries.

Example Usages:

     find_package(ImageMagick)
     find_package(ImageMagick COMPONENTS convert)
     find_package(ImageMagick COMPONENTS convert mogrify display)
     find_package(ImageMagick COMPONENTS Magick++)
     find_package(ImageMagick COMPONENTS Magick++ convert)

Note that the standard find_package() features are supported
(i.e., ‘QUIET’, ‘REQUIRED’, etc.).

15.2.53 FindIntl
----------------

New in version 3.2.

Find the Gettext libintl headers and libraries.

This module reports information about the Gettext libintl installation
in several variables.  General variables:

     Intl_FOUND - true if the libintl headers and libraries were found
     Intl_INCLUDE_DIRS - the directory containing the libintl headers
     Intl_LIBRARIES - libintl libraries to be linked

The following cache variables may also be set:

     Intl_INCLUDE_DIR - the directory containing the libintl headers
     Intl_LIBRARY - the libintl library (if any)

     Note: On some platforms, such as Linux with GNU libc, the gettext
     functions are present in the C standard library and libintl is not
     required.  ‘Intl_LIBRARIES’ will be empty in this case.

     Note: If you wish to use the Gettext tools (‘msgmerge’, ‘msgfmt’,
     etc.), use FindGettext.

15.2.54 FindITK
---------------

This module no longer exists.

This module existed in versions of CMake prior to 3.1, but became only a
thin wrapper around ‘find_package(ITK NO_MODULE)’ to provide
compatibility for projects using long-outdated conventions.  Now
‘find_package(ITK)’ will search for ‘ITKConfig.cmake’ directly.

15.2.55 FindJasper
------------------

Try to find the Jasper JPEG2000 library

Once done this will define

     JASPER_FOUND - system has Jasper
     JASPER_INCLUDE_DIR - the Jasper include directory
     JASPER_LIBRARIES - the libraries needed to use Jasper
     JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)

15.2.56 FindJava
----------------

Find Java

This module finds if Java is installed and determines where the include
files and libraries are.  The caller may set variable ‘JAVA_HOME’ to
specify a Java installation prefix explicitly.

See also the FindJNI module to find Java Native Interface
(JNI).

Specify one or more of the following components as you call this find
module.  See example below.

     Runtime     = Java Runtime Environment used to execute Java byte-compiled applications
     Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
     IdlJ        = Interface Description Language (IDL) to Java compiler
     JarSigner   = Signer and verifier tool for Java Archive (JAR) files

This module sets the following result variables:

     Java_JAVA_EXECUTABLE      = the full path to the Java runtime
     Java_JAVAC_EXECUTABLE     = the full path to the Java compiler
     Java_JAVAH_EXECUTABLE     = the full path to the Java header generator
     Java_JAVADOC_EXECUTABLE   = the full path to the Java documentation generator
     Java_IDLJ_EXECUTABLE      = the full path to the Java idl compiler
     Java_JAR_EXECUTABLE       = the full path to the Java archiver
     Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
     Java_VERSION_STRING       = Version of java found, eg. 1.6.0_12
     Java_VERSION_MAJOR        = The major version of the package found.
     Java_VERSION_MINOR        = The minor version of the package found.
     Java_VERSION_PATCH        = The patch version of the package found.
     Java_VERSION_TWEAK        = The tweak version of the package found (after '_')
     Java_VERSION              = This is set to: $major[.$minor[.$patch[.$tweak]]]

The minimum required version of Java can be specified using the
find_package() syntax, e.g.

     find_package(Java 1.8)

NOTE: ‘${Java_VERSION}’ and ‘${Java_VERSION_STRING}’ are not guaranteed
to be identical.  For example some java version may return:
‘Java_VERSION_STRING = 1.8.0_17’ and ‘Java_VERSION = 1.8.0.17’

another example is the Java OEM, with: ‘Java_VERSION_STRING = 1.8.0-oem’
and ‘Java_VERSION = 1.8.0’

For these components the following variables are set:

     Java_FOUND                    - TRUE if all components are found.
     Java_<component>_FOUND        - TRUE if <component> is found.

Example Usages:

     find_package(Java)
     find_package(Java 1.8 REQUIRED)
     find_package(Java COMPONENTS Runtime)
     find_package(Java COMPONENTS Development)

15.2.57 FindJNI
---------------

Find Java Native Interface (JNI) libraries.

JNI enables Java code running in a Java Virtual Machine (JVM) to call
and be called by native applications and libraries written in other
languages such as C, C++.

This module finds if Java is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  The caller may set variable ‘JAVA_HOME’ to specify a Java
installation prefix explicitly.

15.2.57.1 Result Variables
..........................

This module sets the following result variables:

‘JNI_INCLUDE_DIRS’

     the include dirs to use

‘JNI_LIBRARIES’

     the libraries to use (JAWT and JVM)

‘JNI_FOUND’

     TRUE if JNI headers and libraries were found.

15.2.57.2 Cache Variables
.........................

The following cache variables are also available to set or use:

‘JAVA_AWT_LIBRARY’

     the path to the Java AWT Native Interface (JAWT) library

‘JAVA_JVM_LIBRARY’

     the path to the Java Virtual Machine (JVM) library

‘JAVA_INCLUDE_PATH’

     the include path to jni.h

‘JAVA_INCLUDE_PATH2’

     the include path to jni_md.h and jniport.h

‘JAVA_AWT_INCLUDE_PATH’

     the include path to jawt.h

15.2.58 FindJPEG
----------------

Find the Joint Photographic Experts Group (JPEG) library (‘libjpeg’)

15.2.58.1 Imported targets
..........................

This module defines the following IMPORTED targets:

‘JPEG::JPEG’

     The JPEG library, if found.

15.2.58.2 Result variables
..........................

This module will set the following variables in your project:

‘JPEG_FOUND’

     If false, do not try to use JPEG.

‘JPEG_INCLUDE_DIRS’

     where to find jpeglib.h, etc.

‘JPEG_LIBRARIES’

     the libraries needed to use JPEG.

‘JPEG_VERSION’

     the version of the JPEG library found

15.2.58.3 Cache variables
.........................

The following cache variables may also be set:

‘JPEG_INCLUDE_DIRS’

     where to find jpeglib.h, etc.

‘JPEG_LIBRARY_RELEASE’

     where to find the JPEG library (optimized).

‘JPEG_LIBRARY_DEBUG’

     where to find the JPEG library (debug).

15.2.58.4 Obsolete variables
............................

‘JPEG_INCLUDE_DIR’

     where to find jpeglib.h, etc.  (same as JPEG_INCLUDE_DIRS)

‘JPEG_LIBRARY’

     where to find the JPEG library.

15.2.59 FindKDE3
----------------

Find the KDE3 include and library dirs, KDE preprocessors and define a
some macros

This module defines the following variables:

‘KDE3_DEFINITIONS’

     compiler definitions required for compiling KDE software

‘KDE3_INCLUDE_DIR’

     the KDE include directory

‘KDE3_INCLUDE_DIRS’

     the KDE and the Qt include directory, for use with
     include_directories()

‘KDE3_LIB_DIR’

     the directory where the KDE libraries are installed, for use with
     link_directories()

‘QT_AND_KDECORE_LIBS’

     this contains both the Qt and the kdecore library

‘KDE3_DCOPIDL_EXECUTABLE’

     the dcopidl executable

‘KDE3_DCOPIDL2CPP_EXECUTABLE’

     the dcopidl2cpp executable

‘KDE3_KCFGC_EXECUTABLE’

     the kconfig_compiler executable

‘KDE3_FOUND’

     set to TRUE if all of the above has been found

The following user adjustable options are provided:

‘KDE3_BUILD_TESTS’

     enable this to build KDE testcases

It also adds the following macros (from ‘KDE3Macros.cmake’) ‘SRCS_VAR’
is always the variable which contains the list of source files for your
application or library.

KDE3_AUTOMOC(file1 … fileN)

     Call this if you want to have automatic moc file handling.
     This means if you include "foo.moc" in the source file foo.cpp
     a moc file for the header foo.h will be created automatically.
     You can set the property SKIP_AUTOMAKE using set_source_files_properties()
     to exclude some files in the list from being processed.

KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )

     If you don't use the KDE3_AUTOMOC() macro, for the files
     listed here moc files will be created (named "foo.moc.cpp")

KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )

     Use this to generate DCOP skeletions from the listed headers.

KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )

     Use this to generate DCOP stubs from the listed headers.

KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )

     Use this to add the Qt designer ui files to your application/library.

KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )

     Use this to add KDE kconfig compiler files to your application/library.

KDE3_INSTALL_LIBTOOL_FILE(target)

     This will create and install a simple libtool file for the given target.

KDE3_ADD_EXECUTABLE(name file1 … fileN )

     Currently identical to add_executable(), may provide some advanced
     features in the future.

KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )

     Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
     If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
     otherwise it won't.
     It creates and installs an appropriate libtool la-file.

KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )

     Create a KDE application in the form of a module loadable via kdeinit.
     A library named kdeinit_<name> will be created and a small executable
     which links to it.

The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
longer supported.

Author: Alexander Neundorf <<neundorf@kde.org>>

15.2.60 FindKDE4
----------------

Find KDE4 and provide all necessary variables and macros to compile
software for it.  It looks for KDE 4 in the following directories in the
given order:

     CMAKE_INSTALL_PREFIX
     KDEDIRS
     /opt/kde4

Please look in ‘FindKDE4Internal.cmake’ and ‘KDE4Macros.cmake’ for more
information.  They are installed with the KDE 4 libraries in
$KDEDIRS/share/apps/cmake/modules/.

Author: Alexander Neundorf <<neundorf@kde.org>>

15.2.61 FindLAPACK
------------------

Find Linear Algebra PACKage (LAPACK) library

This module finds an installed Fortran library that implements the
LAPACK linear-algebra interface (see ‘http://www.netlib.org/lapack/’).

The approach follows that taken for the ‘autoconf’ macro file,
‘acx_lapack.m4’ (distributed at
‘http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html’).

15.2.61.1 Input Variables
.........................

The following variables may be set to influence this module’s behavior:

‘BLA_STATIC’

     if ‘ON’ use static linkage

‘BLA_VENDOR’

     If set, checks only the specified vendor, if not set checks all the
     possibilities.  List of vendors valid in this module:

        * ‘FlexiBLAS’

        * ‘OpenBLAS’

        * ‘FLAME’

        * ‘Intel10_32’ (intel mkl v10 32 bit, threaded code)

        * ‘Intel10_64lp’ (intel mkl v10+ 64 bit, threaded code, lp64
          model)

        * ‘Intel10_64lp_seq’ (intel mkl v10+ 64 bit, sequential code,
          lp64 model)

        * ‘Intel10_64ilp’ (intel mkl v10+ 64 bit, threaded code, ilp64
          model)

        * ‘Intel10_64ilp_seq’ (intel mkl v10+ 64 bit, sequential code,
          ilp64 model)

        * ‘Intel10_64_dyn’ (intel mkl v10+ 64 bit, single dynamic
          library)

        * ‘Intel’ (obsolete versions of mkl 32 and 64 bit)

        * ‘ACML’

        * ‘Apple’

        * ‘NAS’

        * ‘Arm’

        * ‘Arm_mp’

        * ‘Arm_ilp64’

        * ‘Arm_ilp64_mp’

        * ‘Generic’

‘BLA_F95’

     if ‘ON’ tries to find the BLAS95/LAPACK95 interfaces

15.2.61.2 Imported targets
..........................

This module defines the following IMPORTED target:

‘LAPACK::LAPACK’

     The libraries to use for LAPACK, if found.

15.2.61.3 Result Variables
..........................

This module defines the following variables:

‘LAPACK_FOUND’

     library implementing the LAPACK interface is found

‘LAPACK_LINKER_FLAGS’

     uncached list of required linker flags (excluding ‘-l’ and ‘-L’).

‘LAPACK_LIBRARIES’

     uncached list of libraries (using full path name) to link against
     to use LAPACK

‘LAPACK95_LIBRARIES’

     uncached list of libraries (using full path name) to link against
     to use LAPACK95

‘LAPACK95_FOUND’

     library implementing the LAPACK95 interface is found

     Note: C, CXX or Fortran must be enabled to detect a BLAS/LAPACK
     library.  C or CXX must be enabled to use Intel Math Kernel Library
     (MKL).

     For example, to use Intel MKL libraries and/or Intel compiler:

          set(BLA_VENDOR Intel10_64lp)
          find_package(LAPACK)

15.2.62 FindLATEX
-----------------

Find LaTeX

This module finds an installed LaTeX and determines the location of the
compiler.  Additionally the module looks for Latex-related software like
BibTeX.

This module sets the following result variables:

     LATEX_FOUND:          whether found Latex and requested components
     LATEX_<component>_FOUND:  whether found <component>
     LATEX_COMPILER:       path to the LaTeX compiler
     PDFLATEX_COMPILER:    path to the PdfLaTeX compiler
     XELATEX_COMPILER:     path to the XeLaTeX compiler
     LUALATEX_COMPILER:    path to the LuaLaTeX compiler
     BIBTEX_COMPILER:      path to the BibTeX compiler
     BIBER_COMPILER:       path to the Biber compiler
     MAKEINDEX_COMPILER:   path to the MakeIndex compiler
     XINDY_COMPILER:       path to the xindy compiler
     DVIPS_CONVERTER:      path to the DVIPS converter
     DVIPDF_CONVERTER:     path to the DVIPDF converter
     PS2PDF_CONVERTER:     path to the PS2PDF converter
     PDFTOPS_CONVERTER:    path to the pdftops converter
     LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
     HTLATEX_COMPILER:     path to the htlatex compiler

Possible components are:

     PDFLATEX
     XELATEX
     LUALATEX
     BIBTEX
     BIBER
     MAKEINDEX
     XINDY
     DVIPS
     DVIPDF
     PS2PDF
     PDFTOPS
     LATEX2HTML
     HTLATEX

Example Usages:

     find_package(LATEX)
     find_package(LATEX COMPONENTS PDFLATEX)
     find_package(LATEX COMPONENTS BIBTEX PS2PDF)

15.2.63 FindLibArchive
----------------------

Find libarchive library and headers.  Libarchive is multi-format archive
and compression library.

The module defines the following variables:

     LibArchive_FOUND        - true if libarchive was found
     LibArchive_INCLUDE_DIRS - include search path
     LibArchive_LIBRARIES    - libraries to link
     LibArchive_VERSION      - libarchive 3-component version number

The module defines the following ‘IMPORTED’ targets:

     LibArchive::LibArchive  - target for linking against libarchive

15.2.64 FindLibinput
--------------------

New in version 3.14.

Find libinput headers and library.

15.2.64.1 Imported Targets
..........................

‘Libinput::Libinput’

     The libinput library, if found.

15.2.64.2 Result Variables
..........................

This will define the following variables in your project:

‘Libinput_FOUND’

     true if (the requested version of) libinput is available.

‘Libinput_VERSION’

     the version of libinput.

‘Libinput_LIBRARIES’

     the libraries to link against to use libinput.

‘Libinput_INCLUDE_DIRS’

     where to find the libinput headers.

‘Libinput_COMPILE_OPTIONS’

     this should be passed to target_compile_options(), if the target is
     not used for linking

15.2.65 FindLibLZMA
-------------------

Find LZMA compression algorithm headers and library.

15.2.65.1 Imported Targets
..........................

This module defines IMPORTED target ‘LibLZMA::LibLZMA’, if
liblzma has been found.

15.2.65.2 Result variables
..........................

This module will set the following variables in your project:

‘LIBLZMA_FOUND’

     True if liblzma headers and library were found.

‘LIBLZMA_INCLUDE_DIRS’

     Directory where liblzma headers are located.

‘LIBLZMA_LIBRARIES’

     Lzma libraries to link against.

‘LIBLZMA_HAS_AUTO_DECODER’

     True if lzma_auto_decoder() is found (required).

‘LIBLZMA_HAS_EASY_ENCODER’

     True if lzma_easy_encoder() is found (required).

‘LIBLZMA_HAS_LZMA_PRESET’

     True if lzma_lzma_preset() is found (required).

‘LIBLZMA_VERSION_MAJOR’

     The major version of lzma

‘LIBLZMA_VERSION_MINOR’

     The minor version of lzma

‘LIBLZMA_VERSION_PATCH’

     The patch version of lzma

‘LIBLZMA_VERSION_STRING’

     version number as a string (ex: “5.0.3”)

15.2.66 FindLibXml2
-------------------

Find the XML processing library (libxml2).

15.2.66.1 IMPORTED Targets
..........................

The following IMPORTED targets may be defined:

‘LibXml2::LibXml2’

     If the libxml2 library has been found

‘LibXml2::xmllint’

     If the xmllint command-line executable has been found

15.2.66.2 Result variables
..........................

This module will set the following variables in your project:

‘LibXml2_FOUND’

     true if libxml2 headers and libraries were found

‘LIBXML2_INCLUDE_DIR’

     the directory containing LibXml2 headers

‘LIBXML2_INCLUDE_DIRS’

     list of the include directories needed to use LibXml2

‘LIBXML2_LIBRARIES’

     LibXml2 libraries to be linked

‘LIBXML2_DEFINITIONS’

     the compiler switches required for using LibXml2

‘LIBXML2_XMLLINT_EXECUTABLE’

     path to the XML checking tool xmllint coming with LibXml2

‘LIBXML2_VERSION_STRING’

     the version of LibXml2 found (since CMake 2.8.8)

15.2.66.3 Cache variables
.........................

The following cache variables may also be set:

‘LIBXML2_INCLUDE_DIR’

     the directory containing LibXml2 headers

‘LIBXML2_LIBRARY’

     path to the LibXml2 library

15.2.67 FindLibXslt
-------------------

Find the XSL Transformations, Extensible Stylesheet Language
Transformations (XSLT) library (LibXslt)

15.2.67.1 IMPORTED Targets
..........................

The following IMPORTED targets may be defined:

‘LibXslt::LibXslt’

     If the libxslt library has been found

‘LibXslt::LibExslt’

     If the libexslt library has been found

‘LibXslt::xsltproc’

     If the xsltproc command-line executable has been found

15.2.67.2 Result variables
..........................

This module will set the following variables in your project:

     LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the
     LibXslt include directory LIBXSLT_LIBRARIES - Link these to LibXslt
     LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
     LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
     2.8.8)

Additionally, the following two variables are set (but not required for
using xslt):

‘LIBXSLT_EXSLT_INCLUDE_DIR’

     The include directory for exslt.

‘LIBXSLT_EXSLT_LIBRARIES’

     Link to these if you need to link against the exslt library.

‘LIBXSLT_XSLTPROC_EXECUTABLE’

     Contains the full path to the xsltproc executable if found.

15.2.68 FindLTTngUST
--------------------

New in version 3.6.

Find Linux Trace Toolkit Next Generation (LTTng-UST)(1) library.

   ---------- Footnotes ----------

   (1) http://lttng.org/

15.2.68.1 Imported target
.........................

This module defines the following IMPORTED target:

‘LTTng::UST’

     The LTTng-UST library, if found

15.2.68.2 Result variables
..........................

This module sets the following

‘LTTNGUST_FOUND’

     ‘TRUE’ if system has LTTng-UST

‘LTTNGUST_INCLUDE_DIRS’

     The LTTng-UST include directories

‘LTTNGUST_LIBRARIES’

     The libraries needed to use LTTng-UST

‘LTTNGUST_VERSION_STRING’

     The LTTng-UST version

‘LTTNGUST_HAS_TRACEF’

     ‘TRUE’ if the ‘tracef()’ API is available in the system’s LTTng-UST

‘LTTNGUST_HAS_TRACELOG’

     ‘TRUE’ if the ‘tracelog()’ API is available in the system’s
     LTTng-UST

15.2.69 FindLua
---------------

Locate Lua library.

This module defines:

     ::

     LUA_FOUND - if false, do not try to link to Lua LUA_LIBRARIES -
     both lua and lualib LUA_INCLUDE_DIR - where to find lua.h
     LUA_VERSION_STRING - the version of Lua found LUA_VERSION_MAJOR -
     the major version of Lua LUA_VERSION_MINOR - the minor version of
     Lua LUA_VERSION_PATCH - the patch version of Lua

Note that the expected include convention is

     #include "lua.h"

and not

     #include <lua/lua.h>

This is because, the lua location is not standardized and may exist in
locations other than lua/

15.2.70 FindLua50
-----------------

Locate Lua library.  This module defines:

     ::

     LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES,
     both lua and lualib LUA_INCLUDE_DIR, where to find lua.h and
     lualib.h (and probably lauxlib.h)

Note that the expected include convention is

     #include "lua.h"

and not

     #include <lua/lua.h>

This is because, the lua location is not standardized and may exist in
locations other than lua/

15.2.71 FindLua51
-----------------

Locate Lua library.  This module defines:

     ::

     LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
     LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the
     version of Lua found (since CMake 2.8.8)

Note that the expected include convention is

     #include "lua.h"

and not

     #include <lua/lua.h>

This is because, the lua location is not standardized and may exist in
locations other than lua/

15.2.72 FindMatlab
------------------

Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab tools,
libraries and compilers to CMake.

This package primary purpose is to find the libraries associated with
Matlab or the MCR in order to be able to build Matlab extensions (mex
files).  It can also be used:

   * to run specific commands in Matlab in case Matlab is available

   * for declaring Matlab unit test

   * to retrieve various information from Matlab (mex extensions,
     versions and release queries, …)

The module supports the following components:

   * ‘ENG_LIBRARY’ and ‘MAT_LIBRARY’: respectively the ‘ENG’ and ‘MAT’
     libraries of Matlab

   * ‘MAIN_PROGRAM’ the Matlab binary program.  Note that this component
     is not available on the MCR version, and will yield an error if the
     MCR is found instead of the regular Matlab installation.

   * ‘MEX_COMPILER’ the MEX compiler.

   * ‘MCC_COMPILER’ the MCC compiler, included with the Matlab Compiler
     add-on.

   * ‘SIMULINK’ the Simulink environment.

     Note: The version given to the find_package() directive
     is the Matlab `version', which should not be confused with the
     Matlab `release' name (eg.  ‘R2014’).  The
     matlab_get_version_from_release_name() and
     matlab_get_release_name_from_version() provide a mapping
     between the release name and the version.

The variable Matlab_ROOT_DIR may be specified in order to
give the path of the desired Matlab version.  Otherwise, the behaviour
is platform specific:

   * Windows: The installed versions of Matlab/MCR are retrieved from
     the Windows registry

   * OS X: The installed versions of Matlab/MCR are given by the MATLAB
     default installation paths in ‘/Application’.  If no such
     application is found, it falls back to the one that might be
     accessible from the ‘PATH’.

   * Unix: The desired Matlab should be accessible from the ‘PATH’.
     This does not work for MCR installation and Matlab_ROOT_DIR
     should be specified on this platform.

Additional information is provided when MATLAB_FIND_DEBUG is
set.  When a Matlab/MCR installation is found automatically and the
‘MATLAB_VERSION’ is not given, the version is queried from Matlab
directly (on Windows this may pop up a Matlab window) or from the MCR
installation.

The mapping of the release names and the version of Matlab is performed
by defining pairs (name, version).  The variable
MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
find_package() in order to handle additional versions.

A Matlab scripts can be added to the set of tests using the
matlab_add_unit_test().  By default, the Matlab unit test framework
will be used (>= 2013a) to run this script, but regular ‘.m’ files
returning an exit code can be used as well (0 indicating a success).

15.2.72.1 Module Input Variables
................................

Users or projects may set the following variables to configure the
module behaviour:

Matlab_ROOT_DIR.

     the root of the Matlab installation.

See MATLAB_FIND_DEBUG.

     outputs debug information

See MATLAB_ADDITIONAL_VERSIONS.

     additional versions of Matlab for the automatic retrieval of the
     installed versions.

15.2.72.2 Variables defined by the module
.........................................

15.2.72.3 Result variables
..........................

‘Matlab_FOUND’

     ‘TRUE’ if the Matlab installation is found, ‘FALSE’ otherwise.  All
     variable below are defined if Matlab is found.

‘Matlab_ROOT_DIR’

     the final root of the Matlab installation determined by the
     FindMatlab module.

‘Matlab_MAIN_PROGRAM’

     the Matlab binary program.  Available only if the component
     ‘MAIN_PROGRAM’ is given in the find_package() directive.

‘Matlab_INCLUDE_DIRS’

     the path of the Matlab libraries headers

‘Matlab_MEX_LIBRARY’

     library for mex, always available.

‘Matlab_MX_LIBRARY’

     mx library of Matlab (arrays), always available.

‘Matlab_ENG_LIBRARY’

     Matlab engine library.  Available only if the component
     ‘ENG_LIBRARY’ is requested.

‘Matlab_MAT_LIBRARY’

     Matlab matrix library.  Available only if the component
     ‘MAT_LIBRARY’ is requested.

‘Matlab_ENGINE_LIBRARY’

     Matlab C++ engine library, always available for R2018a and newer.

‘Matlab_DATAARRAY_LIBRARY’

     Matlab C++ data array library, always available for R2018a and
     newer.

‘Matlab_LIBRARIES’

     the whole set of libraries of Matlab

‘Matlab_MEX_COMPILER’

     the mex compiler of Matlab.  Currently not used.  Available only if
     the component ‘MEX_COMPILER’ is requested.

‘Matlab_MCC_COMPILER’

     the mcc compiler of Matlab.  Included with the Matlab Compiler
     add-on.  Available only if the component ‘MCC_COMPILER’ is
     requested.

15.2.72.4 Cached variables
..........................

‘Matlab_MEX_EXTENSION’

     the extension of the mex files for the current platform (given by
     Matlab).

‘Matlab_ROOT_DIR’

     the location of the root of the Matlab installation found.  If this
     value is changed by the user, the result variables are recomputed.

15.2.72.5 Provided macros
.........................

See matlab_get_version_from_release_name().

     returns the version from the release name

See matlab_get_release_name_from_version().

     returns the release name from the Matlab version

15.2.72.6 Provided functions
............................

See matlab_add_mex().

     adds a target compiling a MEX file.

See matlab_add_unit_test().

     adds a Matlab unit test file as a test to the project.

See matlab_extract_all_installed_versions_from_registry().

     parses the registry for all Matlab versions.  Available on Windows
     only.  The part of the registry parsed is dependent on the host
     processor

See matlab_get_all_valid_matlab_roots_from_registry().

     returns all the possible Matlab or MCR paths, according to a
     previously given list.  Only the existing/accessible paths are
     kept.  This is mainly useful for the searching all possible Matlab
     installation.

See matlab_get_mex_suffix().

     returns the suffix to be used for the mex files
     (platform/architecture dependent)

See matlab_get_version_from_matlab_run().

     returns the version of Matlab/MCR, given the full directory of the
     Matlab/MCR installation path.

15.2.72.7 Known issues
......................

`Symbol clash in a MEX target'

     By default, every symbols inside a MEX file defined with the
     command matlab_add_mex() have hidden visibility, except
     for the entry point.  This is the default behaviour of the MEX
     compiler, which lowers the risk of symbol collision between the
     libraries shipped with Matlab, and the libraries to which the MEX
     file is linking to.  This is also the default on Windows platforms.

     However, this is not sufficient in certain case, where for instance
     your MEX file is linking against libraries that are already loaded
     by Matlab, even if those libraries have different SONAMES. A
     possible solution is to hide the symbols of the libraries to which
     the MEX target is linking to.  This can be achieved in GNU GCC
     compilers with the linker option ‘-Wl,--exclude-libs,ALL’.

`Tests using GPU resources'

     in case your MEX file is using the GPU and in order to be able to
     run unit tests on this MEX file, the GPU resources should be
     properly released by Matlab.  A possible solution is to make Matlab
     aware of the use of the GPU resources in the session, which can be
     performed by a command such as ‘D = gpuDevice()’ at the beginning
     of the test script (or via a fixture).

15.2.72.8 Reference
...................

 -- Variable: Matlab_ROOT_DIR

     The root folder of the Matlab installation.  If set before the call
     to find_package(), the module will look for the
     components in that path.  If not set, then an automatic search of
     Matlab will be performed.  If set, it should point to a valid
     version of Matlab.

 -- Variable: MATLAB_FIND_DEBUG

     If set, the lookup of Matlab and the intermediate configuration
     steps are outputted to the console.

 -- Variable: MATLAB_ADDITIONAL_VERSIONS

     If set, specifies additional versions of Matlab that may be looked
     for.  The variable should be a list of strings, organised by pairs
     of release name and versions, such as follows:

          set(MATLAB_ADDITIONAL_VERSIONS
              "release_name1=corresponding_version1"
              "release_name2=corresponding_version2"
              ...
              )

     Example:

          set(MATLAB_ADDITIONAL_VERSIONS
              "R2013b=8.2"
              "R2013a=8.1"
              "R2012b=8.0")

     The order of entries in this list matters when several versions of
     Matlab are installed.  The priority is set according to the
     ordering in this list.

 -- Command: matlab_get_version_from_release_name

     Returns the version of Matlab (17.58) from a release name (R2017k)

 -- Command: matlab_get_release_name_from_version

     Returns the release name (R2017k) from the version of Matlab
     (17.58)

 -- Command: matlab_extract_all_installed_versions_from_registry

     This function parses the registry and founds the Matlab versions
     that are installed.  The found versions are returned in
     ‘matlab_versions’.  Set ‘win64’ to ‘TRUE’ if the 64 bit version of
     Matlab should be looked for The returned list contains all versions
     under ‘HKLM\\SOFTWARE\\Mathworks\\MATLAB’ and
     ‘HKLM\\SOFTWARE\\Mathworks\\MATLAB Runtime’ or an empty list in
     case an error occurred (or nothing found).

          Note: Only the versions are provided.  No check is made over
          the existence of the installation referenced in the registry,

 -- Command: matlab_get_all_valid_matlab_roots_from_registry

     Populates the Matlab root with valid versions of Matlab or Matlab
     Runtime (MCR). The returned matlab_roots is organized in triplets
     ‘(type,version_number,matlab_root_path)’, where ‘type’ indicates
     either ‘MATLAB’ or ‘MCR’.

          matlab_get_all_valid_matlab_roots_from_registry(
              matlab_versions
              matlab_roots)

     ‘matlab_versions’

          the versions of each of the Matlab or MCR installations

     ‘matlab_roots’

          the location of each of the Matlab or MCR installations

 -- Command: matlab_get_mex_suffix

     Returns the extension of the mex files (the suffixes).  This
     function should not be called before the appropriate Matlab root
     has been found.

          matlab_get_mex_suffix(
              matlab_root
              mex_suffix)

     ‘matlab_root’

          the root of the Matlab/MCR installation

     ‘mex_suffix’

          the variable name in which the suffix will be returned.

 -- Command: matlab_get_version_from_matlab_run

     This function runs Matlab program specified on arguments and
     extracts its version.  If the path provided for the Matlab
     installation points to an MCR installation, the version is
     extracted from the installed files.

          matlab_get_version_from_matlab_run(
              matlab_binary_path
              matlab_list_versions)

     ‘matlab_binary_path’

          the location of the ‘matlab’ binary executable

     ‘matlab_list_versions’

          the version extracted from Matlab

 -- Command: matlab_add_unit_test

     Adds a Matlab unit test to the test set of cmake/ctest.  This
     command requires the component ‘MAIN_PROGRAM’ and hence is not
     available for an MCR installation.

     The unit test uses the Matlab unittest framework (default,
     available starting Matlab 2013b+) except if the option
     ‘NO_UNITTEST_FRAMEWORK’ is given.

     The function expects one Matlab test script file to be given.  In
     the case ‘NO_UNITTEST_FRAMEWORK’ is given, the unittest script file
     should contain the script to be run, plus an exit command with the
     exit value.  This exit value will be passed to the ctest framework
     (0 success, non 0 failure).  Additional arguments accepted by
     add_test() can be passed through ‘TEST_ARGS’ (eg.
     ‘CONFIGURATION <config> ...’).

          matlab_add_unit_test(
              NAME <name>
              UNITTEST_FILE matlab_file_containing_unittest.m
              [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
              [UNITTEST_PRECOMMAND matlab_command_to_run]
              [TIMEOUT timeout]
              [ADDITIONAL_PATH path1 [path2 ...]]
              [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
              [TEST_ARGS arg1 [arg2 ...]]
              [NO_UNITTEST_FRAMEWORK]
              )

     The function arguments are:

     ‘NAME’

          name of the unittest in ctest.

     ‘UNITTEST_FILE’

          the matlab unittest file.  Its path will be automatically
          added to the Matlab path.

     ‘CUSTOM_TEST_COMMAND’

          Matlab script command to run as the test.  If this is not set,
          then the following is run: ‘runtests('matlab_file_name'),
          exit(max([ans(1,:).Failed]))’ where ‘matlab_file_name’ is the
          ‘UNITTEST_FILE’ without the extension.

     ‘UNITTEST_PRECOMMAND’

          Matlab script command to be ran before the file containing the
          test (eg.  GPU device initialisation based on CMake
          variables).

     ‘TIMEOUT’

          the test timeout in seconds.  Defaults to 180 seconds as the
          Matlab unit test may hang.

     ‘ADDITIONAL_PATH’

          a list of paths to add to the Matlab path prior to running the
          unit test.

     ‘MATLAB_ADDITIONAL_STARTUP_OPTIONS’

          a list of additional option in order to run Matlab from the
          command line.  ‘-nosplash -nodesktop -nodisplay’ are always
          added.

     ‘TEST_ARGS’

          Additional options provided to the add_test command.  These
          options are added to the default options (eg.  “CONFIGURATIONS
          Release”)

     ‘NO_UNITTEST_FRAMEWORK’

          when set, indicates that the test should not use the unittest
          framework of Matlab (available for versions >= R2013a).

     ‘WORKING_DIRECTORY’

          This will be the working directory for the test.  If specified
          it will also be the output directory used for the log file of
          the test run.  If not specified the temporary directory
          ‘${CMAKE_BINARY_DIR}/Matlab’ will be used as the working
          directory and the log location.

 -- Command: matlab_add_mex

     Adds a Matlab MEX target.  This commands compiles the given sources
     with the current tool-chain in order to produce a MEX file.  The
     final name of the produced output may be specified, as well as
     additional link libraries, and a documentation entry for the MEX
     file.  Remaining arguments of the call are passed to the
     add_library() or add_executable() command.

          matlab_add_mex(
              NAME <name>
              [EXECUTABLE | MODULE | SHARED]
              SRC src1 [src2 ...]
              [OUTPUT_NAME output_name]
              [DOCUMENTATION file.txt]
              [LINK_TO target1 target2 ...]
              [R2017b | R2018a]
              [EXCLUDE_FROM_ALL]
              [...]
          )

     ‘NAME’

          name of the target.

     ‘SRC’

          list of source files.

     ‘LINK_TO’

          a list of additional link dependencies.  The target links to
          ‘libmex’ and ‘libmx’ by default.

     ‘OUTPUT_NAME’

          if given, overrides the default name.  The default name is the
          name of the target without any prefix and with
          ‘Matlab_MEX_EXTENSION’ suffix.

     ‘DOCUMENTATION’

          if given, the file ‘file.txt’ will be considered as being the
          documentation file for the MEX file.  This file is copied into
          the same folder without any processing, with the same name as
          the final mex file, and with extension ‘.m’.  In that case,
          typing ‘help <name>’ in Matlab prints the documentation
          contained in this file.

     ‘R2017b’ or ‘R2018a’ may be given to specify the version of the C API

          to use: ‘R2017b’ specifies the traditional (separate complex)
          C API, and corresponds to the ‘-R2017b’ flag for the ‘mex’
          command.  ‘R2018a’ specifies the new interleaved complex C
          API, and corresponds to the ‘-R2018a’ flag for the ‘mex’
          command.  Ignored if MATLAB version prior to R2018a.  Defaults
          to ‘R2017b’.

     ‘MODULE’ or ‘SHARED’ may be given to specify the type of library to be

          created.  ‘EXECUTABLE’ may be given to create an executable
          instead of a library.  If no type is given explicitly, the
          type is ‘SHARED’.

     ‘EXCLUDE_FROM_ALL’

          This option has the same meaning as for
          EXCLUDE_FROM_ALL and is forwarded to
          add_library() or add_executable() commands.

     The documentation file is not processed and should be in the
     following format:

          % This is the documentation
          function ret = mex_target_output_name(input1)

15.2.73 FindMFC
---------------

Find Microsoft Foundation Class Library (MFC) on Windows

Find the native MFC - i.e.  decide if an application can link to the MFC
libraries.

     MFC_FOUND - Was MFC support found

You don’t need to include anything or link anything to use it.

15.2.74 FindMotif
-----------------

Try to find Motif (or lesstif)

Once done this will define:

     MOTIF_FOUND        - system has MOTIF
     MOTIF_INCLUDE_DIR  - include paths to use Motif
     MOTIF_LIBRARIES    - Link these to use Motif

15.2.75 FindMPEG
----------------

Find the native MPEG includes and library

This module defines

     MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
     MPEG_LIBRARIES, the libraries required to use MPEG.
     MPEG_FOUND, If false, do not try to use MPEG.

also defined, but not for general use are

     MPEG_mpeg2_LIBRARY, where to find the MPEG library.
     MPEG_vo_LIBRARY, where to find the vo library.

15.2.76 FindMPEG2
-----------------

Find the native MPEG2 includes and library

This module defines

     MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
     MPEG2_LIBRARIES, the libraries required to use MPEG2.
     MPEG2_FOUND, If false, do not try to use MPEG2.

also defined, but not for general use are

     MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
     MPEG2_vo_LIBRARY, where to find the vo library.

15.2.77 FindMPI
---------------

Find a Message Passing Interface (MPI) implementation.

The Message Passing Interface (MPI) is a library used to write
high-performance distributed-memory parallel applications, and is
typically deployed on a cluster.  MPI is a standard interface (defined
by the MPI forum) for which many implementations are available.

15.2.77.1 Variables for using MPI
.................................

The module exposes the components ‘C’, ‘CXX’, ‘MPICXX’ and ‘Fortran’.
Each of these controls the various MPI languages to search for.  The
difference between ‘CXX’ and ‘MPICXX’ is that ‘CXX’ refers to the MPI C
API being usable from C++, whereas ‘MPICXX’ refers to the MPI-2 C++ API
that was removed again in MPI-3.

Depending on the enabled components the following variables will be set:

‘MPI_FOUND’

     Variable indicating that MPI settings for all requested languages
     have been found.  If no components are specified, this is true if
     MPI settings for all enabled languages were detected.  Note that
     the ‘MPICXX’ component does not affect this variable.

‘MPI_VERSION’

     Minimal version of MPI detected among the requested languages, or
     all enabled languages if no components were specified.

This module will set the following variables per language in your
project, where ‘<lang>’ is one of C, CXX, or Fortran:

‘MPI_<lang>_FOUND’

     Variable indicating the MPI settings for ‘<lang>’ were found and
     that simple MPI test programs compile with the provided settings.

‘MPI_<lang>_COMPILER’

     MPI compiler for ‘<lang>’ if such a program exists.

‘MPI_<lang>_COMPILE_OPTIONS’

     Compilation options for MPI programs in ‘<lang>’, given as a
     ;-list.

‘MPI_<lang>_COMPILE_DEFINITIONS’

     Compilation definitions for MPI programs in ‘<lang>’, given as a
     ;-list.

‘MPI_<lang>_INCLUDE_DIRS’

     Include path(s) for MPI header.

‘MPI_<lang>_LINK_FLAGS’

     Linker flags for MPI programs.

‘MPI_<lang>_LIBRARIES’

     All libraries to link MPI programs against.

Additionally, the following IMPORTED targets are defined:

‘MPI::MPI_<lang>’

     Target for using MPI from ‘<lang>’.

The following variables indicating which bindings are present will be
defined:

‘MPI_MPICXX_FOUND’

     Variable indicating whether the MPI-2 C++ bindings are present
     (introduced in MPI-2, removed with MPI-3).

‘MPI_Fortran_HAVE_F77_HEADER’

     True if the Fortran 77 header ‘mpif.h’ is available.

‘MPI_Fortran_HAVE_F90_MODULE’

     True if the Fortran 90 module ‘mpi’ can be used for accessing MPI
     (MPI-2 and higher only).

‘MPI_Fortran_HAVE_F08_MODULE’

     True if the Fortran 2008 ‘mpi_f08’ is available to MPI programs
     (MPI-3 and higher only).

If possible, the MPI version will be determined by this module.  The
facilities to detect the MPI version were introduced with MPI-1.2, and
therefore cannot be found for older MPI versions.

‘MPI_<lang>_VERSION_MAJOR’

     Major version of MPI implemented for ‘<lang>’ by the MPI
     distribution.

‘MPI_<lang>_VERSION_MINOR’

     Minor version of MPI implemented for ‘<lang>’ by the MPI
     distribution.

‘MPI_<lang>_VERSION’

     MPI version implemented for ‘<lang>’ by the MPI distribution.

Note that there’s no variable for the C bindings being accessible
through ‘mpi.h’, since the MPI standards always have required this
binding to work in both C and C++ code.

For running MPI programs, the module sets the following variables

‘MPIEXEC_EXECUTABLE’

     Executable for running MPI programs, if such exists.

‘MPIEXEC_NUMPROC_FLAG’

     Flag to pass to ‘mpiexec’ before giving it the number of processors
     to run on.

‘MPIEXEC_MAX_NUMPROCS’

     Number of MPI processors to utilize.  Defaults to the number of
     processors detected on the host system.

‘MPIEXEC_PREFLAGS’

     Flags to pass to ‘mpiexec’ directly before the executable to run.

‘MPIEXEC_POSTFLAGS’

     Flags to pass to ‘mpiexec’ after other flags.

15.2.77.2 Variables for locating MPI
....................................

This module performs a four step search for an MPI implementation:

  1. Search for ‘MPIEXEC_EXECUTABLE’ and, if found, use its base
     directory.

  2. Check if the compiler has MPI support built-in.  This is the case
     if the user passed a compiler wrapper as ‘CMAKE_<LANG>_COMPILER’ or
     if they’re on a Cray system.

  3. Attempt to find an MPI compiler wrapper and determine the compiler
     information from it.

  4. Try to find an MPI implementation that does not ship such a wrapper
     by guessing settings.  Currently, only Microsoft MPI and MPICH2 on
     Windows are supported.

For controlling the ‘MPIEXEC_EXECUTABLE’ step, the following variables
may be set:

‘MPIEXEC_EXECUTABLE’

     Manually specify the location of ‘mpiexec’.

‘MPI_HOME’

     Specify the base directory of the MPI installation.

‘ENV{MPI_HOME}’

     Environment variable to specify the base directory of the MPI
     installation.

‘ENV{I_MPI_ROOT}’

     Environment variable to specify the base directory of the MPI
     installation.

For controlling the compiler wrapper step, the following variables may
be set:

‘MPI_<lang>_COMPILER’

     Search for the specified compiler wrapper and use it.

‘MPI_<lang>_COMPILER_FLAGS’

     Flags to pass to the MPI compiler wrapper during interrogation.
     Some compiler wrappers support linking debug or tracing libraries
     if a specific flag is passed and this variable may be used to
     obtain them.

‘MPI_COMPILER_FLAGS’

     Used to initialize ‘MPI_<lang>_COMPILER_FLAGS’ if no language
     specific flag has been given.  Empty by default.

‘MPI_EXECUTABLE_SUFFIX’

     A suffix which is appended to all names that are being looked for.
     For instance you may set this to ‘.mpich’ or ‘.openmpi’ to prefer
     the one or the other on Debian and its derivatives.

In order to control the guessing step, the following variable may be
set:

‘MPI_GUESS_LIBRARY_NAME’

     Valid values are ‘MSMPI’ and ‘MPICH2’.  If set, only the given
     library will be searched for.  By default, ‘MSMPI’ will be
     preferred over ‘MPICH2’ if both are available.  This also sets
     ‘MPI_SKIP_COMPILER_WRAPPER’ to ‘true’, which may be overridden.

Each of the search steps may be skipped with the following control
variables:

‘MPI_ASSUME_NO_BUILTIN_MPI’

     If true, the module assumes that the compiler itself does not
     provide an MPI implementation and skips to step 2.

‘MPI_SKIP_COMPILER_WRAPPER’

     If true, no compiler wrapper will be searched for.

‘MPI_SKIP_GUESSING’

     If true, the guessing step will be skipped.

Additionally, the following control variable is available to change
search behavior:

‘MPI_CXX_SKIP_MPICXX’

     Add some definitions that will disable the MPI-2 C++ bindings.
     Currently supported are MPICH, Open MPI, Platform MPI and
     derivatives thereof, for example MVAPICH or Intel MPI.

If the find procedure fails for a variable ‘MPI_<lang>_WORKS’, then the
settings detected by or passed to the module did not work and even a
simple MPI test program failed to compile.

If all of these parameters were not sufficient to find the right MPI
implementation, a user may disable the entire autodetection process by
specifying both a list of libraries in ‘MPI_<lang>_LIBRARIES’ and a list
of include directories in ‘MPI_<lang>_ADDITIONAL_INCLUDE_DIRS’.  Any
other variable may be set in addition to these two.  The module will
then validate the MPI settings and store the settings in the cache.

15.2.77.3 Cache variables for MPI
.................................

The variable ‘MPI_<lang>_INCLUDE_DIRS’ will be assembled from the
following variables.  For C and CXX:

‘MPI_<lang>_HEADER_DIR’

     Location of the ‘mpi.h’ header on disk.

For Fortran:

‘MPI_Fortran_F77_HEADER_DIR’

     Location of the Fortran 77 header ‘mpif.h’, if it exists.

‘MPI_Fortran_MODULE_DIR’

     Location of the ‘mpi’ or ‘mpi_f08’ modules, if available.

For all languages the following variables are additionally considered:

‘MPI_<lang>_ADDITIONAL_INCLUDE_DIRS’

     A ;-list of paths needed in addition to the normal
     include directories.

‘MPI_<include_name>_INCLUDE_DIR’

     Path variables for include folders referred to by ‘<include_name>’.

‘MPI_<lang>_ADDITIONAL_INCLUDE_VARS’

     A ;-list of ‘<include_name>’ that will be added to the
     include locations of ‘<lang>’.

The variable ‘MPI_<lang>_LIBRARIES’ will be assembled from the following
variables:

‘MPI_<lib_name>_LIBRARY’

     The location of a library called ‘<lib_name>’ for use with MPI.

‘MPI_<lang>_LIB_NAMES’

     A ;-list of ‘<lib_name>’ that will be added to the
     include locations of ‘<lang>’.

15.2.77.4 Usage of mpiexec
..........................

When using ‘MPIEXEC_EXECUTABLE’ to execute MPI applications, you should
typically use all of the ‘MPIEXEC_EXECUTABLE’ flags as follows:

     ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
       ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS

where ‘EXECUTABLE’ is the MPI program, and ‘ARGS’ are the arguments to
pass to the MPI program.

15.2.77.5 Advanced variables for using MPI
..........................................

The module can perform some advanced feature detections upon explicit
request.

`Important notice:' The following checks cannot be performed without
`executing' an MPI test program.  Consider the special considerations
for the behavior of try_run() during cross compilation.
Moreover, running an MPI program can cause additional issues, like a
firewall notification on some systems.  You should only enable these
detections if you absolutely need the information.

If the following variables are set to true, the respective search will
be performed:

‘MPI_DETERMINE_Fortran_CAPABILITIES’

     Determine for all available Fortran bindings what the values of
     ‘MPI_SUBARRAYS_SUPPORTED’ and ‘MPI_ASYNC_PROTECTS_NONBLOCKING’ are
     and make their values available as
     ‘MPI_Fortran_<binding>_SUBARRAYS’ and
     ‘MPI_Fortran_<binding>_ASYNCPROT’, where ‘<binding>’ is one of
     ‘F77_HEADER’, ‘F90_MODULE’ and ‘F08_MODULE’.

‘MPI_DETERMINE_LIBRARY_VERSION’

     For each language, find the output of ‘MPI_Get_library_version’ and
     make it available as ‘MPI_<lang>_LIBRARY_VERSION_STRING’.  This
     information is usually tied to the runtime component of an MPI
     implementation and might differ depending on ‘<lang>’.  Note that
     the return value is entirely implementation defined.  This
     information might be used to identify the MPI vendor and for
     example pick the correct one of multiple third party binaries that
     matches the MPI vendor.

15.2.77.6 Backward Compatibility
................................

For backward compatibility with older versions of FindMPI, these
variables are set, but deprecated:

     MPI_COMPILER        MPI_LIBRARY        MPI_EXTRA_LIBRARY
     MPI_COMPILE_FLAGS   MPI_INCLUDE_PATH   MPI_LINK_FLAGS
     MPI_LIBRARIES

In new projects, please use the ‘MPI_<lang>_XXX’ equivalents.
Additionally, the following variables are deprecated:

‘MPI_<lang>_COMPILE_FLAGS’

     Use ‘MPI_<lang>_COMPILE_OPTIONS’ and
     ‘MPI_<lang>_COMPILE_DEFINITIONS’ instead.

‘MPI_<lang>_INCLUDE_PATH’

     For consumption use ‘MPI_<lang>_INCLUDE_DIRS’ and for specifying
     folders use ‘MPI_<lang>_ADDITIONAL_INCLUDE_DIRS’ instead.

‘MPIEXEC’

     Use ‘MPIEXEC_EXECUTABLE’ instead.

15.2.78 FindODBC
----------------

New in version 3.12.

Find an Open Database Connectivity (ODBC) include directory and library.

On Windows, when building with Visual Studio, this module assumes the
ODBC library is provided by the available Windows SDK.

On Unix, this module allows to search for ODBC library provided by
unixODBC or iODBC implementations of ODBC API. This module reads hint
about location of the config program:

 -- Variable: ODBC_CONFIG

     Location of odbc_config or iodbc-config program

Otherwise, this module tries to find the config program, first from
unixODBC, then from iODBC. If no config program found, this module
searches for ODBC header and library in list of known locations.

15.2.78.1 Imported targets
..........................

This module defines the following IMPORTED targets:

 -- Variable: ODBC::ODBC

     Imported target for using the ODBC library, if found.

15.2.78.2 Result variables
..........................

 -- Variable: ODBC_FOUND

     Set to true if ODBC library found, otherwise false or undefined.

 -- Variable: ODBC_INCLUDE_DIRS

     Paths to include directories listed in one variable for use by ODBC
     client.  May be empty on Windows, where the include directory
     corresponding to the expected Windows SDK is already available in
     the compilation environment.

 -- Variable: ODBC_LIBRARIES

     Paths to libraries to linked against to use ODBC. May just a
     library name on Windows, where the library directory corresponding
     to the expected Windows SDK is already available in the compilation
     environment.

 -- Variable: ODBC_CONFIG

     Path to unixODBC or iODBC config program, if found or specified.

15.2.78.3 Cache variables
.........................

For users who wish to edit and control the module behavior, this module
reads hints about search locations from the following variables:

 -- Variable: ODBC_INCLUDE_DIR

     Path to ODBC include directory with ‘sql.h’ header.

 -- Variable: ODBC_LIBRARY

     Path to ODBC library to be linked.

These variables should not be used directly by project code.

15.2.78.4 Limitations
.....................

On Windows, this module does not search for iODBC. On Unix, there is no
way to prefer unixODBC over iODBC, or vice versa, other than providing
the config program location using the ‘ODBC_CONFIG’.  This module does
not allow to search for a specific ODBC driver.

15.2.79 FindOpenACC
-------------------

New in version 3.10.

Detect OpenACC support by the compiler.

This module can be used to detect OpenACC support in a compiler.  If the
compiler supports OpenACC, the flags required to compile with OpenACC
support are returned in variables for the different languages.
Currently, only PGI, GNU and Cray compilers are supported.

15.2.79.1 Variables
...................

This module will set the following variables per language in your
project, where ‘<lang>’ is one of C, CXX, or Fortran:

‘OpenACC_<lang>_FOUND’

     Variable indicating if OpenACC support for ‘<lang>’ was detected.

‘OpenACC_<lang>_FLAGS’

     OpenACC compiler flags for ‘<lang>’, separated by spaces.

‘OpenACC_<lang>_OPTIONS’

     OpenACC compiler flags for ‘<lang>’, as a list.  Suitable for usage
     with target_compile_options or target_link_options.

Additionally, the module provides IMPORTED targets:

‘OpenACC::OpenACC_<lang>’

     Target for using OpenACC from ‘<lang>’.

The module will also try to provide the OpenACC version variables:

‘OpenACC_<lang>_SPEC_DATE’

     Date of the OpenACC specification implemented by the ‘<lang>’
     compiler.

‘OpenACC_<lang>_VERSION_MAJOR’

     Major version of OpenACC implemented by the ‘<lang>’ compiler.

‘OpenACC_<lang>_VERSION_MINOR’

     Minor version of OpenACC implemented by the ‘<lang>’ compiler.

‘OpenACC_<lang>_VERSION’

     OpenACC version implemented by the ‘<lang>’ compiler.

The specification date is formatted as given in the OpenACC standard:
‘yyyymm’ where ‘yyyy’ and ‘mm’ represents the year and month of the
OpenACC specification implemented by the ‘<lang>’ compiler.

15.2.79.2 Input Variables
.........................

‘OpenACC_ACCEL_TARGET=<target>’ If set, will the correct target
accelerator flag set to the <target> will be returned with
OpenACC_<lang>_FLAGS.

15.2.80 FindOpenAL
------------------

Finds Open Audio Library (OpenAL).

Projects using this module should use ‘#include "al.h"’ to include the
OpenAL header file, `not' ‘#include <AL/al.h>’.  The reason for this is
that the latter is not entirely portable.  Windows/Creative Labs does
not by default put their headers in ‘AL/’ and macOS uses the convention
‘<OpenAL/al.h>’.

15.2.80.1 Hints
...............

Environment variable ‘$OPENALDIR’ can be used to set the prefix of
OpenAL installation to be found.

By default on macOS, system framework is search first.  In other words,
OpenAL is searched in the following order:

  1. System framework: ‘/System/Library/Frameworks’, whose priority can
     be changed via setting the CMAKE_FIND_FRAMEWORK.
     variable.

  2. Environment variable ‘$OPENALDIR’.

  3. System paths.

  4. User-compiled framework: ‘~/Library/Frameworks’.

  5. Manually compiled framework: ‘/Library/Frameworks’.

  6. Add-on package: ‘/opt’.

15.2.80.2 Result Variables
..........................

This module defines the following variables:

‘OPENAL_FOUND’

     If false, do not try to link to OpenAL

‘OPENAL_INCLUDE_DIR’

     OpenAL include directory

‘OPENAL_LIBRARY’

     Path to the OpenAL library

‘OPENAL_VERSION_STRING’

     Human-readable string containing the version of OpenAL

15.2.81 FindOpenCL
------------------

New in version 3.1.

Finds Open Computing Language (OpenCL)

15.2.81.1 IMPORTED Targets
..........................

This module defines IMPORTED target ‘OpenCL::OpenCL’, if
OpenCL has been found.

15.2.81.2 Result Variables
..........................

This module defines the following variables:

     OpenCL_FOUND          - True if OpenCL was found
     OpenCL_INCLUDE_DIRS   - include directories for OpenCL
     OpenCL_LIBRARIES      - link against this library to use OpenCL
     OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
     OpenCL_VERSION_MAJOR  - The major version of the OpenCL implementation
     OpenCL_VERSION_MINOR  - The minor version of the OpenCL implementation

The module will also define two cache variables:

     OpenCL_INCLUDE_DIR    - the OpenCL include directory
     OpenCL_LIBRARY        - the path to the OpenCL library

15.2.82 FindOpenGL
------------------

FindModule for OpenGL and OpenGL Utility Library (GLU).

15.2.82.1 Optional COMPONENTS
.............................

This module respects several optional COMPONENTS: ‘EGL’, ‘GLX’, and
‘OpenGL’.  There are corresponding import targets for each of these
flags.

15.2.82.2 IMPORTED Targets
..........................

This module defines the IMPORTED targets:

‘OpenGL::GL’

     Defined to the platform-specific OpenGL libraries if the system has
     OpenGL.

‘OpenGL::OpenGL’

     Defined to libOpenGL if the system is GLVND-based.

‘OpenGL::GLU’

     Defined if the system has OpenGL Utility Library (GLU).

‘OpenGL::GLX’

     Defined if the system has OpenGL Extension to the X Window System
     (GLX).

‘OpenGL::EGL’

     Defined if the system has EGL.

15.2.82.3 Result Variables
..........................

This module sets the following variables:

‘OPENGL_FOUND’

     True, if the system has OpenGL and all components are found.

‘OPENGL_XMESA_FOUND’

     True, if the system has XMESA.

‘OPENGL_GLU_FOUND’

     True, if the system has GLU.

‘OpenGL_OpenGL_FOUND’

     True, if the system has an OpenGL library.

‘OpenGL_GLX_FOUND’

     True, if the system has GLX.

‘OpenGL_EGL_FOUND’

     True, if the system has EGL.

‘OPENGL_INCLUDE_DIR’

     Path to the OpenGL include directory.

‘OPENGL_EGL_INCLUDE_DIRS’

     Path to the EGL include directory.

‘OPENGL_LIBRARIES’

     Paths to the OpenGL library, windowing system libraries, and GLU
     libraries.  On Linux, this assumes GLX and is never correct for
     EGL-based targets.  Clients are encouraged to use the ‘OpenGL::*’
     import targets instead.

15.2.82.4 Cache variables
.........................

The following cache variables may also be set:

‘OPENGL_egl_LIBRARY’

     Path to the EGL library.

‘OPENGL_glu_LIBRARY’

     Path to the GLU library.

‘OPENGL_glx_LIBRARY’

     Path to the GLVND ‘GLX’ library.

‘OPENGL_opengl_LIBRARY’

     Path to the GLVND ‘OpenGL’ library

‘OPENGL_gl_LIBRARY’

     Path to the OpenGL library.  New code should prefer the ‘OpenGL::*’
     import targets.

15.2.82.5 Linux-specific
........................

Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND
separates context libraries from OpenGL itself; OpenGL lives in
“libOpenGL”, and contexts are defined in “libGLX” or “libEGL”.  GLVND is
currently the only way to get OpenGL 3+ functionality via EGL in a
manner portable across vendors.  Projects may use GLVND explicitly with
target ‘OpenGL::OpenGL’ and either ‘OpenGL::GLX’ or ‘OpenGL::EGL’.

Projects may use the ‘OpenGL::GL’ target (or ‘OPENGL_LIBRARIES’
variable) to use legacy GL interfaces.  These will use the legacy GL
library located by ‘OPENGL_gl_LIBRARY’, if available.  If
‘OPENGL_gl_LIBRARY’ is empty or not found and GLVND is available, the
‘OpenGL::GL’ target will use GLVND ‘OpenGL::OpenGL’ and ‘OpenGL::GLX’
(and the ‘OPENGL_LIBRARIES’ variable will use the corresponding
libraries).  Thus, for non-EGL-based Linux targets, the ‘OpenGL::GL’
target is most portable.

A ‘OpenGL_GL_PREFERENCE’ variable may be set to specify the preferred
way to provide legacy GL interfaces in case multiple choices are
available.  The value may be one of:

‘GLVND’

     If the GLVND OpenGL and GLX libraries are available, prefer them.
     This forces ‘OPENGL_gl_LIBRARY’ to be empty.  This is the default
     if components were requested (since components correspond to GLVND
     libraries) or if policy CMP0072 is set to ‘NEW’.

‘LEGACY’

     Prefer to use the legacy libGL library, if available.  This is the
     default if no components were requested and policy CMP0072
     is not set to ‘NEW’.

For EGL targets the client must rely on GLVND support on the user’s
system.  Linking should use the ‘OpenGL::OpenGL OpenGL::EGL’ targets.
Using GLES* libraries is theoretically possible in place of
‘OpenGL::OpenGL’, but this module does not currently support that;
contributions welcome.

‘OPENGL_egl_LIBRARY’ and ‘OPENGL_EGL_INCLUDE_DIRS’ are defined in the
case of GLVND. For non-GLVND Linux and other systems these are left
undefined.

15.2.82.6 macOS-Specific
........................

On OSX FindOpenGL defaults to using the framework version of OpenGL.
People will have to change the cache values of OPENGL_glu_LIBRARY and
OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.

15.2.83 FindOpenMP
------------------

Finds Open Multi-Processing (OpenMP) support.

This module can be used to detect OpenMP support in a compiler.  If the
compiler supports OpenMP, the flags required to compile with OpenMP
support are returned in variables for the different languages.  The
variables may be empty if the compiler does not need a special flag to
support OpenMP.

15.2.83.1 Variables
...................

The module exposes the components ‘C’, ‘CXX’, and ‘Fortran’.  Each of
these controls the various languages to search OpenMP support for.

Depending on the enabled components the following variables will be set:

‘OpenMP_FOUND’

     Variable indicating that OpenMP flags for all requested languages
     have been found.  If no components are specified, this is true if
     OpenMP settings for all enabled languages were detected.

‘OpenMP_VERSION’

     Minimal version of the OpenMP standard detected among the requested
     languages, or all enabled languages if no components were
     specified.

This module will set the following variables per language in your
project, where ‘<lang>’ is one of C, CXX, or Fortran:

‘OpenMP_<lang>_FOUND’

     Variable indicating if OpenMP support for ‘<lang>’ was detected.

‘OpenMP_<lang>_FLAGS’

     OpenMP compiler flags for ‘<lang>’, separated by spaces.

‘OpenMP_<lang>_INCLUDE_DIRS’

     Directories that must be added to the header search path for
     ‘<lang>’ when using OpenMP.

For linking with OpenMP code written in ‘<lang>’, the following
variables are provided:

‘OpenMP_<lang>_LIB_NAMES’

     ;-list of libraries for OpenMP programs for ‘<lang>’.

‘OpenMP_<libname>_LIBRARY’

     Location of the individual libraries needed for OpenMP support in
     ‘<lang>’.

‘OpenMP_<lang>_LIBRARIES’

     A list of libraries needed to link with OpenMP code written in
     ‘<lang>’.

Additionally, the module provides IMPORTED targets:

‘OpenMP::OpenMP_<lang>’

     Target for using OpenMP from ‘<lang>’.

Specifically for Fortran, the module sets the following variables:

‘OpenMP_Fortran_HAVE_OMPLIB_HEADER’

     Boolean indicating if OpenMP is accessible through ‘omp_lib.h’.

‘OpenMP_Fortran_HAVE_OMPLIB_MODULE’

     Boolean indicating if OpenMP is accessible through the ‘omp_lib’
     Fortran module.

The module will also try to provide the OpenMP version variables:

‘OpenMP_<lang>_SPEC_DATE’

     Date of the OpenMP specification implemented by the ‘<lang>’
     compiler.

‘OpenMP_<lang>_VERSION_MAJOR’

     Major version of OpenMP implemented by the ‘<lang>’ compiler.

‘OpenMP_<lang>_VERSION_MINOR’

     Minor version of OpenMP implemented by the ‘<lang>’ compiler.

‘OpenMP_<lang>_VERSION’

     OpenMP version implemented by the ‘<lang>’ compiler.

The specification date is formatted as given in the OpenMP standard:
‘yyyymm’ where ‘yyyy’ and ‘mm’ represents the year and month of the
OpenMP specification implemented by the ‘<lang>’ compiler.

For some compilers, it may be necessary to add a header search path to
find the relevant OpenMP headers.  This location may be
language-specific.  Where this is needed, the module may attempt to find
the location, but it can be provided directly by setting the
‘OpenMP_<lang>_INCLUDE_DIR’ cache variable.  Note that this variable is
an _input_ control to the module.  Project code should use the
‘OpenMP_<lang>_INCLUDE_DIRS’ _output_ variable if it needs to know what
include directories are needed.

15.2.84 FindOpenSceneGraph
--------------------------

Find OpenSceneGraph (3D graphics application programming interface)

This module searches for the OpenSceneGraph core “osg” library as well
as FindOpenThreads, and whatever additional ‘COMPONENTS’
(nodekits) that you specify.

     See http://www.openscenegraph.org

NOTE: To use this module effectively you must either require ‘CMake >=
2.6.3’ with cmake_minimum_required(VERSION 2.6.3) or
download and place FindOpenThreads, Findosg.
functions, see Findosg and ‘Find<etc>.cmake’ files into your
CMAKE_MODULE_PATH.

__________________________________________________________________

This module accepts the following variables (note mixed case)

     OpenSceneGraph_DEBUG - Enable debugging output

     OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
                                       automatically

The following environment variables are also respected for finding the
OSG and it’s various components.  CMAKE_PREFIX_PATH can also
be used for this (see find_library(). CMake documentation).

‘<MODULE>_DIR’

     (where ‘MODULE’ is of the form “OSGVOLUME” and there is a
     FindosgVolume.cmake‘ file)

‘OSG_DIR’

‘OSGDIR’

‘OSG_ROOT’

[CMake 2.8.10]: The CMake variable ‘OSG_DIR’ can now be used as well to
influence detection, instead of needing to specify an environment
variable.

This module defines the following output variables:

     OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?

     OPENSCENEGRAPH_VERSION - The version of the OSG which was found

     OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers

     OPENSCENEGRAPH_LIBRARIES - The OSG libraries

================================== Example Usage:

     find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
         # libOpenThreads & libosg automatically searched
     include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})

     add_executable(foo foo.cc)
     target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})

15.2.85 FindOpenSSL
-------------------

Find the OpenSSL encryption library.

15.2.85.1 Optional COMPONENTS
.............................

This module supports two optional COMPONENTS: ‘Crypto’ and ‘SSL’.  Both
components have associated imported targets, as described below.

15.2.85.2 Imported Targets
..........................

This module defines the following IMPORTED targets:

‘OpenSSL::SSL’

     The OpenSSL ‘ssl’ library, if found.

‘OpenSSL::Crypto’

     The OpenSSL ‘crypto’ library, if found.

‘OpenSSL::applink’

     The OpenSSL ‘applink’ components that might be need to be compiled
     into projects under MSVC. This target is available only if found
     OpenSSL version is not less than 0.9.8.  By linking this target the
     above OpenSSL targets can be linked even if the project has
     different MSVC runtime configurations with the above OpenSSL
     targets.  This target has no effect on platforms other than MSVC.

NOTE: Due to how ‘INTERFACE_SOURCES’ are consumed by the consuming
target, unless you certainly know what you are doing, it is always
preferred to link ‘OpenSSL::applink’ target as ‘PRIVATE’ and to make
sure that this target is linked at most once for the whole dependency
graph of any library or executable:

     target_link_libraries(myTarget PRIVATE OpenSSL::applink)

Otherwise you would probably encounter unexpected random problems when
building and linking, as both the ISO C and the ISO C++ standard claims
almost nothing about what a link process should be.

15.2.85.3 Result Variables
..........................

This module will set the following variables in your project:

‘OPENSSL_FOUND’

     System has the OpenSSL library.  If no components are requested it
     only requires the crypto library.

‘OPENSSL_INCLUDE_DIR’

     The OpenSSL include directory.

‘OPENSSL_CRYPTO_LIBRARY’

     The OpenSSL crypto library.

‘OPENSSL_CRYPTO_LIBRARIES’

     The OpenSSL crypto library and its dependencies.

‘OPENSSL_SSL_LIBRARY’

     The OpenSSL SSL library.

‘OPENSSL_SSL_LIBRARIES’

     The OpenSSL SSL library and its dependencies.

‘OPENSSL_LIBRARIES’

     All OpenSSL libraries and their dependencies.

‘OPENSSL_VERSION’

     This is set to ‘$major.$minor.$revision$patch’ (e.g.  ‘0.9.8s’).

‘OPENSSL_APPLINK_SOURCE’

     The sources in the target ‘OpenSSL::applink’ that is mentioned
     above.  This variable shall always be undefined if found openssl
     version is less than 0.9.8 or if platform is not MSVC.

15.2.85.4 Hints
...............

Set ‘OPENSSL_ROOT_DIR’ to the root directory of an OpenSSL installation.
Set ‘OPENSSL_USE_STATIC_LIBS’ to ‘TRUE’ to look for static libraries.
Set ‘OPENSSL_MSVC_STATIC_RT’ set ‘TRUE’ to choose the MT version of the
lib.

15.2.86 FindOpenThreads
-----------------------

OpenThreads is a C++ based threading library.  Its largest userbase
seems to OpenSceneGraph so you might notice I accept OSGDIR as an
environment path.  I consider this part of the Findosg* suite used to
find OpenSceneGraph components.  Each component is separate and you must
opt in to each module.

Locate OpenThreads This module defines OPENTHREADS_LIBRARY
OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
OPENTHREADS_INCLUDE_DIR, where to find the headers

$OPENTHREADS_DIR is an environment variable that would correspond to the
./configure –prefix=$OPENTHREADS_DIR used in building osg.

[CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
be used as well to influence detection, instead of needing to specify an
environment variable.

Created by Eric Wing.

15.2.87 Findosg
---------------

NOTE: It is highly recommended that you use the new
FindOpenSceneGraph.cmake introduced in CMake 2.6.3 and not use this Find
module directly.

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osg This module defines

OSG_FOUND - Was the Osg found?  OSG_INCLUDE_DIR - Where to find the
headers OSG_LIBRARIES - The libraries to link against for the OSG (use
this)

OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.88 Findosg_functions
-------------------------

This CMake file contains two macros to assist with searching for OSG
libraries and nodekits.  Please see FindOpenSceneGraph.cmake for full
documentation.

15.2.89 FindosgAnimation
------------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgAnimation This module defines

OSGANIMATION_FOUND - Was osgAnimation found?  OSGANIMATION_INCLUDE_DIR -
Where to find the headers OSGANIMATION_LIBRARIES - The libraries to link
against for the OSG (use this)

OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
OSG debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.90 FindosgDB
-----------------

This is part of the ‘Findosg*’ suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL module
doesn’t work with your system as an example).  If you want to use a more
convenient module that includes everything, use the
FindOpenSceneGraph instead of the ‘Findosg*.cmake’ modules.

Locate osgDB This module defines:

‘OSGDB_FOUND’

     Was osgDB found?

‘OSGDB_INCLUDE_DIR’

     Where to find the headers

‘OSGDB_LIBRARIES’

     The libraries to link against for the osgDB

‘OSGDB_LIBRARY’

     The osgDB library

‘OSGDB_LIBRARY_DEBUG’

     The osgDB debug library

‘$OSGDIR’ is an environment variable that would correspond to:

     ./configure --prefix=$OSGDIR used in building osg.

15.2.91 FindosgFX
-----------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgFX This module defines

OSGFX_FOUND - Was osgFX found?  OSGFX_INCLUDE_DIR - Where to find the
headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
(use this)

OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.92 FindosgGA
-----------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgGA This module defines

OSGGA_FOUND - Was osgGA found?  OSGGA_INCLUDE_DIR - Where to find the
headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
(use this)

OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.93 FindosgIntrospection
----------------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgINTROSPECTION This module defines

OSGINTROSPECTION_FOUND - Was osgIntrospection found?
OSGINTROSPECTION_INCLUDE_DIR - Where to find the headers
OSGINTROSPECTION_LIBRARIES - The libraries to link for osgIntrospection
(use this)

OSGINTROSPECTION_LIBRARY - The osgIntrospection library
OSGINTROSPECTION_LIBRARY_DEBUG - The osgIntrospection debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.94 FindosgManipulator
--------------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgManipulator This module defines

OSGMANIPULATOR_FOUND - Was osgManipulator found?
OSGMANIPULATOR_INCLUDE_DIR - Where to find the headers
OSGMANIPULATOR_LIBRARIES - The libraries to link for osgManipulator (use
this)

OSGMANIPULATOR_LIBRARY - The osgManipulator library
OSGMANIPULATOR_LIBRARY_DEBUG - The osgManipulator debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.95 FindosgParticle
-----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgParticle This module defines

OSGPARTICLE_FOUND - Was osgParticle found?  OSGPARTICLE_INCLUDE_DIR -
Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
for osgParticle (use this)

OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
- The osgParticle debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.96 FindosgPresentation
---------------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgPresentation This module defines

OSGPRESENTATION_FOUND - Was osgPresentation found?
OSGPRESENTATION_INCLUDE_DIR - Where to find the headers
OSGPRESENTATION_LIBRARIES - The libraries to link for osgPresentation
(use this)

OSGPRESENTATION_LIBRARY - The osgPresentation library
OSGPRESENTATION_LIBRARY_DEBUG - The osgPresentation debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.  Modified to work with osgPresentation by Robert
Osfield, January 2012.

15.2.97 FindosgProducer
-----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgProducer This module defines

OSGPRODUCER_FOUND - Was osgProducer found?  OSGPRODUCER_INCLUDE_DIR -
Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
for osgProducer (use this)

OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
- The osgProducer debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.98 FindosgQt
-----------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgQt This module defines

OSGQT_FOUND - Was osgQt found?  OSGQT_INCLUDE_DIR - Where to find the
headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)

OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.  Modified to work with osgQt by Robert Osfield,
January 2012.

15.2.99 FindosgShadow
---------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgShadow This module defines

OSGSHADOW_FOUND - Was osgShadow found?  OSGSHADOW_INCLUDE_DIR - Where to
find the headers OSGSHADOW_LIBRARIES - The libraries to link for
osgShadow (use this)

OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
osgShadow debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.100 FindosgSim
-------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgSim This module defines

OSGSIM_FOUND - Was osgSim found?  OSGSIM_INCLUDE_DIR - Where to find the
headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)

OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.101 FindosgTerrain
-----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgTerrain This module defines

OSGTERRAIN_FOUND - Was osgTerrain found?  OSGTERRAIN_INCLUDE_DIR - Where
to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
osgTerrain (use this)

OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
The osgTerrain debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.102 FindosgText
--------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgText This module defines

OSGTEXT_FOUND - Was osgText found?  OSGTEXT_INCLUDE_DIR - Where to find
the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
this)

OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The
osgText debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.103 FindosgUtil
--------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgUtil This module defines

OSGUTIL_FOUND - Was osgUtil found?  OSGUTIL_INCLUDE_DIR - Where to find
the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
this)

OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
osgUtil debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.104 FindosgViewer
----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgViewer This module defines

OSGVIEWER_FOUND - Was osgViewer found?  OSGVIEWER_INCLUDE_DIR - Where to
find the headers OSGVIEWER_LIBRARIES - The libraries to link for
osgViewer (use this)

OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
osgViewer debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.105 FindosgVolume
----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgVolume This module defines

OSGVOLUME_FOUND - Was osgVolume found?  OSGVOLUME_INCLUDE_DIR - Where to
find the headers OSGVOLUME_LIBRARIES - The libraries to link for
osgVolume (use this)

OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
osgVolume debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

Created by Eric Wing.

15.2.106 FindosgWidget
----------------------

This is part of the Findosg* suite used to find OpenSceneGraph
components.  Each component is separate and you must opt in to each
module.  You must also opt into OpenGL and OpenThreads (and Producer if
needed) as these modules won’t do it for you.  This is to allow you
control over your own system piece by piece in case you need to opt out
of certain components or change the Find behavior for a particular
module (perhaps because the default FindOpenGL.cmake module doesn’t work
with your system as an example).  If you want to use a more convenient
module that includes everything, use the FindOpenSceneGraph.cmake
instead of the Findosg*.cmake modules.

Locate osgWidget This module defines

OSGWIDGET_FOUND - Was osgWidget found?  OSGWIDGET_INCLUDE_DIR - Where to
find the headers OSGWIDGET_LIBRARIES - The libraries to link for
osgWidget (use this)

OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
osgWidget debug library

$OSGDIR is an environment variable that would correspond to the
./configure –prefix=$OSGDIR used in building osg.

FindosgWidget.cmake tweaked from Findosg* suite as created by Eric Wing.

15.2.107 FindPatch
------------------

New in version 3.10.

The module defines the following variables:

‘Patch_EXECUTABLE’

     Path to patch command-line executable.

‘Patch_FOUND’

     True if the patch command-line executable was found.

The following IMPORTED targets are also defined:

‘Patch::patch’

     The command-line executable.

Example usage:

     find_package(Patch)
     if(Patch_FOUND)
       message("Patch found: ${Patch_EXECUTABLE}")
     endif()

15.2.108 FindPerl
-----------------

Find perl

this module looks for Perl

     PERL_EXECUTABLE     - the full path to perl
     PERL_FOUND          - If false, don't attempt to use perl.
     PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)

15.2.109 FindPerlLibs
---------------------

Find Perl libraries

This module finds if PERL is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     PERLLIBS_FOUND    = True if perl.h & libperl were found
     PERL_INCLUDE_PATH = path to where perl.h is found
     PERL_LIBRARY      = path to libperl
     PERL_EXECUTABLE   = full path to the perl binary

The minimum required version of Perl can be specified using the standard
syntax, e.g.  find_package(PerlLibs 6.0)

     The following variables are also available if needed
     (introduced after CMake 2.6.4)

     PERL_SITESEARCH     = path to the sitesearch install dir (-V:installsitesearch)
     PERL_SITEARCH       = path to the sitelib install directory (-V:installsitearch)
     PERL_SITELIB        = path to the sitelib install directory (-V:installsitelib)
     PERL_VENDORARCH     = path to the vendor arch install directory (-V:installvendorarch)
     PERL_VENDORLIB      = path to the vendor lib install directory (-V:installvendorlib)
     PERL_ARCHLIB        = path to the core arch lib install directory (-V:archlib)
     PERL_PRIVLIB        = path to the core priv lib install directory (-V:privlib)
     PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
     PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
     PERL_EXTRA_C_FLAGS = Compilation flags used to build perl

15.2.110 FindPHP4
-----------------

Find PHP4

This module finds if PHP4 is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     PHP4_INCLUDE_PATH       = path to where php.h can be found
     PHP4_EXECUTABLE         = full path to the php4 binary

15.2.111 FindPhysFS
-------------------

Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
the library to link against PHYSFS_FOUND, if false, do not try to link
to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h

$PHYSFSDIR is an environment variable that would correspond to the
./configure –prefix=$PHYSFSDIR used in building PHYSFS.

Created by Eric Wing.

15.2.112 FindPike
-----------------

Find Pike

This module finds if PIKE is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     PIKE_INCLUDE_PATH       = path to where program.h is found
     PIKE_EXECUTABLE         = full path to the pike binary

15.2.113 FindPkgConfig
----------------------

A ‘pkg-config’ module for CMake.

Finds the ‘pkg-config’ executable and adds the pkg_get_variable(),
see pkg_check_modules() and pkg_search_module().
commands.  The following variables will also be set:

‘PKG_CONFIG_FOUND’

     if pkg-config executable was found

‘PKG_CONFIG_EXECUTABLE’

     pathname of the pkg-config program

‘PKG_CONFIG_VERSION_STRING’

     version of pkg-config (since CMake 2.8.8)

 -- Command: pkg_check_modules

     Checks for all the given modules, setting a variety of result
     variables in the calling scope.

          pkg_check_modules(<prefix>
                            [REQUIRED] [QUIET]
                            [NO_CMAKE_PATH]
                            [NO_CMAKE_ENVIRONMENT_PATH]
                            [IMPORTED_TARGET [GLOBAL]]
                            <moduleSpec> [<moduleSpec>...])

     When the ‘REQUIRED’ argument is given, the command will fail with
     an error if module(s) could not be found.

     When the ‘QUIET’ argument is given, no status messages will be
     printed.

     By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or
     later, or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to
     a boolean ‘True’ value, then the CMAKE_PREFIX_PATH,
     CMAKE_FRAMEWORK_PATH, and CMAKE_APPBUNDLE_PATH
     cache and environment variables will be added to the
     ‘pkg-config’ search path.  The ‘NO_CMAKE_PATH’ and
     ‘NO_CMAKE_ENVIRONMENT_PATH’ arguments disable this behavior for the
     cache variables and environment variables respectively.

     The ‘IMPORTED_TARGET’ argument will create an imported target named
     ‘PkgConfig::<prefix>’ that can be passed directly as an argument to
     target_link_libraries().  The ‘GLOBAL’ argument will make
     the imported target available in global scope.

     Each ‘<moduleSpec>’ can be either a bare module name or it can be a
     module name with a version constraint (operators ‘=’, ‘<’, ‘>’,
     ‘<=’ and ‘>=’ are supported).  The following are examples for a
     module named ‘foo’ with various constraints:

        - ‘foo’ matches any version.

        - ‘foo<2’ only matches versions before 2.

        - ‘foo>=3.1’ matches any version from 3.1 or later.

        - ‘foo=1.2.3’ requires that foo must be exactly version 1.2.3.

     The following variables may be set upon return.  Two sets of values
     exist: One for the common case (‘<XXX> = <prefix>’) and another for
     the information ‘pkg-config’ provides when called with the
     ‘--static’ option (‘<XXX> = <prefix>_STATIC’).

     ‘<XXX>_FOUND’

          set to 1 if module(s) exist

     ‘<XXX>_LIBRARIES’

          only the libraries (without the ‘-l’)

     ‘<XXX>_LINK_LIBRARIES’

          the libraries and their absolute paths

     ‘<XXX>_LIBRARY_DIRS’

          the paths of the libraries (without the ‘-L’)

     ‘<XXX>_LDFLAGS’

          all required linker flags

     ‘<XXX>_LDFLAGS_OTHER’

          all other linker flags

     ‘<XXX>_INCLUDE_DIRS’

          the ‘-I’ preprocessor flags (without the ‘-I’)

     ‘<XXX>_CFLAGS’

          all required cflags

     ‘<XXX>_CFLAGS_OTHER’

          the other compiler flags

     All but ‘<XXX>_FOUND’ may be a ;-list if the associated
     variable returned from ‘pkg-config’ has multiple values.

     There are some special variables whose prefix depends on the number
     of ‘<moduleSpec>’ given.  When there is only one ‘<moduleSpec>’,
     ‘<YYY>’ will simply be ‘<prefix>’, but if two or more
     ‘<moduleSpec>’ items are given, ‘<YYY>’ will be
     ‘<prefix>_<moduleName>’.

     ‘<YYY>_VERSION’

          version of the module

     ‘<YYY>_PREFIX’

          prefix directory of the module

     ‘<YYY>_INCLUDEDIR’

          include directory of the module

     ‘<YYY>_LIBDIR’

          lib directory of the module

     Examples:

          pkg_check_modules (GLIB2 glib-2.0)

     Looks for any version of glib2.  If found, the output variable
     ‘GLIB2_VERSION’ will hold the actual version found.

          pkg_check_modules (GLIB2 glib-2.0>=2.10)

     Looks for at least version 2.10 of glib2.  If found, the output
     variable ‘GLIB2_VERSION’ will hold the actual version found.

          pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)

     Looks for both glib2-2.0 (at least version 2.10) and any version of
     gtk2+-2.0.  Only if both are found will ‘FOO’ be considered found.
     The ‘FOO_glib-2.0_VERSION’ and ‘FOO_gtk+-2.0_VERSION’ variables
     will be set to their respective found module versions.

          pkg_check_modules (XRENDER REQUIRED xrender)

     Requires any version of ‘xrender’.  Example output variables set by
     a successful call:

          XRENDER_LIBRARIES=Xrender;X11
          XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp

 -- Command: pkg_search_module

     The behavior of this command is the same as
     pkg_check_modules(), except that rather than checking for all
     the specified modules, it searches for just the first successful
     match.

          pkg_search_module(<prefix>
                            [REQUIRED] [QUIET]
                            [NO_CMAKE_PATH]
                            [NO_CMAKE_ENVIRONMENT_PATH]
                            [IMPORTED_TARGET [GLOBAL]]
                            <moduleSpec> [<moduleSpec>...])

     If a module is found, the ‘<prefix>_MODULE_NAME’ variable will
     contain the name of the matching module.  This variable can be used
     if you need to run pkg_get_variable().

     Example:

          pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)

 -- Command: pkg_get_variable

     Retrieves the value of a pkg-config variable ‘varName’ and stores
     it in the result variable ‘resultVar’ in the calling scope.

          pkg_get_variable(<resultVar> <moduleName> <varName>)

     If ‘pkg-config’ returns multiple values for the specified variable,
     ‘resultVar’ will contain a ;-list.

     For example:

          pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)

15.2.113.1 Variables Affecting Behavior
.......................................

 -- Variable: PKG_CONFIG_EXECUTABLE

     This can be set to the path of the pkg-config executable.  If not
     provided, it will be set by the module as a result of calling
     find_program() internally.  The ‘PKG_CONFIG’ environment
     variable can be used as a hint.

 -- Variable: PKG_CONFIG_USE_CMAKE_PREFIX_PATH

     Specifies whether pkg_check_modules() and
     pkg_search_module() should add the paths in the
     CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH and
     CMAKE_APPBUNDLE_PATH cache and environment variables to the
     ‘pkg-config’ search path.

     If this variable is not set, this behavior is enabled by default if
     CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
     disabled otherwise.

15.2.114 FindPNG
----------------

Find libpng, the official reference library for the PNG image format.

15.2.114.1 Imported targets
...........................

This module defines the following IMPORTED target:

‘PNG::PNG’

     The libpng library, if found.

15.2.114.2 Result variables
...........................

This module will set the following variables in your project:

‘PNG_INCLUDE_DIRS’

     where to find png.h, etc.

‘PNG_LIBRARIES’

     the libraries to link against to use PNG.

‘PNG_DEFINITIONS’

     You should add_definitions(${PNG_DEFINITIONS}) before compiling
     code that includes png library files.

‘PNG_FOUND’

     If false, do not try to use PNG.

‘PNG_VERSION_STRING’

     the version of the PNG library found (since CMake 2.8.8)

15.2.114.3 Obsolete variables
.............................

The following variables may also be set, for backwards compatibility:

‘PNG_LIBRARY’

     where to find the PNG library.

‘PNG_INCLUDE_DIR’

     where to find the PNG headers (same as PNG_INCLUDE_DIRS)

Since PNG depends on the ZLib compression library, none of the above
will be defined unless ZLib can be found.

15.2.115 FindPostgreSQL
-----------------------

Find the PostgreSQL installation.

15.2.115.1 IMPORTED Targets
...........................

This module defines IMPORTED target ‘PostgreSQL::PostgreSQL’
if PostgreSQL has been found.

15.2.115.2 Result Variables
...........................

This module will set the following variables in your project:

‘PostgreSQL_FOUND’

     True if PostgreSQL is found.

‘PostgreSQL_LIBRARIES’

     the PostgreSQL libraries needed for linking

‘PostgreSQL_INCLUDE_DIRS’

     the directories of the PostgreSQL headers

‘PostgreSQL_LIBRARY_DIRS’

     the link directories for PostgreSQL libraries

‘PostgreSQL_VERSION_STRING’

     the version of PostgreSQL found

15.2.116 FindProducer
---------------------

Though Producer isn’t directly part of OpenSceneGraph, its primary user
is OSG so I consider this part of the Findosg* suite used to find
OpenSceneGraph components.  You’ll notice that I accept OSGDIR as an
environment path.

Each component is separate and you must opt in to each module.  You must
also opt into OpenGL (and OpenThreads?)  as these modules won’t do it
for you.  This is to allow you control over your own system piece by
piece in case you need to opt out of certain components or change the
Find behavior for a particular module (perhaps because the default
FindOpenGL.cmake module doesn’t work with your system as an example).
If you want to use a more convenient module that includes everything,
use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.

Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
find the headers

$PRODUCER_DIR is an environment variable that would correspond to the
./configure –prefix=$PRODUCER_DIR used in building osg.

Created by Eric Wing.

15.2.117 FindProtobuf
---------------------

Locate and configure the Google Protocol Buffers library.

The following variables can be set and are optional:

‘Protobuf_SRC_ROOT_FOLDER’

     When compiling with MSVC, if this cache variable is set the
     protobuf-default VS project build locations (vsprojects/Debug and
     vsprojects/Release or vsprojects/x64/Debug and
     vsprojects/x64/Release) will be searched for libraries and
     binaries.

‘Protobuf_IMPORT_DIRS’

     List of additional directories to be searched for imported .proto
     files.

‘Protobuf_DEBUG’

     Show debug messages.

‘Protobuf_USE_STATIC_LIBS’

     Set to ON to force the use of the static libraries.  Default is
     OFF.

Defines the following variables:

‘Protobuf_FOUND’

     Found the Google Protocol Buffers library (libprotobuf & header
     files)

‘Protobuf_VERSION’

     Version of package found.

‘Protobuf_INCLUDE_DIRS’

     Include directories for Google Protocol Buffers

‘Protobuf_LIBRARIES’

     The protobuf libraries

‘Protobuf_PROTOC_LIBRARIES’

     The protoc libraries

‘Protobuf_LITE_LIBRARIES’

     The protobuf-lite libraries

The following IMPORTED targets are also defined:

‘protobuf::libprotobuf’

     The protobuf library.

‘protobuf::libprotobuf-lite’

     The protobuf lite library.

‘protobuf::libprotoc’

     The protoc library.

‘protobuf::protoc’

     The protoc compiler.

The following cache variables are also available to set or use:

‘Protobuf_LIBRARY’

     The protobuf library

‘Protobuf_PROTOC_LIBRARY’

     The protoc library

‘Protobuf_INCLUDE_DIR’

     The include directory for protocol buffers

‘Protobuf_PROTOC_EXECUTABLE’

     The protoc compiler

‘Protobuf_LIBRARY_DEBUG’

     The protobuf library (debug)

‘Protobuf_PROTOC_LIBRARY_DEBUG’

     The protoc library (debug)

‘Protobuf_LITE_LIBRARY’

     The protobuf lite library

‘Protobuf_LITE_LIBRARY_DEBUG’

     The protobuf lite library (debug)

Example:

     find_package(Protobuf REQUIRED)
     include_directories(${Protobuf_INCLUDE_DIRS})
     include_directories(${CMAKE_CURRENT_BINARY_DIR})
     protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
     protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
     protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
     protobuf_generate_python(PROTO_PY foo.proto)
     add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
     target_link_libraries(bar ${Protobuf_LIBRARIES})

     Note: The ‘protobuf_generate_cpp’ and ‘protobuf_generate_python’
     functions and add_executable() or add_library()
     calls only work properly within the same directory.

 -- Command: protobuf_generate_cpp

     Add custom commands to process ‘.proto’ files to C++:

          protobuf_generate_cpp (<SRCS> <HDRS>
              [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])

     ‘SRCS’

          Variable to define with autogenerated source files

     ‘HDRS’

          Variable to define with autogenerated header files

     ‘DESCRIPTORS’

          Variable to define with autogenerated descriptor files, if
          requested.

     ‘EXPORT_MACRO’

          is a macro which should expand to ‘__declspec(dllexport)’ or
          ‘__declspec(dllimport)’ depending on what is being compiled.

     ‘ARGN’

          ‘.proto’ files

 -- Command: protobuf_generate_python

     Add custom commands to process ‘.proto’ files to Python:

          protobuf_generate_python (<PY> [<ARGN>...])

     ‘PY’

          Variable to define with autogenerated Python files

     ‘ARGN’

          ‘.proto’ files

15.2.118 FindPython
-------------------

New in version 3.12.

Find Python interpreter, compiler and development environment (include
directories and libraries).

When a version is requested, it can be specified as a simple value or as
a range.  For a detailed description of version range usage and
capabilities, refer to the find_package() command.

The following components are supported:

   * ‘Interpreter’: search for Python interpreter.

   * ‘Compiler’: search for Python compiler.  Only offered by
     IronPython.

   * ‘Development’: search for development artifacts (include
     directories and libraries).  This component includes two
     sub-components which can be specified independently:

        * ‘Development.Module’: search for artifacts for Python module
          developments.

        * ‘Development.Embed’: search for artifacts for Python embedding
          developments.

   * ‘NumPy’: search for NumPy include directories.

If no ‘COMPONENTS’ are specified, ‘Interpreter’ is assumed.

If component ‘Development’ is specified, it implies sub-components
‘Development.Module’ and ‘Development.Embed’.

To ensure consistent versions between components ‘Interpreter’,
‘Compiler’, ‘Development’ (or one of its sub-components) and ‘NumPy’,
specify all components at the same time:

     find_package (Python COMPONENTS Interpreter Development)

This module looks preferably for version 3 of Python.  If not found,
version 2 is searched.  To manage concurrent versions 3 and 2 of Python,
use FindPython3 and FindPython2 modules rather
than this one.

     Note: If components ‘Interpreter’ and ‘Development’ (or one of its
     sub-components) are both specified, this module search only for
     interpreter with same platform architecture as the one defined by
     ‘CMake’ configuration.  This constraint does not apply if only
     ‘Interpreter’ component is specified.

15.2.118.1 Imported Targets
...........................

This module defines the following Imported Targets. (when
CMAKE_ROLE is ‘PROJECT’):

‘Python::Interpreter’

     Python interpreter.  Target defined if component ‘Interpreter’ is
     found.

‘Python::Compiler’

     Python compiler.  Target defined if component ‘Compiler’ is found.

‘Python::Module’

     Python library for Python module.  Target defined if component
     ‘Development.Module’ is found.

‘Python::Python’

     Python library for Python embedding.  Target defined if component
     ‘Development.Embed’ is found.

‘Python::NumPy’

     NumPy Python library.  Target defined if component ‘NumPy’ is
     found.

15.2.118.2 Result Variables
...........................

This module will set the following variables in your project (see
Standard Variable Names):

‘Python_FOUND’

     System has the Python requested components.

‘Python_Interpreter_FOUND’

     System has the Python interpreter.

‘Python_EXECUTABLE’

     Path to the Python interpreter.

‘Python_INTERPRETER_ID’

     A short string unique to the interpreter. Possible values include:

             * Python

             * ActivePython

             * Anaconda

             * Canopy

             * IronPython

             * PyPy

‘Python_STDLIB’

     Standard platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)’
     or else ‘sysconfig.get_path('stdlib')’.

‘Python_STDARCH’

     Standard platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)’
     or else ‘sysconfig.get_path('platstdlib')’.

‘Python_SITELIB’

     Third-party platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)’
     or else ‘sysconfig.get_path('purelib')’.

‘Python_SITEARCH’

     Third-party platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)’
     or else ‘sysconfig.get_path('platlib')’.

‘Python_SOABI’

     Extension suffix for modules.

     Information returned by
     ‘distutils.sysconfig.get_config_var('SOABI')’ or computed from
     ‘distutils.sysconfig.get_config_var('EXT_SUFFIX')’ or
     ‘python-config --extension-suffix’.  If package
     ‘distutils.sysconfig’ is not available,
     ‘sysconfig.get_config_var('SOABI')’ or
     ‘sysconfig.get_config_var('EXT_SUFFIX')’ are used.

‘Python_Compiler_FOUND’

     System has the Python compiler.

‘Python_COMPILER’

     Path to the Python compiler.  Only offered by IronPython.

‘Python_COMPILER_ID’

     A short string unique to the compiler. Possible values include:

             * IronPython

‘Python_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python_Development_FOUND’

     System has the Python development artifacts.

‘Python_Development.Module_FOUND’

     System has the Python development artifacts for Python module.

‘Python_Development.Embed_FOUND’

     System has the Python development artifacts for Python embedding.

‘Python_INCLUDE_DIRS’

     The Python include directories.

‘Python_LINK_OPTIONS’

     The Python link options.  Some configurations require specific link
     options for a correct build and execution.

‘Python_LIBRARIES’

     The Python libraries.

‘Python_LIBRARY_DIRS’

     The Python library directories.

‘Python_RUNTIME_LIBRARY_DIRS’

     The Python runtime library directories.

‘Python_VERSION’

     Python version.

‘Python_VERSION_MAJOR’

     Python major version.

‘Python_VERSION_MINOR’

     Python minor version.

‘Python_VERSION_PATCH’

     Python patch version.

‘Python_PyPy_VERSION’

     Python PyPy version.

‘Python_NumPy_FOUND’

     System has the NumPy.

‘Python_NumPy_INCLUDE_DIRS’

     The NumPy include directories.

‘Python_NumPy_VERSION’

     The NumPy version.

15.2.118.3 Hints
................

‘Python_ROOT_DIR’

     Define the root directory of a Python installation.

‘Python_USE_STATIC_LIBS’

        * If not defined, search for shared libraries and static
          libraries in that order.

        * If set to TRUE, search `only' for static libraries.

        * If set to FALSE, search `only' for shared libraries.

‘Python_FIND_ABI’

     This variable defines which ABIs, as defined in PEP 3149(1), should
     be searched.

          Note: This hint will be honored only when searched for
          ‘Python’ version 3.

          Note: If ‘Python_FIND_ABI’ is not defined, any ABI will be
          searched.

     The ‘Python_FIND_ABI’ variable is a 3-tuple specifying, in that
     order, ‘pydebug’ (‘d’), ‘pymalloc’ (‘m’) and ‘unicode’ (‘u’) flags.
     Each element can be set to one of the following:

        * ‘ON’: Corresponding flag is selected.

        * ‘OFF’: Corresponding flag is not selected.

        * ‘ANY’: The two possibilities (‘ON’ and ‘OFF’) will be
          searched.

     From this 3-tuple, various ABIs will be searched starting from the
     most specialized to the most general.  Moreover, ‘debug’ versions
     will be searched `after' ‘non-debug’ ones.

     For example, if we have:

          set (Python_FIND_ABI "ON" "ANY" "ANY")

     The following flags combinations will be appended, in that order,
     to the artifact names: ‘dmu’, ‘dm’, ‘du’, and ‘d’.

     And to search any possible ABIs:

          set (Python_FIND_ABI "ANY" "ANY" "ANY")

     The following combinations, in that order, will be used: ‘mu’, ‘m’,
     ‘u’, ‘<empty>’, ‘dmu’, ‘dm’, ‘du’ and ‘d’.

          Note: This hint is useful only on ‘POSIX’ systems.  So, on
          ‘Windows’ systems, when ‘Python_FIND_ABI’ is defined, ‘Python’
          distributions from python.org(2) will be found only if value
          for each flag is ‘OFF’ or ‘ANY’.

‘Python_FIND_STRATEGY’

     This variable defines how lookup will be done.  The
     ‘Python_FIND_STRATEGY’ variable can be set to one of the following:

        * ‘VERSION’: Try to find the most recent version in all
          specified locations.  This is the default if policy
          CMP0094 is undefined or set to ‘OLD’.

        * ‘LOCATION’: Stops lookup as soon as a version satisfying
          version constraints is founded.  This is the default if policy
          CMP0094 is set to ‘NEW’.

‘Python_FIND_REGISTRY’

     On Windows the ‘Python_FIND_REGISTRY’ variable determine the order
     of preference between registry and environment variables.  the
     ‘Python_FIND_REGISTRY’ variable can be set to one of the following:

        * ‘FIRST’: Try to use registry before environment variables.
          This is the default.

        * ‘LAST’: Try to use registry after environment variables.

        * ‘NEVER’: Never try to use registry.

‘Python_FIND_FRAMEWORK’

     On macOS the ‘Python_FIND_FRAMEWORK’ variable determine the order
     of preference between Apple-style and unix-style package
     components.  This variable can take same values as
     CMAKE_FIND_FRAMEWORK variable.

          Note: Value ‘ONLY’ is not supported so ‘FIRST’ will be used
          instead.

     If ‘Python_FIND_FRAMEWORK’ is not defined, see
     CMAKE_FIND_FRAMEWORK variable will be used, if any.

‘Python_FIND_VIRTUALENV’

     This variable defines the handling of virtual environments managed
     by ‘virtualenv’ or ‘conda’.  It is meaningful only when a virtual
     environment is active (i.e.  the ‘activate’ script has been
     evaluated).  In this case, it takes precedence over
     ‘Python_FIND_REGISTRY’ and ‘CMAKE_FIND_FRAMEWORK’ variables.  The
     ‘Python_FIND_VIRTUALENV’ variable can be set to one of the
     following:

        * ‘FIRST’: The virtual environment is used before any other
          standard paths to look-up for the interpreter.  This is the
          default.

        * ‘ONLY’: Only the virtual environment is used to look-up for
          the interpreter.

        * ‘STANDARD’: The virtual environment is not used to look-up for
          the interpreter but environment variable ‘PATH’ is always
          considered.  In this case, variable ‘Python_FIND_REGISTRY’
          (Windows) or ‘CMAKE_FIND_FRAMEWORK’ (macOS) can be set with
          value ‘LAST’ or ‘NEVER’ to select preferably the interpreter
          from the virtual environment.

          Note: If the component ‘Development’ is requested, it is
          `strongly' recommended to also include the component
          ‘Interpreter’ to get expected result.

‘Python_FIND_IMPLEMENTATIONS’

     This variable defines, in an ordered list, the different
     implementations which will be searched.  The
     ‘Python_FIND_IMPLEMENTATIONS’ variable can hold the following
     values:

        * ‘CPython’: this is the standard implementation.  Various
          products, like ‘Anaconda’ or ‘ActivePython’, rely on this
          implementation.

        * ‘IronPython’: This implementation use the ‘CSharp’ language
          for ‘.NET Framework’ on top of the ‘Dynamic Language Runtime’
          (‘DLR’).  See IronPython(3).

        * ‘PyPy’: This implementation use ‘RPython’ language and
          ‘RPython translation toolchain’ to produce the python
          interpreter.  See PyPy(4).

     The default value is:

        * Windows platform: ‘CPython’, ‘IronPython’

        * Other platforms: ‘CPython’

          Note: This hint has the lowest priority of all hints, so even
          if, for example, you specify ‘IronPython’ first and ‘CPython’
          in second, a python product based on ‘CPython’ can be selected
          because, for example with ‘Python_FIND_STRATEGY=LOCATION’,
          each location will be search first for ‘IronPython’ and second
          for ‘CPython’.

          Note: When ‘IronPython’ is specified, on platforms other than
          ‘Windows’, the ‘.Net’ interpreter (i.e.  ‘mono’ command) is
          expected to be available through the ‘PATH’ variable.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-3149/

   (2) https://www.python.org/

   (3) http://ironpython.net

   (4) https://www.pypy.org

15.2.118.4 Artifacts Specification
..................................

To solve special cases, it is possible to specify directly the artifacts
by setting the following variables:

‘Python_EXECUTABLE’

     The path to the interpreter.

‘Python_COMPILER’

     The path to the compiler.

‘Python_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python_LIBRARY’

     The path to the library.  It will be used to compute the variables
     ‘Python_LIBRARIES’, ‘Python_LIBRARY_DIRS’ and
     ‘Python_RUNTIME_LIBRARY_DIRS’.

‘Python_INCLUDE_DIR’

     The path to the directory of the ‘Python’ headers.  It will be used
     to compute the variable ‘Python_INCLUDE_DIRS’.

‘Python_NumPy_INCLUDE_DIR’

     The path to the directory of the ‘NumPy’ headers.  It will be used
     to compute the variable ‘Python_NumPy_INCLUDE_DIRS’.

     Note: All paths must be absolute.  Any artifact specified with a
     relative path will be ignored.

     Note: When an artifact is specified, all ‘HINTS’ will be ignored
     and no search will be performed for this artifact.

     If more than one artifact is specified, it is the user’s
     responsibility to ensure the consistency of the various artifacts.

By default, this module supports multiple calls in different directories
of a project with different version/component requirements while
providing correct and consistent results for each call.  To support this
behavior, ‘CMake’ cache is not used in the traditional way which can be
problematic for interactive specification.  So, to enable also
interactive specification, module behavior can be controlled with the
following variable:

‘Python_ARTIFACTS_INTERACTIVE’

     Selects the behavior of the module.  This is a boolean variable:

        * If set to ‘TRUE’: Create CMake cache entries for the above
          artifact specification variables so that users can edit them
          interactively.  This disables support for multiple
          version/component requirements.

        * If set to ‘FALSE’ or undefined: Enable multiple
          version/component requirements.

15.2.118.5 Commands
...................

This module defines the command ‘Python_add_library’ (when
CMAKE_ROLE is ‘PROJECT’), which has the same semantics as
add_library() and adds a dependency to target ‘Python::Python’ or,
when library type is ‘MODULE’, to target ‘Python::Module’ and takes care
of Python module naming rules:

     Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
                         <source1> [<source2> ...])

If the library type is not specified, ‘MODULE’ is assumed.

For ‘MODULE’ library type, if option ‘WITH_SOABI’ is specified, the
module suffix will include the ‘Python_SOABI’ value, if any.

15.2.119 FindPython2
--------------------

New in version 3.12.

Find Python 2 interpreter, compiler and development environment (include
directories and libraries).

When a version is requested, it can be specified as a simple value or as
a range.  For a detailed description of version range usage and
capabilities, refer to the find_package() command.

The following components are supported:

   * ‘Interpreter’: search for Python 2 interpreter

   * ‘Compiler’: search for Python 2 compiler.  Only offered by
     IronPython.

   * ‘Development’: search for development artifacts (include
     directories and libraries).  This component includes two
     sub-components which can be specified independently:

        * ‘Development.Module’: search for artifacts for Python 2 module
          developments.

        * ‘Development.Embed’: search for artifacts for Python 2
          embedding developments.

   * ‘NumPy’: search for NumPy include directories.

If no ‘COMPONENTS’ are specified, ‘Interpreter’ is assumed.

If component ‘Development’ is specified, it implies sub-components
‘Development.Module’ and ‘Development.Embed’.

To ensure consistent versions between components ‘Interpreter’,
‘Compiler’, ‘Development’ (or one of its sub-components) and ‘NumPy’,
specify all components at the same time:

     find_package (Python2 COMPONENTS Interpreter Development)

This module looks only for version 2 of Python.  This module can be used
concurrently with FindPython3 module to use both Python
versions.

The FindPython module can be used if Python version does not
matter for you.

     Note: If components ‘Interpreter’ and ‘Development’ (or one of its
     sub-components) are both specified, this module search only for
     interpreter with same platform architecture as the one defined by
     ‘CMake’ configuration.  This constraint does not apply if only
     ‘Interpreter’ component is specified.

15.2.119.1 Imported Targets
...........................

This module defines the following Imported Targets. (when
CMAKE_ROLE is ‘PROJECT’):

‘Python2::Interpreter’

     Python 2 interpreter.  Target defined if component ‘Interpreter’ is
     found.

‘Python2::Compiler’

     Python 2 compiler.  Target defined if component ‘Compiler’ is
     found.

‘Python2::Module’

     Python 2 library for Python module.  Target defined if component
     ‘Development.Module’ is found.

‘Python2::Python’

     Python 2 library for Python embedding.  Target defined if component
     ‘Development.Embed’ is found.

‘Python2::NumPy’

     NumPy library for Python 2.  Target defined if component ‘NumPy’ is
     found.

15.2.119.2 Result Variables
...........................

This module will set the following variables in your project (see
Standard Variable Names):

‘Python2_FOUND’

     System has the Python 2 requested components.

‘Python2_Interpreter_FOUND’

     System has the Python 2 interpreter.

‘Python2_EXECUTABLE’

     Path to the Python 2 interpreter.

‘Python2_INTERPRETER_ID’

     A short string unique to the interpreter. Possible values include:

             * Python

             * ActivePython

             * Anaconda

             * Canopy

             * IronPython

             * PyPy

‘Python2_STDLIB’

     Standard platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)’
     or else ‘sysconfig.get_path('stdlib')’.

‘Python2_STDARCH’

     Standard platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)’
     or else ‘sysconfig.get_path('platstdlib')’.

‘Python2_SITELIB’

     Third-party platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)’
     or else ‘sysconfig.get_path('purelib')’.

‘Python2_SITEARCH’

     Third-party platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)’
     or else ‘sysconfig.get_path('platlib')’.

‘Python2_Compiler_FOUND’

     System has the Python 2 compiler.

‘Python2_COMPILER’

     Path to the Python 2 compiler.  Only offered by IronPython.

‘Python2_COMPILER_ID’

     A short string unique to the compiler. Possible values include:

             * IronPython

‘Python2_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python2_Development_FOUND’

     System has the Python 2 development artifacts.

‘Python2_Development.Module_FOUND’

     System has the Python 2 development artifacts for Python module.

‘Python2_Development.Embed_FOUND’

     System has the Python 2 development artifacts for Python embedding.

‘Python2_INCLUDE_DIRS’

     The Python 2 include directories.

‘Python2_LINK_OPTIONS’

     The Python 2 link options.  Some configurations require specific
     link options for a correct build and execution.

‘Python2_LIBRARIES’

     The Python 2 libraries.

‘Python2_LIBRARY_DIRS’

     The Python 2 library directories.

‘Python2_RUNTIME_LIBRARY_DIRS’

     The Python 2 runtime library directories.

‘Python2_VERSION’

     Python 2 version.

‘Python2_VERSION_MAJOR’

     Python 2 major version.

‘Python2_VERSION_MINOR’

     Python 2 minor version.

‘Python2_VERSION_PATCH’

     Python 2 patch version.

‘Python2_PyPy_VERSION’

     Python 2 PyPy version.

‘Python2_NumPy_FOUND’

     System has the NumPy.

‘Python2_NumPy_INCLUDE_DIRS’

     The NumPy include directories.

‘Python2_NumPy_VERSION’

     The NumPy version.

15.2.119.3 Hints
................

‘Python2_ROOT_DIR’

     Define the root directory of a Python 2 installation.

‘Python2_USE_STATIC_LIBS’

        * If not defined, search for shared libraries and static
          libraries in that order.

        * If set to TRUE, search `only' for static libraries.

        * If set to FALSE, search `only' for shared libraries.

‘Python2_FIND_STRATEGY’

     This variable defines how lookup will be done.  The
     ‘Python2_FIND_STRATEGY’ variable can be set to one of the
     following:

        * ‘VERSION’: Try to find the most recent version in all
          specified locations.  This is the default if policy
          CMP0094 is undefined or set to ‘OLD’.

        * ‘LOCATION’: Stops lookup as soon as a version satisfying
          version constraints is founded.  This is the default if policy
          CMP0094 is set to ‘NEW’.

‘Python2_FIND_REGISTRY’

     On Windows the ‘Python2_FIND_REGISTRY’ variable determine the order
     of preference between registry and environment variables.  the
     ‘Python2_FIND_REGISTRY’ variable can be set to one of the
     following:

        * ‘FIRST’: Try to use registry before environment variables.
          This is the default.

        * ‘LAST’: Try to use registry after environment variables.

        * ‘NEVER’: Never try to use registry.

‘Python2_FIND_FRAMEWORK’

     On macOS the ‘Python2_FIND_FRAMEWORK’ variable determine the order
     of preference between Apple-style and unix-style package
     components.  This variable can take same values as
     CMAKE_FIND_FRAMEWORK variable.

          Note: Value ‘ONLY’ is not supported so ‘FIRST’ will be used
          instead.

     If ‘Python2_FIND_FRAMEWORK’ is not defined, see
     CMAKE_FIND_FRAMEWORK variable will be used, if any.

‘Python2_FIND_VIRTUALENV’

     This variable defines the handling of virtual environments managed
     by ‘virtualenv’ or ‘conda’.  It is meaningful only when a virtual
     environment is active (i.e.  the ‘activate’ script has been
     evaluated).  In this case, it takes precedence over
     ‘Python2_FIND_REGISTRY’ and ‘CMAKE_FIND_FRAMEWORK’ variables.  The
     ‘Python2_FIND_VIRTUALENV’ variable can be set to one of the
     following:

        * ‘FIRST’: The virtual environment is used before any other
          standard paths to look-up for the interpreter.  This is the
          default.

        * ‘ONLY’: Only the virtual environment is used to look-up for
          the interpreter.

        * ‘STANDARD’: The virtual environment is not used to look-up for
          the interpreter but environment variable ‘PATH’ is always
          considered.  In this case, variable ‘Python2_FIND_REGISTRY’
          (Windows) or ‘CMAKE_FIND_FRAMEWORK’ (macOS) can be set with
          value ‘LAST’ or ‘NEVER’ to select preferably the interpreter
          from the virtual environment.

          Note: If the component ‘Development’ is requested, it is
          `strongly' recommended to also include the component
          ‘Interpreter’ to get expected result.

‘Python2_FIND_IMPLEMENTATIONS’

     This variable defines, in an ordered list, the different
     implementations which will be searched.  The
     ‘Python2_FIND_IMPLEMENTATIONS’ variable can hold the following
     values:

        * ‘CPython’: this is the standard implementation.  Various
          products, like ‘Anaconda’ or ‘ActivePython’, rely on this
          implementation.

        * ‘IronPython’: This implementation use the ‘CSharp’ language
          for ‘.NET Framework’ on top of the ‘Dynamic Language Runtime’
          (‘DLR’).  See IronPython(1).

        * ‘PyPy’: This implementation use ‘RPython’ language and
          ‘RPython translation toolchain’ to produce the python
          interpreter.  See PyPy(2).

     The default value is:

        * Windows platform: ‘CPython’, ‘IronPython’

        * Other platforms: ‘CPython’

          Note: This hint has the lowest priority of all hints, so even
          if, for example, you specify ‘IronPython’ first and ‘CPython’
          in second, a python product based on ‘CPython’ can be selected
          because, for example with ‘Python2_FIND_STRATEGY=LOCATION’,
          each location will be search first for ‘IronPython’ and second
          for ‘CPython’.

          Note: When ‘IronPython’ is specified, on platforms other than
          ‘Windows’, the ‘.Net’ interpreter (i.e.  ‘mono’ command) is
          expected to be available through the ‘PATH’ variable.

   ---------- Footnotes ----------

   (1) http://ironpython.net

   (2) https://www.pypy.org

15.2.119.4 Artifacts Specification
..................................

To solve special cases, it is possible to specify directly the artifacts
by setting the following variables:

‘Python2_EXECUTABLE’

     The path to the interpreter.

‘Python2_COMPILER’

     The path to the compiler.

‘Python2_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python2_LIBRARY’

     The path to the library.  It will be used to compute the variables
     ‘Python2_LIBRARIES’, ‘Python2_LIBRARY_DIRS’ and
     ‘Python2_RUNTIME_LIBRARY_DIRS’.

‘Python2_INCLUDE_DIR’

     The path to the directory of the ‘Python’ headers.  It will be used
     to compute the variable ‘Python2_INCLUDE_DIRS’.

‘Python2_NumPy_INCLUDE_DIR’

     The path to the directory of the ‘NumPy’ headers.  It will be used
     to compute the variable ‘Python2_NumPy_INCLUDE_DIRS’.

     Note: All paths must be absolute.  Any artifact specified with a
     relative path will be ignored.

     Note: When an artifact is specified, all ‘HINTS’ will be ignored
     and no search will be performed for this artifact.

     If more than one artifact is specified, it is the user’s
     responsibility to ensure the consistency of the various artifacts.

By default, this module supports multiple calls in different directories
of a project with different version/component requirements while
providing correct and consistent results for each call.  To support this
behavior, ‘CMake’ cache is not used in the traditional way which can be
problematic for interactive specification.  So, to enable also
interactive specification, module behavior can be controlled with the
following variable:

‘Python2_ARTIFACTS_INTERACTIVE’

     Selects the behavior of the module.  This is a boolean variable:

        * If set to ‘TRUE’: Create CMake cache entries for the above
          artifact specification variables so that users can edit them
          interactively.  This disables support for multiple
          version/component requirements.

        * If set to ‘FALSE’ or undefined: Enable multiple
          version/component requirements.

15.2.119.5 Commands
...................

This module defines the command ‘Python2_add_library’ (when
CMAKE_ROLE is ‘PROJECT’), which has the same semantics as
add_library() and adds a dependency to target ‘Python2::Python’ or,
when library type is ‘MODULE’, to target ‘Python2::Module’ and takes
care of Python module naming rules:

     Python2_add_library (<name> [STATIC | SHARED | MODULE]
                          <source1> [<source2> ...])

If library type is not specified, ‘MODULE’ is assumed.

15.2.120 FindPython3
--------------------

New in version 3.12.

Find Python 3 interpreter, compiler and development environment (include
directories and libraries).

When a version is requested, it can be specified as a simple value or as
a range.  For a detailed description of version range usage and
capabilities, refer to the find_package() command.

The following components are supported:

   * ‘Interpreter’: search for Python 3 interpreter

   * ‘Compiler’: search for Python 3 compiler.  Only offered by
     IronPython.

   * ‘Development’: search for development artifacts (include
     directories and libraries).  This component includes two
     sub-components which can be specified independently:

        * ‘Development.Module’: search for artifacts for Python 3 module
          developments.

        * ‘Development.Embed’: search for artifacts for Python 3
          embedding developments.

   * ‘NumPy’: search for NumPy include directories.

If no ‘COMPONENTS’ are specified, ‘Interpreter’ is assumed.

If component ‘Development’ is specified, it implies sub-components
‘Development.Module’ and ‘Development.Embed’.

To ensure consistent versions between components ‘Interpreter’,
‘Compiler’, ‘Development’ (or one of its sub-components) and ‘NumPy’,
specify all components at the same time:

     find_package (Python3 COMPONENTS Interpreter Development)

This module looks only for version 3 of Python.  This module can be used
concurrently with FindPython2 module to use both Python
versions.

The FindPython module can be used if Python version does not
matter for you.

     Note: If components ‘Interpreter’ and ‘Development’ (or one of its
     sub-components) are both specified, this module search only for
     interpreter with same platform architecture as the one defined by
     ‘CMake’ configuration.  This constraint does not apply if only
     ‘Interpreter’ component is specified.

15.2.120.1 Imported Targets
...........................

This module defines the following Imported Targets. (when
CMAKE_ROLE is ‘PROJECT’):

‘Python3::Interpreter’

     Python 3 interpreter.  Target defined if component ‘Interpreter’ is
     found.

‘Python3::Compiler’

     Python 3 compiler.  Target defined if component ‘Compiler’ is
     found.

‘Python3::Module’

     Python 3 library for Python module.  Target defined if component
     ‘Development.Module’ is found.

‘Python3::Python’

     Python 3 library for Python embedding.  Target defined if component
     ‘Development.Embed’ is found.

‘Python3::NumPy’

     NumPy library for Python 3.  Target defined if component ‘NumPy’ is
     found.

15.2.120.2 Result Variables
...........................

This module will set the following variables in your project (see
Standard Variable Names):

‘Python3_FOUND’

     System has the Python 3 requested components.

‘Python3_Interpreter_FOUND’

     System has the Python 3 interpreter.

‘Python3_EXECUTABLE’

     Path to the Python 3 interpreter.

‘Python3_INTERPRETER_ID’

     A short string unique to the interpreter. Possible values include:

             * Python

             * ActivePython

             * Anaconda

             * Canopy

             * IronPython

             * PyPy

‘Python3_STDLIB’

     Standard platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)’
     or else ‘sysconfig.get_path('stdlib')’.

‘Python3_STDARCH’

     Standard platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)’
     or else ‘sysconfig.get_path('platstdlib')’.

‘Python3_SITELIB’

     Third-party platform independent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)’
     or else ‘sysconfig.get_path('purelib')’.

‘Python3_SITEARCH’

     Third-party platform dependent installation directory.

     Information returned by
     ‘distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)’
     or else ‘sysconfig.get_path('platlib')’.

‘Python3_SOABI’

     Extension suffix for modules.

     Information returned by
     ‘distutils.sysconfig.get_config_var('SOABI')’ or computed from
     ‘distutils.sysconfig.get_config_var('EXT_SUFFIX')’ or
     ‘python3-config --extension-suffix’.  If package
     ‘distutils.sysconfig’ is not available,
     ‘sysconfig.get_config_var('SOABI')’ or
     ‘sysconfig.get_config_var('EXT_SUFFIX')’ are used.

‘Python3_Compiler_FOUND’

     System has the Python 3 compiler.

‘Python3_COMPILER’

     Path to the Python 3 compiler.  Only offered by IronPython.

‘Python3_COMPILER_ID’

     A short string unique to the compiler. Possible values include:

             * IronPython

‘Python3_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python3_Development_FOUND’

     System has the Python 3 development artifacts.

‘Python3_Development.Module_FOUND’

     System has the Python 3 development artifacts for Python module.

‘Python3_Development.Embed_FOUND’

     System has the Python 3 development artifacts for Python embedding.

‘Python3_INCLUDE_DIRS’

     The Python 3 include directories.

‘Python3_LINK_OPTIONS’

     The Python 3 link options.  Some configurations require specific
     link options for a correct build and execution.

‘Python3_LIBRARIES’

     The Python 3 libraries.

‘Python3_LIBRARY_DIRS’

     The Python 3 library directories.

‘Python3_RUNTIME_LIBRARY_DIRS’

     The Python 3 runtime library directories.

‘Python3_VERSION’

     Python 3 version.

‘Python3_VERSION_MAJOR’

     Python 3 major version.

‘Python3_VERSION_MINOR’

     Python 3 minor version.

‘Python3_VERSION_PATCH’

     Python 3 patch version.

‘Python3_PyPy_VERSION’

     Python 3 PyPy version.

‘Python3_NumPy_FOUND’

     System has the NumPy.

‘Python3_NumPy_INCLUDE_DIRS’

     The NumPy include directories.

‘Python3_NumPy_VERSION’

     The NumPy version.

15.2.120.3 Hints
................

‘Python3_ROOT_DIR’

     Define the root directory of a Python 3 installation.

‘Python3_USE_STATIC_LIBS’

        * If not defined, search for shared libraries and static
          libraries in that order.

        * If set to TRUE, search `only' for static libraries.

        * If set to FALSE, search `only' for shared libraries.

‘Python3_FIND_ABI’

     This variable defines which ABIs, as defined in PEP 3149(1), should
     be searched.

          Note: If ‘Python3_FIND_ABI’ is not defined, any ABI will be
          searched.

     The ‘Python3_FIND_ABI’ variable is a 3-tuple specifying, in that
     order, ‘pydebug’ (‘d’), ‘pymalloc’ (‘m’) and ‘unicode’ (‘u’) flags.
     Each element can be set to one of the following:

        * ‘ON’: Corresponding flag is selected.

        * ‘OFF’: Corresponding flag is not selected.

        * ‘ANY’: The two possibilities (‘ON’ and ‘OFF’) will be
          searched.

     From this 3-tuple, various ABIs will be searched starting from the
     most specialized to the most general.  Moreover, ‘debug’ versions
     will be searched `after' ‘non-debug’ ones.

     For example, if we have:

          set (Python3_FIND_ABI "ON" "ANY" "ANY")

     The following flags combinations will be appended, in that order,
     to the artifact names: ‘dmu’, ‘dm’, ‘du’, and ‘d’.

     And to search any possible ABIs:

          set (Python3_FIND_ABI "ANY" "ANY" "ANY")

     The following combinations, in that order, will be used: ‘mu’, ‘m’,
     ‘u’, ‘<empty>’, ‘dmu’, ‘dm’, ‘du’ and ‘d’.

          Note: This hint is useful only on ‘POSIX’ systems.  So, on
          ‘Windows’ systems, when ‘Python3_FIND_ABI’ is defined,
          ‘Python’ distributions from python.org(2) will be found only
          if value for each flag is ‘OFF’ or ‘ANY’.

‘Python3_FIND_STRATEGY’

     This variable defines how lookup will be done.  The
     ‘Python3_FIND_STRATEGY’ variable can be set to one of the
     following:

        * ‘VERSION’: Try to find the most recent version in all
          specified locations.  This is the default if policy
          CMP0094 is undefined or set to ‘OLD’.

        * ‘LOCATION’: Stops lookup as soon as a version satisfying
          version constraints is founded.  This is the default if policy
          CMP0094 is set to ‘NEW’.

‘Python3_FIND_REGISTRY’

     On Windows the ‘Python3_FIND_REGISTRY’ variable determine the order
     of preference between registry and environment variables.  The
     ‘Python3_FIND_REGISTRY’ variable can be set to one of the
     following:

        * ‘FIRST’: Try to use registry before environment variables.
          This is the default.

        * ‘LAST’: Try to use registry after environment variables.

        * ‘NEVER’: Never try to use registry.

‘Python3_FIND_FRAMEWORK’

     On macOS the ‘Python3_FIND_FRAMEWORK’ variable determine the order
     of preference between Apple-style and unix-style package
     components.  This variable can take same values as
     CMAKE_FIND_FRAMEWORK variable.

          Note: Value ‘ONLY’ is not supported so ‘FIRST’ will be used
          instead.

     If ‘Python3_FIND_FRAMEWORK’ is not defined, see
     CMAKE_FIND_FRAMEWORK variable will be used, if any.

‘Python3_FIND_VIRTUALENV’

     This variable defines the handling of virtual environments managed
     by ‘virtualenv’ or ‘conda’.  It is meaningful only when a virtual
     environment is active (i.e.  the ‘activate’ script has been
     evaluated).  In this case, it takes precedence over
     ‘Python3_FIND_REGISTRY’ and ‘CMAKE_FIND_FRAMEWORK’ variables.  The
     ‘Python3_FIND_VIRTUALENV’ variable can be set to one of the
     following:

        * ‘FIRST’: The virtual environment is used before any other
          standard paths to look-up for the interpreter.  This is the
          default.

        * ‘ONLY’: Only the virtual environment is used to look-up for
          the interpreter.

        * ‘STANDARD’: The virtual environment is not used to look-up for
          the interpreter but environment variable ‘PATH’ is always
          considered.  In this case, variable ‘Python3_FIND_REGISTRY’
          (Windows) or ‘CMAKE_FIND_FRAMEWORK’ (macOS) can be set with
          value ‘LAST’ or ‘NEVER’ to select preferably the interpreter
          from the virtual environment.

          Note: If the component ‘Development’ is requested, it is
          `strongly' recommended to also include the component
          ‘Interpreter’ to get expected result.

‘Python3_FIND_IMPLEMENTATIONS’

     This variable defines, in an ordered list, the different
     implementations which will be searched.  The
     ‘Python3_FIND_IMPLEMENTATIONS’ variable can hold the following
     values:

        * ‘CPython’: this is the standard implementation.  Various
          products, like ‘Anaconda’ or ‘ActivePython’, rely on this
          implementation.

        * ‘IronPython’: This implementation use the ‘CSharp’ language
          for ‘.NET Framework’ on top of the ‘Dynamic Language Runtime’
          (‘DLR’).  See IronPython(3).

        * ‘PyPy’: This implementation use ‘RPython’ language and
          ‘RPython translation toolchain’ to produce the python
          interpreter.  See PyPy(4).

     The default value is:

        * Windows platform: ‘CPython’, ‘IronPython’

        * Other platforms: ‘CPython’

          Note: This hint has the lowest priority of all hints, so even
          if, for example, you specify ‘IronPython’ first and ‘CPython’
          in second, a python product based on ‘CPython’ can be selected
          because, for example with ‘Python3_FIND_STRATEGY=LOCATION’,
          each location will be search first for ‘IronPython’ and second
          for ‘CPython’.

          Note: When ‘IronPython’ is specified, on platforms other than
          ‘Windows’, the ‘.Net’ interpreter (i.e.  ‘mono’ command) is
          expected to be available through the ‘PATH’ variable.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-3149/

   (2) https://www.python.org/

   (3) http://ironpython.net

   (4) https://www.pypy.org

15.2.120.4 Artifacts Specification
..................................

To solve special cases, it is possible to specify directly the artifacts
by setting the following variables:

‘Python3_EXECUTABLE’

     The path to the interpreter.

‘Python3_COMPILER’

     The path to the compiler.

‘Python3_DOTNET_LAUNCHER’

     The ‘.Net’ interpreter.  Only used by ‘IronPython’ implementation.

‘Python3_LIBRARY’

     The path to the library.  It will be used to compute the variables
     ‘Python3_LIBRARIES’, ‘Python3_LIBRARY_DIRS’ and
     ‘Python3_RUNTIME_LIBRARY_DIRS’.

‘Python3_INCLUDE_DIR’

     The path to the directory of the ‘Python’ headers.  It will be used
     to compute the variable ‘Python3_INCLUDE_DIRS’.

‘Python3_NumPy_INCLUDE_DIR’

     The path to the directory of the ‘NumPy’ headers.  It will be used
     to compute the variable ‘Python3_NumPy_INCLUDE_DIRS’.

     Note: All paths must be absolute.  Any artifact specified with a
     relative path will be ignored.

     Note: When an artifact is specified, all ‘HINTS’ will be ignored
     and no search will be performed for this artifact.

     If more than one artifact is specified, it is the user’s
     responsibility to ensure the consistency of the various artifacts.

By default, this module supports multiple calls in different directories
of a project with different version/component requirements while
providing correct and consistent results for each call.  To support this
behavior, ‘CMake’ cache is not used in the traditional way which can be
problematic for interactive specification.  So, to enable also
interactive specification, module behavior can be controlled with the
following variable:

‘Python3_ARTIFACTS_INTERACTIVE’

     Selects the behavior of the module.  This is a boolean variable:

        * If set to ‘TRUE’: Create CMake cache entries for the above
          artifact specification variables so that users can edit them
          interactively.  This disables support for multiple
          version/component requirements.

        * If set to ‘FALSE’ or undefined: Enable multiple
          version/component requirements.

15.2.120.5 Commands
...................

This module defines the command ‘Python3_add_library’ (when
CMAKE_ROLE is ‘PROJECT’), which has the same semantics as
add_library() and adds a dependency to target ‘Python3::Python’ or,
when library type is ‘MODULE’, to target ‘Python3::Module’ and takes
care of Python module naming rules:

     Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
                          <source1> [<source2> ...])

If the library type is not specified, ‘MODULE’ is assumed.

For ‘MODULE’ library type, if option ‘WITH_SOABI’ is specified, the
module suffix will include the ‘Python3_SOABI’ value, if any.

15.2.121 FindQt3
----------------

Locate Qt include paths and libraries

This module defines:

     QT_INCLUDE_DIR    - where to find qt.h, etc.
     QT_LIBRARIES      - the libraries to link against to use Qt.
     QT_DEFINITIONS    - definitions to use when
                         compiling code that uses Qt.
     QT_FOUND          - If false, don't try to use Qt.
     QT_VERSION_STRING - the version of Qt found

If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE

Also defined, but not for general use are:

     QT_MOC_EXECUTABLE, where to find the moc tool.
     QT_UIC_EXECUTABLE, where to find the uic tool.
     QT_QT_LIBRARY, where to find the Qt library.
     QT_QTMAIN_LIBRARY, where to find the qtmain
      library. This is only required by Qt3 on Windows.

15.2.122 FindQt4
----------------

15.2.122.1 Finding and Using Qt4
................................

This module can be used to find Qt4.  The most important issue is that
the Qt4 qmake is available via the system path.  This qmake is then used
to detect basically everything else.  This module defines a number of
IMPORTED targets, macros and variables.

Typical usage could be something like:

     set(CMAKE_AUTOMOC ON)
     set(CMAKE_INCLUDE_CURRENT_DIR ON)
     find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
     add_executable(myexe main.cpp)
     target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)

     Note: When using IMPORTED targets, the qtmain.lib
     static library is automatically linked on Windows for WIN32
     executables.  To disable that globally, set the
     ‘QT4_NO_LINK_QTMAIN’ variable before finding Qt4.  To disable that
     for a particular executable, set the ‘QT4_NO_LINK_QTMAIN’ target
     property to ‘TRUE’ on the executable.

15.2.122.2 Qt Build Tools
.........................

Qt relies on some bundled tools for code generation, such as ‘moc’ for
meta-object code generation,‘‘uic‘‘ for widget layout and population,
and ‘rcc’ for virtual filesystem content generation.  These tools may be
automatically invoked by cmake(1) if the appropriate
conditions are met.  See cmake-qt(7) for more.

15.2.122.3 Qt Macros
....................

In some cases it can be necessary or useful to invoke the Qt build tools
in a more-manual way.  Several macros are available to add targets for
such uses.

     macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
           create moc code from a list of files containing Qt class with
           the Q_OBJECT declaration.  Per-directory preprocessor definitions
           are also added.  If the <tgt> is specified, the
           INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
           the <tgt> are passed to moc.  Options may be given to moc, such as
           those found when executing "moc -help".

     macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
           create code from a list of Qt designer ui files.
           Options may be given to uic, such as those found
           when executing "uic -help"

     macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
           create code from a list of Qt resource files.
           Options may be given to rcc, such as those found
           when executing "rcc -help"

     macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
           creates a rule to run moc on infile and create outfile.
           Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
           because you need a custom filename for the moc file or something
           similar.  If the <tgt> is specified, the
           INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
           the <tgt> are passed to moc.

     macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
           Create the interface header and implementation files with the
           given basename from the given interface xml file and add it to
           the list of sources.

           You can pass additional parameters to the qdbusxml2cpp call by setting
           properties on the input file:

           INCLUDE the given file will be included in the generate interface header

           CLASSNAME the generated class is named accordingly

           NO_NAMESPACE the generated class is not wrapped in a namespace

     macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
           Create the interface header and implementation files
           for all listed interface xml files.
           The basename will be automatically determined from the name
           of the xml file.

           The source file properties described for
           QT4_ADD_DBUS_INTERFACE also apply here.

     macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
                                [basename] [classname])
           create a dbus adaptor (header and implementation file) from the xml file
           describing the interface, and add it to the list of sources. The adaptor
           forwards the calls to a parent class, defined in parentheader and named
           parentclassname. The name of the generated files will be
           <basename>adaptor.{cpp,h} where basename defaults to the basename of the
           xml file.
           If <classname> is provided, then it will be used as the classname of the
           adaptor itself.

     macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
           generate the xml interface file from the given header.
           If the optional argument interfacename is omitted, the name of the
           interface file is constructed from the basename of the header with
           the suffix .xml appended.
           Options may be given to qdbuscpp2xml, such as those found when
           executing "qdbuscpp2xml --help"

     macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
                                   ts_files ... OPTIONS ...)
           out: qm_files
           in:  directories sources ts_files
           options: flags to pass to lupdate, such as -extensions to specify
           extensions for a directory scan.
           generates commands to create .ts (via lupdate) and .qm
           (via lrelease) - files from directories and/or sources. The ts files are
           created and/or updated in the source tree (unless given with full paths).
           The qm files are generated in the build tree.
           Updating the translations can be done by adding the qm_files
           to the source list of your library/executable, so they are
           always updated, or by adding a custom target to control when
           they get updated/generated.

     macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
           out: qm_files
           in:  ts_files
           generates commands to create .qm from .ts - files. The generated
           filenames can be found in qm_files. The ts_files
           must exist and are not updated in any way.

     macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
           The qt4_automoc macro is obsolete.  Use the CMAKE_AUTOMOC feature instead.
           This macro is still experimental.
           It can be used to have moc automatically handled.
           So if you have the files foo.h and foo.cpp, and in foo.h a
           a class uses the Q_OBJECT macro, moc has to run on it. If you don't
           want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
           #include "foo.moc"
           in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
           scan all listed files at cmake-time for such included moc files and if it
           finds them cause a rule to be generated to run moc at build time on the
           accompanying header file foo.h.
           If a source file has the SKIP_AUTOMOC property set it will be ignored by
           this macro.
           If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
           INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.

     function QT4_USE_MODULES( target [link_type] modules...)
            This function is obsolete. Use target_link_libraries with IMPORTED targets
            instead.
            Make <target> use the <modules> from Qt. Using a Qt module means
            to link to the library, add the relevant include directories for the
            module, and add the relevant compiler defines for using the module.
            Modules are roughly equivalent to components of Qt4, so usage would be
            something like:
             qt4_use_modules(myexe Core Gui Declarative)
            to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
            can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
            same argument to the target_link_libraries call.

15.2.122.4 IMPORTED Targets
...........................

A particular Qt library may be used by using the corresponding
IMPORTED target with the target_link_libraries().
command:

     target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)

Using a target in this way causes :cmake(1)‘ to use the appropriate
include directories and compile definitions for the target when
compiling ‘myexe’.

Targets are aware of their dependencies, so for example it is not
necessary to list ‘Qt4::QtCore’ if another Qt library is listed, and it
is not necessary to list ‘Qt4::QtGui’ if ‘Qt4::QtDeclarative’ is listed.
Targets may be tested for existence in the usual way with the
if(TARGET) command.

The Qt toolkit may contain both debug and release libraries.
cmake(1) will choose the appropriate version based on the build
configuration.

‘Qt4::QtCore’

     The QtCore target

‘Qt4::QtGui’

     The QtGui target

‘Qt4::Qt3Support’

     The Qt3Support target

‘Qt4::QtAssistant’

     The QtAssistant target

‘Qt4::QtAssistantClient’

     The QtAssistantClient target

‘Qt4::QAxContainer’

     The QAxContainer target (Windows only)

‘Qt4::QAxServer’

     The QAxServer target (Windows only)

‘Qt4::QtDBus’

     The QtDBus target

‘Qt4::QtDeclarative’

     The QtDeclarative target

‘Qt4::QtDesigner’

     The QtDesigner target

‘Qt4::QtDesignerComponents’

     The QtDesignerComponents target

‘Qt4::QtHelp’

     The QtHelp target

‘Qt4::QtMotif’

     The QtMotif target

‘Qt4::QtMultimedia’

     The QtMultimedia target

‘Qt4::QtNetwork’

     The QtNetwork target

‘Qt4::QtNsPLugin’

     The QtNsPLugin target

‘Qt4::QtOpenGL’

     The QtOpenGL target

‘Qt4::QtScript’

     The QtScript target

‘Qt4::QtScriptTools’

     The QtScriptTools target

‘Qt4::QtSql’

     The QtSql target

‘Qt4::QtSvg’

     The QtSvg target

‘Qt4::QtTest’

     The QtTest target

‘Qt4::QtUiTools’

     The QtUiTools target

‘Qt4::QtWebKit’

     The QtWebKit target

‘Qt4::QtXml’

     The QtXml target

‘Qt4::QtXmlPatterns’

     The QtXmlPatterns target

‘Qt4::phonon’

     The phonon target

15.2.122.5 Result Variables
...........................

     Below is a detailed list of variables that FindQt4.cmake sets.

‘Qt4_FOUND’

     If false, don’t try to use Qt 4.

‘QT_FOUND’

     If false, don’t try to use Qt.  This variable is for compatibility
     only.

‘QT4_FOUND’

     If false, don’t try to use Qt 4.  This variable is for
     compatibility only.

‘QT_VERSION_MAJOR’

     The major version of Qt found.

‘QT_VERSION_MINOR’

     The minor version of Qt found.

‘QT_VERSION_PATCH’

     The patch version of Qt found.

15.2.123 FindQuickTime
----------------------

Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
find the headers

$QUICKTIME_DIR is an environment variable that would correspond to the
./configure –prefix=$QUICKTIME_DIR

Created by Eric Wing.

15.2.124 FindRTI
----------------

Try to find M&S HLA RTI libraries

This module finds if any HLA RTI is installed and locates the standard
RTI include files and libraries.

RTI is a simulation infrastructure standardized by IEEE and SISO. It has
a well defined C++ API that assures that simulation applications are
independent on a particular RTI implementation.

     http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)

This code sets the following variables:

     RTI_INCLUDE_DIR = the directory where RTI includes file are found
     RTI_LIBRARIES = The libraries to link against to use RTI
     RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
     RTI_FOUND = Set to FALSE if any HLA RTI was not found

Report problems to <<certi-devel@nongnu.org>>

15.2.125 FindRuby
-----------------

Find Ruby

This module finds if Ruby is installed and determines where the include
files and libraries are.  Ruby 1.8 through 2.7 are supported.

The minimum required version of Ruby can be specified using the standard
syntax, e.g.

     find_package(Ruby 2.5.1 EXACT REQUIRED)
     # OR
     find_package(Ruby 2.4)

It also determines what the name of the library is.

Virtual environments such as RVM are handled as well, by passing the
argument ‘Ruby_FIND_VIRTUALENV’

15.2.125.1 Result Variables
...........................

This module will set the following variables in your project:

‘Ruby_FOUND’

     set to true if ruby was found successfully

‘Ruby_EXECUTABLE’

     full path to the ruby binary

‘Ruby_INCLUDE_DIRS’

     include dirs to be used when using the ruby library

‘Ruby_LIBRARIES’

     libraries needed to use ruby from C.

‘Ruby_VERSION’

     the version of ruby which was found, e.g.  “1.8.7”

‘Ruby_VERSION_MAJOR’

     Ruby major version.

‘Ruby_VERSION_MINOR’

     Ruby minor version.

‘Ruby_VERSION_PATCH’

     Ruby patch version.

The following variables are also provided for compatibility reasons,
don’t use them in new code:

‘RUBY_EXECUTABLE’

     same as Ruby_EXECUTABLE.

‘RUBY_INCLUDE_DIRS’

     same as Ruby_INCLUDE_DIRS.

‘RUBY_INCLUDE_PATH’

     same as Ruby_INCLUDE_DIRS.

‘RUBY_LIBRARY’

     same as Ruby_LIBRARY.

‘RUBY_VERSION’

     same as Ruby_VERSION.

‘RUBY_FOUND’

     same as Ruby_FOUND.

15.2.125.2 Hints
................

‘Ruby_ROOT_DIR’

     Define the root directory of a Ruby installation.

‘Ruby_FIND_VIRTUALENV’

     This variable defines the handling of virtual environments managed
     by ‘rvm’.  It is meaningful only when a virtual environment is
     active (i.e.  the ‘rvm’ script has been evaluated or at least the
     ‘MY_RUBY_HOME’ environment variable is set).  The
     ‘Ruby_FIND_VIRTUALENV’ variable can be set to empty or one of the
     following:

        * ‘FIRST’: The virtual environment is used before any other
          standard paths to look-up for the interpreter.  This is the
          default.

        * ‘ONLY’: Only the virtual environment is used to look-up for
          the interpreter.

        * ‘STANDARD’: The virtual environment is not used to look-up for
          the interpreter (assuming it isn’t still in the PATH…)

15.2.126 FindSDL
----------------

Locate the SDL library

15.2.126.1 Imported targets
...........................

This module defines the following IMPORTED target:

‘SDL::SDL’

     The SDL library, if found

15.2.126.2 Result variables
...........................

This module will set the following variables in your project:

‘SDL_INCLUDE_DIRS’

     where to find SDL.h

‘SDL_LIBRARIES’

     the name of the library to link against

‘SDL_FOUND’

     if false, do not try to link to SDL

‘SDL_VERSION’

     the human-readable string containing the version of SDL if found

‘SDL_VERSION_MAJOR’

     SDL major version

‘SDL_VERSION_MINOR’

     SDL minor version

‘SDL_VERSION_PATCH’

     SDL patch version

15.2.126.3 Cache variables
..........................

These variables may optionally be set to help this module find the
correct files:

‘SDL_INCLUDE_DIR’

     where to find SDL.h

‘SDL_LIBRARY’

     the name of the library to link against

15.2.126.4 Variables for locating SDL
.....................................

This module responds to the flag:

‘SDL_BUILDING_LIBRARY’

     If this is defined, then no SDL_main will be linked in because only
     applications need main().  Otherwise, it is assumed you are
     building an application and this module will attempt to locate and
     set the proper link flags as part of the returned SDL_LIBRARY
     variable.

15.2.126.5 Obsolete variables
.............................

These variables are obsolete and provided for backwards compatibility:

‘SDL_VERSION_STRING’

     the human-readable string containing the version of SDL if found.
     Identical to SDL_VERSION

Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
X framework based version.  (Other versions link to -lSDLmain which this
module will try to find on your behalf.)  Also for OS X, this module
will automatically add the -framework Cocoa on your behalf.

Additional Note: If you see an empty SDL_LIBRARY_TEMP in your
configuration and no SDL_LIBRARY, it means CMake did not find your SDL
library (SDL.dll, libsdl.so, SDL.framework, etc).  Set SDL_LIBRARY_TEMP
to point to your SDL library, and configure again.  Similarly, if you
see an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
These values are used to generate the final SDL_LIBRARY variable, but
when these values are unset, SDL_LIBRARY does not get created.

$SDLDIR is an environment variable that would correspond to the
./configure –prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02

On OSX, this will prefer the Framework version (if found) over others.
People will have to manually change the cache values of SDL_LIBRARY to
override this selection or set the CMake environment CMAKE_INCLUDE_PATH
to modify the search paths.

Note that the header path has changed from SDL/SDL.h to just SDL.h This
needed to change because “proper” SDL convention is #include “SDL.h”,
not <SDL/SDL.h>.  This is done for portability reasons because not all
systems place things in SDL/ (see FreeBSD).

15.2.127 FindSDL_image
----------------------

Locate SDL_image library

This module defines:

     SDL_IMAGE_LIBRARIES, the name of the library to link against
     SDL_IMAGE_INCLUDE_DIRS, where to find the headers
     SDL_IMAGE_FOUND, if false, do not try to link against
     SDL_IMAGE_VERSION_STRING - human-readable string containing the
                                version of SDL_image

For backward compatibility the following variables are also set:

     SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
     SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
     SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)

$SDLDIR is an environment variable that would correspond to the
./configure –prefix=$SDLDIR used in building SDL.

Created by Eric Wing.  This was influenced by the FindSDL.cmake module,
but with modifications to recognize OS X frameworks and additional Unix
paths (FreeBSD, etc).

15.2.128 FindSDL_mixer
----------------------

Locate SDL_mixer library

This module defines:

     SDL_MIXER_LIBRARIES, the name of the library to link against
     SDL_MIXER_INCLUDE_DIRS, where to find the headers
     SDL_MIXER_FOUND, if false, do not try to link against
     SDL_MIXER_VERSION_STRING - human-readable string containing the
                                version of SDL_mixer

For backward compatibility the following variables are also set:

     SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
     SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
     SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)

$SDLDIR is an environment variable that would correspond to the
./configure –prefix=$SDLDIR used in building SDL.

Created by Eric Wing.  This was influenced by the FindSDL.cmake module,
but with modifications to recognize OS X frameworks and additional Unix
paths (FreeBSD, etc).

15.2.129 FindSDL_net
--------------------

Locate SDL_net library

This module defines:

     SDL_NET_LIBRARIES, the name of the library to link against
     SDL_NET_INCLUDE_DIRS, where to find the headers
     SDL_NET_FOUND, if false, do not try to link against
     SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net

For backward compatibility the following variables are also set:

     SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
     SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
     SDLNET_FOUND (same value as SDL_NET_FOUND)

$SDLDIR is an environment variable that would correspond to the
./configure –prefix=$SDLDIR used in building SDL.

Created by Eric Wing.  This was influenced by the FindSDL.cmake module,
but with modifications to recognize OS X frameworks and additional Unix
paths (FreeBSD, etc).

15.2.130 FindSDL_sound
----------------------

Locates the SDL_sound library

This module depends on SDL being found and must be called AFTER
FindSDL.cmake is called.

This module defines

     SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
     SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
     SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
       to link against.
     SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
       flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
       This is available mostly for cases this module failed to anticipate for
       and you must add additional flags. This is marked as ADVANCED.
     SDL_SOUND_VERSION_STRING, human-readable string containing the
       version of SDL_sound

This module also defines (but you shouldn’t need to use directly)

     SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
     against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.

And might define the following as needed

     MIKMOD_LIBRARY
     MODPLUG_LIBRARY
     OGG_LIBRARY
     VORBIS_LIBRARY
     SMPEG_LIBRARY
     FLAC_LIBRARY
     SPEEX_LIBRARY

Typically, you should not use these variables directly, and you should
use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
audio libraries (if needed) to successfully compile on your system.

Created by Eric Wing.  This module is a bit more complicated than the
other FindSDL* family modules.  The reason is that SDL_sound can be
compiled in a large variety of different ways which are independent of
platform.  SDL_sound may dynamically link against other 3rd party
libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
ModPlug, MikMod, FLAC, Speex, and potentially others.  Under some
circumstances which I don’t fully understand, there seems to be a
requirement that dependent libraries of libraries you use must also be
explicitly linked against in order to successfully compile.  SDL_sound
does not currently have any system in place to know how it was compiled.
So this CMake module does the hard work in trying to discover which 3rd
party libraries are required for building (if any).  This module uses a
brute force approach to create a test program that uses SDL_sound, and
then tries to build it.  If the build fails, it parses the error output
for known symbol names to figure out which libraries are needed.

Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
would correspond to the ./configure –prefix=$SDLDIR used in building
SDL.

On OSX, this will prefer the Framework version (if found) over others.
People will have to manually change the cache values of SDL_LIBRARY to
override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
to modify the search paths.

15.2.131 FindSDL_ttf
--------------------

Locate SDL_ttf library

This module defines:

     SDL_TTF_LIBRARIES, the name of the library to link against
     SDL_TTF_INCLUDE_DIRS, where to find the headers
     SDL_TTF_FOUND, if false, do not try to link against
     SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf

For backward compatibility the following variables are also set:

     SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
     SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
     SDLTTF_FOUND (same value as SDL_TTF_FOUND)

$SDLDIR is an environment variable that would correspond to the
./configure –prefix=$SDLDIR used in building SDL.

Created by Eric Wing.  This was influenced by the FindSDL.cmake module,
but with modifications to recognize OS X frameworks and additional Unix
paths (FreeBSD, etc).

15.2.132 FindSelfPackers
------------------------

Find upx

This module looks for some executable packers (i.e.  software that
compress executables or shared libs into on-the-fly self-extracting
executables or shared libs.  Examples:

     UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html

15.2.133 FindSquish
-------------------

– Typical Use

This module can be used to find Squish.

     SQUISH_FOUND                    If false, don't try to use Squish
     SQUISH_VERSION                  The full version of Squish found
     SQUISH_VERSION_MAJOR            The major version of Squish found
     SQUISH_VERSION_MINOR            The minor version of Squish found
     SQUISH_VERSION_PATCH            The patch version of Squish found

     SQUISH_INSTALL_DIR              The Squish installation directory
                                     (containing bin, lib, etc)
     SQUISH_SERVER_EXECUTABLE        The squishserver executable
     SQUISH_CLIENT_EXECUTABLE        The squishrunner executable

     SQUISH_INSTALL_DIR_FOUND        Was the install directory found?
     SQUISH_SERVER_EXECUTABLE_FOUND  Was the server executable found?
     SQUISH_CLIENT_EXECUTABLE_FOUND  Was the client executable found?

It provides the function squish_add_test() for adding a squish test to
cmake using Squish >= 4.x:

     squish_add_test(cmakeTestName
       AUT targetName SUITE suiteName TEST squishTestName
       [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )

The arguments have the following meaning:

‘cmakeTestName’

     this will be used as the first argument for add_test()

‘AUT targetName’

     the name of the cmake target which will be used as AUT, i.e.  the
     executable which will be tested.

‘SUITE suiteName’

     this is either the full path to the squish suite, or just the last
     directory of the suite, i.e.  the suite name.  In this case the
     CMakeLists.txt which calls squish_add_test() must be located in the
     parent directory of the suite directory.

‘TEST squishTestName’

     the name of the squish test, i.e.  the name of the subdirectory of
     the test inside the suite directory.

‘SETTINGSGROUP group’

     deprecated, this argument will be ignored.

‘PRE_COMMAND command’

     if specified, the given command will be executed before starting
     the squish test.

‘POST_COMMAND command’

     same as PRE_COMMAND, but after the squish test has been executed.

     enable_testing()
     find_package(Squish 6.5)
     if (SQUISH_FOUND)
        squish_add_test(myTestName
          AUT myApp
          SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
          TEST someSquishTest
          )
     endif ()

For users of Squish version 3.x the macro squish_v3_add_test() is
provided:

     squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
     Use this macro to add a test using Squish 3.x.

     enable_testing()
     find_package(Squish 3.0)
     if (SQUISH_FOUND)
       squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
     endif ()

15.2.134 FindSQLite3
--------------------

New in version 3.14.

Find the SQLite libraries, v3

15.2.134.1 IMPORTED targets
...........................

This module defines the following IMPORTED target:

‘SQLite::SQLite3’

15.2.134.2 Result variables
...........................

This module will set the following variables if found:

‘SQLite3_INCLUDE_DIRS’

     where to find sqlite3.h, etc.

‘SQLite3_LIBRARIES’

     the libraries to link against to use SQLite3.

‘SQLite3_VERSION’

     version of the SQLite3 library found

‘SQLite3_FOUND’

     TRUE if found

15.2.135 FindSubversion
-----------------------

Extract information from a subversion working copy

The module defines the following variables:

     Subversion_SVN_EXECUTABLE - path to svn command line client
     Subversion_VERSION_SVN - version of svn command line client
     Subversion_FOUND - true if the command line client was found
     SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons

The minimum required version of Subversion can be specified using the
standard syntax, e.g.  ‘find_package(Subversion 1.4)’.

If the command line client executable is found two macros are defined:

     Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
     Subversion_WC_LOG(<dir> <var-prefix>)

‘Subversion_WC_INFO’ extracts information of a subversion working copy
at a given location.  This macro defines the following variables if
running Subversion’s ‘info’ command on ‘<dir>’ succeeds; otherwise a
‘SEND_ERROR’ message is generated.  The error can be ignored by
providing the ‘IGNORE_SVN_FAILURE’ option, which causes these variables
to remain undefined.

     <var-prefix>_WC_URL - url of the repository (at <dir>)
     <var-prefix>_WC_ROOT - root url of the repository
     <var-prefix>_WC_REVISION - current revision
     <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
     <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
     <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
     <var-prefix>_WC_INFO - output of command `svn info <dir>'

‘Subversion_WC_LOG’ retrieves the log message of the base revision of a
subversion working copy at a given location.  This macro defines the
variable:

     <var-prefix>_LAST_CHANGED_LOG - last log of base revision

Example usage:

     find_package(Subversion)
     if(SUBVERSION_FOUND)
       Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
       message("Current revision is ${Project_WC_REVISION}")
       Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
       message("Last changed log is ${Project_LAST_CHANGED_LOG}")
     endif()

15.2.136 FindSWIG
-----------------

Find the Simplified Wrapper and Interface Generator (SWIG(1))
executable.

This module finds an installed SWIG and determines its version.  If a
‘COMPONENTS’ or ‘OPTIONAL_COMPONENTS’ argument is given to the
find_package() command, it will also determine supported target
languages.

When a version is requested, it can be specified as a simple value or as
a range.  For a detailed description of version range usage and
capabilities, refer to the find_package() command.

The module defines the following variables:

‘SWIG_FOUND’

     Whether SWIG and any required components were found on the system.

‘SWIG_EXECUTABLE’

     Path to the SWIG executable.

‘SWIG_DIR’

     Path to the installed SWIG ‘Lib’ directory (result of ‘swig
     -swiglib’).

‘SWIG_VERSION’

     SWIG executable version (result of ‘swig -version’).

‘SWIG_<lang>_FOUND’

     If ‘COMPONENTS’ or ‘OPTIONAL_COMPONENTS’ are requested, each
     available target language ‘<lang>’ (lowercase) will be set to TRUE.

Any ‘COMPONENTS’ given to ‘find_package’ should be the names of
supported target languages as provided to the LANGUAGE argument of
‘swig_add_library’, such as ‘python’ or ‘perl5’.  Language names `must'
be lowercase.

All information is collected from the ‘SWIG_EXECUTABLE’, so the version
to be found can be changed from the command line by means of setting
‘SWIG_EXECUTABLE’.

Example usage requiring SWIG 4.0 or higher and Python language support,
with optional Fortran support:

     find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
     if(SWIG_FOUND)
       message("SWIG found: ${SWIG_EXECUTABLE}")
       if(NOT SWIG_fortran_FOUND)
         message(WARNING "SWIG Fortran bindings cannot be generated")
       endif()
     endif()

   ---------- Footnotes ----------

   (1) http://swig.org

15.2.137 FindTCL
----------------

TK_INTERNAL_PATH was removed.

This module finds if Tcl is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     TCL_FOUND              = Tcl was found
     TK_FOUND               = Tk was found
     TCLTK_FOUND            = Tcl and Tk were found
     TCL_LIBRARY            = path to Tcl library (tcl tcl80)
     TCL_INCLUDE_PATH       = path to where tcl.h can be found
     TCL_TCLSH              = path to tclsh binary (tcl tcl80)
     TK_LIBRARY             = path to Tk library (tk tk80 etc)
     TK_INCLUDE_PATH        = path to where tk.h can be found
     TK_WISH                = full path to the wish executable

In an effort to remove some clutter and clear up some issues for people
who are not necessarily Tcl/Tk gurus/developers, some variables were
moved or removed.  Changes compared to CMake 2.4 are:

     => they were only useful for people writing Tcl/Tk extensions.
     => these libs are not packaged by default with Tcl/Tk distributions.
        Even when Tcl/Tk is built from source, several flavors of debug libs
        are created and there is no real reason to pick a single one
        specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
        Let's leave that choice to the user by allowing him to assign
        TCL_LIBRARY to any Tcl library, debug or not.
     => this ended up being only a Win32 variable, and there is a lot of
        confusion regarding the location of this file in an installed Tcl/Tk
        tree anyway (see 8.5 for example). If you need the internal path at
        this point it is safer you ask directly where the *source* tree is
        and dig from there.

15.2.138 FindTclsh
------------------

Find tclsh

This module finds if TCL is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     TCLSH_FOUND = TRUE if tclsh has been found
     TCL_TCLSH = the path to the tclsh executable

15.2.139 FindTclStub
--------------------

TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.

This module finds Tcl stub libraries.  It first finds Tcl include files
and libraries by calling FindTCL.cmake.  How to Use the Tcl Stubs
Library:

     http://tcl.activestate.com/doc/howto/stubs.html

Using Stub Libraries:

     http://safari.oreilly.com/0130385603/ch48lev1sec3

This code sets the following variables:

     TCL_STUB_LIBRARY       = path to Tcl stub library
     TK_STUB_LIBRARY        = path to Tk stub library
     TTK_STUB_LIBRARY       = path to ttk stub library

In an effort to remove some clutter and clear up some issues for people
who are not necessarily Tcl/Tk gurus/developers, some variables were
moved or removed.  Changes compared to CMake 2.4 are:

     => these libs are not packaged by default with Tcl/Tk distributions.
        Even when Tcl/Tk is built from source, several flavors of debug libs
        are created and there is no real reason to pick a single one
        specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
        Let's leave that choice to the user by allowing him to assign
        TCL_STUB_LIBRARY to any Tcl library, debug or not.

15.2.140 FindThreads
--------------------

This module determines the thread library of the system.

15.2.140.1 Imported Targets
...........................

This module defines the following IMPORTED target:

‘Threads::Threads’

     The thread library, if found.

15.2.140.2 Result Variables
...........................

The following variables are set:

‘Threads_FOUND’

     If a supported thread library was found.

‘CMAKE_THREAD_LIBS_INIT’

     The thread library to use.  This may be empty if the thread
     functions are provided by the system libraries and no special flags
     are needed to use them.

‘CMAKE_USE_WIN32_THREADS_INIT’

     If the found thread library is the win32 one.

‘CMAKE_USE_PTHREADS_INIT’

     If the found thread library is pthread compatible.

‘CMAKE_HP_PTHREADS_INIT’

     If the found thread library is the HP thread library.

15.2.140.3 Variables Affecting Behavior
.......................................

 -- Variable: THREADS_PREFER_PTHREAD_FLAG

     If the use of the -pthread compiler and linker flag is preferred
     then the caller can set this variable to TRUE. The compiler flag
     can only be used with the imported target.  Use of both the
     imported target as well as this switch is highly recommended for
     new code.

     This variable has no effect if the system libraries provide the
     thread functions, i.e.  when ‘CMAKE_THREAD_LIBS_INIT’ will be
     empty.

15.2.141 FindTIFF
-----------------

Find the TIFF library (‘libtiff’, ‘https://libtiff.gitlab.io/libtiff/’).

15.2.141.1 Optional COMPONENTS
..............................

This module supports the optional component ‘CXX’, for use with the
COMPONENTS argument of the find_package() command.  This
component has an associated imported target, as described below.

15.2.141.2 Imported targets
...........................

This module defines the following IMPORTED targets:

‘TIFF::TIFF’

     The TIFF library, if found.

‘TIFF::CXX’

     The C++ wrapper libtiffxx, if requested by the ‘COMPONENTS CXX’
     option, if the compiler is not MSVC (which includes the C++ wrapper
     in libtiff), and if found.

15.2.141.3 Result variables
...........................

This module will set the following variables in your project:

‘TIFF_FOUND’

     true if the TIFF headers and libraries were found

‘TIFF_INCLUDE_DIR’

     the directory containing the TIFF headers

‘TIFF_INCLUDE_DIRS’

     the directory containing the TIFF headers

‘TIFF_LIBRARIES’

     TIFF libraries to be linked

15.2.141.4 Cache variables
..........................

The following cache variables may also be set:

‘TIFF_INCLUDE_DIR’

     the directory containing the TIFF headers

‘TIFF_LIBRARY_RELEASE’

     the path to the TIFF library for release configurations

‘TIFF_LIBRARY_DEBUG’

     the path to the TIFF library for debug configurations

‘TIFFXX_LIBRARY_RELEASE’

     the path to the TIFFXX library for release configurations

‘TIFFXX_LIBRARY_DEBUG’

     the path to the TIFFXX library for debug configurations

15.2.142 FindUnixCommands
-------------------------

Find Unix commands, including the ones from Cygwin

This module looks for the Unix commands ‘bash’, ‘cp’, ‘gzip’, ‘mv’,
‘rm’, and ‘tar’ and stores the result in the variables ‘BASH’, ‘CP’,
‘GZIP’, ‘MV’, ‘RM’, and ‘TAR’.

15.2.143 FindVTK
----------------

This module no longer exists.

This module existed in versions of CMake prior to 3.1, but became only a
thin wrapper around ‘find_package(VTK NO_MODULE)’ to provide
compatibility for projects using long-outdated conventions.  Now
‘find_package(VTK)’ will search for ‘VTKConfig.cmake’ directly.

15.2.144 FindVulkan
-------------------

New in version 3.7.

Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
computing API.

15.2.144.1 IMPORTED Targets
...........................

This module defines IMPORTED target ‘Vulkan::Vulkan’, if
Vulkan has been found.

This module defines IMPORTED target ‘Vulkan::glslc’, if
Vulkan and the GLSLC SPIR-V compiler has been found.

15.2.144.2 Result Variables
...........................

This module defines the following variables:

     Vulkan_FOUND          - "True" if Vulkan was found
     Vulkan_INCLUDE_DIRS   - include directories for Vulkan
     Vulkan_LIBRARIES      - link against this library to use Vulkan

The module will also define three cache variables:

     Vulkan_INCLUDE_DIR        - the Vulkan include directory
     Vulkan_LIBRARY            - the path to the Vulkan library
     Vulkan_GLSLC_EXECUTABLE   - the path to the GLSL SPIR-V compiler

15.2.144.3 Hints
................

The ‘VULKAN_SDK’ environment variable optionally specifies the location
of the Vulkan SDK root directory for the given architecture.  It is
typically set by sourcing the toplevel ‘setup-env.sh’ script of the
Vulkan SDK directory into the shell environment.

15.2.145 FindWget
-----------------

Find wget

This module looks for wget.  This module defines the following values:

     WGET_EXECUTABLE: the full path to the wget tool.
     WGET_FOUND: True if wget has been found.

15.2.146 FindWish
-----------------

Find wish installation

This module finds if TCL is installed and determines where the include
files and libraries are.  It also determines what the name of the
library is.  This code sets the following variables:

     TK_WISH = the path to the wish executable

if UNIX is defined, then it will look for the cygwin version first

15.2.147 FindwxWidgets
----------------------

Find a wxWidgets (a.k.a., wxWindows) installation.

This module finds if wxWidgets is installed and selects a default
configuration to use.  wxWidgets is a modular library.  To specify the
modules that you will use, you need to name them as components to the
package:

find_package(wxWidgets COMPONENTS core base … OPTIONAL_COMPONENTS net …)

There are two search branches: a windows style and a unix style.  For
windows, the following variables are searched for and set to defaults in
case of multiple choices.  Change them if the defaults are not desired
(i.e., these are the only variables you should change to select a
configuration):

     wxWidgets_ROOT_DIR      - Base wxWidgets directory
                               (e.g., C:/wxWidgets-2.6.3).
     wxWidgets_LIB_DIR       - Path to wxWidgets libraries
                               (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
     wxWidgets_CONFIGURATION - Configuration to use
                               (e.g., msw, mswd, mswu, mswunivud, etc.)
     wxWidgets_EXCLUDE_COMMON_LIBRARIES
                             - Set to TRUE to exclude linking of
                               commonly required libs (e.g., png tiff
                               jpeg zlib regex expat).

For unix style it uses the wx-config utility.  You can select between
debug/release, unicode/ansi, universal/non-universal, and static/shared
in the QtDialog or ccmake interfaces by turning ON/OFF the following
variables:

     wxWidgets_USE_DEBUG
     wxWidgets_USE_UNICODE
     wxWidgets_USE_UNIVERSAL
     wxWidgets_USE_STATIC

There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
that need to be passed to the wx-config utility.  For example, to use
the base toolkit found in the /usr/local path, set the variable (before
calling the FIND_PACKAGE command) as such:

     set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)

The following are set after the configuration is done for both windows
and unix style:

     wxWidgets_FOUND            - Set to TRUE if wxWidgets was found.
     wxWidgets_INCLUDE_DIRS     - Include directories for WIN32
                                  i.e., where to find "wx/wx.h" and
                                  "wx/setup.h"; possibly empty for unices.
     wxWidgets_LIBRARIES        - Path to the wxWidgets libraries.
     wxWidgets_LIBRARY_DIRS     - compile time link dirs, useful for
                                  rpath on UNIX. Typically an empty string
                                  in WIN32 environment.
     wxWidgets_DEFINITIONS      - Contains defines required to compile/link
                                  against WX, e.g. WXUSINGDLL
     wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
                                  against WX debug builds, e.g. __WXDEBUG__
     wxWidgets_CXX_FLAGS        - Include dirs and compiler flags for
                                  unices, empty on WIN32. Essentially
                                  "`wx-config --cxxflags`".
     wxWidgets_USE_FILE         - Convenience include file.

Sample usage:

     # Note that for MinGW users the order of libs is important!
     find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
     if(wxWidgets_FOUND)
       include(${wxWidgets_USE_FILE})
       # and for each of your dependent executable/library targets:
       target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
     endif()

If wxWidgets is required (i.e., not an optional part):

     find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
     include(${wxWidgets_USE_FILE})
     # and for each of your dependent executable/library targets:
     target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})

15.2.148 FindX11
----------------

Find X11 installation

Try to find X11 on UNIX systems.  The following values are defined

     X11_FOUND        - True if X11 is available
     X11_INCLUDE_DIR  - include directories to use X11
     X11_LIBRARIES    - link against these to use X11

and also the following more fine grained variables and targets:

     X11_ICE_INCLUDE_PATH,          X11_ICE_LIB,        X11_ICE_FOUND,        X11::ICE
     X11_SM_INCLUDE_PATH,           X11_SM_LIB,         X11_SM_FOUND,         X11::SM
     X11_X11_INCLUDE_PATH,          X11_X11_LIB,                              X11::X11
     X11_Xaccessrules_INCLUDE_PATH,
     X11_Xaccessstr_INCLUDE_PATH,                       X11_Xaccess_FOUND
     X11_Xau_INCLUDE_PATH,          X11_Xau_LIB,        X11_Xau_FOUND,        X11::Xau
     X11_xcb_INCLUDE_PATH,          X11_xcb_LIB,        X11_xcb_FOUND,        X11::xcb
     X11_X11_xcb_INCLUDE_PATH,      X11_X11_xcb_LIB,    X11_X11_xcb_FOUND,    X11::X11_xcb
     X11_xcb_icccm_INCLUDE_PATH,    X11_xcb_icccm_LIB,  X11_xcb_icccm_FOUND,  X11::xcb_icccm
     X11_xcb_util_INCLUDE_PATH,     X11_xcb_util_LIB,   X11_xcb_util_FOUND,   X11::xcb_util
     X11_xcb_xfixes_INCLUDE_PATH,   X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
     X11_xcb_xkb_INCLUDE_PATH,      X11_xcb_xkb_LIB,    X11_xcb_xkb_FOUND,    X11::xcb_xkb
     X11_Xcomposite_INCLUDE_PATH,   X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
     X11_Xcursor_INCLUDE_PATH,      X11_Xcursor_LIB,    X11_Xcursor_FOUND,    X11::Xcursor
     X11_Xdamage_INCLUDE_PATH,      X11_Xdamage_LIB,    X11_Xdamage_FOUND,    X11::Xdamage
     X11_Xdmcp_INCLUDE_PATH,        X11_Xdmcp_LIB,      X11_Xdmcp_FOUND,      X11::Xdmcp
     X11_Xext_INCLUDE_PATH,         X11_Xext_LIB,       X11_Xext_FOUND,       X11::Xext
     X11_Xxf86misc_INCLUDE_PATH,    X11_Xxf86misc_LIB,  X11_Xxf86misc_FOUND,  X11::Xxf86misc
     X11_Xxf86vm_INCLUDE_PATH,      X11_Xxf86vm_LIB     X11_Xxf86vm_FOUND,    X11::Xxf86vm
     X11_Xfixes_INCLUDE_PATH,       X11_Xfixes_LIB,     X11_Xfixes_FOUND,     X11::Xfixes
     X11_Xft_INCLUDE_PATH,          X11_Xft_LIB,        X11_Xft_FOUND,        X11::Xft
     X11_Xi_INCLUDE_PATH,           X11_Xi_LIB,         X11_Xi_FOUND,         X11::Xi
     X11_Xinerama_INCLUDE_PATH,     X11_Xinerama_LIB,   X11_Xinerama_FOUND,   X11::Xinerama
     X11_Xkb_INCLUDE_PATH,
     X11_Xkblib_INCLUDE_PATH,                           X11_Xkb_FOUND,        X11::Xkb
     X11_xkbcommon_INCLUDE_PATH,    X11_xkbcommon_LIB,  X11_xkbcommon_FOUND,  X11::xkbcommon
     X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
     X11_xkbfile_INCLUDE_PATH,      X11_xkbfile_LIB,    X11_xkbfile_FOUND,    X11::xkbfile
     X11_Xmu_INCLUDE_PATH,          X11_Xmu_LIB,        X11_Xmu_FOUND,        X11::Xmu
     X11_Xpm_INCLUDE_PATH,          X11_Xpm_LIB,        X11_Xpm_FOUND,        X11::Xpm
     X11_Xtst_INCLUDE_PATH,         X11_Xtst_LIB,       X11_Xtst_FOUND,       X11::Xtst
     X11_Xrandr_INCLUDE_PATH,       X11_Xrandr_LIB,     X11_Xrandr_FOUND,     X11::Xrandr
     X11_Xrender_INCLUDE_PATH,      X11_Xrender_LIB,    X11_Xrender_FOUND,    X11::Xrender
     X11_XRes_INCLUDE_PATH,         X11_XRes_LIB,       X11_XRes_FOUND,       X11::XRes
     X11_Xss_INCLUDE_PATH,          X11_Xss_LIB,        X11_Xss_FOUND,        X11::Xss
     X11_Xt_INCLUDE_PATH,           X11_Xt_LIB,         X11_Xt_FOUND,         X11::Xt
     X11_Xutil_INCLUDE_PATH,                            X11_Xutil_FOUND,      X11::Xutil
     X11_Xv_INCLUDE_PATH,           X11_Xv_LIB,         X11_Xv_FOUND,         X11::Xv
     X11_dpms_INCLUDE_PATH,         (in X11_Xext_LIB),  X11_dpms_FOUND
     X11_XShm_INCLUDE_PATH,         (in X11_Xext_LIB),  X11_XShm_FOUND
     X11_Xshape_INCLUDE_PATH,       (in X11_Xext_LIB),  X11_Xshape_FOUND
     X11_XSync_INCLUDE_PATH,        (in X11_Xext_LIB),  X11_XSync_FOUND
     X11_Xaw_INCLUDE_PATH,          X11_Xaw_LIB         X11_Xaw_FOUND         X11::Xaw

15.2.149 FindXalanC
-------------------

New in version 3.5.

Find the Apache Xalan-C++ XSL transform processor headers and libraries.

15.2.149.1 Imported targets
...........................

This module defines the following IMPORTED targets:

‘XalanC::XalanC’

     The Xalan-C++ ‘xalan-c’ library, if found.

15.2.149.2 Result variables
...........................

This module will set the following variables in your project:

‘XalanC_FOUND’

     true if the Xalan headers and libraries were found

‘XalanC_VERSION’

     Xalan release version

‘XalanC_INCLUDE_DIRS’

     the directory containing the Xalan headers; note
     ‘XercesC_INCLUDE_DIRS’ is also required

‘XalanC_LIBRARIES’

     Xalan libraries to be linked; note ‘XercesC_LIBRARIES’ is also
     required

15.2.149.3 Cache variables
..........................

The following cache variables may also be set:

‘XalanC_INCLUDE_DIR’

     the directory containing the Xalan headers

‘XalanC_LIBRARY’

     the Xalan library

15.2.150 FindXCTest
-------------------

New in version 3.3.

Functions to help creating and executing XCTest bundles.

An XCTest bundle is a CFBundle with a special product-type and bundle
extension.  The Mac Developer Library provides more information in the
Testing with Xcode(1) document.

   ---------- Footnotes ----------

   (1)
http://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/testing_with_xcode/

15.2.150.1 Module Functions
...........................

 -- Command: xctest_add_bundle

     The ‘xctest_add_bundle’ function creates a XCTest bundle named
     <target> which will test the target <testee>.  Supported target
     types for testee are Frameworks and App Bundles:

          xctest_add_bundle(
            <target>  # Name of the XCTest bundle
            <testee>  # Target name of the testee
            )

 -- Command: xctest_add_test

     The ‘xctest_add_test’ function adds an XCTest bundle to the project
     to be run by ctest(1).  The test will be named <name> and
     tests <bundle>:

          xctest_add_test(
            <name>    # Test name
            <bundle>  # Target name of XCTest bundle
            )

15.2.150.2 Module Variables
...........................

The following variables are set by including this module:

 -- Variable: XCTest_FOUND

     True if the XCTest Framework and executable were found.

 -- Variable: XCTest_EXECUTABLE

     The path to the xctest command line tool used to execute XCTest
     bundles.

 -- Variable: XCTest_INCLUDE_DIRS

     The directory containing the XCTest Framework headers.

 -- Variable: XCTest_LIBRARIES

     The location of the XCTest Framework.

15.2.151 FindXercesC
--------------------

New in version 3.1.

Find the Apache Xerces-C++ validating XML parser headers and libraries.

15.2.151.1 Imported targets
...........................

This module defines the following IMPORTED targets:

‘XercesC::XercesC’

     The Xerces-C++ ‘xerces-c’ library, if found.

15.2.151.2 Result variables
...........................

This module will set the following variables in your project:

‘XercesC_FOUND’

     true if the Xerces headers and libraries were found

‘XercesC_VERSION’

     Xerces release version

‘XercesC_INCLUDE_DIRS’

     the directory containing the Xerces headers

‘XercesC_LIBRARIES’

     Xerces libraries to be linked

15.2.151.3 Cache variables
..........................

The following cache variables may also be set:

‘XercesC_INCLUDE_DIR’

     the directory containing the Xerces headers

‘XercesC_LIBRARY’

     the Xerces library

15.2.152 FindXMLRPC
-------------------

Find xmlrpc

Find the native XMLRPC headers and libraries.

     XMLRPC_INCLUDE_DIRS      - where to find xmlrpc.h, etc.
     XMLRPC_LIBRARIES         - List of libraries when using xmlrpc.
     XMLRPC_FOUND             - True if xmlrpc found.

XMLRPC modules may be specified as components for this find module.
Modules may be listed by running “xmlrpc-c-config”.  Modules include:

     c++            C++ wrapper code
     libwww-client  libwww-based client
     cgi-server     CGI-based server
     abyss-server   ABYSS-based server

Typical usage:

     find_package(XMLRPC REQUIRED libwww-client)

15.2.153 FindZLIB
-----------------

Find the native ZLIB includes and library.

15.2.153.1 IMPORTED Targets
...........................

This module defines IMPORTED target ‘ZLIB::ZLIB’, if ZLIB
has been found.

15.2.153.2 Result Variables
...........................

This module defines the following variables:

     ZLIB_INCLUDE_DIRS   - where to find zlib.h, etc.
     ZLIB_LIBRARIES      - List of libraries when using zlib.
     ZLIB_FOUND          - True if zlib found.

     ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
     ZLIB_VERSION_MAJOR  - The major version of zlib
     ZLIB_VERSION_MINOR  - The minor version of zlib
     ZLIB_VERSION_PATCH  - The patch version of zlib
     ZLIB_VERSION_TWEAK  - The tweak version of zlib

15.2.153.3 Backward Compatibility
.................................

The following variable are provided for backward compatibility

     ZLIB_MAJOR_VERSION  - The major version of zlib
     ZLIB_MINOR_VERSION  - The minor version of zlib
     ZLIB_PATCH_VERSION  - The patch version of zlib

15.2.153.4 Hints
................

A user may set ‘ZLIB_ROOT’ to a zlib installation root to tell this
module where to look.

15.3 Deprecated Modules
=======================

15.3.1 Deprecated Utility Modules
---------------------------------

15.3.1.1 CMakeDetermineVSServicePack
....................................

Deprecated since version 3.0: Do not use.

The functionality of this module has been superseded by the
CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler
version number.

Determine the Visual Studio service pack of the ‘cl’ in use.

Usage:

     if(MSVC)
       include(CMakeDetermineVSServicePack)
       DetermineVSServicePack( my_service_pack )
       if( my_service_pack )
         message(STATUS "Detected: ${my_service_pack}")
       endif()
     endif()

Function DetermineVSServicePack sets the given variable to one of the
following values or an empty string if unknown:

     vc80, vc80sp1
     vc90, vc90sp1
     vc100, vc100sp1
     vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4

15.3.1.2 CMakeExpandImportedTargets
...................................

Deprecated since version 3.4: Do not use.

This module was once needed to expand imported targets to the underlying
libraries they reference on disk for use with the try_compile()
and try_run() commands.  These commands now support
imported libraries in their ‘LINK_LIBRARIES’ options (since CMake 2.8.11
for try_compile() and since CMake 3.2 for try_run()).

This module does not support the policy CMP0022. ‘NEW’
behavior or use of the INTERFACE_LINK_LIBRARIES property
because generator expressions cannot be evaluated during
configuration.

     CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
                                   [CONFIGURATION <config>])

CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
all imported targets contained in this list with their actual file paths
of the referenced libraries on disk, including the libraries from their
link interfaces.  If a CONFIGURATION is given, it uses the respective
configuration of the imported targets if it exists.  If no CONFIGURATION
is given, it uses the first configuration from
${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.

     cmake_expand_imported_targets(expandedLibs
       LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
       CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )

15.3.1.3 CMakeForceCompiler
...........................

Deprecated since version 3.6: Do not use.

The macros provided by this module were once intended for use by
cross-compiling toolchain files when CMake was not able to automatically
detect the compiler identification.  Since the introduction of this
module, CMake’s compiler identification capabilities have improved and
can now be taught to recognize any compiler.  Furthermore, the suite of
information CMake detects from a compiler is now too extensive to be
provided by toolchain files using these macros.

One common use case for this module was to skip CMake’s checks for a
working compiler when using a cross-compiler that cannot link binaries
without special flags or custom linker scripts.  This case is now
supported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE.
variable in the toolchain file instead.

__________________________________________________________________

Macro ‘CMAKE_FORCE_C_COMPILER’ has the following signature:

     CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_C_COMPILER to the given compiler and the cmake
internal variable CMAKE_C_COMPILER_ID to the given
compiler-id.  It also bypasses the check for working compiler and basic
compiler information tests.

Macro ‘CMAKE_FORCE_CXX_COMPILER’ has the following signature:

     CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_CXX_COMPILER to the given compiler and the
cmake internal variable CMAKE_CXX_COMPILER_ID to the given
compiler-id.  It also bypasses the check for working compiler and basic
compiler information tests.

Macro ‘CMAKE_FORCE_Fortran_COMPILER’ has the following signature:

     CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_Fortran_COMPILER to the given compiler and the
cmake internal variable CMAKE_Fortran_COMPILER_ID to the
given compiler-id.  It also bypasses the check for working compiler and
basic compiler information tests.

So a simple toolchain file could look like this:

     include (CMakeForceCompiler)
     set(CMAKE_SYSTEM_NAME Generic)
     CMAKE_FORCE_C_COMPILER   (chc12 MetrowerksHicross)
     CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)

15.3.1.4 CMakeParseArguments
............................

This module once implemented the cmake_parse_arguments().
command that is now implemented natively by CMake.  It is now an empty
placeholder for compatibility with projects that include it to get the
command from CMake 3.4 and lower.

15.3.1.5 MacroAddFileDependencies
.................................

MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)

Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged.  There are
usually better ways to specify the correct dependencies.

MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a convenience
wrapper around the OBJECT_DEPENDS source file property.  You can just
use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
depend_files) instead.

15.3.1.6 TestCXXAcceptsFlag
...........................

Deprecated since version 3.0: See CheckCXXCompilerFlag.

Check if the CXX compiler accepts a flag.

     CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)

‘<flags>’

     the flags to try

‘<variable>’

     variable to store the result

15.3.1.7 UsePkgConfig
.....................

Obsolete pkg-config module for CMake, use FindPkgConfig instead.

This module defines the following macro:

PKGCONFIG(package includedir libdir linkflags cflags)

Calling PKGCONFIG will fill the desired information into the 4 given
arguments, e.g.  PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR LIBART_LINK_DIR
LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT found or the
specified software package doesn’t exist, the variable will be empty
when the function returns, otherwise they will contain the respective
information

15.3.1.8 Use_wxWindows
......................

Deprecated since version 2.8.10: Use ‘find_package(wxWidgets)’ and
‘include(${wxWidgets_USE_FILE})’ instead.

This convenience include finds if wxWindows is installed and set the
appropriate libs, incdirs, flags etc.  author Jan Woetzel <jw -at-
mip.informatik.uni-kiel.de> (07/2003)

USAGE:

     just include Use_wxWindows.cmake
     in your projects CMakeLists.txt

include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)

     if you are sure you need GL then

set(WXWINDOWS_USE_GL 1)

     *before* you include this file.

15.3.1.9 WriteBasicConfigVersionFile
....................................

Deprecated since version 3.0: Use the identical command
write_basic_package_version_file() from module
CMakePackageConfigHelpers.

     WRITE_BASIC_CONFIG_VERSION_FILE( filename
       [VERSION major.minor.patch]
       COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
       [ARCH_INDEPENDENT]
       )

15.3.2 Deprecated Find Modules
------------------------------

15.3.2.1 FindCUDA
.................

Deprecated since version 3.10: Superseded by first-class support for the
CUDA language in CMake.  Superseded by the FindCUDAToolkit.
for CUDA toolkit libraries.

15.3.2.2 Replacement
....................

It is no longer necessary to use this module or call
‘find_package(CUDA)’ for compiling CUDA code.  Instead, list ‘CUDA’
among the languages named in the top-level call to the project()
command, or call the enable_language() command with
‘CUDA’.  Then one can add CUDA (‘.cu’) sources to programs directly in
calls to add_library() and add_executable().

To find and use the CUDA toolkit libraries the FindCUDAToolkit
module has superseded this module.  It works whether or not the
‘CUDA’ language is enabled.

15.3.2.3 Documentation of Deprecated Usage
..........................................

Tools for building CUDA C files: libraries and build dependencies.

This script locates the NVIDIA CUDA C tools.  It should work on Linux,
Windows, and macOS and should be reasonably up to date with CUDA C
releases.

This script makes use of the standard find_package().
arguments of ‘<VERSION>’, ‘REQUIRED’ and ‘QUIET’.  ‘CUDA_FOUND’ will
report if an acceptable version of CUDA was found.

The script will prompt the user to specify ‘CUDA_TOOLKIT_ROOT_DIR’ if
the prefix cannot be determined by the location of nvcc in the system
path and ‘REQUIRED’ is specified to find_package().  To use a
different installed version of the toolkit set the environment variable
‘CUDA_BIN_PATH’ before running cmake (e.g.
‘CUDA_BIN_PATH=/usr/local/cuda1.0’ instead of the default
‘/usr/local/cuda’) or set ‘CUDA_TOOLKIT_ROOT_DIR’ after configuring.  If
you change the value of ‘CUDA_TOOLKIT_ROOT_DIR’, various components that
depend on the path will be relocated.

It might be necessary to set ‘CUDA_TOOLKIT_ROOT_DIR’ manually on certain
platforms, or to use a CUDA runtime not installed in the default
location.  In newer versions of the toolkit the CUDA library is included
with the graphics driver – be sure that the driver version matches what
is needed by the CUDA runtime version.

The following variables affect the behavior of the macros in the script
(in alphabetical order).  Note that any of these flags can be changed
multiple times in the same directory before calling
‘CUDA_ADD_EXECUTABLE’, ‘CUDA_ADD_LIBRARY’, ‘CUDA_COMPILE’,
‘CUDA_COMPILE_PTX’, ‘CUDA_COMPILE_FATBIN’, ‘CUDA_COMPILE_CUBIN’ or
‘CUDA_WRAP_SRCS’:

     CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
     -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
        Note that making this different from the host code when generating object
        or C files from CUDA code just won't work, because size_t gets defined by
        nvcc in the generated source.  If you compile to PTX and then load the
        file yourself, you can mix bit sizes between device and host.

     CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
     -- Set to ON if you want the custom build rule to be attached to the source
        file in Visual Studio.  Turn OFF if you add the same cuda file to multiple
        targets.

        This allows the user to build the target from the CUDA file; however, bad
        things can happen if the CUDA source file is added to multiple targets.
        When performing parallel builds it is possible for the custom build
        command to be run more than once and in parallel causing cryptic build
        errors.  VS runs the rules for every source file in the target, and a
        source can have only one rule no matter how many projects it is added to.
        When the rule is run from multiple targets race conditions can occur on
        the generated file.  Eventually everything will get built, but if the user
        is unaware of this behavior, there may be confusion.  It would be nice if
        this script could detect the reuse of source files across multiple targets
        and turn the option off for the user, but no good solution could be found.

     CUDA_BUILD_CUBIN (Default OFF)
     -- Set to ON to enable and extra compilation pass with the -cubin option in
        Device mode. The output is parsed and register, shared memory usage is
        printed during build.

     CUDA_BUILD_EMULATION (Default OFF for device mode)
     -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
        when CUDA_BUILD_EMULATION is TRUE.

     CUDA_LINK_LIBRARIES_KEYWORD (Default "")
      -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
         target_link_libraries calls. The default is to use no keyword which
         uses the old "plain" form of target_link_libraries. Note that is matters
         because whatever is used inside the FindCUDA module must also be used
         outside - the two forms of target_link_libraries cannot be mixed.

     CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
     -- Set to the path you wish to have the generated files placed.  If it is
        blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
        Intermediate files will always be placed in
        CMAKE_CURRENT_BINARY_DIR/CMakeFiles.

     CUDA_HOST_COMPILATION_CPP (Default ON)
     -- Set to OFF for C compilation of host code.

     CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
     -- Set the host compiler to be used by nvcc.  Ignored if -ccbin or
        --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
        CUDA_NVCC_FLAGS_<CONFIG> variables.  For Visual Studio targets,
        the host compiler is constructed with one or more visual studio macros
        such as $(VCInstallDir), that expands out to the path when
        the command is run from within VS.
        If the CUDAHOSTCXX environment variable is set it will
        be used as the default.

     CUDA_NVCC_FLAGS
     CUDA_NVCC_FLAGS_<CONFIG>
     -- Additional NVCC command line arguments.  NOTE: multiple arguments must be
        semi-colon delimited (e.g. --compiler-options;-Wall)

     CUDA_PROPAGATE_HOST_FLAGS (Default ON)
     -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
        dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
        host compiler through nvcc's -Xcompiler flag.  This helps make the
        generated host code match the rest of the system better.  Sometimes
        certain flags give nvcc problems, and this will help you turn the flag
        propagation off.  This does not affect the flags supplied directly to nvcc
        via CUDA_NVCC_FLAGS or through the OPTION flags specified through
        CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS.  Flags used for
        shared library compilation are not affected by this flag.

     CUDA_SEPARABLE_COMPILATION (Default OFF)
     -- If set this will enable separable compilation for all CUDA runtime object
        files.  If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
        (e.g. calling CUDA_WRAP_SRCS directly),
        CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
        CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.

     CUDA_SOURCE_PROPERTY_FORMAT
     -- If this source file property is set, it can override the format specified
        to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN).  If an input source file
        is not a .cu file, setting this file will cause it to be treated as a .cu
        file. See documentation for set_source_files_properties on how to set
        this property.

     CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
     -- When enabled the static version of the CUDA runtime library will be used
        in CUDA_LIBRARIES.  If the version of CUDA configured doesn't support
        this option, then it will be silently disabled.

     CUDA_VERBOSE_BUILD (Default OFF)
     -- Set to ON to see all the commands used when building the CUDA file.  When
        using a Makefile generator the value defaults to VERBOSE (run make
        VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
        always print the output.

The script creates the following macros (in alphabetical order):

     CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
     -- Adds the cufft library to the target (can be any target).  Handles whether
        you are in emulation mode or not.

     CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
     -- Adds the cublas library to the target (can be any target).  Handles
        whether you are in emulation mode or not.

     CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
                          [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
     -- Creates an executable "cuda_target" which is made up of the files
        specified.  All of the non CUDA C files are compiled using the standard
        build rules specified by CMAKE and the cuda files are compiled to object
        files using nvcc and the host compiler.  In addition CUDA_INCLUDE_DIRS is
        added automatically to include_directories().  Some standard CMake target
        calls can be used on the target after calling this macro
        (e.g. set_target_properties and target_link_libraries), but setting
        properties that adjust compilation flags will not affect code compiled by
        nvcc.  Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
        CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.

     CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
                       [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
     -- Same as CUDA_ADD_EXECUTABLE except that a library is created.

     CUDA_BUILD_CLEAN_TARGET()
     -- Creates a convenience target that deletes all the dependency files
        generated.  You should make clean after running this target to ensure the
        dependency files get regenerated.

     CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
                   [OPTIONS ...] )
     -- Returns a list of generated files from the input source files to be used
        with ADD_LIBRARY or ADD_EXECUTABLE.

     CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
     -- Returns a list of PTX files generated from the input source files.

     CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
     -- Returns a list of FATBIN files generated from the input source files.

     CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
     -- Returns a list of CUBIN files generated from the input source files.

     CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
                                                          cuda_target
                                                          object_files )
     -- Compute the name of the intermediate link file used for separable
        compilation.  This file name is typically passed into
        CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS.  output_file_var is produced
        based on cuda_target the list of objects files that need separable
        compilation as specified by object_files.  If the object_files list is
        empty, then output_file_var will be empty.  This function is called
        automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE.  Note that
        this is a function and not a macro.

     CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
     -- Sets the directories that should be passed to nvcc
        (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
        files.

     CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
                                              nvcc_flags object_files)
     -- Generates the link object required by separable compilation from the given
        object files.  This is called automatically for CUDA_ADD_EXECUTABLE and
        CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
        directly.  When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
        nvcc_flags passed in are the same as the flags passed in via the OPTIONS
        argument.  The only nvcc flag added automatically is the bitness flag as
        specified by CUDA_64_BIT_DEVICE_CODE.  Note that this is a function
        instead of a macro.

     CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
     -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
        target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
         - "Auto" detects local machine GPU compute arch at runtime.
         - "Common" and "All" cover common and entire subsets of architectures
        ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
        NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
        NUM: Any number. Only those pairs are currently accepted by NVCC though:
              2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
        Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
        Additionally, sets ${out_variable}_readable to the resulting numeric list
        Example:
         CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
          LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})

        More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
        Note that this is a function instead of a macro.

     CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
                      [STATIC | SHARED | MODULE] [OPTIONS ...] )
     -- This is where all the magic happens.  CUDA_ADD_EXECUTABLE,
        CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
        function under the hood.

        Given the list of files (file0 file1 ... fileN) this macro generates
        custom commands that generate either PTX or linkable objects (use "PTX" or
        "OBJ" for the format argument to switch).  Files that don't end with .cu
        or have the HEADER_FILE_ONLY property are ignored.

        The arguments passed in after OPTIONS are extra command line options to
        give to nvcc.  You can also specify per configuration options by
        specifying the name of the configuration followed by the options.  General
        options must precede configuration specific options.  Not all
        configurations need to be specified, only the ones provided will be used.

           OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
           DEBUG -g
           RELEASE --use_fast_math
           RELWITHDEBINFO --use_fast_math;-g
           MINSIZEREL --use_fast_math

        For certain configurations (namely VS generating object files with
        CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
        be produced for the given cuda file.  This is because when you add the
        cuda file to Visual Studio it knows that this file produces an object file
        and will link in the resulting object file automatically.

        This script will also generate a separate cmake script that is used at
        build time to invoke nvcc.  This is for several reasons.

          1. nvcc can return negative numbers as return values which confuses
          Visual Studio into thinking that the command succeeded.  The script now
          checks the error codes and produces errors when there was a problem.

          2. nvcc has been known to not delete incomplete results when it
          encounters problems.  This confuses build systems into thinking the
          target was generated when in fact an unusable file exists.  The script
          now deletes the output files if there was an error.

          3. By putting all the options that affect the build into a file and then
          make the build rule dependent on the file, the output files will be
          regenerated when the options change.

        This script also looks at optional arguments STATIC, SHARED, or MODULE to
        determine when to target the object compilation for a shared library.
        BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
        CUDA_ADD_LIBRARY.  On some systems special flags are added for building
        objects intended for shared libraries.  A preprocessor macro,
        <target_name>_EXPORTS is defined when a shared library compilation is
        detected.

        Flags passed into add_definitions with -D or /D are passed along to nvcc.

The script defines the following variables:

     CUDA_VERSION_MAJOR    -- The major version of cuda as reported by nvcc.
     CUDA_VERSION_MINOR    -- The minor version.
     CUDA_VERSION
     CUDA_VERSION_STRING   -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
     CUDA_HAS_FP16         -- Whether a short float (float16,fp16) is supported.

     CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
     CUDA_SDK_ROOT_DIR     -- Path to the CUDA SDK.  Use this to find files in the
                              SDK.  This script will not directly support finding
                              specific libraries or headers, as that isn't
                              supported by NVIDIA.  If you want to change
                              libraries when the path changes see the
                              FindCUDA.cmake script for an example of how to clear
                              these variables.  There are also examples of how to
                              use the CUDA_SDK_ROOT_DIR to locate headers or
                              libraries, if you so choose (at your own risk).
     CUDA_INCLUDE_DIRS     -- Include directory for cuda headers.  Added automatically
                              for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
     CUDA_LIBRARIES        -- Cuda RT library.
     CUDA_CUFFT_LIBRARIES  -- Device or emulation library for the Cuda FFT
                              implementation (alternative to:
                              CUDA_ADD_CUFFT_TO_TARGET macro)
     CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
                              implementation (alternative to:
                              CUDA_ADD_CUBLAS_TO_TARGET macro).
     CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
                                   Only available for CUDA version 5.5+
     CUDA_cudadevrt_LIBRARY -- Device runtime library.
                               Required for separable compilation.
     CUDA_cupti_LIBRARY    -- CUDA Profiling Tools Interface library.
                              Only available for CUDA version 4.0+.
     CUDA_curand_LIBRARY   -- CUDA Random Number Generation library.
                              Only available for CUDA version 3.2+.
     CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
                              Only available for CUDA version 7.0+.
     CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
                              Only available for CUDA version 3.2+.
     CUDA_npp_LIBRARY      -- NVIDIA Performance Primitives lib.
                              Only available for CUDA version 4.0+.
     CUDA_nppc_LIBRARY     -- NVIDIA Performance Primitives lib (core).
                              Only available for CUDA version 5.5+.
     CUDA_nppi_LIBRARY     -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 5.5 - 8.0.
     CUDA_nppial_LIBRARY   -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppicc_LIBRARY   -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppicom_LIBRARY  -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0 - 10.2.
                              Replaced by nvjpeg.
     CUDA_nppidei_LIBRARY  -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppif_LIBRARY    -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppig_LIBRARY    -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppim_LIBRARY    -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppist_LIBRARY   -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppisu_LIBRARY   -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_nppitc_LIBRARY   -- NVIDIA Performance Primitives lib (image processing).
                              Only available for CUDA version 9.0.
     CUDA_npps_LIBRARY     -- NVIDIA Performance Primitives lib (signal processing).
                              Only available for CUDA version 5.5+.
     CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
                              Only available for CUDA version 3.2+.
                              Windows only.
     CUDA_nvcuvid_LIBRARY  -- CUDA Video Decoder library.
                              Only available for CUDA version 3.2+.
                              Windows only.
     CUDA_nvToolsExt_LIBRARY
                           -- NVIDA CUDA Tools Extension library.
                              Available for CUDA version 5+.
     CUDA_OpenCL_LIBRARY   -- NVIDA CUDA OpenCL library.
                              Available for CUDA version 5+.

15.3.2.4 FindPythonInterp
.........................

Deprecated since version 3.12: Use FindPython3,
FindPython2 or FindPython instead.

Find python interpreter

This module finds if Python interpreter is installed and determines
where the executables are.  This code sets the following variables:

     PYTHONINTERP_FOUND         - Was the Python executable found
     PYTHON_EXECUTABLE          - path to the Python interpreter

     PYTHON_VERSION_STRING      - Python version found e.g. 2.5.2
     PYTHON_VERSION_MAJOR       - Python major version found e.g. 2
     PYTHON_VERSION_MINOR       - Python minor version found e.g. 5
     PYTHON_VERSION_PATCH       - Python patch version found e.g. 2

The Python_ADDITIONAL_VERSIONS variable can be used to specify a list of
version numbers that should be taken into account when searching for
Python.  You need to set this variable before calling
find_package(PythonInterp).

If calling both ‘find_package(PythonInterp)’ and
‘find_package(PythonLibs)’, call ‘find_package(PythonInterp)’ first to
get the currently active Python version by default with a consistent
version of PYTHON_LIBRARIES.

     Note: A call to ‘find_package(PythonInterp ${V})’ for python
     version ‘V’ may find a ‘python’ executable with no version suffix.
     In this case no attempt is made to avoid python executables from
     other versions.  Use FindPython3, FindPython2
     or FindPython instead.

15.3.2.5 FindPythonLibs
.......................

Deprecated since version 3.12: Use FindPython3,
FindPython2 or FindPython instead.

Find python libraries

This module finds if Python is installed and determines where the
include files and libraries are.  It also determines what the name of
the library is.  This code sets the following variables:

     PYTHONLIBS_FOUND           - have the Python libs been found
     PYTHON_LIBRARIES           - path to the python library
     PYTHON_INCLUDE_PATH        - path to where Python.h is found (deprecated)
     PYTHON_INCLUDE_DIRS        - path to where Python.h is found
     PYTHON_DEBUG_LIBRARIES     - path to the debug library (deprecated)
     PYTHONLIBS_VERSION_STRING  - version of the Python libs found (since CMake 2.8.8)

The Python_ADDITIONAL_VERSIONS variable can be used to specify a list of
version numbers that should be taken into account when searching for
Python.  You need to set this variable before calling
find_package(PythonLibs).

If you’d like to specify the installation of Python to use, you should
modify the following cache variables:

     PYTHON_LIBRARY             - path to the python library
     PYTHON_INCLUDE_DIR         - path to where Python.h is found

If calling both ‘find_package(PythonInterp)’ and
‘find_package(PythonLibs)’, call ‘find_package(PythonInterp)’ first to
get the currently active Python version by default with a consistent
version of PYTHON_LIBRARIES.

15.3.2.6 FindQt
...............

Searches for all installed versions of Qt3 or Qt4.

This module cannot handle Qt5 or any later versions.  For those, see
cmake-qt(7).

This module exists for the find_package() command only if
policy CMP0084 is not set to ‘NEW’.

This module should only be used if your project can work with multiple
versions of Qt.  If not, you should just directly use FindQt4 or
FindQt3.  If multiple versions of Qt are found on the machine, then The
user must set the option DESIRED_QT_VERSION to the version they want to
use.  If only one version of qt is found on the machine, then the
DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
FindQt4 module is included.  Once the user sets DESIRED_QT_VERSION, then
the FindQt3 or FindQt4 module is included.

     QT_REQUIRED if this is set to TRUE then if CMake can
                 not find Qt4 or Qt3 an error is raised
                 and a message is sent to the user.

     DESIRED_QT_VERSION OPTION is created
     QT4_INSTALLED is set to TRUE if qt4 is found.
     QT3_INSTALLED is set to TRUE if qt3 is found.

15.3.2.7 FindwxWindows
......................

Deprecated since version 3.0: Replaced by FindwxWidgets.

Find wxWindows (wxWidgets) installation

This module finds if wxWindows/wxWidgets is installed and determines
where the include files and libraries are.  It also determines what the
name of the library is.  This code sets the following variables:

     WXWINDOWS_FOUND     = system has WxWindows
     WXWINDOWS_LIBRARIES = path to the wxWindows libraries
                           on Unix/Linux with additional
                           linker flags from
                           "wx-config --libs"
     CMAKE_WXWINDOWS_CXX_FLAGS  = Compiler flags for wxWindows,
                                  essentially "`wx-config --cxxflags`"
                                  on Linux
     WXWINDOWS_INCLUDE_DIR      = where to find "wx/wx.h" and "wx/setup.h"
     WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
                                   Unix
     WXWINDOWS_DEFINITIONS      = extra defines

OPTIONS If you need OpenGL support please

     set(WXWINDOWS_USE_GL 1)

in your CMakeLists.txt `before' you include this file.

     HAVE_ISYSTEM      - true required to replace -I by -isystem on g++

For convenience include Use_wxWindows.cmake in your project’s
CMakeLists.txt using
include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).

USAGE

     set(WXWINDOWS_USE_GL 1)
     find_package(wxWindows)

NOTES wxWidgets 2.6.x is supported for monolithic builds e.g.  compiled
in wx/build/msw dir as:

     nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1

DEPRECATED

     CMAKE_WX_CAN_COMPILE
     WXWINDOWS_LIBRARY
     CMAKE_WX_CXX_FLAGS
     WXWINDOWS_INCLUDE_PATH

AUTHOR Jan Woetzel <‘http://www.mip.informatik.uni-kiel.de/~jw’>
(07/2003-01/2006)

15.3.3 Legacy CPack Modules
---------------------------

These modules used to be mistakenly exposed to the user, and have been
moved out of user visibility.  They are for CPack internal use, and
should never be used directly.

15.3.3.1 CPackArchive
.....................

New in version 3.9.

The documentation for the CPack Archive generator has moved here:
CPack Archive Generator.

15.3.3.2 CPackBundle
....................

The documentation for the CPack Bundle generator has moved here:
CPack Bundle Generator.

15.3.3.3 CPackCygwin
....................

The documentation for the CPack Cygwin generator has moved here:
CPack Cygwin Generator.

15.3.3.4 CPackDeb
.................

The documentation for the CPack DEB generator has moved here:
CPack DEB Generator.

15.3.3.5 CPackDMG
.................

The documentation for the CPack DragNDrop generator has moved here:
CPack DragNDrop Generator.

15.3.3.6 CPackFreeBSD
.....................

New in version 3.10.

The documentation for the CPack FreeBSD generator has moved here:
CPack FreeBSD Generator.

15.3.3.7 CPackNSIS
..................

The documentation for the CPack NSIS generator has moved here:
CPack NSIS Generator.

15.3.3.8 CPackNuGet
...................

New in version 3.12.

The documentation for the CPack NuGet generator has moved here:
CPack NuGet Generator.

15.3.3.9 CPackPackageMaker
..........................

The documentation for the CPack PackageMaker generator has moved here:
CPack PackageMaker Generator.

15.3.3.10 CPackProductBuild
...........................

New in version 3.7.

The documentation for the CPack productbuild generator has moved here:
CPack productbuild Generator.

15.3.3.11 CPackRPM
..................

The documentation for the CPack RPM generator has moved here:
CPack RPM Generator.

15.3.3.12 CPackWIX
..................

The documentation for the CPack WIX generator has moved here:
CPack WIX Generator.

16 cmake-packages(7)
********************

16.1 Introduction
=================

Packages provide dependency information to CMake based buildsystems.
Packages are found with the find_package() command.  The
result of using find_package() is either a set of
IMPORTED targets, or a set of variables corresponding to
build-relevant information.

16.2 Using Packages
===================

CMake provides direct support for two forms of packages, see
Config-file Packages and Find-module Packages.
Indirect support for ‘pkg-config’ packages is also provided via the
FindPkgConfig module.  In all cases, the basic form of
find_package() calls is the same:

     find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module
     find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
     find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module

In cases where it is known that a package configuration file is provided
by upstream, and only that should be used, the ‘CONFIG’ keyword may be
passed to find_package().:

     find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
     find_package(Qt5Gui 5.1.0 CONFIG)

Similarly, the ‘MODULE’ keyword says to use only a find-module:

     find_package(Qt4 4.7.0 MODULE REQUIRED)

Specifying the type of package explicitly improves the error message
shown to the user if it is not found.

Both types of packages also support specifying components of a package,
either after the ‘REQUIRED’ keyword:

     find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)

or as a separate ‘COMPONENTS’ list:

     find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)

or as a separate ‘OPTIONAL_COMPONENTS’ list:

     find_package(Qt5 5.1.0 COMPONENTS Widgets
                            OPTIONAL_COMPONENTS Xml Sql
     )

Handling of ‘COMPONENTS’ and ‘OPTIONAL_COMPONENTS’ is defined by the
package.

By setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName>.
variable to ‘TRUE’, the ‘<PackageName>’ package will not be searched,
and will always be ‘NOTFOUND’.

16.2.1 Config-file Packages
---------------------------

A config-file package is a set of files provided by upstreams for
downstreams to use.  CMake searches in a number of locations for package
configuration files, as described in the find_package().
documentation.  The most simple way for a CMake user to tell
cmake(1) to search in a non-standard prefix for a package is to set
the ‘CMAKE_PREFIX_PATH’ cache variable.

Config-file packages are provided by upstream vendors as part of
development packages, that is, they belong with the header files and any
other files provided to assist downstreams in using the package.

A set of variables which provide package status information are also set
automatically when using a config-file package.  The
‘<PackageName>_FOUND’ variable is set to true or false, depending on
whether the package was found.  The ‘<PackageName>_DIR’ cache variable
is set to the location of the package configuration file.

16.2.2 Find-module Packages
---------------------------

A find module is a file with a set of rules for finding the required
pieces of a dependency, primarily header files and libraries.
Typically, a find module is needed when the upstream is not built with
CMake, or is not CMake-aware enough to otherwise provide a package
configuration file.  Unlike a package configuration file, it is not
shipped with upstream, but is used by downstream to find the files by
guessing locations of files with platform-specific hints.

Unlike the case of an upstream-provided package configuration file, no
single point of reference identifies the package as being found, so the
‘<PackageName>_FOUND’ variable is not automatically set by the
find_package() command.  It can still be expected to be set by
convention however and should be set by the author of the Find-module.
Similarly there is no ‘<PackageName>_DIR’ variable, but each of the
artifacts such as library locations and header file locations provide a
separate cache variable.

See the cmake-developer(7) manual for more information about
creating Find-module files.

16.3 Package Layout
===================

A config-file package consists of a Package Configuration File
and optionally a Package Version File provided with the
project distribution.

16.3.1 Package Configuration File
---------------------------------

Consider a project ‘Foo’ that installs the following files:

     <prefix>/include/foo-1.2/foo.h
     <prefix>/lib/foo-1.2/libfoo.a

It may also provide a CMake package configuration file:

     <prefix>/lib/cmake/foo-1.2/FooConfig.cmake

with content defining IMPORTED targets, or defining
variables, such as:

     # ...
     # (compute PREFIX relative to file location)
     # ...
     set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
     set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a)

If another project wishes to use ‘Foo’ it need only to locate the
‘FooConfig.cmake’ file and load it to get all the information it needs
about package content locations.  Since the package configuration file
is provided by the package installation it already knows all the file
locations.

The find_package() command may be used to search for the
package configuration file.  This command constructs a set of
installation prefixes and searches under each prefix in several
locations.  Given the name ‘Foo’, it looks for a file called
‘FooConfig.cmake’ or ‘foo-config.cmake’.  The full set of locations is
specified in the find_package() command documentation.  One
place it looks is:

     <prefix>/lib/cmake/Foo*/

where ‘Foo*’ is a case-insensitive globbing expression.  In our example
the globbing expression will match ‘<prefix>/lib/cmake/foo-1.2’ and the
package configuration file will be found.

Once found, a package configuration file is immediately loaded.  It,
together with a package version file, contains all the information the
project needs to use the package.

16.3.2 Package Version File
---------------------------

When the find_package() command finds a candidate package
configuration file it looks next to it for a version file.  The version
file is loaded to test whether the package version is an acceptable
match for the version requested.  If the version file claims
compatibility the configuration file is accepted.  Otherwise it is
ignored.

The name of the package version file must match that of the package
configuration file but has either ‘-version’ or ‘Version’ appended to
the name before the ‘.cmake’ extension.  For example, the files:

     <prefix>/lib/cmake/foo-1.3/foo-config.cmake
     <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake

and:

     <prefix>/lib/cmake/bar-4.2/BarConfig.cmake
     <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake

are each pairs of package configuration files and corresponding package
version files.

When the find_package() command loads a version file it first
sets the following variables:

‘PACKAGE_FIND_NAME’

     The ‘<PackageName>’

‘PACKAGE_FIND_VERSION’

     Full requested version string

‘PACKAGE_FIND_VERSION_MAJOR’

     Major version if requested, else 0

‘PACKAGE_FIND_VERSION_MINOR’

     Minor version if requested, else 0

‘PACKAGE_FIND_VERSION_PATCH’

     Patch version if requested, else 0

‘PACKAGE_FIND_VERSION_TWEAK’

     Tweak version if requested, else 0

‘PACKAGE_FIND_VERSION_COUNT’

     Number of version components, 0 to 4

The version file must use these variables to check whether it is
compatible or an exact match for the requested version and set the
following variables with results:

‘PACKAGE_VERSION’

     Full provided version string

‘PACKAGE_VERSION_EXACT’

     True if version is exact match

‘PACKAGE_VERSION_COMPATIBLE’

     True if version is compatible

‘PACKAGE_VERSION_UNSUITABLE’

     True if unsuitable as any version

Version files are loaded in a nested scope so they are free to set any
variables they wish as part of their computation.  The find_package
command wipes out the scope when the version file has completed and it
has checked the output variables.  When the version file claims to be an
acceptable match for the requested version the find_package command sets
the following variables for use by the project:

‘<PackageName>_VERSION’

     Full provided version string

‘<PackageName>_VERSION_MAJOR’

     Major version if provided, else 0

‘<PackageName>_VERSION_MINOR’

     Minor version if provided, else 0

‘<PackageName>_VERSION_PATCH’

     Patch version if provided, else 0

‘<PackageName>_VERSION_TWEAK’

     Tweak version if provided, else 0

‘<PackageName>_VERSION_COUNT’

     Number of version components, 0 to 4

The variables report the version of the package that was actually found.
The ‘<PackageName>’ part of their name matches the argument given to the
find_package() command.

16.4 Creating Packages
======================

Usually, the upstream depends on CMake itself and can use some CMake
facilities for creating the package files.  Consider an upstream which
provides a single shared library:

     project(UpstreamLib)

     set(CMAKE_INCLUDE_CURRENT_DIR ON)
     set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)

     set(Upstream_VERSION 3.4.1)

     include(GenerateExportHeader)

     add_library(ClimbingStats SHARED climbingstats.cpp)
     generate_export_header(ClimbingStats)
     set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
     set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
     set_property(TARGET ClimbingStats PROPERTY
       INTERFACE_ClimbingStats_MAJOR_VERSION 3)
     set_property(TARGET ClimbingStats APPEND PROPERTY
       COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
     )

     install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
       LIBRARY DESTINATION lib
       ARCHIVE DESTINATION lib
       RUNTIME DESTINATION bin
       INCLUDES DESTINATION include
     )
     install(
       FILES
         climbingstats.h
         "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
       DESTINATION
         include
       COMPONENT
         Devel
     )

     include(CMakePackageConfigHelpers)
     write_basic_package_version_file(
       "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
       VERSION ${Upstream_VERSION}
       COMPATIBILITY AnyNewerVersion
     )

     export(EXPORT ClimbingStatsTargets
       FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
       NAMESPACE Upstream::
     )
     configure_file(cmake/ClimbingStatsConfig.cmake
       "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
       COPYONLY
     )

     set(ConfigPackageLocation lib/cmake/ClimbingStats)
     install(EXPORT ClimbingStatsTargets
       FILE
         ClimbingStatsTargets.cmake
       NAMESPACE
         Upstream::
       DESTINATION
         ${ConfigPackageLocation}
     )
     install(
       FILES
         cmake/ClimbingStatsConfig.cmake
         "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
       DESTINATION
         ${ConfigPackageLocation}
       COMPONENT
         Devel
     )

The CMakePackageConfigHelpers module provides a macro for
creating a simple ‘ConfigVersion.cmake’ file.  This file sets the
version of the package.  It is read by CMake when find_package()
is called to determine the compatibility with the requested version,
and to set some version-specific variables ‘<PackageName>_VERSION’,
‘<PackageName>_VERSION_MAJOR’, ‘<PackageName>_VERSION_MINOR’ etc.  The
install(EXPORT) command is used to export the targets in the
‘ClimbingStatsTargets’ export-set, defined previously by the
install(TARGETS) command.  This command generates the
‘ClimbingStatsTargets.cmake’ file to contain IMPORTED.
targets, suitable for use by downstreams and arranges to install it to
‘lib/cmake/ClimbingStats’.  The generated
‘ClimbingStatsConfigVersion.cmake’ and a
‘cmake/ClimbingStatsConfig.cmake’ are installed to the same location,
completing the package.

The generated IMPORTED targets have appropriate properties
set to define their usage requirements, such as
INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS
and other relevant built-in ‘INTERFACE_’ properties.  The
‘INTERFACE’ variant of user-defined properties listed in
COMPATIBLE_INTERFACE_STRING and other Compatible Interface Properties
are also propagated to the generated IMPORTED
targets.  In the above case, ‘ClimbingStats_MAJOR_VERSION’ is
defined as a string which must be compatible among the dependencies of
any depender.  By setting this custom defined user property in this
version and in the next version of ‘ClimbingStats’, see cmake(1).
will issue a diagnostic if there is an attempt to use version 3 together
with version 4.  Packages can choose to employ such a pattern if
different major versions of the package are designed to be incompatible.

A ‘NAMESPACE’ with double-colons is specified when exporting the targets
for installation.  This convention of double-colons gives CMake a hint
that the name is an IMPORTED target when it is used by
downstreams with the target_link_libraries() command.  This
way, CMake can issue a diagnostic if the package providing it has not
yet been found.

In this case, when using install(TARGETS) the ‘INCLUDES
DESTINATION’ was specified.  This causes the ‘IMPORTED’ targets to have
their INTERFACE_INCLUDE_DIRECTORIES populated with the
‘include’ directory in the CMAKE_INSTALL_PREFIX.  When the
‘IMPORTED’ target is used by downstream, it automatically consumes the
entries from that property.

16.4.1 Creating a Package Configuration File
--------------------------------------------

In this case, the ‘ClimbingStatsConfig.cmake’ file could be as simple
as:

     include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")

As this allows downstreams to use the ‘IMPORTED’ targets.  If any macros
should be provided by the ‘ClimbingStats’ package, they should be in a
separate file which is installed to the same location as the
‘ClimbingStatsConfig.cmake’ file, and included from there.

This can also be extended to cover dependencies:

     # ...
     add_library(ClimbingStats SHARED climbingstats.cpp)
     generate_export_header(ClimbingStats)

     find_package(Stats 2.6.4 REQUIRED)
     target_link_libraries(ClimbingStats PUBLIC Stats::Types)

As the ‘Stats::Types’ target is a ‘PUBLIC’ dependency of
‘ClimbingStats’, downstreams must also find the ‘Stats’ package and link
to the ‘Stats::Types’ library.  The ‘Stats’ package should be found in
the ‘ClimbingStatsConfig.cmake’ file to ensure this.  The
‘find_dependency’ macro from the CMakeFindDependencyMacro.
helps with this by propagating whether the package is ‘REQUIRED’, or
‘QUIET’ etc.  All ‘REQUIRED’ dependencies of a package should be found
in the ‘Config.cmake’ file:

     include(CMakeFindDependencyMacro)
     find_dependency(Stats 2.6.4)

     include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

The ‘find_dependency’ macro also sets ‘ClimbingStats_FOUND’ to ‘False’
if the dependency is not found, along with a diagnostic that the
‘ClimbingStats’ package can not be used without the ‘Stats’ package.

If ‘COMPONENTS’ are specified when the downstream uses
find_package(), they are listed in the
‘<PackageName>_FIND_COMPONENTS’ variable.  If a particular component is
non-optional, then the ‘<PackageName>_FIND_REQUIRED_<comp>’ will be
true.  This can be tested with logic in the package configuration file:

     include(CMakeFindDependencyMacro)
     find_dependency(Stats 2.6.4)

     include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

     set(_supported_components Plot Table)

     foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
       if (NOT ";${_supported_components};" MATCHES _comp)
         set(ClimbingStats_FOUND False)
         set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
       endif()
       include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
     endforeach()

Here, the ‘ClimbingStats_NOT_FOUND_MESSAGE’ is set to a diagnosis that
the package could not be found because an invalid component was
specified.  This message variable can be set for any case where the
‘_FOUND’ variable is set to ‘False’, and will be displayed to the user.

16.4.1.1 Creating a Package Configuration File for the Build Tree
.................................................................

The export(EXPORT) command creates an IMPORTED.
targets definition file which is specific to the build-tree, and is not
relocatable.  This can similarly be used with a suitable package
configuration file and package version file to define a package for the
build tree which may be used without installation.  Consumers of the
build tree can simply ensure that the CMAKE_PREFIX_PATH.
contains the build directory, or set the ‘ClimbingStats_DIR’ to
‘<build_dir>/ClimbingStats’ in the cache.

16.4.2 Creating Relocatable Packages
------------------------------------

A relocatable package must not reference absolute paths of files on the
machine where the package is built that will not exist on the machines
where the package may be installed.

Packages created by install(EXPORT) are designed to be
relocatable, using paths relative to the location of the package itself.
When defining the interface of a target for ‘EXPORT’, keep in mind that
the include directories should be specified as relative paths which are
relative to the CMAKE_INSTALL_PREFIX.:

     target_include_directories(tgt INTERFACE
       # Wrong, not relocatable:
       $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
     )

     target_include_directories(tgt INTERFACE
       # Ok, relocatable:
       $<INSTALL_INTERFACE:include/TgtName>
     )

The ‘$<INSTALL_PREFIX>’ generator expression may be used as a
placeholder for the install prefix without resulting in a
non-relocatable package.  This is necessary if complex generator
expressions are used:

     target_include_directories(tgt INTERFACE
       # Ok, relocatable:
       $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
     )

This also applies to paths referencing external dependencies.  It is not
advisable to populate any properties which may contain paths, such as
INTERFACE_INCLUDE_DIRECTORIES and
INTERFACE_LINK_LIBRARIES, with paths relevant to dependencies.  For
example, this code may not work well for a relocatable package:

     target_link_libraries(ClimbingStats INTERFACE
       ${Foo_LIBRARIES} ${Bar_LIBRARIES}
       )
     target_include_directories(ClimbingStats INTERFACE
       "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
       )

The referenced variables may contain the absolute paths to libraries and
include directories `as found on the machine the package was made on'.
This would create a package with hard-coded paths to dependencies and
not suitable for relocation.

Ideally such dependencies should be used through their own
IMPORTED targets that have their own IMPORTED_LOCATION.
and usage requirement properties such as
INTERFACE_INCLUDE_DIRECTORIES populated appropriately.  Those
imported targets may then be used with the
target_link_libraries() command for ‘ClimbingStats’:

     target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)

With this approach the package references its external dependencies only
through the names of IMPORTED targets.  When a consumer uses
the installed package, the consumer will run the appropriate
find_package() commands (via the ‘find_dependency’ macro described
above) to find the dependencies and populate the imported targets with
appropriate paths on their own machine.

Unfortunately many modules shipped with CMake do not yet
provide IMPORTED targets because their development pre-dated
this approach.  This may improve incrementally over time.  Workarounds
to create relocatable packages using such modules include:

   * When building the package, specify each ‘Foo_LIBRARY’ cache entry
     as just a library name, e.g.  ‘-DFoo_LIBRARY=foo’.  This tells the
     corresponding find module to populate the ‘Foo_LIBRARIES’ with just
     ‘foo’ to ask the linker to search for the library instead of
     hard-coding a path.

   * Or, after installing the package content but before creating the
     package installation binary for redistribution, manually replace
     the absolute paths with placeholders for substitution by the
     installation tool when the package is installed.

16.5 Package Registry
=====================

CMake provides two central locations to register packages that have been
built or installed anywhere on a system:

   * User Package Registry.

   * System Package Registry.

The registries are especially useful to help projects find packages in
non-standard install locations or directly in their own build trees.  A
project may populate either the user or system registry (using its own
means, see below) to refer to its location.  In either case the package
should store at the registered location a Package Configuration File.
(‘<PackageName>Config.cmake’) and optionally a Package Version File.
(‘<PackageName>ConfigVersion.cmake’).

The find_package() command searches the two package
registries as two of the search steps specified in its documentation.
If it has sufficient permissions it also removes stale package registry
entries that refer to directories that do not exist or do not contain a
matching package configuration file.

16.5.1 User Package Registry
----------------------------

The User Package Registry is stored in a per-user location.  The
export(PACKAGE) command may be used to register a project build
tree in the user package registry.  CMake currently provides no
interface to add install trees to the user package registry.  Installers
must be manually taught to register their packages if desired.

On Windows the user package registry is stored in the Windows registry
under a key in ‘HKEY_CURRENT_USER’.

A ‘<PackageName>’ may appear under registry key:

     HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>

as a ‘REG_SZ’ value, with arbitrary name, that specifies the directory
containing the package configuration file.

On UNIX platforms the user package registry is stored in the user home
directory under ‘~/.cmake/packages’.  A ‘<PackageName>’ may appear under
the directory:

     ~/.cmake/packages/<PackageName>

as a file, with arbitrary name, whose content specifies the directory
containing the package configuration file.

16.5.2 System Package Registry
------------------------------

The System Package Registry is stored in a system-wide location.  CMake
currently provides no interface to add to the system package registry.
Installers must be manually taught to register their packages if
desired.

On Windows the system package registry is stored in the Windows registry
under a key in ‘HKEY_LOCAL_MACHINE’.  A ‘<PackageName>’ may appear under
registry key:

     HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>

as a ‘REG_SZ’ value, with arbitrary name, that specifies the directory
containing the package configuration file.

There is no system package registry on non-Windows platforms.

16.5.3 Disabling the Package Registry
-------------------------------------

In some cases using the Package Registries is not desirable.  CMake
allows one to disable them using the following variables:

   * The export(PACKAGE) command does not populate the user
     package registry when CMP0090 is set to ‘NEW’ unless
     the CMAKE_EXPORT_PACKAGE_REGISTRY variable explicitly
     enables it.  When CMP0090 is `not' set to ‘NEW’ then
     export(PACKAGE) populates the user package registry
     unless the CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable
     explicitly disables it.

   * CMAKE_FIND_USE_PACKAGE_REGISTRY disables the User
     Package Registry in all the find_package() calls when
     set to ‘FALSE’.

   * Deprecated CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.
     disables the User Package Registry in all the find_package()
     calls when set to ‘TRUE’.  This variable is ignored when
     CMAKE_FIND_USE_PACKAGE_REGISTRY has been set.

   * CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY disables
     the System Package Registry in all the find_package().
     calls.

16.5.4 Package Registry Example
-------------------------------

A simple convention for naming package registry entries is to use
content hashes.  They are deterministic and unlikely to collide ( see
export(PACKAGE) uses this approach).  The name of an entry
referencing a specific directory is simply the content hash of the
directory path itself.

If a project arranges for package registry entries to exist, such as:

     > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
     HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
      45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
      7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build

or:

     $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
     /home/me/work/lib/cmake/MyPackage
     $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
     /home/me/work/MyPackage-build

then the ‘CMakeLists.txt’ code:

     find_package(MyPackage)

will search the registered locations for package configuration files
(‘MyPackageConfig.cmake’).  The search order among package registry
entries for a single package is unspecified and the entry names (hashes
in this example) have no meaning.  Registered locations may contain
package version files (‘MyPackageConfigVersion.cmake’) to tell
find_package() whether a specific location is suitable for the
version requested.

16.5.5 Package Registry Ownership
---------------------------------

Package registry entries are individually owned by the project
installations that they reference.  A package installer is responsible
for adding its own entry and the corresponding uninstaller is
responsible for removing it.

The export(PACKAGE) command populates the user package
registry with the location of a project build tree.  Build trees tend to
be deleted by developers and have no “uninstall” event that could
trigger removal of their entries.  In order to keep the registries clean
the find_package() command automatically removes stale
entries it encounters if it has sufficient permissions.  CMake provides
no interface to remove an entry referencing an existing build tree once
export(PACKAGE) has been invoked.  However, if the project
removes its package configuration file from the build tree then the
entry referencing the location will be considered stale.

17.1 Introduction
=================

Policies in CMake are used to preserve backward compatible behavior
across multiple releases.  When a new policy is introduced, newer CMake
versions will begin to warn about the backward compatible behavior.  It
is possible to disable the warning by explicitly requesting the OLD, or
backward compatible behavior using the cmake_policy().
command.  It is also possible to request ‘NEW’, or non-backward
compatible behavior for a policy, also avoiding the warning.  Each
policy can also be set to either ‘NEW’ or ‘OLD’ behavior explicitly on
the command line with the CMAKE_POLICY_DEFAULT_CMP<NNNN>.
variable.

A policy is a deprecation mechanism and not a reliable feature toggle.
A policy should almost never be set to ‘OLD’, except to silence warnings
in an otherwise frozen or stable codebase, or temporarily as part of a
larger migration path.  The ‘OLD’ behavior of each policy is undesirable
and will be replaced with an error condition in a future release.

The cmake_minimum_required() command does more than report
an error if a too-old version of CMake is used to build a project.  It
also sets all policies introduced in that CMake version or earlier to
‘NEW’ behavior.  To manage policies without increasing the minimum
required CMake version, the if(POLICY) command may be used:

     if(POLICY CMP0990)
       cmake_policy(SET CMP0990 NEW)
     endif()

This has the effect of using the ‘NEW’ behavior with newer CMake
releases which users may be using and not issuing a compatibility
warning.

The setting of a policy is confined in some cases to not propagate to
the parent scope.  For example, if the files read by the
include() command or the find_package() command contain
a use of cmake_policy(), that policy setting will not affect
the caller by default.  Both commands accept an optional
‘NO_POLICY_SCOPE’ keyword to control this behavior.

The CMAKE_MINIMUM_REQUIRED_VERSION variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.

17.2 Policies Introduced by CMake 3.19
======================================

17.2.1 CMP0114
--------------

New in version 3.19.

ExternalProject step targets fully adopt their steps.

The ExternalProject_Add(). ‘STEP_TARGETS’ option, and the
ExternalProject_Add_StepTargets() function, can be used to
create build targets for individual steps of an external project.

In CMake 3.18 and below, step targets have some limitations:

   * Step targets always depend on targets named by the
     ExternalProject_Add(). ‘DEPENDS’ option even though not all
     steps need them.  In order to allow step targets to be created
     without those dependencies, the ExternalProject_Add().
     ‘INDEPENDENT_STEP_TARGETS’ option or the
     ExternalProject_Add_StepTargets(). ‘NO_DEPENDS’ option may be
     used.  However, adding such “independent” step targets makes sense
     only for specific steps such as ‘download’, ‘update’, and ‘patch’
     because they do not need any of the external project’s build
     dependencies.  Furthermore, it does not make sense to create
     independent step targets for steps that depend on non-independent
     steps.  Such rules are not enforced, and projects that do not
     follow them can generate build systems with confusing and
     generator-specific behavior.

   * Step targets hold copies of the custom commands implementing their
     steps that are separate from the copies in the primary target
     created by ExternalProject_Add(), and the primary target
     does not depend on the step targets.  In parallel builds that drive
     the primary target and step targets concurrently, multiple copies
     of the steps’ commands may run concurrently and race each other.

     Also, prior to policy CMP0113, the step targets
     generated by Makefile Generators also contain all the
     custom commands on which their step depends.  This can lead to
     repeated execution of those steps even in serial builds.

In CMake 3.19 and above, the ExternalProject module prefers
a revised design to address these problems:

   * Each step is classified as “independent” if it does not depend on
     other targets named by the ExternalProject_Add().
     ‘DEPENDS’.  The predefined steps are automatically classified by
     default:

        * The ‘download’, ‘update’, and ‘patch’ steps are independent.

        * The ‘configure’, ‘build’, ‘test’, and ‘install’ steps are not.

     For custom steps, the ExternalProject_Add_Step().
     command provides an ‘INDEPENDENT’ option to mark them as
     independent.  It is an error to mark a step as independent if it
     depends on other steps that are not.  Note that this use of the
     term “independent” refers only to independence from external
     targets and is orthogonal to a step’s dependencies on other steps.

   * Step targets created by the ExternalProject_Add().
     ‘STEP_TARGETS’ option or the ExternalProject_Add_Step().
     function are now independent if and only if their steps are marked
     as independent.  The ExternalProject_Add().
     ‘INDEPENDENT_STEP_TARGETS’ option and
     ExternalProject_Add_StepTargets(). ‘NO_DEPENDS’ option are no
     longer allowed.

   * Step targets, when created, are fully responsible for holding the
     custom commands implementing their steps.  The primary target
     created by ExternalProject_Add() depends on the step
     targets, and the step targets depend on each other.  The
     target-level dependencies match the file-level dependencies used by
     the custom commands for each step.

     When the ExternalProject_Add(). ‘UPDATE_DISCONNECTED’ or
     ‘TEST_EXCLUDE_FROM_MAIN’ option is used, or the
     ExternalProject_Add_Step(). ‘EXCLUDE_FROM_MAIN’ option is used
     for a custom step, some step targets may be created automatically.
     These are needed to hold the steps commonly depended upon by the
     primary target and the disconnected step targets.

Policy ‘CMP0114’ provides compatibility for projects that have not been
updated to expect the new behavior.  The ‘OLD’ behavior for this policy
is to use the above-documented behavior from 3.18 and below.  The ‘NEW’
behavior for this policy is to use the above-documented behavior
preferred by 3.19 and above.

This policy was introduced in CMake version 3.19.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

17.2.2 CMP0113
--------------

New in version 3.19.

Makefile Generators do not repeat custom commands from target
dependencies.

Consider a chain of custom commands split across two dependent targets:

     add_custom_command(OUTPUT output-not-created
       COMMAND ... DEPENDS ...)
     set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1)
     add_custom_command(OUTPUT output-created
       COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created)
     add_custom_target(first DEPENDS output-not-created)
     add_custom_target(second DEPENDS output-created)
     add_dependencies(second first)

In CMake 3.18 and lower, the Makefile generators put a copy of both
custom commands in the Makefile for target ‘second’ even though its
dependency on target ‘first’ ensures that the first custom command runs
before the second.  Running ‘make second’ would cause the first custom
command to run once in the ‘first’ target and then again in the ‘second’
target.

CMake 3.19 and above prefer to not duplicate custom commands in a target
that are already generated in other targets on which the target depends
(directly or indirectly).  This policy provides compatibility for
projects that have not been updated to expect the new behavior.  In
particular, projects that relied on the duplicate execution or that did
not properly set the SYMBOLIC source file property may be
affected.

The ‘OLD’ behavior for this policy is to duplicate custom commands in
dependent targets.  The ‘NEW’ behavior of this policy is to not
duplicate custom commands in dependent targets.

This policy was introduced in CMake version 3.19.  Unlike many policies,
CMake version 3.19.2 does `not' warn when this policy is not set and
simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.2.3 CMP0112
--------------

New in version 3.19.

Target file component generator expressions do not add target
dependencies.

The following target-based generator expressions that query for
directory or file name components no longer add a dependency on the
evaluated target.

        - ‘TARGET_FILE_NAME’

        - ‘TARGET_FILE_DIR’

        - ‘TARGET_LINKER_FILE_BASE_NAME’

        - ‘TARGET_LINKER_FILE_NAME’

        - ‘TARGET_LINKER_FILE_DIR’

        - ‘TARGET_SONAME_FILE_NAME’

        - ‘TARGET_SONAME_FILE_DIR’

        - ‘TARGET_PDB_FILE_NAME’

        - ‘TARGET_PDB_FILE_DIR’

        - ‘TARGET_BUNDLE_DIR’

        - ‘TARGET_BUNDLE_CONTENT_DIR’

In CMake 3.18 and lower a dependency on the evaluated target of the
above generator expressions would always be added.  CMake 3.19 and above
prefer to not add this dependency.  This policy provides compatibility
for projects that have not been updated to expect the new behavior.

The ‘OLD’ behavior for this policy is to add a dependency on the
evaluated target for the above generator expressions.  The ‘NEW’
behavior of this policy is to not add a dependency on the evaluated
target for the above generator expressions.

This policy was introduced in CMake version 3.19.  Unlike many policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0112 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.2.4 CMP0111
--------------

New in version 3.19.

An imported target missing its location property fails during
generation.

Imported Targets for library files and executables require
that their location on disk is specified in a target property such as
IMPORTED_LOCATION, IMPORTED_IMPLIB, or a
per-configuration equivalent.  If a needed location property is not set,
CMake 3.18 and below generate the string ‘<TARGET_NAME>-NOTFOUND’ in its
place, which results in failures of the corresponding rules at build
time.  CMake 3.19 and above prefer instead to raise an error during
generation.  This policy provides compatibility for projects that have
not been updated to expect the new behavior.

The ‘OLD’ behavior of this policy is to generate the location of an
imported unknown, static or shared library target as
‘<TARGET_NAME>-NOTFOUND’ if not set.  The ‘NEW’ behavior is to raise an
error.

This policy was introduced in CMake version 3.19.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.2.5 CMP0110
--------------

New in version 3.19.

add_test() supports arbitrary characters in test names.

add_test() can now (officially) create tests with whitespace
and other special characters in its name.  Before CMake version 3.19
that was not allowed, however, it was possible to work around this
limitation by explicitly putting escaped quotes arount the test’s name
in the ‘add_test’ command.

Although never officially supported several projects in the wild found
and implemented this workaround.  However, the new change which
officially allows the ‘add_test’ command to support whitespace and other
special characters in test names now breaks that workaround.  In order
for these projects to work smoothly with newer CMake versions, this
policy was introduced.

The ‘OLD’ behavior of this policy is to still prevent ‘add_test’ from
handling whitespace and special characters properly (if not using the
mentioned workaround).  The ‘NEW’ behavior on the other hand allows
names with whitespace and special characters for tests created by
‘add_test’.

This policy was introduced in CMake version 3.19.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

17.2.6 CMP0109
--------------

New in version 3.19.

find_program() requires permission to execute but not to
read.

In CMake 3.18 and below, the find_program() command on UNIX
would find files that are readable without requiring execute permission,
and would not find files that are executable without read permission.
In CMake 3.19 and above, ‘find_program’ now prefers to require execute
permission but not read permission.  This policy provides compatibility
with projects that have not been updated to expect the new behavior.

The ‘OLD’ behavior for this policy is for ‘find_program’ to require read
permission but not execute permission.  The ‘NEW’ behavior for this
policy is for ‘find_program’ to require execute permission but not read
permission.

This policy was introduced in CMake version 3.19.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3 Policies Introduced by CMake 3.18
======================================

17.3.1 CMP0108
--------------

New in version 3.18.

A target is not allowed to link to itself even through an ‘ALIAS’
target.

In CMake 3.17 and below, a target can link to a target aliased to
itself.

The ‘OLD’ behavior for this policy is to allow a target to link to a
target aliased to itself.

The ‘NEW’ behavior of this policy is to prevent a target to link to
itself through an ‘ALIAS’ target.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3.2 CMP0107
--------------

New in version 3.18.

It is not allowed to create an ‘ALIAS’ target with the same name as an
another target.

In CMake 3.17 and below, an ‘ALIAS’ target can overwrite silently an
existing target with the same name.

The ‘OLD’ behavior for this policy is to allow target overwrite.

The ‘NEW’ behavior of this policy is to prevent target overwriting.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3.3 CMP0106
--------------

New in version 3.18.

The Documentation module is removed.

The Documentation was added as a support mechanism for the
VTK project and was tuned for that project.  Instead of CMake providing
this module with (now old) VTK patterns for cache variables and required
packages, the module is now deprecated by CMake itself.

The ‘OLD’ behavior of this policy is for Documentation to
add cache variables and find VTK documentation dependent packages.  The
‘NEW’ behavior is to act as an empty module.

This policy was introduced in CMake version 3.18.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3.4 CMP0105
--------------

New in version 3.18.

LINK_OPTIONS and INTERFACE_LINK_OPTIONS target
properties are now used for the device link step.

In CMake 3.17 and below, link options are not used by the device link
step.

The ‘OLD’ behavior for this policy is to ignore the link options.

The ‘NEW’ behavior of this policy is to use the link options during the
device link step.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3.5 CMP0104
--------------

New in version 3.18.

Initialize CMAKE_CUDA_ARCHITECTURES when
CMAKE_CUDA_COMPILER_ID is ‘NVIDIA’.  Raise an error if
CUDA_ARCHITECTURES is empty.

CMAKE_CUDA_ARCHITECTURES introduced in CMake 3.18 is used to
initialize CUDA_ARCHITECTURES, which passes correct code
generation flags to the CUDA compiler.

Previous to this users had to manually specify the code generation
flags.  This policy is for backwards compatibility with manually
specifying code generation flags.

The ‘OLD’ behavior for this policy is to not initialize
CMAKE_CUDA_ARCHITECTURES when CMAKE_CUDA_COMPILER_ID.
is ‘NVIDIA’.  Empty CUDA_ARCHITECTURES is allowed.

The ‘NEW’ behavior of this policy is to initialize
CMAKE_CUDA_ARCHITECTURES when CMAKE_CUDA_COMPILER_ID.
is ‘NVIDIA’ and raise an error if CUDA_ARCHITECTURES is
empty during generation.

If CUDA_ARCHITECTURES is set to a false value no
architectures flags are passed to the compiler.  This is intended to
support packagers and the rare cases where full control over the passed
flags is required.

This policy was introduced in CMake version 3.18.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.3.5.1 Examples
.................

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72)

Generates code for real and virtual architectures ‘30’, ‘50’ and ‘72’.

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)

Generates code for real architecture ‘70’ and virtual architecture ‘72’.

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)

CMake will not pass any architecture flags to the compiler.

17.3.6 CMP0103
--------------

New in version 3.18.

Multiple calls to export() command with same ‘FILE’ without
‘APPEND’ is no longer allowed.

In CMake 3.17 and below, multiple calls to export() command
with the same ‘FILE’ without ‘APPEND’ are accepted silently but only the
last occurrence is taken into account during the generation.

The ‘OLD’ behavior for this policy is to ignore the multiple occurrences of

     export() command except the last one.

The ‘NEW’ behavior of this policy is to raise an error on second call to
export() command with same ‘FILE’ without ‘APPEND’.

This policy was introduced in CMake version 3.18.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.4 Policies Introduced by CMake 3.17
======================================

17.4.1 CMP0102
--------------

New in version 3.17.

The mark_as_advanced() command no longer creates a cache
entry if one does not already exist.

In CMake 3.16 and below, if a variable was not defined at all or just
defined locally, the mark_as_advanced() command would create
a new cache entry with an ‘UNINITIALIZED’ type and no value.  When a
find_path(). (or other similar ‘find_’ command) would next
run, it would find this undefined cache entry and set it up with an
empty string value.  This process would end up deleting the local
variable in the process (due to the way the cache works), effectively
clearing any stored ‘find_’ results that were only available in the
local scope.

The ‘OLD’ behavior for this policy is to create the empty cache
definition.  The ‘NEW’ behavior of this policy is to ignore variables
which do not already exist in the cache.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.4.2 CMP0101
--------------

New in version 3.17.

target_compile_options() now honors ‘BEFORE’ keyword in all
scopes.

In CMake 3.16 and below the target_compile_options() ignores
the ‘BEFORE’ keyword in private scope.  CMake 3.17 and later honors
‘BEFORE’ keyword in all scopes.  This policy provides compatibility for
projects that have not been updated to expect the new behavior.

The ‘OLD’ behavior for this policy is to not honor ‘BEFORE’ keyword in
private scope.  The ‘NEW’ behavior of this policy is to honor ‘BEFORE’
keyword in all scopes.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.4.3 CMP0100
--------------

New in version 3.17.

Let AUTOMOC and AUTOUIC process header files
that end with a ‘.hh’ extension.

Since version 3.17, CMake processes header files that end with a ‘.hh’
extension in AUTOMOC and AUTOUIC.  In earlier
CMake versions, these header files were ignored by AUTOMOC.
and AUTOUIC.

This policy affects how header files that end with a ‘.hh’ extension get
treated in AUTOMOC and AUTOUIC.

The ‘OLD’ behavior for this policy is to ignore ‘.hh’ header files in
AUTOMOC and AUTOUIC.

The ‘NEW’ behavior for this policy is to process ‘.hh’ header files in
AUTOMOC and AUTOUIC just like other header
files.

     Note: To silence the ‘CMP0100’ warning source files can be excluded
     from AUTOMOC and AUTOUIC processing by
     setting the source file properties SKIP_AUTOMOC,
     SKIP_AUTOUIC or SKIP_AUTOGEN.

          # Source skip example:
          set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON)
          set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON)
          set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON)

This policy was introduced in CMake version 3.17.0.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.4.4 CMP0099
--------------

New in version 3.17.

Target link properties INTERFACE_LINK_OPTIONS,
INTERFACE_LINK_DIRECTORIES and INTERFACE_LINK_DEPENDS.
are now transitive over private dependencies of static libraries.

In CMake 3.16 and below the interface link properties attached to
libraries are not propagated for private dependencies of static
libraries.  Only the libraries themselves are propagated to link the
dependent binary.  CMake 3.17 and later prefer to propagate all
interface link properties.  This policy provides compatibility for
projects that have not been updated to expect the new behavior.

The ‘OLD’ behavior for this policy is to not propagate interface link
properties.  The ‘NEW’ behavior of this policy is to propagate interface
link properties.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.4.5 CMP0098
--------------

New in version 3.17.

FindFLEX runs ‘flex’ in directory
CMAKE_CURRENT_BINARY_DIR when executing.

The module provides a ‘FLEX_TARGET’ macro which generates FLEX output.
In CMake 3.16 and below the macro would generate a custom command that
runs ‘flex’ in the current source directory.  CMake 3.17 and later
prefer to run it in the build directory and use
CMAKE_CURRENT_BINARY_DIR as the ‘WORKING_DIRECTORY’ of its
add_custom_command() invocation.  This ensures that any implicitly
generated file is written relative to the build tree rather than the
source tree, unless the generated file is provided as absolute path.

This policy provides compatibility for projects that have not been
updated to expect the new behavior.

The ‘OLD’ behavior for this policy is for ‘FLEX_TARGET’ to use the
current source directory for the ‘WORKING_DIRECTORY’ and where to
generate implicit files.  The ‘NEW’ behavior of this policy is to use
the current binary directory for the ‘WORKING_DIRECTORY’ relative to
which implicit files are generated unless provided as absolute path.

This policy was introduced in CMake version 3.17.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.5 Policies Introduced by CMake 3.16
======================================

17.5.1 CMP0097
--------------

New in version 3.16.

ExternalProject_Add() with ‘GIT_SUBMODULES ""’ initializes
no submodules.

The module provides a ‘GIT_SUBMODULES’ option which controls what
submodules to initialize and update.  Starting with CMake 3.16,
explicitly setting ‘GIT_SUBMODULES’ to an empty string means no
submodules will be initialized or updated.

This policy provides compatibility for projects that have not been
updated to expect the new behavior.

The ‘OLD’ behavior for this policy is for ‘GIT_SUBMODULES’ when set to
an empty string to initialize and update all git submodules.  The ‘NEW’
behavior for this policy is for ‘GIT_SUBMODULES’ when set to an empty
string to initialize and update no git submodules.

This policy was introduced in CMake version 3.16.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike most policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

17.5.2 CMP0096
--------------

New in version 3.16.

The project() command preserves leading zeros in version
components.

When a ‘VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]’ argument is
given to the project() command, it stores the version string
in the ‘PROJECT_VERSION’ variable and stores individual integer version
components in ‘PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK}’ variables (see
policy CMP0048).  CMake 3.15 and below dropped leading zeros
from each component.  CMake 3.16 and higher prefer to preserve leading
zeros.  This policy provides compatibility for projects that have not
been updated to expect the new behavior.

The ‘OLD’ behavior of this policy drops leading zeros in all components,
e.g.  such that version ‘1.07.06’ becomes ‘1.7.6’.  The ‘NEW’ behavior
of this policy preserves the leading zeros in all components, such that
version ‘1.07.06’ remains unchanged.

This policy was introduced in CMake version 3.16.  Unlike many policies,
CMake version 3.19.2 does `not' warn when this policy is not set and
simply uses the ‘OLD’ behavior.  Use the cmake_policy().
command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.5.3 CMP0095
--------------

New in version 3.16.

‘RPATH’ entries are properly escaped in the intermediary CMake install
script.

In CMake 3.15 and earlier, ‘RPATH’ entries set via
CMAKE_INSTALL_RPATH or via INSTALL_RPATH have not been
escaped before being inserted into the ‘cmake_install.cmake’ script.
Dynamic linkers on ELF-based systems (e.g.  Linux and FreeBSD) allow
certain keywords in ‘RPATH’ entries, such as ‘${ORIGIN}’ (More details
are available in the ‘ld.so’ man pages on those systems).  The syntax of
these keywords can match CMake’s variable syntax.  In order to not be
substituted (usually to an empty string) already by the intermediary
‘cmake_install.cmake’ script, the user had to double-escape such ‘RPATH’
keywords, e.g.  ‘set(CMAKE_INSTALL_RPATH "\\\${ORIGIN}/../lib")’.  Since
the intermediary ‘cmake_install.cmake’ script is an implementation
detail of CMake, CMake 3.16 and later will make sure ‘RPATH’ entries are
inserted literally by escaping any coincidental CMake syntax.

The ‘OLD’ behavior of this policy is to not escape ‘RPATH’ entries in
the intermediary ‘cmake_install.cmake’ script.  The ‘NEW’ behavior is to
properly escape coincidental CMake syntax in ‘RPATH’ entries when
generating the intermediary ‘cmake_install.cmake’ script.

This policy was introduced in CMake version 3.16.  CMake version 3.19.2
warns when the policy is not set and detected usage of CMake-like syntax
and uses ‘OLD’ behavior.  Use the cmake_policy() command to
set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6 Policies Introduced by CMake 3.15
======================================

17.6.1 CMP0094
--------------

New in version 3.15.

Modules FindPython3, FindPython2 and
FindPython use ‘LOCATION’ for lookup strategy.

Starting with CMake 3.15, Modules FindPython3,
FindPython2 and FindPython set value ‘LOCATION’ for,
respectively, variables ‘Python3_FIND_STRATEGY’, ‘Python2_FIND_STRATEGY’
and ‘Python_FIND_STRATEGY’.  This policy provides compatibility with
projects that expect the legacy behavior.

The ‘OLD’ behavior for this policy set value ‘VERSION’ for variables
‘Python3_FIND_STRATEGY’, ‘Python2_FIND_STRATEGY’ and
‘Python_FIND_STRATEGY’.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses the ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6.2 CMP0093
--------------

New in version 3.15.

FindBoost reports ‘Boost_VERSION’ in ‘x.y.z’ format.

In CMake 3.14 and below the module would report the Boost version number
as specified in the preprocessor definition ‘BOOST_VERSION’ in the
‘boost/version.hpp’ file.  In CMake 3.15 and later it is preferred that
the reported version number matches the ‘x.y.z’ format reported by the
CMake package shipped with Boost ‘1.70.0’ and later.  The macro value is
still reported in the ‘Boost_VERSION_MACRO’ variable.

The ‘OLD’ behavior for this policy is for FindBoost to
report ‘Boost_VERSION’ as specified in the preprocessor definition
‘BOOST_VERSION’ in ‘boost/version.hpp’.  The ‘NEW’ behavior for this
policy is for FindBoost to report ‘Boost_VERSION’ in ‘x.y.z’
format.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses the ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6.3 CMP0092
--------------

New in version 3.15.

MSVC warning flags are not in CMAKE_<LANG>_FLAGS by default.

When using MSVC-like compilers in CMake 3.14 and below, warning flags
like ‘/W3’ are added to CMAKE_<LANG>_FLAGS by default.  This
is problematic for projects that want to choose a different warning
level programmatically.  In particular, it requires string editing of
the CMAKE_<LANG>_FLAGS variables with knowledge of the CMake
builtin defaults so they can be replaced.

CMake 3.15 and above prefer to leave out warning flags from the value of
CMAKE_<LANG>_FLAGS by default.

This policy provides compatibility with projects that have not been
updated to expect the lack of warning flags.  The policy setting takes
effect as of the first project() or enable_language()
command that initializes CMAKE_<LANG>_FLAGS for a given
language ‘<LANG>’.

     Note: Once the policy has taken effect at the top of a project for
     a given language, that choice must be used throughout the tree for
     that language.  In projects that have nested projects in
     subdirectories, be sure to convert everything together.

The ‘OLD’ behavior for this policy is to place MSVC warning flags in the
default CMAKE_<LANG>_FLAGS cache entries.  The ‘NEW’
behavior for this policy is to `not' place MSVC warning flags in the
default cache entries.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6.4 CMP0091
--------------

New in version 3.15.

MSVC runtime library flags are selected by an abstraction.

Compilers targeting the MSVC ABI have flags to select the MSVC runtime
library.  Runtime library selection typically varies with build
configuration because there is a separate runtime library for Debug
builds.

In CMake 3.14 and below, MSVC runtime library selection flags are added
to the default CMAKE_<LANG>_FLAGS_<CONFIG> cache entries by
CMake automatically.  This allows users to edit their cache entries to
adjust the flags.  However, the presence of such default flags is
problematic for projects that want to choose a different runtime library
programmatically.  In particular, it requires string editing of the
CMAKE_<LANG>_FLAGS_<CONFIG> variables with knowledge of the
CMake builtin defaults so they can be replaced.

CMake 3.15 and above prefer to leave the MSVC runtime library selection
flags out of the default CMAKE_<LANG>_FLAGS_<CONFIG> values
and instead offer a first-class abstraction.  The
CMAKE_MSVC_RUNTIME_LIBRARY variable and
MSVC_RUNTIME_LIBRARY target property may be set to select the MSVC
runtime library.  If they are not set then CMake uses the default value
‘MultiThreaded$<$<CONFIG:Debug>:Debug>DLL’ which is equivalent to the
original flags.

This policy provides compatibility with projects that have not been
updated to be aware of the abstraction.  The policy setting takes effect
as of the first project() or enable_language().
command that enables a language whose compiler targets the MSVC ABI.

     Note: Once the policy has taken effect at the top of a project,
     that choice must be used throughout the tree.  In projects that
     have nested projects in subdirectories, be sure to convert
     everything together.

The ‘OLD’ behavior for this policy is to place MSVC runtime library
flags in the default CMAKE_<LANG>_FLAGS_<CONFIG> cache
entries and ignore the CMAKE_MSVC_RUNTIME_LIBRARY.
abstraction.  The ‘NEW’ behavior for this policy is to `not' place MSVC
runtime library flags in the default cache entries and use the
abstraction instead.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike many policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6.5 CMP0090
--------------

New in version 3.15.

export(PACKAGE) does not populate package registry by
default.

In CMake 3.14 and below the export(PACKAGE) command
populated the user package registry by default and users needed to set
the CMAKE_EXPORT_NO_PACKAGE_REGISTRY to disable it, e.g.  in
automated build and packaging environments.  Since the user package
registry is stored outside the build tree, this side effect should not
be enabled by default.  Therefore CMake 3.15 and above prefer that
export(PACKAGE) does nothing unless an explicit
CMAKE_EXPORT_PACKAGE_REGISTRY variable is set to enable it.  This
policy provides compatibility with projects that have not been updated.

The ‘OLD’ behavior for this policy is for export(PACKAGE).
command to populate the user package registry unless
CMAKE_EXPORT_NO_PACKAGE_REGISTRY is enabled.  The ‘NEW’ behavior
is for export(PACKAGE) command to do nothing unless the
CMAKE_EXPORT_PACKAGE_REGISTRY is enabled.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike most policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.6.6 CMP0089
--------------

New in version 3.15.

Compiler id for IBM Clang-based XL compilers is now ‘XLClang’.

CMake 3.15 and above recognize that IBM’s Clang-based XL compilers that
define ‘__ibmxl__’ are a new front-end distinct from ‘xlc’ with a
different command line and set of capabilities.  CMake now prefers to
present this to projects by setting the CMAKE_<LANG>_COMPILER_ID
variable to ‘XLClang’ instead of ‘XL’.  However, existing projects
may assume the compiler id for Clang-based XL is just ‘XL’ as it was in
CMake versions prior to 3.15.  Therefore this policy determines for
Clang-based XL compilers which compiler id to report in the
CMAKE_<LANG>_COMPILER_ID variable after language ‘<LANG>’ is
enabled by the project() or enable_language().
command.  The policy must be set prior to the invocation of either
command.

The ‘OLD’ behavior for this policy is to use compiler id ‘XL’.  The
‘NEW’ behavior for this policy is to use compiler id ‘XLClang’.

This policy was introduced in CMake version 3.15.  Use the
cmake_policy() command to set this policy to ‘OLD’ or ‘NEW’
explicitly.  Unlike most policies, CMake version 3.19.2 does `not' warn
by default when this policy is not set and simply uses ‘OLD’ behavior.
See documentation of the CMAKE_POLICY_WARNING_CMP0089.
variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7 Policies Introduced by CMake 3.14
======================================

17.7.1 CMP0088
--------------

New in version 3.14.

FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR.
when executing.

The module provides a ‘BISON_TARGET’ macro which generates BISON output.
In CMake 3.13 and below the macro would generate a custom command that
runs ‘bison’ in the source directory.  CMake 3.14 and later prefer to
run it in the build directory and use CMAKE_CURRENT_BINARY_DIR
as the ‘WORKING_DIRECTORY’ of its add_custom_command().
invocation.  This ensures that any implicitly generated file is written
to the build tree rather than the source.

This policy provides compatibility for projects that have not been
updated to expect the new behavior.

The ‘OLD’ behavior for this policy is for ‘BISON_TARGET’ to use the
current source directory for the ‘WORKING_DIRECTORY’ and where to
generate implicit files.  The ‘NEW’ behavior of this policy is to use
the current binary directory for the ‘WORKING_DIRECTORY’ and where to
generate implicit files.

This policy was introduced in CMake version 3.14.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike most policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.2 CMP0087
--------------

New in version 3.14.

install(CODE) and install(SCRIPT) support
generator expressions.

In CMake 3.13 and earlier, see install(CODE) and
install(SCRIPT) did not evaluate generator expressions.  CMake
3.14 and later will evaluate generator expressions for
install(CODE) and install(SCRIPT).

The ‘OLD’ behavior of this policy is for install(CODE) and
install(SCRIPT) to not evaluate generator expressions.  The
‘NEW’ behavior is to evaluate generator expressions for
install(CODE) and install(SCRIPT).

Note that it is the value of this policy setting at the end of the
directory scope that is important, not its setting at the time of the
call to install(CODE) or install(SCRIPT).  This
has implications for calling these commands from places that have their
own policy scope but not their own directory scope (e.g.  from files
brought in via include() rather than
add_subdirectory()).

This policy was introduced in CMake version 3.14.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.3 CMP0086
--------------

New in version 3.14.

UseSWIG honors ‘SWIG_MODULE_NAME’ via ‘-module’ flag.

Starting with CMake 3.14, see UseSWIG passes option ‘-module
<module_name>’ to ‘SWIG’ compiler if the file property
‘SWIG_MODULE_NAME’ is specified.  This policy provides compatibility
with projects that expect the legacy behavior.

The ‘OLD’ behavior for this policy is to never pass ‘-module’ option.
The ‘NEW’ behavior is to pass ‘-module’ option to ‘SWIG’ compiler if
‘SWIG_MODULE_NAME’ is specified.

This policy was introduced in CMake version 3.14.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.4 CMP0085
--------------

New in version 3.14.

‘$<IN_LIST:...>’ handles empty list items.

In CMake 3.13 and lower, the ‘$<IN_LIST:...>’ generator expression
always returned ‘0’ if the first argument was empty, even if the list
contained an empty item.  This behavior is inconsistent with the
‘IN_LIST’ behavior of if(), which this generator expression
is meant to emulate.  CMake 3.14 and later handles this case correctly.

The ‘OLD’ behavior of this policy is for ‘$<IN_LIST:...>’ to always
return ‘0’ if the first argument is empty.  The ‘NEW’ behavior is to
return ‘1’ if the first argument is empty and the list contains an empty
item.

This policy was introduced in CMake version 3.14.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.5 CMP0084
--------------

New in version 3.14.

The FindQt module does not exist for find_package().

The existence of FindQt means that for Qt upstream to
provide package config files that can be found by ‘find_package(Qt)’,
the consuming project has to explicitly specify ‘find_package(Qt
CONFIG)’.  Removing this module gives Qt a path forward for exporting
its own config files which can easily be found by consuming projects.

This policy pretends that CMake’s internal FindQt module
does not exist for find_package().  If a project really wants
to use Qt 3 or 4, it can call ‘find_package(Qt[34])’, ‘include(FindQt)’,
or add FindQt to their CMAKE_MODULE_PATH.

The ‘OLD’ behavior of this policy is for FindQt to exist for
find_package().  The ‘NEW’ behavior is to pretend that it
doesn’t exist for find_package().

This policy was introduced in CMake version 3.14.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.6 CMP0083
--------------

New in version 3.14.

To control generation of Position Independent Executable (‘PIE’) or not,
some flags are required at link time.

CMake 3.13 and lower did not add these link flags when
POSITION_INDEPENDENT_CODE is set.

The ‘OLD’ behavior for this policy is to not manage ‘PIE’ link flags.
The ‘NEW’ behavior is to add link flags if
POSITION_INDEPENDENT_CODE is set:

   * Set to ‘TRUE’: flags to produce a position independent executable
     are passed to the linker step.  For example ‘-pie’ for ‘GCC’.

   * Set to ‘FALSE’: flags not to produce a position independent
     executable are passed to the linker step.  For example ‘-no-pie’
     for ‘GCC’.

   * Not set: no flags are passed to the linker step.

Since a given linker may not support ‘PIE’ flags in all environments in
which it is used, it is the project’s responsibility to use the
CheckPIESupported module to check for support to ensure that the
POSITION_INDEPENDENT_CODE target property for executables
will be honored at link time.

This policy was introduced in CMake version 3.14.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike most policies, CMake version 3.19.2 does not warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: Android platform has a special handling of ‘PIE’ so it is not
     required to use the CheckPIESupported module to ensure
     flags are passed to the linker.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.7.6.1 Examples
.................

Behave like CMake 3.13 and do not apply any ‘PIE’ flags at link stage.

     cmake_minimum_required(VERSION 3.13)
     project(foo)

     # ...

     add_executable(foo ...)
     set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

Use the CheckPIESupported module to detect whether ‘PIE’ is
supported by the current linker and environment.  Apply ‘PIE’ flags only
if the linker supports them.

     cmake_minimum_required(VERSION 3.14) # CMP0083 NEW
     project(foo)

     include(CheckPIESupported)
     check_pie_supported()

     # ...

     add_executable(foo ...)
     set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

17.7.7 CMP0082
--------------

New in version 3.14.

Install rules from add_subdirectory() calls are interleaved
with those in caller.

CMake 3.13 and lower ran the install rules from
add_subdirectory() after all other install rules, even if
add_subdirectory() was called before the other install rules.
CMake 3.14 and above prefer to interleave these
add_subdirectory() install rules with the others so that they are
run in the order they are declared.  This policy provides compatibility
for projects that have not been updated to expect the new behavior.

The ‘OLD’ behavior for this policy is to run the install rules from
add_subdirectory() after the other install rules.  The ‘NEW’
behavior for this policy is to run all install rules in the order they
are declared.

This policy was introduced in CMake version 3.14.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0082 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8 Policies Introduced by CMake 3.13
======================================

17.8.1 CMP0081
--------------

New in version 3.13.

Relative paths not allowed in LINK_DIRECTORIES target
property.

CMake 3.12 and lower allowed the LINK_DIRECTORIES directory
property to contain relative paths.  The base path for such relative
entries is not well defined.  CMake 3.13 and later will issue a
‘FATAL_ERROR’ if the LINK_DIRECTORIES target property (which
is initialized by the LINK_DIRECTORIES directory property)
contains a relative path.

The ‘OLD’ behavior for this policy is not to warn about relative paths
in the LINK_DIRECTORIES target property.  The ‘NEW’ behavior
for this policy is to issue a ‘FATAL_ERROR’ if LINK_DIRECTORIES
contains a relative path.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8.2 CMP0080
--------------

New in version 3.13.

BundleUtilities cannot be included at configure time.

The macros provided by BundleUtilities are intended to be
invoked at install time rather than at configure time, because they
depend on the listed targets already existing at the time they are
invoked.  If they are invoked at configure time, the targets haven’t
been built yet, and the commands will fail.

This policy restricts the inclusion of BundleUtilities to
‘cmake -P’ style scripts and install rules.  Specifically, it looks for
the presence of CMAKE_GENERATOR and throws a fatal error if
it exists.

The ‘OLD’ behavior of this policy is to allow BundleUtilities
to be included at configure time.  The ‘NEW’ behavior of this
policy is to disallow such inclusion.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8.3 CMP0079
--------------

New in version 3.13.

target_link_libraries() allows use with targets in other
directories.

Prior to CMake 3.13 the target_link_libraries() command did
not accept targets not created in the calling directory as its first
argument for calls that update the LINK_LIBRARIES of the
target itself.  It did accidentally accept targets from other
directories on calls that only update the
INTERFACE_LINK_LIBRARIES, but would simply add entries to the
property as if the call were made in the original directory.  Thus link
interface libraries specified this way were always looked up by
generators in the scope of the original target rather than in the scope
that called target_link_libraries().

CMake 3.13 now allows the target_link_libraries() command to
be called from any directory to add link dependencies and link interface
libraries to targets created in other directories.  The entries are
added to LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES
using a special (internal) suffix to tell the generators to look up
the names in the calling scope rather than the scope that created the
target.

This policy provides compatibility with projects that already use
target_link_libraries() with the ‘INTERFACE’ keyword on a target in
another directory to add INTERFACE_LINK_LIBRARIES entries to
be looked up in the target’s directory.  Such projects should be updated
to be aware of the new scoping rules in that case.

The ‘OLD’ behavior of this policy is to disallow
target_link_libraries() calls naming targets from another directory
except in the previously accidentally allowed case of using the
‘INTERFACE’ keyword only.  The ‘NEW’ behavior of this policy is to allow
all such calls but use the new scoping rules.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8.4 CMP0078
--------------

New in version 3.13.

UseSWIG generates standard target names.

Starting with CMake 3.13, see UseSWIG generates now standard
target names.  This policy provides compatibility with projects that
expect the legacy behavior.

The ‘OLD’ behavior for this policy relies on
‘UseSWIG_TARGET_NAME_PREFERENCE’ variable that can be used to specify an
explicit preference.  The value may be one of:

   * ‘LEGACY’: legacy strategy is applied.  Variable
     ‘SWIG_MODULE_<name>_REAL_NAME’ must be used to get real target
     name.  This is the default if not specified.

   * ‘STANDARD’: target name matches specified name.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8.5 CMP0077
--------------

New in version 3.13.

option() honors normal variables.

The option() command is typically used to create a cache
entry to allow users to set the option.  However, there are cases in
which a normal (non-cached) variable of the same name as the option may
be defined by the project prior to calling the option().
command.  For example, a project that embeds another project as a
subdirectory may want to hard-code options of the subproject to build
the way it needs.

For historical reasons in CMake 3.12 and below the option().
command `removes' a normal (non-cached) variable of the same name when:

   * a cache entry of the specified name does not exist at all, or

   * a cache entry of the specified name exists but has not been given a
     type (e.g.  via ‘-D<name>=ON’ on the command line).

In both of these cases (typically on the first run in a new build tree),
the option() command gives the cache entry type ‘BOOL’ and
removes any normal (non-cached) variable of the same name.  In the
remaining case that the cache entry of the specified name already exists
and has a type (typically on later runs in a build tree), the
option() command changes nothing and any normal variable of the
same name remains set.

In CMake 3.13 and above the option() command prefers to do
nothing when a normal variable of the given name already exists.  It
does not create or update a cache entry or remove the normal variable.
The new behavior is consistent between the first and later runs in a
build tree.  This policy provides compatibility with projects that have
not been updated to expect the new behavior.

When the option() command sees a normal variable of the
given name:

   * The ‘OLD’ behavior for this policy is to proceed even when a normal
     variable of the same name exists.  If the cache entry does not
     already exist and have a type then it is created and/or given a
     type and the normal variable is removed.

   * The ‘NEW’ behavior for this policy is to do nothing when a normal
     variable of the same name exists.  The normal variable is not
     removed.  The cache entry is not created or updated and is ignored
     if it exists.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.8.6 CMP0076
--------------

New in version 3.13.

The target_sources() command converts relative paths to
absolute.

In CMake 3.13 and above, the target_sources() command now
converts relative source file paths to absolute paths in the following
cases:

   * Source files are added to the target’s INTERFACE_SOURCES
     property.

   * The target’s SOURCE_DIR property differs from
     CMAKE_CURRENT_SOURCE_DIR.

A path that begins with a generator expression is always left
unmodified.

This policy provides compatibility with projects that have not been
updated to expect this behavior.  The ‘OLD’ behavior for this policy is
to leave all relative source file paths unmodified.  The ‘NEW’ behavior
of this policy is to convert relative paths to absolute according to
above rules.

This policy was introduced in CMake version 3.13.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.9 Policies Introduced by CMake 3.12
======================================

17.9.1 CMP0075
--------------

New in version 3.12.

Include file check macros honor ‘CMAKE_REQUIRED_LIBRARIES’.

In CMake 3.12 and above, the

   * ‘check_include_file’ macro in the CheckIncludeFile.
     module, the

   * ‘check_include_file_cxx’ macro in the CheckIncludeFileCXX
     module, and the

   * ‘check_include_files’ macro in the CheckIncludeFiles.
     module

now prefer to link the check executable to the libraries listed in the
‘CMAKE_REQUIRED_LIBRARIES’ variable.  This policy provides compatibility
with projects that have not been updated to expect this behavior.

The ‘OLD’ behavior for this policy is to ignore
‘CMAKE_REQUIRED_LIBRARIES’ in the include file check macros.  The ‘NEW’
behavior of this policy is to honor ‘CMAKE_REQUIRED_LIBRARIES’ in the
include file check macros.

This policy was introduced in CMake version 3.12.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.9.2 CMP0074
--------------

New in version 3.12.

find_package() uses ‘<PackageName>_ROOT’ variables.

In CMake 3.12 and above the find_package(<PackageName>).
command now searches prefixes specified by the <PackageName>_ROOT.
CMake variable and the <PackageName>_ROOT environment
variable.  Package roots are maintained as a stack so nested calls to
all ‘find_*’ commands inside find modules and config packages also
search the roots as prefixes.  This policy provides compatibility with
projects that have not been updated to avoid using ‘<PackageName>_ROOT’
variables for other purposes.

The ‘OLD’ behavior for this policy is to ignore ‘<PackageName>_ROOT’
variables.  The ‘NEW’ behavior for this policy is to use
‘<PackageName>_ROOT’ variables.

This policy was introduced in CMake version 3.12.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.9.3 CMP0073
--------------

New in version 3.12.

Do not produce legacy ‘_LIB_DEPENDS’ cache entries.

Ancient CMake versions once used ‘<tgt>_LIB_DEPENDS’ cache entries to
propagate library link dependencies.  This has long been done by other
means, leaving the export_library_dependencies() command as
the only user of these values.  That command has long been disallowed by
policy CMP0033, but the ‘<tgt>_LIB_DEPENDS’ cache entries
were left for compatibility with possible non-standard uses by projects.

CMake 3.12 and above now prefer to not produce these cache entries at
all.  This policy provides compatibility with projects that have not
been updated to avoid using them.

The ‘OLD’ behavior for this policy is to set ‘<tgt>_LIB_DEPENDS’ cache
entries.  The ‘NEW’ behavior for this policy is to not set them.

This policy was introduced in CMake version 3.12.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.
Unlike most policies, CMake version 3.19.2 does `not' warn when this
policy is not set and simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.10 Policies Introduced by CMake 3.11
=======================================

17.10.1 CMP0072
---------------

New in version 3.11.

FindOpenGL prefers GLVND by default when available.

The FindOpenGL module provides an ‘OpenGL::GL’ target and an
‘OPENGL_LIBRARIES’ variable for projects to use for legacy GL
interfaces.  When both a legacy GL library (e.g.  ‘libGL.so’) and GLVND
libraries for OpenGL and GLX (e.g.  ‘libOpenGL.so’ and ‘libGLX.so’) are
available, the module must choose between them.  It documents an
‘OpenGL_GL_PREFERENCE’ variable that can be used to specify an explicit
preference.  When no such preference is set, the module must choose a
default preference.

CMake 3.11 and above prefer to choose GLVND libraries.  This policy
provides compatibility with projects that expect the legacy GL library
to be used.

The ‘OLD’ behavior for this policy is to set ‘OpenGL_GL_PREFERENCE’ to
‘LEGACY’.  The ‘NEW’ behavior for this policy is to set
‘OpenGL_GL_PREFERENCE’ to ‘GLVND’.

This policy was introduced in CMake version 3.11.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.11 Policies Introduced by CMake 3.10
=======================================

17.11.1 CMP0071
---------------

New in version 3.10.

Let AUTOMOC and AUTOUIC process GENERATED
files.

Since version 3.10, CMake processes `regular' and GENERATED.
source files in AUTOMOC and AUTOUIC.  In earlier
CMake versions, only `regular' source files were processed.
GENERATED source files were ignored silently.

This policy affects how source files that are GENERATED get
treated in AUTOMOC and AUTOUIC.

The ‘OLD’ behavior for this policy is to ignore GENERATED.
source files in AUTOMOC and AUTOUIC.

The ‘NEW’ behavior for this policy is to process GENERATED.
source files in AUTOMOC and AUTOUIC just like
regular source files.

     Note: To silence the ‘CMP0071’ warning source files can be excluded
     from AUTOMOC and AUTOUIC processing by
     setting the source file properties SKIP_AUTOMOC,
     SKIP_AUTOUIC or SKIP_AUTOGEN.

Source skip example:

     # ...
     set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON)
     set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON)
     set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON)
     # ...

This policy was introduced in CMake version 3.10.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.11.2 CMP0070
---------------

New in version 3.10.

Define file(GENERATE) behavior for relative paths.

CMake 3.10 and newer define that relative paths given to ‘INPUT’ and
‘OUTPUT’ arguments of ‘file(GENERATE)’ are interpreted relative to the
current source and binary directories, respectively.  CMake 3.9 and
lower did not define any behavior for relative paths but did not
diagnose them either and accidentally treated them relative to the
process working directory.  Policy ‘CMP0070’ provides compatibility with
projects that used the old undefined behavior.

This policy affects behavior of relative paths given to
‘file(GENERATE)’.  The ‘OLD’ behavior for this policy is to treat the
paths relative to the working directory of CMake.  The ‘NEW’ behavior
for this policy is to interpret relative paths with respect to the
current source or binary directory of the caller.

This policy was introduced in CMake version 3.10.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.12 Policies Introduced by CMake 3.9
======================================

17.12.1 CMP0069
---------------

New in version 3.9.

INTERPROCEDURAL_OPTIMIZATION is enforced when enabled.

CMake 3.9 and newer prefer to add IPO flags whenever the
INTERPROCEDURAL_OPTIMIZATION target property is enabled and
produce an error if flags are not known to CMake for the current
compiler.  Since a given compiler may not support IPO flags in all
environments in which it is used, it is now the project’s responsibility
to use the CheckIPOSupported module to check for support
before enabling the INTERPROCEDURAL_OPTIMIZATION target
property.  This approach allows a project to conditionally activate IPO
when supported.  It also allows an end user to set the
CMAKE_INTERPROCEDURAL_OPTIMIZATION variable in an environment
known to support IPO even if the project does not enable the property.

Since CMake 3.8 and lower only honored
INTERPROCEDURAL_OPTIMIZATION for the Intel compiler on Linux, some
projects may unconditionally enable the target property.  Policy
‘CMP0069’ provides compatibility with such projects.

This policy takes effect whenever the IPO property is enabled.  The
‘OLD’ behavior for this policy is to add IPO flags only for Intel
compiler on Linux.  The ‘NEW’ behavior for this policy is to add IPO
flags for the current compiler or produce an error if CMake does not
know the flags.

This policy was introduced in CMake version 3.9.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.12.1.1 Examples
..................

Behave like CMake 3.8 and do not apply any IPO flags except for Intel
compiler on Linux:

     cmake_minimum_required(VERSION 3.8)
     project(foo)

     # ...

     set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)

Use the CheckIPOSupported module to detect whether IPO is
supported by the current compiler, environment, and CMake version.
Produce a fatal error if support is not available:

     cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
     project(foo)

     include(CheckIPOSupported)
     check_ipo_supported()

     # ...

     set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)

Apply IPO flags only if compiler supports it:

     cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
     project(foo)

     include(CheckIPOSupported)

     # ...

     check_ipo_supported(RESULT result)
     if(result)
       set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
     endif()

Apply IPO flags without any checks.  This may lead to build errors if
IPO is not supported by the compiler in the current environment.
Produce an error if CMake does not know IPO flags for the current
compiler:

     cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
     project(foo)

     # ...

     set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)

17.12.2 CMP0068
---------------

New in version 3.9.

‘RPATH’ settings on macOS do not affect ‘install_name’.

CMake 3.9 and newer remove any effect the following settings may have on
the ‘install_name’ of a target on macOS:

   * BUILD_WITH_INSTALL_RPATH target property

   * SKIP_BUILD_RPATH target property

   * CMAKE_SKIP_RPATH variable

   * CMAKE_SKIP_INSTALL_RPATH variable

Previously, setting BUILD_WITH_INSTALL_RPATH had the effect
of setting both the ‘install_name’ of a target to
INSTALL_NAME_DIR and the ‘RPATH’ to INSTALL_RPATH.  In
CMake 3.9, it only affects setting of ‘RPATH’.  However, if one wants
INSTALL_NAME_DIR to apply to the target in the build tree,
one may set BUILD_WITH_INSTALL_NAME_DIR.

If SKIP_BUILD_RPATH, CMAKE_SKIP_RPATH or
CMAKE_SKIP_INSTALL_RPATH were used to strip the directory portion
of the ‘install_name’ of a target, one may set ‘INSTALL_NAME_DIR=""’
instead.

The ‘OLD’ behavior of this policy is to use the ‘RPATH’ settings for
‘install_name’ on macOS. The ‘NEW’ behavior of this policy is to ignore
the ‘RPATH’ settings for ‘install_name’ on macOS.

This policy was introduced in CMake version 3.9.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.13 Policies Introduced by CMake 3.8
======================================

17.13.1 CMP0067
---------------

New in version 3.8.

Honor language standard in try_compile() source-file
signature.

The try_compile() source file signature is intended to allow
callers to check whether they will be able to compile a given source
file with the current toolchain.  In order to match compiler behavior,
any language standard mode should match.  However, CMake 3.7 and below
did not do this.  CMake 3.8 and above prefer to honor the language
standard settings for ‘C’, ‘CXX’ (C++), and ‘CUDA’ using the values of
the variables:

   * CMAKE_C_STANDARD.

   * CMAKE_C_STANDARD_REQUIRED.

   * CMAKE_C_EXTENSIONS.

   * CMAKE_CXX_STANDARD.

   * CMAKE_CXX_STANDARD_REQUIRED.

   * CMAKE_CXX_EXTENSIONS.

   * CMAKE_CUDA_STANDARD.

   * CMAKE_CUDA_STANDARD_REQUIRED.

   * CMAKE_CUDA_EXTENSIONS.

This policy provides compatibility for projects that do not expect the
language standard settings to be used automatically.

The ‘OLD’ behavior of this policy is to ignore language standard setting
variables when generating the ‘try_compile’ test project.  The ‘NEW’
behavior of this policy is to honor language standard setting variables.

This policy was introduced in CMake version 3.8.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0067 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.14 Policies Introduced by CMake 3.7
======================================

17.14.1 CMP0066
---------------

New in version 3.7.

Honor per-config flags in try_compile() source-file
signature.

The source file signature of the try_compile() command uses
the value of the CMAKE_<LANG>_FLAGS variable in the test
project so that the test compilation works as it would in the main
project.  However, CMake 3.6 and below do not also honor config-specific
compiler flags such as those in the CMAKE_<LANG>_FLAGS_DEBUG.
variable.  CMake 3.7 and above prefer to honor config-specific compiler
flags too.  This policy provides compatibility for projects that do not
expect config-specific compiler flags to be used.

The ‘OLD’ behavior of this policy is to ignore config-specific flag
variables like CMAKE_<LANG>_FLAGS_DEBUG and only use CMake’s
built-in defaults for the current compiler and platform.

The ‘NEW’ behavior of this policy is to honor config-specific flag
variabldes like CMAKE_<LANG>_FLAGS_DEBUG.

This policy was introduced in CMake version 3.7.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0066 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.15 Policies Introduced by CMake 3.4
======================================

17.15.1 CMP0065
---------------

New in version 3.4.

Do not add flags to export symbols from executables without the
ENABLE_EXPORTS target property.

CMake 3.3 and below, for historical reasons, always linked executables
on some platforms with flags like ‘-rdynamic’ to export symbols from the
executables for use by any plugins they may load via ‘dlopen’.  CMake
3.4 and above prefer to do this only for executables that are explicitly
marked with the ENABLE_EXPORTS target property.

The ‘OLD’ behavior of this policy is to always use the additional link
flags when linking executables regardless of the value of the
ENABLE_EXPORTS target property.

The ‘NEW’ behavior of this policy is to only use the additional link
flags when linking executables if the ENABLE_EXPORTS target
property is set to ‘True’.

This policy was introduced in CMake version 3.4.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0065 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.15.2 CMP0064
---------------

New in version 3.4.

Recognize ‘TEST’ as a operator for the if() command.

The ‘TEST’ operator was added to the if() command to
determine if a given test name was created by the add_test().
command.

The ‘OLD’ behavior for this policy is to ignore the ‘TEST’ operator.
The ‘NEW’ behavior is to interpret the ‘TEST’ operator.

This policy was introduced in CMake version 3.4.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16 Policies Introduced by CMake 3.3
======================================

17.16.1 CMP0063
---------------

New in version 3.3.

Honor visibility properties for all target types.

The <LANG>_VISIBILITY_PRESET and
VISIBILITY_INLINES_HIDDEN target properties affect visibility of
symbols during dynamic linking.  When first introduced these properties
affected compilation of sources only in shared libraries, module
libraries, and executables with the ENABLE_EXPORTS property
set.  This was sufficient for the basic use cases of shared libraries
and executables with plugins.  However, some sources may be compiled as
part of static libraries or object libraries and then linked into a
shared library later.  CMake 3.3 and above prefer to honor these
properties for sources compiled in all target types.  This policy
preserves compatibility for projects expecting the properties to work
only for some target types.

The ‘OLD’ behavior for this policy is to ignore the visibility
properties for static libraries, object libraries, and executables
without exports.  The ‘NEW’ behavior for this policy is to honor the
visibility properties for all target types.

This policy was introduced in CMake version 3.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16.2 CMP0062
---------------

New in version 3.3.

Disallow install() of export() result.

The export() command generates a file containing
Imported Targets, which is suitable for use from the build
directory.  It is not suitable for installation because it contains
absolute paths to buildsystem locations, and is particular to a single
build configuration.

The install(EXPORT) generates and installs files which
contain Imported Targets.  These files are generated with
relative paths (unless the user specifies absolute paths), and are
designed for multi-configuration use.  See Creating Packages.
for more.

CMake 3.3 no longer allows the use of the install(FILES).
command with the result of the export() command.

The ‘OLD’ behavior for this policy is to allow installing the result of
an export() command.  The ‘NEW’ behavior for this policy is
not to allow installing the result of an export() command.

This policy was introduced in CMake version 3.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16.3 CMP0061
---------------

New in version 3.3.

CTest does not by default tell ‘make’ to ignore errors (‘-i’).

The ctest_build() and build_command() commands no
longer generate build commands for Makefile Generators with
the ‘-i’ option.  Previously this was done to help build as much of
tested projects as possible.  However, this behavior is not consistent
with other generators and also causes the return code of the ‘make’ tool
to be meaningless.

Of course users may still add this option manually by setting
CTEST_BUILD_COMMAND or the ‘MAKECOMMAND’ cache entry.  See the
CTest Build Step. ‘MakeCommand’ setting documentation for
their effects.

The ‘OLD’ behavior for this policy is to add ‘-i’ to ‘make’ calls in
CTest.  The ‘NEW’ behavior for this policy is to not add ‘-i’.

This policy was introduced in CMake version 3.3.  Unlike most policies,
CMake version 3.19.2 does `not' warn when this policy is not set and
simply uses ‘OLD’ behavior.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16.4 CMP0060
---------------

New in version 3.3.

Link libraries by full path even in implicit directories.

Policy CMP0003 was introduced with the intention of always
linking library files by full path when a full path is given to the
target_link_libraries() command.  However, on some platforms
(e.g.  HP-UX) the compiler front-end adds alternative library search
paths for the current architecture (e.g.  ‘/usr/lib/<arch>’ has
alternatives to libraries in ‘/usr/lib’ for the current architecture).
On such platforms the find_library() may find a library such
as ‘/usr/lib/libfoo.so’ that does not belong to the current
architecture.

Prior to policy CMP0003 projects would still build in such
cases because the incorrect library path would be converted to ‘-lfoo’
on the link line and the linker would find the proper library in the
arch-specific search path provided by the compiler front-end implicitly.
At the time we chose to remain compatible with such projects by always
converting library files found in implicit link directories to ‘-lfoo’
flags to ask the linker to search for them.  This approach allowed
existing projects to continue to build while still linking to libraries
outside implicit link directories via full path (such as those in the
build tree).

CMake does allow projects to override this behavior by using an
IMPORTED library target with its IMPORTED_LOCATION.
property set to the desired full path to a library file.  In fact, many
Find Modules are learning to provide Imported Targets
instead of just the traditional ‘Foo_LIBRARIES’ variable listing
library files.  However, this makes the link line generated for a
library found by a Find Module depend on whether it is linked through an
imported target or not, which is inconsistent.  Furthermore, this
behavior has been a source of confusion because the generated link line
for a library file depends on its location.  It is also problematic for
projects trying to link statically because flags like ‘-Wl,-Bstatic
-lfoo -Wl,-Bdynamic’ may be used to help the linker select ‘libfoo.a’
instead of ‘libfoo.so’ but then leak dynamic linking to following
libraries.  (See the LINK_SEARCH_END_STATIC target property
for a solution typically used for that problem.)

When the special case for libraries in implicit link directories was
first introduced the list of implicit link directories was simply
hard-coded (e.g.  ‘/lib’, ‘/usr/lib’, and a few others).  Since that
time, CMake has learned to detect the implicit link directories used by
the compiler front-end.  If necessary, the find_library().
command could be taught to use this information to help find libraries
of the proper architecture.

For these reasons, CMake 3.3 and above prefer to drop the special case
and link libraries by full path even when they are in implicit link
directories.  Policy ‘CMP0060’ provides compatibility for existing
projects.

The ‘OLD’ behavior for this policy is to ask the linker to search for
libraries whose full paths are known to be in implicit link directories.
The ‘NEW’ behavior for this policy is to link libraries by full path
even if they are in implicit link directories.

This policy was introduced in CMake version 3.3.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0060 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16.5 CMP0059
---------------

New in version 3.3.

Do not treat ‘DEFINITIONS’ as a built-in directory property.

CMake 3.3 and above no longer make a list of definitions available
through the DEFINITIONS directory property.  The
COMPILE_DEFINITIONS directory property may be used instead.

The ‘OLD’ behavior for this policy is to provide the list of flags given
so far to the add_definitions() command.  The ‘NEW’ behavior
is to behave as a normal user-defined directory property.

This policy was introduced in CMake version 3.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.16.6 CMP0058
---------------

New in version 3.3.

Ninja requires custom command byproducts to be explicit.

When an intermediate file generated during the build is consumed by an
expensive operation or a large tree of dependents, one may reduce the
work needed for an incremental rebuild by updating the file timestamp
only when its content changes.  With this approach the generation rule
must have a separate output file that is always updated with a new
timestamp that is newer than any dependencies of the rule so that the
build tool re-runs the rule only when the input changes.  We refer to
the separate output file as a rule’s `witness' and the generated file as
a rule’s `byproduct'.

Byproducts may not be listed as outputs because their timestamps are
allowed to be older than the inputs.  No build tools (like ‘make’) that
existed when CMake was designed have a way to express byproducts.
Therefore CMake versions prior to 3.2 had no way to specify them.
Projects typically left byproducts undeclared in the rules that generate
them.  For example:

     add_custom_command(
       OUTPUT witness.txt
       COMMAND ${CMAKE_COMMAND} -E copy_if_different
               ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
               byproduct.txt # timestamp may not change
       COMMAND ${CMAKE_COMMAND} -E touch witness.txt
       DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
       )
     add_custom_target(Provider DEPENDS witness.txt)
     add_custom_command(
       OUTPUT generated.c
       COMMAND expensive-task -i byproduct.txt -o generated.c
       DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt
       )
     add_library(Consumer generated.c)
     add_dependencies(Consumer Provider)

This works well for all generators except Ninja.  The Ninja
build tool sees a rule listing ‘byproduct.txt’ as a dependency and no
rule listing it as an output.  Ninja then complains that there is no way
to satisfy the dependency and stops building even though there are
order-only dependencies that ensure ‘byproduct.txt’ will exist before
its consumers need it.  See discussion of this problem in Ninja Issue
760(1) for further details on why Ninja works this way.

Instead of leaving byproducts undeclared in the rules that generate
them, Ninja expects byproducts to be listed along with other outputs.
Such rules may be marked with a ‘restat’ option that tells Ninja to
check the timestamps of outputs after the rules run.  This prevents
byproducts whose timestamps do not change from causing their dependents
to re-build unnecessarily.

Since the above approach does not tell CMake what custom command
generates ‘byproduct.txt’, the Ninja generator does not have enough
information to add the byproduct as an output of any rule.  CMake 2.8.12
and above work around this problem and allow projects using the above
approach to build by generating ‘phony’ build rules to tell Ninja to
tolerate such missing files.  However, this workaround prevents Ninja
from diagnosing a dependency that is really missing.  It also works
poorly in in-source builds where every custom command dependency, even
on source files, needs to be treated this way because CMake does not
have enough information to know which files are generated as byproducts
of custom commands.

CMake 3.2 introduced the ‘BYPRODUCTS’ option to the
add_custom_command() and add_custom_target() commands.
This option allows byproducts to be specified explicitly:

     add_custom_command(
       OUTPUT witness.txt
       BYPRODUCTS byproduct.txt # explicit byproduct specification
       COMMAND ${CMAKE_COMMAND} -E copy_if_different
               ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
               byproduct.txt # timestamp may not change
     ...

The ‘BYPRODUCTS’ option is used by the Ninja generator to
list byproducts among the outputs of the custom commands that generate
them, and is ignored by other generators.

CMake 3.3 and above prefer to require projects to specify custom command
byproducts explicitly so that it can avoid using the ‘phony’ rule
workaround altogether.  Policy ‘CMP0058’ was introduced to provide
compatibility with existing projects that still need the workaround.

This policy has no effect on generators other than Ninja.  The
‘OLD’ behavior for this policy is to generate Ninja ‘phony’ rules for
unknown dependencies in the build tree.  The ‘NEW’ behavior for this
policy is to not generate these and instead require projects to specify
custom command ‘BYPRODUCTS’ explicitly.

This policy was introduced in CMake version 3.3.  CMake version 3.19.2
warns when it sees unknown dependencies in out-of-source build trees if
the policy is not set and then uses ‘OLD’ behavior.  Use the
cmake_policy() command to set the policy to ‘OLD’ or ‘NEW’
explicitly.  The policy setting must be in scope at the end of the
top-level ‘CMakeLists.txt’ file of the project and has global effect.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

   ---------- Footnotes ----------

   (1) https://github.com/martine/ninja/issues/760

17.16.7 CMP0057
---------------

New in version 3.3.

Support new if(). IN_LIST operator.

CMake 3.3 adds support for the new IN_LIST operator.

The ‘OLD’ behavior for this policy is to ignore the IN_LIST operator.
The ‘NEW’ behavior is to interpret the IN_LIST operator.

This policy was introduced in CMake version 3.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.17 Policies Introduced by CMake 3.2
======================================

17.17.1 CMP0056
---------------

New in version 3.2.

Honor link flags in try_compile() source-file signature.

The try_compile() command source-file signature generates a
‘CMakeLists.txt’ file to build the source file into an executable.  In
order to compile the source the same way as it might be compiled by the
calling project, the generated project sets the value of the
CMAKE_<LANG>_FLAGS variable to that in the calling project.  The
value of the CMAKE_EXE_LINKER_FLAGS variable may be needed
in some cases too, but CMake 3.1 and lower did not set it in the
generated project.  CMake 3.2 and above prefer to set it so that linker
flags are honored as well as compiler flags.  This policy provides
compatibility with the pre-3.2 behavior.

The ‘OLD’ behavior for this policy is to not set the value of the
CMAKE_EXE_LINKER_FLAGS variable in the generated test project.
The ‘NEW’ behavior for this policy is to set the value of the
CMAKE_EXE_LINKER_FLAGS variable in the test project to the same as
it is in the calling project.

If the project code does not set the policy explicitly, users may set it
on the command line by defining the CMAKE_POLICY_DEFAULT_CMP0056
variable in the cache.

This policy was introduced in CMake version 3.2.  Unlike most policies,
CMake version 3.19.2 does `not' warn by default when this policy is not
set and simply uses ‘OLD’ behavior.  See documentation of the
CMAKE_POLICY_WARNING_CMP0056 variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.17.2 CMP0055
---------------

New in version 3.2.

Strict checking for the break() command.

CMake 3.1 and lower allowed calls to the break() command
outside of a loop context and also ignored any given arguments.  This
was undefined behavior.

The ‘OLD’ behavior for this policy is to allow break() to be
placed outside of loop contexts and ignores any arguments.  The ‘NEW’
behavior for this policy is to issue an error if a misplaced break or
any arguments are found.

This policy was introduced in CMake version 3.2.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.18 Policies Introduced by CMake 3.1
======================================

17.18.1 CMP0054
---------------

New in version 3.1.

Only interpret if() arguments as variables or keywords when
unquoted.

CMake 3.1 and above no longer implicitly dereference variables or
interpret keywords in an if() command argument when it is a
Quoted Argument or a Bracket Argument.

The ‘OLD’ behavior for this policy is to dereference variables and
interpret keywords even if they are quoted or bracketed.  The ‘NEW’
behavior is to not dereference variables or interpret keywords that have
been quoted or bracketed.

Given the following partial example:

     set(A E)
     set(E "")

     if("${A}" STREQUAL "")
       message("Result is TRUE before CMake 3.1 or when CMP0054 is OLD")
     else()
       message("Result is FALSE in CMake 3.1 and above if CMP0054 is NEW")
     endif()

After explicit expansion of variables this gives:

     if("E" STREQUAL "")

With the policy set to ‘OLD’ implicit expansion reduces this
semantically to:

     if("" STREQUAL "")

With the policy set to ‘NEW’ the quoted arguments will not be further
dereferenced:

     if("E" STREQUAL "")

This policy was introduced in CMake version 3.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.18.2 CMP0053
---------------

New in version 3.1.

Simplify variable reference and escape sequence evaluation.

CMake 3.1 introduced a much faster implementation of evaluation of the
Variable References and Escape Sequences.
documented in the cmake-language(7) manual.  While the
behavior is identical to the legacy implementation in most cases, some
corner cases were cleaned up to simplify the behavior.  Specifically:

   * Expansion of ‘@VAR@’ reference syntax defined by the
     configure_file() and string(CONFIGURE) commands
     is no longer performed in other contexts.

   * Literal ‘${VAR}’ reference syntax may contain only alphanumeric
     characters (‘A-Z’, ‘a-z’, ‘0-9’) and the characters ‘_’, ‘.’, ‘/’,
     ‘-’, and ‘+’.  Note that ‘$’ is technically allowed in the ‘NEW’
     behavior, but is invalid for ‘OLD’ behavior.  This is due to an
     oversight during the implementation of CMP0053 and its
     use as a literal variable reference is discouraged for this reason.
     Variables with other characters in their name may still be
     referenced indirectly, e.g.

          set(varname "otherwise & disallowed $ characters")
          message("${${varname}}")

   * The setting of policy CMP0010 is not considered, so
     improper variable reference syntax is always an error.

   * More characters are allowed to be escaped in variable names.
     Previously, only ‘()#" \@^’ were valid characters to escape.  Now
     any non-alphanumeric, non-semicolon, non-NUL character may be
     escaped following the ‘escape_identity’ production in the
     Escape Sequences section of the cmake-language(7).
     manual.

The ‘OLD’ behavior for this policy is to honor the legacy behavior for
variable references and escape sequences.  The ‘NEW’ behavior is to use
the simpler variable expansion and escape sequence evaluation rules.

This policy was introduced in CMake version 3.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.18.3 CMP0052
---------------

New in version 3.1.

Reject source and build dirs in installed
INTERFACE_INCLUDE_DIRECTORIES.

CMake 3.0 and lower allowed subdirectories of the source directory or
build directory to be in the INTERFACE_INCLUDE_DIRECTORIES.
of installed and exported targets, if the directory was also a
subdirectory of the installation prefix.  This makes the installation
depend on the existence of the source dir or binary dir, and the
installation will be broken if either are removed after installation.

See Include Directories and Usage Requirements for more on
specifying include directories for targets.

The ‘OLD’ behavior for this policy is to export the content of the
INTERFACE_INCLUDE_DIRECTORIES with the source or binary directory.
The ‘NEW’ behavior for this policy is to issue an error if such a
directory is used.

This policy was introduced in CMake version 3.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.18.4 CMP0051
---------------

New in version 3.1.

List TARGET_OBJECTS in SOURCES target property.

CMake 3.0 and lower did not include the ‘TARGET_OBJECTS’ generator expression
when returning the SOURCES target property.

Configure-time CMake code is not able to handle generator expressions.
If using the SOURCES target property at configure time, it
may be necessary to first remove generator expressions using the
string(GENEX_STRIP) command.  Generate-time CMake code such as
file(GENERATE) can handle the content without stripping.

The ‘OLD’ behavior for this policy is to omit ‘TARGET_OBJECTS’
expressions from the SOURCES target property.  The ‘NEW’
behavior for this policy is to include ‘TARGET_OBJECTS’ expressions in
the output.

This policy was introduced in CMake version 3.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19 Policies Introduced by CMake 3.0
======================================

17.19.1 CMP0050
---------------

Disallow add_custom_command SOURCE signatures.

CMake 2.8.12 and lower allowed a signature for
add_custom_command() which specified an input to a command.  This
was undocumented behavior.  Modern use of CMake associates custom
commands with their output, rather than their input.

The ‘OLD’ behavior for this policy is to allow the use of
add_custom_command(). SOURCE signatures.  The ‘NEW’ behavior for
this policy is to issue an error if such a signature is used.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.2 CMP0049
---------------

Do not expand variables in target source entries.

CMake 2.8.12 and lower performed an extra layer of variable expansion
when evaluating source file names:

     set(a_source foo.c)
     add_executable(foo \${a_source})

This was undocumented behavior.

The ‘OLD’ behavior for this policy is to expand such variables when
processing the target sources.  The ‘NEW’ behavior for this policy is to
issue an error if such variables need to be expanded.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.3 CMP0048
---------------

The project() command manages ‘VERSION’ variables.

CMake version 3.0 introduced the ‘VERSION’ option of the
project() command to specify a project version as well as the
name.  In order to keep PROJECT_VERSION and related
variables consistent with variable PROJECT_NAME it is
necessary to set the ‘VERSION’ variables to the empty string when no
‘VERSION’ is given to project().  However, this can change
behavior for existing projects that set ‘VERSION’ variables themselves
since project() may now clear them.  This policy controls
the behavior for compatibility with such projects.

The ‘OLD’ behavior for this policy is to leave ‘VERSION’ variables
untouched.  The ‘NEW’ behavior for this policy is to set ‘VERSION’ as
documented by the project() command.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.4 CMP0047
---------------

Use ‘QCC’ compiler id for the qcc drivers on QNX.

CMake 3.0 and above recognize that the QNX qcc compiler driver is
different from the GNU compiler.  CMake now prefers to present this to
projects by setting the CMAKE_<LANG>_COMPILER_ID variable to
‘QCC’ instead of ‘GNU’.  However, existing projects may assume the
compiler id for QNX qcc is just ‘GNU’ as it was in CMake versions prior
to 3.0.  Therefore this policy determines for QNX qcc which compiler id
to report in the CMAKE_<LANG>_COMPILER_ID variable after
language ‘<LANG>’ is enabled by the project() or
enable_language() command.  The policy must be set prior to the
invocation of either command.

The ‘OLD’ behavior for this policy is to use the ‘GNU’ compiler id for
the qcc and QCC compiler drivers.  The ‘NEW’ behavior for this policy is
to use the ‘QCC’ compiler id for those drivers.

This policy was introduced in CMake version 3.0.  Use the
cmake_policy() command to set this policy to ‘OLD’ or ‘NEW’
explicitly.  Unlike most policies, CMake version 3.19.2 does `not' warn
by default when this policy is not set and simply uses ‘OLD’ behavior.
See documentation of the CMAKE_POLICY_WARNING_CMP0047.
variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.5 CMP0046
---------------

Error on non-existent dependency in add_dependencies.

CMake 2.8.12 and lower silently ignored non-existent dependencies listed
in the add_dependencies() command.

The ‘OLD’ behavior for this policy is to silently ignore non-existent
dependencies.  The ‘NEW’ behavior for this policy is to report an error
if non-existent dependencies are listed in the add_dependencies()
command.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.6 CMP0045
---------------

Error on non-existent target in get_target_property.

In CMake 2.8.12 and lower, the get_target_property() command
accepted a non-existent target argument without issuing any error or
warning.  The result variable is set to a ‘-NOTFOUND’ value.

The ‘OLD’ behavior for this policy is to issue no warning and set the
result variable to a ‘-NOTFOUND’ value.  The ‘NEW’ behavior for this
policy is to issue a ‘FATAL_ERROR’ if the command is called with a
non-existent target.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.7 CMP0044
---------------

Case sensitive ‘<LANG>_COMPILER_ID’ generator expressions

CMake 2.8.12 introduced the ‘<LANG>_COMPILER_ID’ generator expressions
to allow comparison of the
CMAKE_<LANG>_COMPILER_ID with a test value.  The possible valid
values are lowercase, but the comparison with the test value was
performed case-insensitively.

The ‘OLD’ behavior for this policy is to perform a case-insensitive
comparison with the value in the ‘<LANG>_COMPILER_ID’ expression.  The
‘NEW’ behavior for this policy is to perform a case-sensitive comparison
with the value in the ‘<LANG>_COMPILER_ID’ expression.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.8 CMP0043
---------------

Ignore COMPILE_DEFINITIONS_<Config> properties

CMake 2.8.12 and lower allowed setting the
COMPILE_DEFINITIONS_<CONFIG> target property and
COMPILE_DEFINITIONS_<CONFIG> directory property to apply
configuration-specific compile definitions.

Since CMake 2.8.10, the COMPILE_DEFINITIONS property has
supported generator expressions for setting
configuration-dependent content.  The continued existence of the
suffixed variables is redundant, and causes a maintenance burden.
Population of the COMPILE_DEFINITIONS_DEBUG property may be
replaced with a population of COMPILE_DEFINITIONS directly or
via target_compile_definitions().:

     # Old Interfaces:
     set_property(TARGET tgt APPEND PROPERTY
       COMPILE_DEFINITIONS_DEBUG DEBUG_MODE
     )
     set_property(DIRECTORY APPEND PROPERTY
       COMPILE_DEFINITIONS_DEBUG DIR_DEBUG_MODE
     )

     # New Interfaces:
     set_property(TARGET tgt APPEND PROPERTY
       COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DEBUG_MODE>
     )
     target_compile_definitions(tgt PRIVATE $<$<CONFIG:Debug>:DEBUG_MODE>)
     set_property(DIRECTORY APPEND PROPERTY
       COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE>
     )

The ‘OLD’ behavior for this policy is to consume the content of the
suffixed COMPILE_DEFINITIONS_<CONFIG> target property when
generating the compilation command.  The ‘NEW’ behavior for this policy
is to ignore the content of the COMPILE_DEFINITIONS_<CONFIG>.
target property .

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.9 CMP0042
---------------

MACOSX_RPATH is enabled by default.

CMake 2.8.12 and newer has support for using ‘@rpath’ in a target’s
install name.  This was enabled by setting the target property
MACOSX_RPATH.  The ‘@rpath’ in an install name is a more flexible
and powerful mechanism than ‘@executable_path’ or ‘@loader_path’ for
locating shared libraries.

CMake 3.0 and later prefer this property to be ON by default.  Projects
wanting ‘@rpath’ in a target’s install name may remove any setting of
the INSTALL_NAME_DIR and CMAKE_INSTALL_NAME_DIR.
variables.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.10 CMP0041
----------------

Error on relative include with generator expression.

Diagnostics in CMake 2.8.12 and lower silently ignored an entry in the
INTERFACE_INCLUDE_DIRECTORIES of a target if it contained a
generator expression at any position.

The path entries in that target property should not be relative.
High-level API should ensure that by adding either a source directory or
a install directory prefix, as appropriate.

As an additional diagnostic, the INTERFACE_INCLUDE_DIRECTORIES
generated on an IMPORTED target for the install
location should not contain paths in the source directory or the build
directory.

The ‘OLD’ behavior for this policy is to ignore relative path entries if
they contain a generator expression.  The ‘NEW’ behavior for this policy
is to report an error if a generator expression appears in another
location and the path is relative.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.11 CMP0040
----------------

The target in the ‘TARGET’ signature of add_custom_command().
must exist and must be defined in the current directory.

CMake 2.8.12 and lower silently ignored a custom command created with
the ‘TARGET’ signature of add_custom_command() if the target
is unknown or was defined outside the current directory.

The ‘OLD’ behavior for this policy is to ignore custom commands for
unknown targets.  The ‘NEW’ behavior for this policy is to report an
error if the target referenced in add_custom_command() is
unknown or was defined outside the current directory.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.12 CMP0039
----------------

Utility targets may not have link dependencies.

CMake 2.8.12 and lower allowed using utility targets in the left hand
side position of the target_link_libraries() command.  This
is an indicator of a bug in user code.

The ‘OLD’ behavior for this policy is to ignore attempts to set the link
libraries of utility targets.  The ‘NEW’ behavior for this policy is to
report an error if an attempt is made to set the link libraries of a
utility target.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.13 CMP0038
----------------

Targets may not link directly to themselves.

CMake 2.8.12 and lower allowed a build target to link to itself directly
with a target_link_libraries() call.  This is an indicator of
a bug in user code.

The ‘OLD’ behavior for this policy is to ignore targets which list
themselves in their own link implementation.  The ‘NEW’ behavior for
this policy is to report an error if a target attempts to link to
itself.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.14 CMP0037
----------------

Target names should not be reserved and should match a validity pattern.

CMake 2.8.12 and lower allowed creating targets using
add_library(), add_executable() and
add_custom_target() with unrestricted choice for the target name.
Newer cmake features such as cmake-generator-expressions(7).
and some diagnostics expect target names to match a restricted pattern.

Target names may contain upper and lower case letters, numbers, the
underscore character (‘_’), dot(‘.’), plus(‘+’) and minus(‘-’).  As a
special case, ‘ALIAS’ and ‘IMPORTED’ targets may contain two consecutive
colons.

Target names reserved by one or more CMake generators are not allowed.
Among others these include ‘all’, ‘clean’, ‘help’, and ‘install’.

Target names associated with optional features, such as ‘test’ and
‘package’, may also be reserved.  CMake 3.10 and below always reserve
them.  CMake 3.11 and above reserve them only when the corresponding
feature is enabled (e.g.  by including the CTest or
CPack modules).

The ‘OLD’ behavior for this policy is to allow creating targets with
reserved names or which do not match the validity pattern.  The ‘NEW’
behavior for this policy is to report an error if an add_* command is
used with an invalid target name.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.15 CMP0036
----------------

The build_name() command should not be called.

This command was added in May 2001 to compute a name for the current
operating system and compiler combination.  The command has long been
documented as discouraged and replaced by the CMAKE_SYSTEM.
and CMAKE_<LANG>_COMPILER variables.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.16 CMP0035
----------------

The variable_requires() command should not be called.

This command was introduced in November 2001 to perform some conditional
logic.  It has long been replaced by the if() command.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.17 CMP0034
----------------

The utility_source() command should not be called.

This command was introduced in March 2001 to help build executables used
to generate other files.  This approach has long been replaced by
add_executable() combined with add_custom_command().

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.18 CMP0033
----------------

The export_library_dependencies() command should not be
called.

This command was added in January 2003 to export ‘<tgt>_LIB_DEPENDS’
internal CMake cache entries to a file for installation with a project.
This was used at the time to allow transitive link dependencies to work
for applications outside of the original build tree of a project.  The
functionality has been superseded by the export() and
install(EXPORT) commands.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.19 CMP0032
----------------

The output_required_files() command should not be called.

This command was added in June 2001 to expose the then-current CMake
implicit dependency scanner.  CMake’s real implicit dependency scanner
has evolved since then but is not exposed through this command.  The
scanning capabilities of this command are very limited and this
functionality is better achieved through dedicated outside tools.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.20 CMP0031
----------------

The load_command() command should not be called.

This command was added in August 2002 to allow projects to add arbitrary
commands implemented in C or C++.  However, it does not work when the
toolchain in use does not match the ABI of the CMake process.  It has
been mostly superseded by the macro() and function()
commands.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.21 CMP0030
----------------

The use_mangled_mesa() command should not be called.

This command was created in September 2001 to support VTK before modern
CMake language and custom command capabilities.  VTK has not used it in
years.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.22 CMP0029
----------------

The subdir_depends() command should not be called.

The implementation of this command has been empty since December 2001
but was kept in CMake for compatibility for a long time.

CMake >= 3.0 prefer that this command never be called.  The ‘OLD’
behavior for this policy is to allow the command to be called.  The
‘NEW’ behavior for this policy is to issue a ‘FATAL_ERROR’ when the
command is called.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.23 CMP0028
----------------

Double colon in target name means ‘ALIAS’ or ‘IMPORTED’ target.

CMake 2.8.12 and lower allowed the use of targets and files with double
colons in target_link_libraries(), with some buildsystem
generators.

The use of double-colons is a common pattern used to namespace
‘IMPORTED’ targets and ‘ALIAS’ targets.  When computing the link
dependencies of a target, the name of each dependency could either be a
target, or a file on disk.  Previously, if a target was not found with a
matching name, the name was considered to refer to a file on disk.  This
can lead to confusing error messages if there is a typo in what should
be a target name.

The ‘OLD’ behavior for this policy is to search for targets, then files
on disk, even if the search term contains double-colons.  The ‘NEW’
behavior for this policy is to issue a ‘FATAL_ERROR’ if a link
dependency contains double-colons but is not an ‘IMPORTED’ target or an
‘ALIAS’ target.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.24 CMP0027
----------------

Conditionally linked imported targets with missing include directories.

CMake 2.8.11 introduced introduced the concept of
INTERFACE_INCLUDE_DIRECTORIES, and a check at cmake time that the
entries in the INTERFACE_INCLUDE_DIRECTORIES of an
‘IMPORTED’ target actually exist.  CMake 2.8.11 also introduced
generator expression support in the target_link_libraries().
command.  However, if an imported target is linked as a result of a
generator expression evaluation, the entries in the
INTERFACE_INCLUDE_DIRECTORIES of that target were not checked for
existence as they should be.

The ‘OLD’ behavior of this policy is to report a warning if an entry in
the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression
conditionally linked ‘IMPORTED’ target does not exist.

The ‘NEW’ behavior of this policy is to report an error if an entry in
the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression
conditionally linked ‘IMPORTED’ target does not exist.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.25 CMP0026
----------------

Disallow use of the LOCATION property for build targets.

CMake 2.8.12 and lower allowed reading the LOCATION target
property (and configuration-specific variants) to determine the eventual
location of build targets.  This relies on the assumption that all
necessary information is available at configure-time to determine the
final location and filename of the target.  However, this property is
not fully determined until later at generate-time.  At generate time,
the ‘$<TARGET_FILE>’ generator expression can be used to determine the
eventual LOCATION of a target output.

Code which reads the LOCATION target property can be ported
to use the ‘$<TARGET_FILE>’ generator expression together with the
file(GENERATE) subcommand to generate a file containing the target
location.

The ‘OLD’ behavior for this policy is to allow reading the
LOCATION properties from build-targets.  The ‘NEW’ behavior for
this policy is to not to allow reading the LOCATION.
properties from build-targets.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.26 CMP0025
----------------

Compiler id for Apple Clang is now ‘AppleClang’.

CMake 3.0 and above recognize that Apple Clang is a different compiler
than upstream Clang and that they have different version numbers.  CMake
now prefers to present this to projects by setting the
CMAKE_<LANG>_COMPILER_ID variable to ‘AppleClang’ instead of
‘Clang’.  However, existing projects may assume the compiler id for
Apple Clang is just ‘Clang’ as it was in CMake versions prior to 3.0.
Therefore this policy determines for Apple Clang which compiler id to
report in the CMAKE_<LANG>_COMPILER_ID variable after
language ‘<LANG>’ is enabled by the project() or
enable_language() command.  The policy must be set prior to the
invocation of either command.

The ‘OLD’ behavior for this policy is to use compiler id ‘Clang’.  The
‘NEW’ behavior for this policy is to use compiler id ‘AppleClang’.

This policy was introduced in CMake version 3.0.  Use the
cmake_policy() command to set this policy to ‘OLD’ or ‘NEW’
explicitly.  Unlike most policies, CMake version 3.19.2 does `not' warn
by default when this policy is not set and simply uses ‘OLD’ behavior.
See documentation of the CMAKE_POLICY_WARNING_CMP0025.
variable to control the warning.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.19.27 CMP0024
----------------

Disallow include export result.

CMake 2.8.12 and lower allowed use of the include() command
with the result of the export() command.  This relies on the
assumption that the export() command has an immediate effect
at configure-time during a cmake run.  Certain properties of targets are
not fully determined until later at generate-time, such as the link
language and complete list of link libraries.  Future refactoring will
change the effect of the export() command to be executed at
generate-time.  Use ‘ALIAS’ targets instead in cases where the goal is
to refer to targets by another name.

The ‘OLD’ behavior for this policy is to allow including the result of
an export() command.  The ‘NEW’ behavior for this policy is
not to allow including the result of an export() command.

This policy was introduced in CMake version 3.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20 Policies Introduced by CMake 2.8
======================================

17.20.1 CMP0023
---------------

Plain and keyword target_link_libraries() signatures cannot
be mixed.

CMake 2.8.12 introduced the target_link_libraries() signature
using the ‘PUBLIC’, ‘PRIVATE’, and ‘INTERFACE’ keywords to generalize
the ‘LINK_PUBLIC’ and ‘LINK_PRIVATE’ keywords introduced in CMake 2.8.7.
Use of signatures with any of these keywords sets the link interface of
a target explicitly, even if empty.  This produces confusing behavior
when used in combination with the historical behavior of the plain
target_link_libraries() signature.  For example, consider the code:

     target_link_libraries(mylib A)
     target_link_libraries(mylib PRIVATE B)

After the first line the link interface has not been set explicitly so
CMake would use the link implementation, A, as the link interface.
However, the second line sets the link interface to empty.  In order to
avoid this subtle behavior CMake now prefers to disallow mixing the
plain and keyword signatures of target_link_libraries() for a
single target.

The ‘OLD’ behavior for this policy is to allow keyword and plain
target_link_libraries() signatures to be mixed.  The ‘NEW’ behavior
for this policy is to not to allow mixing of the keyword and plain
signatures.

This policy was introduced in CMake version 2.8.12.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.2 CMP0022
---------------

INTERFACE_LINK_LIBRARIES defines the link interface.

CMake 2.8.11 constructed the ‘link interface’ of a target from
properties matching ‘(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?’.
The modern way to specify config-sensitive content is to use generator
expressions and the ‘IMPORTED_’ prefix makes uniform processing of the
link interface with generator expressions impossible.  The
INTERFACE_LINK_LIBRARIES target property was introduced as a
replacement in CMake 2.8.12.  This new property is named consistently
with the ‘INTERFACE_COMPILE_DEFINITIONS’,
‘INTERFACE_INCLUDE_DIRECTORIES’ and ‘INTERFACE_COMPILE_OPTIONS’
properties.  For in-build targets, CMake will use the
INTERFACE_LINK_LIBRARIES property as the source of the link interface
only if policy ‘CMP0022’ is ‘NEW’.  When exporting a target which has
this policy set to ‘NEW’, only the INTERFACE_LINK_LIBRARIES.
property will be processed and generated for the ‘IMPORTED’ target by
default.  A new option to the install(EXPORT) and export
commands allows export of the old-style properties for compatibility
with downstream users of CMake versions older than 2.8.12.  The
target_link_libraries() command will no longer populate the
properties matching ‘LINK_INTERFACE_LIBRARIES(_<CONFIG>)?’ if this
policy is ‘NEW’.

Warning-free future-compatible code which works with CMake 2.8.7 onwards
can be written by using the ‘LINK_PRIVATE’ and ‘LINK_PUBLIC’ keywords of
target_link_libraries().

The ‘OLD’ behavior for this policy is to ignore the
INTERFACE_LINK_LIBRARIES property for in-build targets.  The ‘NEW’
behavior for this policy is to use the ‘INTERFACE_LINK_LIBRARIES’
property for in-build targets, and ignore the old properties matching
‘(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?’.

This policy was introduced in CMake version 2.8.12.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.3 CMP0021
---------------

Fatal error on relative paths in INCLUDE_DIRECTORIES target
property.

CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES.
target property to contain relative paths.  The base path for such
relative entries is not well defined.  CMake 2.8.12 issues a
‘FATAL_ERROR’ if the INCLUDE_DIRECTORIES property contains a
relative path.

The ‘OLD’ behavior for this policy is not to warn about relative paths
in the ‘INCLUDE_DIRECTORIES’ target property.  The ‘NEW’ behavior for
this policy is to issue a ‘FATAL_ERROR’ if ‘INCLUDE_DIRECTORIES’
contains a relative path.

This policy was introduced in CMake version 2.8.12.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.4 CMP0020
---------------

Automatically link Qt executables to ‘qtmain’ target on Windows.

CMake 2.8.10 and lower required users of Qt to always specify a link
dependency to the ‘qtmain.lib’ static library manually on Windows.
CMake 2.8.11 gained the ability to evaluate generator expressions while
determining the link dependencies from ‘IMPORTED’ targets.  This allows
CMake itself to automatically link executables which link to Qt to the
‘qtmain.lib’ library when using ‘IMPORTED’ Qt targets.  For applications
already linking to ‘qtmain.lib’, this should have little impact.  For
applications which supply their own alternative WinMain implementation
and for applications which use the QAxServer library, this automatic
linking will need to be disabled as per the documentation.

The ‘OLD’ behavior for this policy is not to link executables to
‘qtmain.lib’ automatically when they link to the QtCore ‘IMPORTED’
target.  The ‘NEW’ behavior for this policy is to link executables to
‘qtmain.lib’ automatically when they link to QtCore ‘IMPORTED’ target.

This policy was introduced in CMake version 2.8.11.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.5 CMP0019
---------------

Do not re-expand variables in include and link information.

CMake 2.8.10 and lower re-evaluated values given to the
include_directories, link_directories, and link_libraries commands to
expand any leftover variable references at the end of the configuration
step.  This was for strict compatibility with VERY early CMake versions
because all variable references are now normally evaluated during CMake
language processing.  CMake 2.8.11 and higher prefer to skip the extra
evaluation.

The ‘OLD’ behavior for this policy is to re-evaluate the values for
strict compatibility.  The ‘NEW’ behavior for this policy is to leave
the values untouched.

This policy was introduced in CMake version 2.8.11.  CMake version
3.19.2 warns when the policy is not set and uses ‘OLD’ behavior.  Use
the cmake_policy() command to set it to ‘OLD’ or ‘NEW’
explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.6 CMP0018
---------------

Ignore ‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ variable.

CMake 2.8.8 and lower compiled sources in ‘SHARED’ and ‘MODULE’
libraries using the value of the undocumented
‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ platform variable.  The variable
contained platform-specific flags needed to compile objects for shared
libraries.  Typically it included a flag such as ‘-fPIC’ for position
independent code but also included other flags needed on certain
platforms.  CMake 2.8.9 and higher prefer instead to use the
POSITION_INDEPENDENT_CODE target property to determine what
targets should be position independent, and new undocumented platform
variables to select flags while ignoring
‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ completely.

The default for either approach produces identical compilation flags,
but if a project modifies ‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ from its
original value this policy determines which approach to use.

The ‘OLD’ behavior for this policy is to ignore the
POSITION_INDEPENDENT_CODE property for all targets and use the
modified value of ‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ for ‘SHARED’ and
‘MODULE’ libraries.

The ‘NEW’ behavior for this policy is to ignore
‘CMAKE_SHARED_LIBRARY_<Lang>_FLAGS’ whether it is modified or not and
honor the POSITION_INDEPENDENT_CODE target property.

This policy was introduced in CMake version 2.8.9.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.7 CMP0017
---------------

Prefer files from the CMake module directory when including from there.

Starting with CMake 2.8.4, if a cmake-module shipped with CMake (i.e.
located in the CMake module directory) calls include() or
find_package(), the files located in the CMake module
directory are preferred over the files in CMAKE_MODULE_PATH.
This makes sure that the modules belonging to CMake always get those
files included which they expect, and against which they were developed
and tested.  In all other cases, the files found in
CMAKE_MODULE_PATH still take precedence over the ones in the CMake
module directory.  The ‘OLD’ behavior is to always prefer files from
CMAKE_MODULE_PATH over files from the CMake modules directory.

This policy was introduced in CMake version 2.8.4.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.8 CMP0016
---------------

target_link_libraries() reports error if its only argument is
not a target.

In CMake 2.8.2 and lower the target_link_libraries() command
silently ignored if it was called with only one argument, and this
argument wasn’t a valid target.  In CMake 2.8.3 and above it reports an
error in this case.

This policy was introduced in CMake version 2.8.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.9 CMP0015
---------------

     link_directories() treats paths relative to the source
     dir.

In CMake 2.8.0 and lower the link_directories() command
passed relative paths unchanged to the linker.  In CMake 2.8.1 and above
the link_directories() command prefers to interpret relative
paths with respect to ‘CMAKE_CURRENT_SOURCE_DIR’, which is consistent
with include_directories() and other commands.  The ‘OLD’
behavior for this policy is to use relative paths verbatim in the linker
command.  The ‘NEW’ behavior for this policy is to convert relative
paths to absolute paths by appending the relative path to
‘CMAKE_CURRENT_SOURCE_DIR’.

This policy was introduced in CMake version 2.8.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.10 CMP0014
----------------

Input directories must have ‘CMakeLists.txt’.

CMake versions before 2.8 silently ignored missing ‘CMakeLists.txt’
files in directories referenced by add_subdirectory() or
subdirs(), treating them as if present but empty.  In CMake
2.8.0 and above this cmake_policy() determines whether or
not the case is an error.  The ‘OLD’ behavior for this policy is to
silently ignore the problem.  The ‘NEW’ behavior for this policy is to
report an error.

This policy was introduced in CMake version 2.8.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.11 CMP0013
----------------

Duplicate binary directories are not allowed.

CMake 2.6.3 and below silently permitted add_subdirectory() calls to
create the same binary directory multiple times.  During build system
generation files would be written and then overwritten in the build tree
and could lead to strange behavior.  CMake 2.6.4 and above explicitly
detect duplicate binary directories.  CMake 2.6.4 always considers this
case an error.  In CMake 2.8.0 and above this policy determines whether
or not the case is an error.  The ‘OLD’ behavior for this policy is to
allow duplicate binary directories.  The NEW behavior for this policy is
to disallow duplicate binary directories with an error.

This policy was introduced in CMake version 2.8.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.20.12 CMP0012
----------------

if() recognizes numbers and boolean constants.

In CMake versions 2.6.4 and lower the if() command
implicitly dereferenced arguments corresponding to variables, even those
named like numbers or boolean constants, except for ‘0’ and ‘1’.
Numbers and boolean constants such as ‘true’, ‘false’, ‘yes’, ‘no’,
‘on’, ‘off’, ‘y’, ‘n’, ‘notfound’, ‘ignore’ (all case insensitive) were
recognized in some cases but not all.  For example, the code ‘if(TRUE)’
might have evaluated as ‘false’.  Numbers such as 2 were recognized only
in boolean expressions like ‘if(NOT 2)’ (leading to ‘false’) but not as
a single-argument like ‘if(2)’ (also leading to ‘false’).  Later
versions of CMake prefer to treat numbers and boolean constants
literally, so they should not be used as variable names.

The ‘OLD’ behavior for this policy is to implicitly dereference
variables named like numbers and boolean constants.  The ‘NEW’ behavior
for this policy is to recognize numbers and boolean constants without
dereferencing variables with such names.

This policy was introduced in CMake version 2.8.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21 Policies Introduced by CMake 2.6
======================================

17.21.1 CMP0011
---------------

Included scripts do automatic cmake_policy(). PUSH and POP.

In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by the
include() and find_package() commands would
affect the includer.  Explicit invocations of ‘cmake_policy(PUSH)’ and
‘cmake_policy(POP)’ were required to isolate policy changes and protect
the includer.  While some scripts intend to affect the policies of their
includer, most do not.  In CMake 2.6.3 and above, see include().
and find_package() by default ‘PUSH’ and ‘POP’ an entry on
the policy stack around an included script, but provide a
‘NO_POLICY_SCOPE’ option to disable it.  This policy determines whether
or not to imply ‘NO_POLICY_SCOPE’ for compatibility.  The ‘OLD’ behavior
for this policy is to imply ‘NO_POLICY_SCOPE’ for include().
and find_package() commands.  The ‘NEW’ behavior for this
policy is to allow the commands to do their default cmake_policy ‘PUSH’
and ‘POP’.

This policy was introduced in CMake version 2.6.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.2 CMP0010
---------------

Bad variable reference syntax is an error.

In CMake 2.6.2 and below, incorrect variable reference syntax such as a
missing close-brace (‘${FOO’) was reported but did not stop processing
of CMake code.  This policy determines whether a bad variable reference
is an error.  The ‘OLD’ behavior for this policy is to warn about the
error, leave the string untouched, and continue.  The ‘NEW’ behavior for
this policy is to report an error.

If CMP0053 is set to ‘NEW’, this policy has no effect and is
treated as always being ‘NEW’.

This policy was introduced in CMake version 2.6.3.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.3 CMP0009
---------------

FILE GLOB_RECURSE calls should not follow symlinks by default.

In CMake 2.6.1 and below, see file(GLOB_RECURSE) calls would
follow through symlinks, sometimes coming up with unexpectedly large
result sets because of symlinks to top level directories that contain
hundreds of thousands of files.

This policy determines whether or not to follow symlinks encountered
during a file(GLOB_RECURSE) call.  The ‘OLD’ behavior for
this policy is to follow the symlinks.  The ‘NEW’ behavior for this
policy is not to follow the symlinks by default, but only if
‘FOLLOW_SYMLINKS’ is given as an additional argument to the ‘FILE’
command.

This policy was introduced in CMake version 2.6.2.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.4 CMP0008
---------------

Libraries linked by full-path must have a valid library file name.

In CMake 2.4 and below it is possible to write code like

     target_link_libraries(myexe /full/path/to/somelib)

where ‘somelib’ is supposed to be a valid library file name such as
‘libsomelib.a’ or ‘somelib.lib’.  For Makefile generators this produces
an error at build time because the dependency on the full path cannot be
found.  For Visual Studio Generators. IDE and Xcode
generators this used to work by accident because CMake would always
split off the library directory and ask the linker to search for the
library by name (‘-lsomelib’ or ‘somelib.lib’).  Despite the failure
with Makefiles, some projects have code like this and build only with
Visual Studio and/or Xcode.  This version of CMake prefers to pass the
full path directly to the native build tool, which will fail in this
case because it does not name a valid library file.

This policy determines what to do with full paths that do not appear to
name a valid library file.  The ‘OLD’ behavior for this policy is to
split the library name from the path and ask the linker to search for
it.  The ‘NEW’ behavior for this policy is to trust the given path and
pass it directly to the native build tool unchanged.

This policy was introduced in CMake version 2.6.1.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.5 CMP0007
---------------

list command no longer ignores empty elements.

This policy determines whether the list command will ignore empty
elements in the list.  CMake 2.4 and below list commands ignored all
empty elements in the list.  For example, ‘a;b;;c’ would have length 3
and not 4.  The ‘OLD’ behavior for this policy is to ignore empty list
elements.  The ‘NEW’ behavior for this policy is to correctly count
empty elements in a list.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.6 CMP0006
---------------

Installing MACOSX_BUNDLE targets requires a ‘BUNDLE
DESTINATION’.

This policy determines whether the install(TARGETS) command
must be given a ‘BUNDLE DESTINATION’ when asked to install a target with
the MACOSX_BUNDLE property set.  CMake 2.4 and below did not
distinguish application bundles from normal executables when installing
targets.  CMake 2.6 provides a ‘BUNDLE’ option to the
install(TARGETS) command that specifies rules specific to
application bundles on the Mac.  Projects should use this option when
installing a target with the MACOSX_BUNDLE property set.

The ‘OLD’ behavior for this policy is to fall back to the ‘RUNTIME
DESTINATION’ if a ‘BUNDLE DESTINATION’ is not given.  The ‘NEW’ behavior
for this policy is to produce an error if a bundle target is installed
without a ‘BUNDLE DESTINATION’.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.7 CMP0005
---------------

Preprocessor definition values are now escaped automatically.

This policy determines whether or not CMake should generate escaped
preprocessor definition values added via add_definitions.  CMake
versions 2.4 and below assumed that only trivial values would be given
for macros in add_definitions calls.  It did not attempt to escape
non-trivial values such as string literals in generated build rules.
CMake versions 2.6 and above support escaping of most values, but cannot
assume the user has not added escapes already in an attempt to work
around limitations in earlier versions.

The ‘OLD’ behavior for this policy is to place definition values given
to add_definitions directly in the generated build rules without
attempting to escape anything.  The ‘NEW’ behavior for this policy is to
generate correct escapes for all native build tools automatically.  See
documentation of the ‘COMPILE_DEFINITIONS’ target property for
limitations of the escaping implementation.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.8 CMP0004
---------------

Libraries linked may not have leading or trailing whitespace.

CMake versions 2.4 and below silently removed leading and trailing
whitespace from libraries linked with code like

     target_link_libraries(myexe " A ")

This could lead to subtle errors in user projects.

The ‘OLD’ behavior for this policy is to silently remove leading and
trailing whitespace.  The ‘NEW’ behavior for this policy is to diagnose
the existence of such whitespace as an error.  The setting for this
policy used when checking the library names is that in effect when the
target is created by an add_executable() or
add_library() command.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.9 CMP0003
---------------

Libraries linked via full path no longer produce linker search paths.

This policy affects how libraries whose full paths are NOT known are
found at link time, but was created due to a change in how CMake deals
with libraries whose full paths are known.  Consider the code

     target_link_libraries(myexe /path/to/libA.so)

CMake 2.4 and below implemented linking to libraries whose full paths
are known by splitting them on the link line into separate components
consisting of the linker search path and the library name.  The example
code might have produced something like

     ... -L/path/to -lA ...

in order to link to library A. An analysis was performed to order
multiple link directories such that the linker would find library A in
the desired location, but there are cases in which this does not work.
CMake versions 2.6 and above use the more reliable approach of passing
the full path to libraries directly to the linker in most cases.  The
example code now produces something like

     ... /path/to/libA.so ....

Unfortunately this change can break code like

     target_link_libraries(myexe /path/to/libA.so B)

where ‘B’ is meant to find ‘/path/to/libB.so’.  This code is wrong
because the user is asking the linker to find library B but has not
provided a linker search path (which may be added with the
link_directories command).  However, with the old linking implementation
the code would work accidentally because the linker search path added
for library A allowed library B to be found.

In order to support projects depending on linker search paths added by
linking to libraries with known full paths, the ‘OLD’ behavior for this
policy will add the linker search paths even though they are not needed
for their own libraries.  When this policy is set to ‘OLD’, CMake will
produce a link line such as

     ... -L/path/to /path/to/libA.so -lB ...

which will allow library B to be found as it was previously.  When this
policy is set to NEW, CMake will produce a link line such as

     ... /path/to/libA.so -lB ...

which more accurately matches what the project specified.

The setting for this policy used when generating the link line is that
in effect when the target is created by an add_executable or add_library
command.  For the example described above, the code

     cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
     add_executable(myexe myexe.c)
     target_link_libraries(myexe /path/to/libA.so B)

will work and suppress the warning for this policy.  It may also be
updated to work with the corrected linking approach:

     cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
     link_directories(/path/to) # needed to find library B
     add_executable(myexe myexe.c)
     target_link_libraries(myexe /path/to/libA.so B)

Even better, library B may be specified with a full path:

     add_executable(myexe myexe.c)
     target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)

When all items on the link line have known paths CMake does not check
this policy so it has no effect.

Note that the warning for this policy will be issued for at most one
target.  This avoids flooding users with messages for every target when
setting the policy once will probably fix all targets.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.10 CMP0002
----------------

Logical target names must be globally unique.

Targets names created with add_executable(),
add_library(), or add_custom_target() are logical build
target names.  Logical target names must be globally unique because:

     - Unique names may be referenced unambiguously both in CMake
       code and on make tool command lines.
     - Logical names are used by Xcode and VS IDE generators
       to produce meaningful project names for the targets.

The logical name of executable and library targets does not have to
correspond to the physical file names built.  Consider using the
OUTPUT_NAME target property to create two targets with the same
physical name while keeping logical names distinct.  Custom targets must
simply have globally unique names (unless one uses the global property
ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.11 CMP0001
----------------

‘CMAKE_BACKWARDS_COMPATIBILITY’ should no longer be used.

The behavior is to check ‘CMAKE_BACKWARDS_COMPATIBILITY’ and present it
to the user.  The ‘NEW’ behavior is to ignore
CMAKE_BACKWARDS_COMPATIBILITY completely.

In CMake 2.4 and below the variable ‘CMAKE_BACKWARDS_COMPATIBILITY’ was
used to request compatibility with earlier versions of CMake.  In CMake
2.6 and above all compatibility issues are handled by policies and the
cmake_policy() command.  However, CMake must still check
‘CMAKE_BACKWARDS_COMPATIBILITY’ for projects written for CMake 2.4 and
below.

This policy was introduced in CMake version 2.6.0.  CMake version 3.19.2
warns when the policy is not set and uses ‘OLD’ behavior.  Use the
cmake_policy() command to set it to ‘OLD’ or ‘NEW’ explicitly.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

17.21.12 CMP0000
----------------

A minimum required CMake version must be specified.

CMake requires that projects specify the version of CMake to which they
have been written.  This policy has been put in place so users trying to
build the project may be told when they need to update their CMake.
Specifying a version also helps the project build with CMake versions
newer than that specified.  Use the cmake_minimum_required().
command at the top of your main ‘CMakeLists.txt’ file:

     cmake_minimum_required(VERSION <major>.<minor>)

where ‘<major>.<minor>’ is the version of CMake you want to support
(such as ‘3.14’).  The command will ensure that at least the given
version of CMake is running and help newer versions be compatible with
the project.  See documentation of cmake_minimum_required().
for details.

Note that the command invocation must appear in the ‘CMakeLists.txt’
file itself; a call in an included file is not sufficient.  However, the
cmake_policy() command may be called to set policy ‘CMP0000’
to ‘OLD’ or ‘NEW’ behavior explicitly.  The ‘OLD’ behavior is to
silently ignore the missing invocation.  The ‘NEW’ behavior is to issue
an error instead of a warning.  An included file may set ‘CMP0000’
explicitly to affect how this policy is enforced for the main
‘CMakeLists.txt’ file.

This policy was introduced in CMake version 2.6.0.

     Note: The ‘OLD’ behavior of a policy is deprecated by definition
     and may be removed in a future version of CMake.

18 cmake-presets(7)
*******************

18.1 Introduction
=================

One problem that CMake users often face is sharing settings with other
people for common ways to configure a project.  This may be done to
support CI builds, or for users who frequently use the same build.
CMake supports two files, ‘CMakePresets.json’ and
‘CMakeUserPresets.json’, that allow users to specify common configure
options and share them with others.

‘CMakePresets.json’ and ‘CMakeUserPresets.json’ live in the project’s
root directory.  They both have exactly the same format, and both are
optional (though at least one must be present if ‘--preset’ is
specified.)  ‘CMakePresets.json’ is meant to save project-wide builds,
while ‘CMakeUserPresets.json’ is meant for developers to save their own
local builds.  ‘CMakePresets.json’ may be checked into a version control
system, and ‘CMakeUserPresets.json’ should NOT be checked in.  For
example, if a project is using Git, ‘CMakePresets.json’ may be tracked,
and ‘CMakeUserPresets.json’ should be added to the ‘.gitignore’.

18.2 Format
===========

     The files are a JSON document with an object as the root:

          {
            "version": 1,
            "cmakeMinimumRequired": {
              "major": 3,
              "minor": 19,
              "patch": 0
            },
            "configurePresets": [
              {
                "name": "default",
                "displayName": "Default Config",
                "description": "Default build using Ninja generator",
                "generator": "Ninja",
                "binaryDir": "${sourceDir}/build/default",
                "cacheVariables": {
                  "FIRST_CACHE_VARIABLE": {
                    "type": "BOOL",
                    "value": "OFF"
                  },
                  "SECOND_CACHE_VARIABLE": "ON"
                },
                "environment": {
                  "MY_ENVIRONMENT_VARIABLE": "Test",
                  "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
                },
                "vendor": {
                  "example.com/ExampleIDE/1.0": {
                    "autoFormat": true
                  }
                }
              },
              {
                "name": "ninja-multi",
                "inherits": "default",
                "displayName": "Ninja Multi-Config",
                "description": "Default build using Ninja Multi-Config generator",
                "generator": "Ninja Multi-Config"
              }
            ],
            "vendor": {
              "example.com/ExampleIDE/1.0": {
                "autoFormat": false
              }
            }
          }

     The root object recognizes the following fields:

     ‘version’

          A required integer representing the version of the JSON
          schema.  Currently, the only supported version is 1.

     ‘cmakeMinimumRequired’

          An optional object representing the minimum version of CMake
          needed to build this project.  This object consists of the
          following fields:

          ‘major’

               An optional integer representing the major version.

          ‘minor’

               An optional integer representing the minor version.

          ‘patch’

               An optional integer representing the patch version.

     ‘vendor’

          An optional map containing vendor-specific information.  CMake
          does not interpret the contents of this field except to verify
          that it is a map if it does exist.  However, the keys should
          be a vendor-specific domain name followed by a ‘/’-separated
          path.  For example, the Example IDE 1.0 could use
          ‘example.com/ExampleIDE/1.0’.  The value of each field can be
          anything desired by the vendor, though will typically be a
          map.

     ‘configurePresets’

          An optional array of configure preset objects.  Each preset
          may contain the following fields:

          ‘name’

               A required string representing the machine-friendly name
               of the preset.  This identifier is used in the ‘--preset’
               argument.  There must not be two presets in the union of
               ‘CMakePresets.json’ and ‘CMakeUserPresets.json’ in the
               same directory with the same name.

          ‘hidden’

               An optional boolean specifying whether or not a preset
               should be hidden.  If a preset is hidden, it cannot be
               used in the ‘--preset=’ argument, will not show up in the
               CMake GUI, and does not have to have a valid
               ‘generator’ or ‘binaryDir’, even from inheritance.
               ‘hidden’ presets are intended to be used as a base for
               other presets to inherit via the ‘inherits’ field.

          ‘inherits’

               An optional array of strings representing the names of
               presets to inherit from.  The preset will inherit all of
               the fields from the ‘inherits’ presets by default (except
               ‘name’, ‘hidden’, ‘inherits’, ‘description’, and
               ‘displayName’), but can override them as desired.  If
               multiple ‘inherits’ presets provide conflicting values
               for the same field, the earlier preset in the ‘inherits’
               list will be preferred.  Presets in ‘CMakePresets.json’
               may not inherit from presets in ‘CMakeUserPresets.json’.

               This field can also be a string, which is equivalent to
               an array containing one string.

          ‘vendor’

               An optional map containing vendor-specific information.
               CMake does not interpret the contents of this field
               except to verify that it is a map if it does exist.
               However, it should follow the same conventions as the
               root-level ‘vendor’ field.  If vendors use their own
               per-preset ‘vendor’ field, they should implement
               inheritance in a sensible manner when appropriate.

          ‘displayName’

               An optional string with a human-friendly name of the
               preset.

          ‘description’

               An optional string with a human-friendly description of
               the preset.

          ‘generator’

               An optional string representing the generator to use for
               the preset.  If ‘generator’ is not specified, it must be
               inherited from the ‘inherits’ preset (unless this preset
               is ‘hidden’).

               Note that for Visual Studio generators, unlike in the
               command line ‘-G’ argument, you cannot include the
               platform name in the generator name.  Use the
               ‘architecture’ field instead.

          ‘architecture’ ‘toolset’

               Optional fields representing the platform and toolset,
               respectively, for generators that support them.  Each may
               be either a string or an object with the following
               fields:

               ‘value’

                    An optional string representing the value.

               ‘strategy’

                    An optional string telling CMake how to handle the
                    ‘architecture’ or ‘toolset’ field.  Valid values
                    are:

                    ‘"set"’

                         Set the respective value.  This will result in
                         an error for generators that do not support the
                         respective field.

                    ‘"external"’

                         Do not set the value, even if the generator
                         supports it.  This is useful if, for example, a
                         preset uses the Ninja generator, and an IDE
                         knows how to set up the Visual C++ environment
                         from the ‘architecture’ and ‘toolset’ fields.
                         In that case, CMake will ignore the field, but
                         the IDE can use them to set up the environment
                         before invoking CMake.

          ‘binaryDir’

               An optional string representing the path to the output
               binary directory.  This field supports macro expansion.
               If a relative path is specified, it is calculated
               relative to the source directory.  If ‘binaryDir’ is not
               specified, it must be inherited from the ‘inherits’
               preset (unless this preset is ‘hidden’).

          ‘cmakeExecutable’

               An optional string representing the path to the CMake
               executable to use for this preset.  This is reserved for
               use by IDEs, and is not used by CMake itself.  IDEs that
               use this field should expand any macros in it.

          ‘cacheVariables’

               An optional map of cache variables.  The key is the
               variable name (which may not be an empty string), and the
               value is either ‘null’, a boolean (which is equivalent to
               a value of ‘"TRUE"’ or ‘"FALSE"’ and a type of ‘BOOL’), a
               string representing the value of the variable (which
               supports macro expansion), or an object with the
               following fields:

               ‘type’

                    An optional string representing the type of the
                    variable.

               ‘value’

                    A required string or boolean representing the value
                    of the variable.  A boolean is equivalent to
                    ‘"TRUE"’ or ‘"FALSE"’.  This field supports macro
                    expansion.

               Cache variables are inherited through the ‘inherits’
               field, and the preset’s variables will be the union of
               its own ‘cacheVariables’ and the ‘cacheVariables’ from
               all its parents.  If multiple presets in this union
               define the same variable, the standard rules of
               ‘inherits’ are applied.  Setting a variable to ‘null’
               causes it to not be set, even if a value was inherited
               from another preset.

          ‘environment’

               An optional map of environment variables.  The key is the
               variable name (which may not be an empty string), and the
               value is either ‘null’ or a string representing the value
               of the variable.  Each variable is set regardless of
               whether or not a value was given to it by the process’s
               environment.  This field supports macro expansion, and
               environment variables in this map may reference each
               other, and may be listed in any order, as long as such
               references do not cause a cycle (for example, if ‘ENV_1’
               is ‘$env{ENV_2}’, ‘ENV_2’ may not be ‘$env{ENV_1}’.)

               Environment variables are inherited through the
               ‘inherits’ field, and the preset’s environment will be
               the union of its own ‘environment’ and the ‘environment’
               from all its parents.  If multiple presets in this union
               define the same variable, the standard rules of
               ‘inherits’ are applied.  Setting a variable to ‘null’
               causes it to not be set, even if a value was inherited
               from another preset.

          ‘warnings’

               An optional object specifying the warnings to enable.
               The object may contain the following fields:

               ‘dev’

                    An optional boolean.  Equivalent to passing ‘-Wdev’
                    or ‘-Wno-dev’ on the command line.  This may not be
                    set to ‘false’ if ‘errors.dev’ is set to ‘true’.

               ‘deprecated’

                    An optional boolean.  Equivalent to passing
                    ‘-Wdeprecated’ or ‘-Wno-deprecated’ on the command
                    line.  This may not be set to ‘false’ if
                    ‘errors.deprecated’ is set to ‘true’.

               ‘uninitialized’

                    An optional boolean.  Setting this to ‘true’ is
                    equivalent to passing ‘--warn-uninitialized’ on the
                    command line.

               ‘unusedCli’

                    An optional boolean.  Setting this to ‘false’ is
                    equivalent to passing ‘--no-warn-unused-cli’ on the
                    command line.

               ‘systemVars’

                    An optional boolean.  Setting this to ‘true’ is
                    equivalent to passing ‘--check-system-vars’ on the
                    command line.

          ‘errors’

               An optional object specifying the errors to enable.  The
               object may contain the following fields:

               ‘dev’

                    An optional boolean.  Equivalent to passing
                    ‘-Werror=dev’ or ‘-Wno-error=dev’ on the command
                    line.  This may not be set to ‘true’ if
                    ‘warnings.dev’ is set to ‘false’.

               ‘deprecated’

                    An optional boolean.  Equivalent to passing
                    ‘-Werror=deprecated’ or ‘-Wno-error=deprecated’ on
                    the command line.  This may not be set to ‘true’ if
                    ‘warnings.deprecated’ is set to ‘false’.

          ‘debug’

               An optional object specifying debug options.  The object
               may contain the following fields:

               ‘output’

                    An optional boolean.  Setting this to ‘true’ is
                    equivalent to passing ‘--debug-output’ on the
                    command line.

               ‘tryCompile’

                    An optional boolean.  Setting this to ‘true’ is
                    equivalent to passing ‘--debug-trycompile’ on the
                    command line.

               ‘find’

                    An optional boolean.  Setting this to ‘true’ is
                    equivalent to passing ‘--debug-find’ on the command
                    line.

     As mentioned above, some fields support macro expansion.  Macros
     are recognized in the form ‘$<macro-namespace>{<macro-name>}’.  All
     macros are evaluated in the context of the preset being used, even
     if the macro is in a field that was inherited from another preset.
     For example, if the ‘Base’ preset sets variable ‘PRESET_NAME’ to
     ‘${presetName}’, and the ‘Derived’ preset inherits from ‘Base’,
     ‘PRESET_NAME’ will be set to ‘Derived’.

     It is an error to not put a closing brace at the end of a macro
     name.  For example, ‘${sourceDir’ is invalid.  A dollar sign (‘$’)
     followed by anything other than a left curly brace (‘{’) with a
     possible namespace is interpreted as a literal dollar sign.

     Recognized macros include:

     ‘${sourceDir}’

          Path to the project source directory.

     ‘${sourceParentDir}’

          Path to the project source directory’s parent directory.

     ‘${sourceDirName}’

          The last filename component of ‘${sourceDir}’.  For example,
          if ‘${sourceDir}’ is ‘/path/to/source’, this would be
          ‘source’.

     ‘${presetName}’

          Name specified in the preset’s ‘name’ field.

     ‘${generator}’

          Generator specified in the preset’s ‘generator’ field.

     ‘${dollar}’

          A literal dollar sign (‘$’).

     ‘$env{<variable-name>}’

          Environment variable with name ‘<variable-name>’.  The
          variable name may not be an empty string.  If the variable is
          defined in the ‘environment’ field, that value is used instead
          of the value from the parent environment.  If the environment
          variable is not defined, this evaluates as an empty string.

          Note that while Windows environment variable names are
          case-insensitive, variable names within a preset are still
          case-sensitive.  This may lead to unexpected results when
          using inconsistent casing.  For best results, keep the casing
          of environment variable names consistent.

     ‘$penv{<variable-name>}’

          Similar to ‘$env{<variable-name>}’, except that the value only
          comes from the parent environment, and never from the
          ‘environment’ field.  This allows you to prepend or append
          values to existing environment variables.  For example,
          setting ‘PATH’ to ‘/path/to/ninja/bin:$penv{PATH}’ will
          prepend ‘/path/to/ninja/bin’ to the ‘PATH’ environment
          variable.  This is needed because ‘$env{<variable-name>}’ does
          not allow circular references.

     ‘$vendor{<macro-name>}’

          An extension point for vendors to insert their own macros.
          CMake will not be able to use presets which have a
          ‘$vendor{<macro-name>}’ macro, and effectively ignores such
          presets.  However, it will still be able to use other presets
          from the same file.

          CMake does not make any attempt to interpret
          ‘$vendor{<macro-name>}’ macros.  However, to avoid name
          collisions, IDE vendors should prefix ‘<macro-name>’ with a
          very short (preferably <= 4 characters) vendor identifier
          prefix, followed by a ‘.’, followed by the macro name.  For
          example, the Example IDE could have
          ‘$vendor{xide.ideInstallDir}’.

18.3 Schema
===========

‘This file’ provides a machine-readable JSON schema for the
‘CMakePresets.json’ format.

19 cmake-properties(7)
**********************

19.1 Properties of Global Scope
===============================

19.1.1 ALLOW_DUPLICATE_CUSTOM_TARGETS
-------------------------------------

Allow duplicate custom targets to be created.

Normally CMake requires that all targets built in a project have
globally unique logical names (see policy CMP0002).  This is
necessary to generate meaningful project file names in Xcode.
and Visual Studio Generators. IDE generators.  It also allows
the target names to be referenced unambiguously.

Makefile generators are capable of supporting duplicate
add_custom_target() names.  For projects that care only about
Makefile Generators and do not wish to support Xcode
or Visual Studio Generators. IDE generators, one may set
this property to ‘True’ to allow duplicate custom targets.  The property
allows multiple add_custom_target() command calls in
different directories to specify the same target name.  However, setting
this property will cause non-Makefile generators to produce an error and
refuse to generate the project.

19.1.2 AUTOGEN_SOURCE_GROUP
---------------------------

New in version 3.9.

Name of the source_group() for AUTOMOC and
AUTORCC generated files.

Files generated by AUTOMOC and AUTORCC are not
always known at configure time and therefore can’t be passed to
source_group().  AUTOGEN_SOURCE_GROUP an be used
instead to generate or select a source group for AUTOMOC and
AUTORCC generated files.

For AUTOMOC and AUTORCC specific overrides see
AUTOMOC_SOURCE_GROUP and AUTORCC_SOURCE_GROUP.
respectively.

19.1.3 AUTOGEN_TARGETS_FOLDER
-----------------------------

Name of FOLDER for ‘*_autogen’ targets that are added
automatically by CMake for targets for which AUTOMOC is
enabled.

If not set, CMake uses the FOLDER property of the parent
target as a default value for this property.  See also the documentation
for the FOLDER target property and the AUTOMOC.
target property.

19.1.4 AUTOMOC_SOURCE_GROUP
---------------------------

New in version 3.9.

Name of the source_group() for AUTOMOC generated
files.

When set this is used instead of AUTOGEN_SOURCE_GROUP for
files generated by AUTOMOC.

19.1.5 AUTOMOC_TARGETS_FOLDER
-----------------------------

Name of FOLDER for ‘*_autogen’ targets that are added
automatically by CMake for targets for which AUTOMOC is
enabled.

This property is obsolete.  Use AUTOGEN_TARGETS_FOLDER.
instead.

If not set, CMake uses the FOLDER property of the parent
target as a default value for this property.  See also the documentation
for the FOLDER target property and the AUTOMOC.
target property.

19.1.6 AUTORCC_SOURCE_GROUP
---------------------------

New in version 3.9.

Name of the source_group() for AUTORCC generated
files.

When set this is used instead of AUTOGEN_SOURCE_GROUP for
files generated by AUTORCC.

19.1.7 CMAKE_C_KNOWN_FEATURES
-----------------------------

New in version 3.1.

List of C features known to this version of CMake.

The features listed in this global property may be known to be available
to the C compiler.  If the feature is available with the C compiler, it
will be listed in the CMAKE_C_COMPILE_FEATURES variable.

The features listed here may be used with the
target_compile_features() command.  See the
cmake-compile-features(7) manual for information on compile
features and a list of supported compilers.

The features known to this version of CMake are:

‘c_std_90’

     Compiler mode is at least C 90.

‘c_std_99’

     Compiler mode is at least C 99.

‘c_std_11’

     Compiler mode is at least C 11.

‘c_function_prototypes’

     Function prototypes, as defined in ‘ISO/IEC 9899:1990’.

‘c_restrict’

     ‘restrict’ keyword, as defined in ‘ISO/IEC 9899:1999’.

‘c_static_assert’

     Static assert, as defined in ‘ISO/IEC 9899:2011’.

‘c_variadic_macros’

     Variadic macros, as defined in ‘ISO/IEC 9899:1999’.

19.1.8 CMAKE_CUDA_KNOWN_FEATURES
--------------------------------

New in version 3.17.

List of CUDA features known to this version of CMake.

The features listed in this global property may be known to be available
to the CUDA compiler.  If the feature is available with the C++
compiler, it will be listed in the CMAKE_CUDA_COMPILE_FEATURES
variable.

The features listed here may be used with the
target_compile_features() command.  See the
cmake-compile-features(7) manual for information on compile
features and a list of supported compilers.

The features known to this version of CMake are:

‘cuda_std_03’

     Compiler mode is at least CUDA/C++ 03.

‘cuda_std_11’

     Compiler mode is at least CUDA/C++ 11.

‘cuda_std_14’

     Compiler mode is at least CUDA/C++ 14.

‘cuda_std_17’

     Compiler mode is at least CUDA/C++ 17.

‘cuda_std_20’

     Compiler mode is at least CUDA/C++ 20.

19.1.9 CMAKE_CXX_KNOWN_FEATURES
-------------------------------

New in version 3.1.

List of C++ features known to this version of CMake.

The features listed in this global property may be known to be available
to the C++ compiler.  If the feature is available with the C++ compiler,
it will be listed in the CMAKE_CXX_COMPILE_FEATURES.
variable.

The features listed here may be used with the
target_compile_features() command.  See the
cmake-compile-features(7) manual for information on compile
features and a list of supported compilers.

The features known to this version of CMake are listed below.

19.1.9.1 High level meta features indicating C++ standard support
.................................................................

The following meta features indicate general support for the associated
language standard.  It reflects the language support claimed by the
compiler, but it does not necessarily imply complete conformance to that
standard.

‘cxx_std_98’

     Compiler mode is at least C++ 98.

‘cxx_std_11’

     Compiler mode is at least C++ 11.

‘cxx_std_14’

     Compiler mode is at least C++ 14.

‘cxx_std_17’

     Compiler mode is at least C++ 17.

‘cxx_std_20’

     Compiler mode is at least C++ 20.

19.1.9.2 Low level individual compile features
..............................................

For C++ 11 and C++ 14, compilers were sometimes slow to implement
certain language features.  CMake provided some individual compile
features to help projects determine whether specific features were
available.  These individual features are now less relevant and projects
should generally prefer to use the high level meta features instead.
Individual compile features are not provided for C++ 17 or later.

See the cmake-compile-features(7) manual for further
discussion of the use of individual compile features.

19.1.9.3 Individual features from C++ 98
........................................

‘cxx_template_template_parameters’

     Template template parameters, as defined in ‘ISO/IEC 14882:1998’.

19.1.9.4 Individual features from C++ 11
........................................

‘cxx_alias_templates’

     Template aliases, as defined in N2258(1).

‘cxx_alignas’

     Alignment control ‘alignas’, as defined in N2341(2).

‘cxx_alignof’

     Alignment control ‘alignof’, as defined in N2341(3).

‘cxx_attributes’

     Generic attributes, as defined in N2761(4).

‘cxx_auto_type’

     Automatic type deduction, as defined in N1984(5).

‘cxx_constexpr’

     Constant expressions, as defined in N2235(6).

‘cxx_decltype_incomplete_return_types’

     Decltype on incomplete return types, as defined in N3276(7).

‘cxx_decltype’

     Decltype, as defined in N2343(8).

‘cxx_default_function_template_args’

     Default template arguments for function templates, as defined in
     DR226(9)

‘cxx_defaulted_functions’

     Defaulted functions, as defined in N2346(10).

‘cxx_defaulted_move_initializers’

     Defaulted move initializers, as defined in N3053(11).

‘cxx_delegating_constructors’

     Delegating constructors, as defined in N1986(12).

‘cxx_deleted_functions’

     Deleted functions, as defined in N2346(13).

‘cxx_enum_forward_declarations’

     Enum forward declarations, as defined in N2764(14).

‘cxx_explicit_conversions’

     Explicit conversion operators, as defined in N2437(15).

‘cxx_extended_friend_declarations’

     Extended friend declarations, as defined in N1791(16).

‘cxx_extern_templates’

     Extern templates, as defined in N1987(17).

‘cxx_final’

     Override control ‘final’ keyword, as defined in N2928(18),
     N3206(19) and N3272(20).

‘cxx_func_identifier’

     Predefined ‘__func__’ identifier, as defined in N2340(21).

‘cxx_generalized_initializers’

     Initializer lists, as defined in N2672(22).

‘cxx_inheriting_constructors’

     Inheriting constructors, as defined in N2540(23).

‘cxx_inline_namespaces’

     Inline namespaces, as defined in N2535(24).

‘cxx_lambdas’

     Lambda functions, as defined in N2927(25).

‘cxx_local_type_template_args’

     Local and unnamed types as template arguments, as defined in
     N2657(26).

‘cxx_long_long_type’

     ‘long long’ type, as defined in N1811(27).

‘cxx_noexcept’

     Exception specifications, as defined in N3050(28).

‘cxx_nonstatic_member_init’

     Non-static data member initialization, as defined in N2756(29).

‘cxx_nullptr’

     Null pointer, as defined in N2431(30).

‘cxx_override’

     Override control ‘override’ keyword, as defined in N2928(31),
     N3206(32) and N3272(33).

‘cxx_range_for’

     Range-based for, as defined in N2930(34).

‘cxx_raw_string_literals’

     Raw string literals, as defined in N2442(35).

‘cxx_reference_qualified_functions’

     Reference qualified functions, as defined in N2439(36).

‘cxx_right_angle_brackets’

     Right angle bracket parsing, as defined in N1757(37).

‘cxx_rvalue_references’

     R-value references, as defined in N2118(38).

‘cxx_sizeof_member’

     Size of non-static data members, as defined in N2253(39).

‘cxx_static_assert’

     Static assert, as defined in N1720(40).

‘cxx_strong_enums’

     Strongly typed enums, as defined in N2347(41).

‘cxx_thread_local’

     Thread-local variables, as defined in N2659(42).

‘cxx_trailing_return_types’

     Automatic function return type, as defined in N2541(43).

‘cxx_unicode_literals’

     Unicode string literals, as defined in N2442(44).

‘cxx_uniform_initialization’

     Uniform initialization, as defined in N2640(45).

‘cxx_unrestricted_unions’

     Unrestricted unions, as defined in N2544(46).

‘cxx_user_literals’

     User-defined literals, as defined in N2765(47).

‘cxx_variadic_macros’

     Variadic macros, as defined in N1653(48).

‘cxx_variadic_templates’

     Variadic templates, as defined in N2242(49).

   ---------- Footnotes ----------

   (1) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2258.pdf

   (2) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf

   (3) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf

   (4) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf

   (5) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf

   (6) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf

   (7) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf

   (8) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf

   (9) http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226

   (10)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm

   (11)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3053.html

   (12)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf

   (13)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm

   (14)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf

   (15)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf

   (16)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1791.pdf

   (17)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm

   (18)
http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm

   (19)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm

   (20)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm

   (21)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2340.htm

   (22)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm

   (23)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm

   (24)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm

   (25)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf

   (26)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm

   (27)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1811.pdf

   (28)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3050.html

   (29)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm

   (30)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf

   (31)
http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm

   (32)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm

   (33)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm

   (34)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html

   (35)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm

   (36)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm

   (37)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html

   (38)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html

   (39)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2253.html

   (40)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html

   (41)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf

   (42)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm

   (43)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm

   (44)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm

   (45)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2640.pdf

   (46)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2544.pdf

   (47)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf

   (48)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1653.htm

   (49)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf

19.1.9.5 Individual features from C++ 14
........................................

‘cxx_aggregate_default_initializers’

     Aggregate default initializers, as defined in N3605(1).

‘cxx_attribute_deprecated’

     ‘[[deprecated]]’ attribute, as defined in N3760(2).

‘cxx_binary_literals’

     Binary literals, as defined in N3472(3).

‘cxx_contextual_conversions’

     Contextual conversions, as defined in N3323(4).

‘cxx_decltype_auto’

     ‘decltype(auto)’ semantics, as defined in N3638(5).

‘cxx_digit_separators’

     Digit separators, as defined in N3781(6).

‘cxx_generic_lambdas’

     Generic lambdas, as defined in N3649(7).

‘cxx_lambda_init_captures’

     Initialized lambda captures, as defined in N3648(8).

‘cxx_relaxed_constexpr’

     Relaxed constexpr, as defined in N3652(9).

‘cxx_return_type_deduction’

     Return type deduction on normal functions, as defined in N3386(10).

‘cxx_variable_templates’

     Variable templates, as defined in N3651(11).

   ---------- Footnotes ----------

   (1)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html

   (2)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html

   (3) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf

   (4) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf

   (5)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html

   (6) http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf

   (7)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html

   (8)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html

   (9)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html

   (10)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html

   (11)
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf

19.1.10 CMAKE_ROLE
------------------

New in version 3.14.

Tells what mode the current running script is in.  Could be one of
several values:

‘PROJECT’

     Running in project mode (processing a ‘CMakeLists.txt’ file).

‘SCRIPT’

     Running in ‘-P’ script mode.

‘FIND_PACKAGE’

     Running in ‘--find-package’ mode.

‘CTEST’

     Running in CTest script mode.

‘CPACK’

     Running in CPack.

19.1.11 DEBUG_CONFIGURATIONS
----------------------------

Specify which configurations are for debugging.

The value must be a semi-colon separated list of configuration names.
Currently this property is used only by the
target_link_libraries() command.  Additional uses may be defined in
the future.

This property must be set at the top level of the project and before the
first target_link_libraries() command invocation.  If any
entry in the list does not match a valid configuration for the project
the behavior is undefined.

19.1.12 DISABLED_FEATURES
-------------------------

List of features which are disabled during the CMake run.

List of features which are disabled during the CMake run.  By default it
contains the names of all packages which were not found.  This is
determined using the ‘<NAME>_FOUND’ variables.  Packages which are
searched ‘QUIET’ are not listed.  A project can add its own features to
this list.  This property is used by the macros in
‘FeatureSummary.cmake’.

19.1.13 ECLIPSE_EXTRA_CPROJECT_CONTENTS
---------------------------------------

New in version 3.12.

Additional contents to be inserted into the generated Eclipse cproject
file.

The cproject file defines the CDT specific information.  Some third
party IDE’s are based on Eclipse with the addition of other information
specific to that IDE. Through this property, it is possible to add this
additional contents to the generated project.  It is expected to contain
valid XML.

Also see the ECLIPSE_EXTRA_NATURES property.

19.1.14 ECLIPSE_EXTRA_NATURES
-----------------------------

List of natures to add to the generated Eclipse project file.

Eclipse projects specify language plugins by using natures.  This
property should be set to the unique identifier for a nature (which
looks like a Java package name).

Also see the ECLIPSE_EXTRA_CPROJECT_CONTENTS property.

19.1.15 ENABLED_FEATURES
------------------------

List of features which are enabled during the CMake run.

List of features which are enabled during the CMake run.  By default it
contains the names of all packages which were found.  This is determined
using the ‘<NAME>_FOUND’ variables.  Packages which are searched ‘QUIET’
are not listed.  A project can add its own features to this list.  This
property is used by the macros in ‘FeatureSummary.cmake’.

19.1.16 ENABLED_LANGUAGES
-------------------------

Read-only property that contains the list of currently enabled languages

Set to list of currently enabled languages.

19.1.17 FIND_LIBRARY_USE_LIB32_PATHS
------------------------------------

New in version 3.7.

Whether the find_library() command should automatically
search ‘lib32’ directories.

‘FIND_LIBRARY_USE_LIB32_PATHS’ is a boolean specifying whether the
find_library() command should automatically search the ‘lib32’
variant of directories called ‘lib’ in the search path when building
32-bit binaries.

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

19.1.18 FIND_LIBRARY_USE_LIB64_PATHS
------------------------------------

Whether find_library() should automatically search lib64
directories.

FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
find_library() command should automatically search the lib64
variant of directories called lib in the search path when building
64-bit binaries.

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

19.1.19 FIND_LIBRARY_USE_LIBX32_PATHS
-------------------------------------

New in version 3.9.

Whether the find_library() command should automatically
search ‘libx32’ directories.

‘FIND_LIBRARY_USE_LIBX32_PATHS’ is a boolean specifying whether the
find_library() command should automatically search the
‘libx32’ variant of directories called ‘lib’ in the search path when
building x32-abi binaries.

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

19.1.20 FIND_LIBRARY_USE_OPENBSD_VERSIONING
-------------------------------------------

Whether find_library() should find OpenBSD-style shared
libraries.

This property is a boolean specifying whether the find_library()
command should find shared libraries with OpenBSD-style versioned
extension: “.so.<major>.<minor>”.  The property is set to true on
OpenBSD and false on other platforms.

19.1.21 GENERATOR_IS_MULTI_CONFIG
---------------------------------

New in version 3.9.

Read-only property that is true on multi-configuration generators.

True when using a multi-configuration generator (such as Visual Studio Generators
or Xcode).  Multi-config generators
use CMAKE_CONFIGURATION_TYPES as the set of configurations
and ignore CMAKE_BUILD_TYPE.

19.1.22 GLOBAL_DEPENDS_DEBUG_MODE
---------------------------------

Enable global target dependency graph debug mode.

CMake automatically analyzes the global inter-target dependency graph at
the beginning of native build system generation.  This property causes
it to display details of its analysis to stderr.

19.1.23 GLOBAL_DEPENDS_NO_CYCLES
--------------------------------

Disallow global target dependency graph cycles.

CMake automatically analyzes the global inter-target dependency graph at
the beginning of native build system generation.  It reports an error if
the dependency graph contains a cycle that does not consist of all
STATIC library targets.  This property tells CMake to disallow all
cycles completely, even among static libraries.

19.1.24 IN_TRY_COMPILE
----------------------

Read-only property that is true during a try-compile configuration.

True when building a project inside a try_compile() or
try_run() command.

19.1.25 JOB_POOLS
-----------------

Ninja only: List of available pools.

A pool is a named integer property and defines the maximum number of
concurrent jobs which can be started by a rule assigned to the pool.
The JOB_POOLS property is a semicolon-separated list of
pairs using the syntax NAME=integer (without a space after the equality
sign).

For instance:

     set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10)

Defined pools could be used globally by setting
CMAKE_JOB_POOL_COMPILE and CMAKE_JOB_POOL_LINK or per
target by setting the target properties JOB_POOL_COMPILE and
JOB_POOL_LINK.  Custom commands and custom targets
can specify pools using the option ‘JOB_POOL’.  Using a
pool that is not defined by JOB_POOLS causes an error by
ninja at build time.

If not set, this property uses the value of the CMAKE_JOB_POOLS
variable.

Build targets provided by CMake that are meant for individual
interactive use, such as ‘install’, are placed in the ‘console’ pool
automatically.

19.1.26 PACKAGES_FOUND
----------------------

List of packages which were found during the CMake run.

List of packages which were found during the CMake run.  Whether a
package has been found is determined using the <NAME>_FOUND variables.

19.1.27 PACKAGES_NOT_FOUND
--------------------------

List of packages which were not found during the CMake run.

List of packages which were not found during the CMake run.  Whether a
package has been found is determined using the <NAME>_FOUND variables.

19.1.28 PREDEFINED_TARGETS_FOLDER
---------------------------------

Name of FOLDER for targets that are added automatically by CMake.

If not set, CMake uses “CMakePredefinedTargets” as a default value for
this property.  Targets such as INSTALL, PACKAGE and RUN_TESTS will be
organized into this FOLDER. See also the documentation for the
FOLDER target property.

19.1.29 REPORT_UNDEFINED_PROPERTIES
-----------------------------------

If set, report any undefined properties to this file.

If this property is set to a filename then when CMake runs it will
report any properties or variables that were accessed but not defined
into the filename specified in this property.

19.1.30 RULE_LAUNCH_COMPILE
---------------------------

Specify a launcher for compile rules.

Makefile Generators and the Ninja generator prefix
compiler commands with the given launcher command line.  This is
intended to allow launchers to intercept build problems with high
granularity.  Other generators ignore this property because their
underlying build systems provide no hook to wrap individual commands
with a launcher.

19.1.31 RULE_LAUNCH_CUSTOM
--------------------------

Specify a launcher for custom rules.

Makefile Generators and the Ninja generator prefix
custom commands with the given launcher command line.  This is intended
to allow launchers to intercept build problems with high granularity.
Other generators ignore this property because their underlying build
systems provide no hook to wrap individual commands with a launcher.

19.1.32 RULE_LAUNCH_LINK
------------------------

Specify a launcher for link rules.

Makefile Generators and the Ninja generator prefix
link and archive commands with the given launcher command line.  This is
intended to allow launchers to intercept build problems with high
granularity.  Other generators ignore this property because their
underlying build systems provide no hook to wrap individual commands
with a launcher.

19.1.33 RULE_MESSAGES
---------------------

Specify whether to report a message for each make rule.

This property specifies whether Makefile generators should add a
progress message describing what each build rule does.  If the property
is not set the default is ON. Set the property to OFF to disable
granular messages and report only as each target completes.  This is
intended to allow scripted builds to avoid the build time cost of
detailed reports.  If a CMAKE_RULE_MESSAGES cache entry
exists its value initializes the value of this property.  Non-Makefile
generators currently ignore this property.

19.1.34 TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
------------------------------------------

Set if shared libraries may be named like archives.

On AIX shared libraries may be named “lib<name>.a”.  This property is
set to true on such platforms.

19.1.35 TARGET_MESSAGES
-----------------------

New in version 3.4.

Specify whether to report the completion of each target.

This property specifies whether Makefile Generators should
add a progress message describing that each target has been completed.
If the property is not set the default is ‘ON’.  Set the property to
‘OFF’ to disable target completion messages.

This option is intended to reduce build output when little or no work
needs to be done to bring the build tree up to date.

If a ‘CMAKE_TARGET_MESSAGES’ cache entry exists its value initializes
the value of this property.

Non-Makefile generators currently ignore this property.

See the counterpart property RULE_MESSAGES to disable
everything except for target completion messages.

19.1.36 TARGET_SUPPORTS_SHARED_LIBS
-----------------------------------

Does the target platform support shared libraries.

TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target
platform supports shared libraries.  Basically all current general
general purpose OS do so, the exception are usually embedded systems
with no or special OSs.

19.1.37 USE_FOLDERS
-------------------

Use the FOLDER target property to organize targets into
folders.

If not set, CMake treats this property as ‘OFF’ by default.  CMake
generators that are capable of organizing into a hierarchy of folders
use the values of the FOLDER target property to name those
folders.  See also the documentation for the FOLDER target
property.

19.1.38 XCODE_EMIT_EFFECTIVE_PLATFORM_NAME
------------------------------------------

New in version 3.8.

Control emission of ‘EFFECTIVE_PLATFORM_NAME’ by the Xcode.
generator.

It is required for building the same target with multiple SDKs.  A
common use case is the parallel use of ‘iphoneos’ and ‘iphonesimulator’
SDKs.

Three different states possible that control when the Xcode.
generator emits the ‘EFFECTIVE_PLATFORM_NAME’ variable:

   - If set to ‘ON’ it will always be emitted

   - If set to ‘OFF’ it will never be emitted

   - If unset (the default) it will only be emitted when the project was
     configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
     of the simulators.

     Note: When this behavior is enable for generated Xcode projects,
     the ‘EFFECTIVE_PLATFORM_NAME’ variable will leak into
     Generator expressions like ‘TARGET_FILE’ and will render those
     mostly unusable.

19.2 Properties on Directories
==============================

19.2.1 ADDITIONAL_CLEAN_FILES
-----------------------------

New in version 3.15.

A ;-list of files or directories that will be removed as a
part of the global ‘clean’ target.  It is useful for specifying
generated files or directories that are used by multiple targets or by
CMake itself, or that are generated in ways which cannot be captured as
outputs or byproducts of custom commands.

If an additional clean file is specific to a single target only, then
the ADDITIONAL_CLEAN_FILES target property would usually be
a better choice than this directory property.

Relative paths are allowed and are interpreted relative to the current
binary directory.

Contents of ‘ADDITIONAL_CLEAN_FILES’ may use generator expressions.

This property only works for the Ninja and the Makefile
generators.  It is ignored by other generators.

19.2.2 BINARY_DIR
-----------------

New in version 3.7.

This read-only directory property reports absolute path to the binary
directory corresponding to the source on which it is read.

19.2.3 BUILDSYSTEM_TARGETS
--------------------------

New in version 3.7.

This read-only directory property contains a semicolon-separated list
of buildsystem targets added in the directory by calls to the
add_library(), add_executable(), and
add_custom_target() commands.  The list does not include any
Imported Targets or Alias Targets, but does include
Interface Libraries.  Each entry in the list is the logical
name of a target, suitable to pass to the get_property().
command ‘TARGET’ option.

19.2.4 CACHE_VARIABLES
----------------------

List of cache variables available in the current directory.

This read-only property specifies the list of CMake cache variables
currently defined.  It is intended for debugging purposes.

19.2.5 CLEAN_NO_CUSTOM
----------------------

Set to true to tell Makefile Generators not to remove the
outputs of custom commands for this directory during the ‘make clean’
operation.  This is ignored on other generators because it is not
possible to implement.

19.2.6 CMAKE_CONFIGURE_DEPENDS
------------------------------

Tell CMake about additional input files to the configuration process.
If any named file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.

Specify files as a semicolon-separated list of paths.  Relative paths
are interpreted as relative to the current source directory.

19.2.7 COMPILE_DEFINITIONS
--------------------------

Preprocessor definitions for compiling a directory’s sources.

This property specifies the list of options given so far to the
add_compile_definitions(). (or add_definitions())
command.

The ‘COMPILE_DEFINITIONS’ property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ‘VAR’ or ‘VAR=value’.
Function-style definitions are not supported.  CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).

This property will be initialized in each directory by its value in the
directory’s parent.

CMake will automatically drop some definitions that are not supported by
the native build tool.

Disclaimer: Most native build tools have poor support for escaping
certain values.  CMake has work-arounds for many cases but some values
may just not be possible to pass correctly.  If a value does not seem to
be escaped correctly, do not attempt to work-around the problem by
adding escape sequences to the value.  Your work-around may break in a
future version of CMake that has improved escape support.  Instead
consider defining the macro in a (configured) header file.  Then report
the limitation.  Known limitations include:

     #          - broken almost everywhere
     ;          - broken in VS IDE 7.0 and Borland Makefiles
     ,          - broken in VS IDE
     %          - broken in some cases in NMake
     & |        - broken in some cases on MinGW
     ^ < > \"   - broken in most Make tools on Windows

CMake does not reject these values outright because they do work in some
cases.  Use with caution.

Contents of ‘COMPILE_DEFINITIONS’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

The corresponding COMPILE_DEFINITIONS_<CONFIG> property may
be set to specify per-configuration definitions.  Generator expressions
should be preferred instead of setting the alternative property.

19.2.8 COMPILE_OPTIONS
----------------------

List of options to pass to the compiler.

This property holds a semicolon-separated list of options
given so far to the add_compile_options() command.

This property is used to initialize the COMPILE_OPTIONS.
target property when a target is created, which is used by the
generators to set the options for the compiler.

Contents of ‘COMPILE_OPTIONS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.2.9 DEFINITIONS
------------------

For CMake 2.4 compatibility only.  Use COMPILE_DEFINITIONS.
instead.

This read-only property specifies the list of flags given so far to the
add_definitions() command.  It is intended for debugging
purposes.  Use the COMPILE_DEFINITIONS directory property
instead.

This built-in read-only property does not exist if policy CMP0059
is set to ‘NEW’.

19.2.10 EXCLUDE_FROM_ALL
------------------------

Set this directory property to a true value on a subdirectory to exclude
its targets from the “all” target of its ancestors.  If excluded,
running e.g.  ‘make’ in the parent directory will not build targets the
subdirectory by default.  This does not affect the “all” target of the
subdirectory itself.  Running e.g.  ‘make’ inside the subdirectory will
still build its targets.

If the EXCLUDE_FROM_ALL target property is set on a target
then its value determines whether the target is included in the “all”
target of this directory and its ancestors.

19.2.11 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
------------------------------------------

Specify ‘#include’ line transforms for dependencies in a directory.

This property specifies rules to transform macro-like ‘#include’ lines
during implicit dependency scanning of C and C++ source files.  The list
of rules must be semicolon-separated with each entry of the form
‘A_MACRO(%)=value-with-%’ (the ‘%’ must be literal).  During dependency
scanning occurrences of ‘A_MACRO(...)’ on ‘#include’ lines will be
replaced by the value given with the macro argument substituted for ‘%’.
For example, the entry

     MYDIR(%)=<mydir/%>

will convert lines of the form

     #include MYDIR(myheader.h)

to

     #include <mydir/myheader.h>

allowing the dependency to be followed.

This property applies to sources in all targets within a directory.  The
property value is initialized in each directory by its value in the
directory’s parent.

19.2.12 INCLUDE_DIRECTORIES
---------------------------

List of preprocessor include file search directories.

This property specifies the list of directories given so far to the
include_directories() command.

This property is used to populate the INCLUDE_DIRECTORIES.
target property, which is used by the generators to set the include
directories for the compiler.

In addition to accepting values from that command, values may be set
directly on any directory using the set_property() command,
and can be set on the current directory using the
set_directory_properties() command.  A directory gets its initial
value from its parent directory if it has one.  The initial value of the
INCLUDE_DIRECTORIES target property comes from the value of
this property.  Both directory and target property values are adjusted
by calls to the include_directories() command.  Calls to
set_property() or set_directory_properties(),
however, will update the directory property value without updating
target property values.  Therefore direct property updates must be made
before calls to add_executable() or add_library().
for targets they are meant to affect.

The target property values are used by the generators to set the include
paths for the compiler.

Contents of ‘INCLUDE_DIRECTORIES’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.2.13 INCLUDE_REGULAR_EXPRESSION
----------------------------------

Include file scanning regular expression.

This property specifies the regular expression used during dependency
scanning to match include files that should be followed.  See the
include_regular_expression() command for a high-level interface to
set this property.

19.2.14 INTERPROCEDURAL_OPTIMIZATION
------------------------------------

Enable interprocedural optimization for targets in a directory.

If set to true, enables interprocedural optimizations if they are known
to be supported by the compiler.

19.2.15 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
---------------------------------------------

Per-configuration interprocedural optimization for a directory.

This is a per-configuration version of ‘INTERPROCEDURAL_OPTIMIZATION’.
If set, this property overrides the generic property for the named
configuration.

19.2.16 LABELS
--------------

New in version 3.10.

Specify a list of text labels associated with a directory and all of its
subdirectories.  This is equivalent to setting the LABELS.
target property and the LABELS test property on all targets
and tests in the current directory and subdirectories.  Note: Launchers
must enabled to propagate labels to targets.

The CMAKE_DIRECTORY_LABELS variable can be used to
initialize this property.

The list is reported in dashboard submissions.

19.2.17 LINK_DIRECTORIES
------------------------

List of linker search directories.

This property holds a semicolon-separated list of directories
and is typically populated using the link_directories().
command.  It gets its initial value from its parent directory, if it has
one.

The directory property is used to initialize the LINK_DIRECTORIES
target property when a target is created.  That target property is
used by the generators to set the library search directories for the
linker.

Contents of ‘LINK_DIRECTORIES’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.2.18 LINK_OPTIONS
--------------------

New in version 3.13.

List of options to use for the link step of shared library, module and
executable targets as well as the device link step.

This property holds a semicolon-separated list of options
given so far to the add_link_options() command.

This property is used to initialize the LINK_OPTIONS target
property when a target is created, which is used by the generators to
set the options for the compiler.

Contents of ‘LINK_OPTIONS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.2.19 LISTFILE_STACK
----------------------

The current stack of listfiles being processed.

This property is mainly useful when trying to debug errors in your CMake
scripts.  It returns a list of what list files are currently being
processed, in order.  So if one listfile does an include().
command then that is effectively pushing the included listfile onto the
stack.

19.2.20 MACROS
--------------

List of macro commands available in the current directory.

This read-only property specifies the list of CMake macros currently
defined.  It is intended for debugging purposes.  See the macro()
command.

19.2.21 PARENT_DIRECTORY
------------------------

Source directory that added current subdirectory.

This read-only property specifies the source directory that added the
current source directory as a subdirectory of the build.  In the
top-level directory the value is the empty-string.

19.2.22 RULE_LAUNCH_COMPILE
---------------------------

Specify a launcher for compile rules.

See the global property of the same name for details.  This overrides
the global property for a directory.

19.2.23 RULE_LAUNCH_CUSTOM
--------------------------

Specify a launcher for custom rules.

See the global property of the same name for details.  This overrides
the global property for a directory.

19.2.24 RULE_LAUNCH_LINK
------------------------

Specify a launcher for link rules.

See the global property of the same name for details.  This overrides
the global property for a directory.

19.2.25 SOURCE_DIR
------------------

New in version 3.7.

This read-only directory property reports absolute path to the source
directory on which it is read.

19.2.26 SUBDIRECTORIES
----------------------

New in version 3.7.

This read-only directory property contains a semicolon-separated list
of subdirectories processed so far by the
add_subdirectory() or subdirs() commands.  Each entry
is the absolute path to the source directory (containing the
‘CMakeLists.txt’ file).  This is suitable to pass to the
get_property() command ‘DIRECTORY’ option.

     Note: The subdirs() command does not process its
     arguments until after the calling directory is fully processed.
     Therefore looking up this property in the current directory will
     not see them.

19.2.27 TESTS
-------------

New in version 3.12.

List of tests.

This read-only property holds a semicolon-separated list of
tests defined so far, in the current directory, by the add_test()
command.

19.2.28 TEST_INCLUDE_FILES
--------------------------

New in version 3.10.

A list of cmake files that will be included when ctest is run.

If you specify ‘TEST_INCLUDE_FILES’, those files will be included and
processed when ctest is run on the directory.

19.2.29 VARIABLES
-----------------

List of variables defined in the current directory.

This read-only property specifies the list of CMake variables currently
defined.  It is intended for debugging purposes.

19.2.30 VS_GLOBAL_SECTION_POST_<section>
----------------------------------------

Specify a postSolution global section in Visual Studio.

Setting a property like this generates an entry of the following form in
the solution file:

     GlobalSection(<section>) = postSolution
       <contents based on property value>
     EndGlobalSection

The property must be set to a semicolon-separated list of ‘key=value’
pairs.  Each such pair will be transformed into an entry in the solution
global section.  Whitespace around key and value is ignored.  List
elements which do not contain an equal sign are skipped.

This property only works for Visual Studio 9 and above; it is ignored on
other generators.  The property only applies when set on a directory
whose ‘CMakeLists.txt’ contains a project() command.

Note that CMake generates postSolution sections ‘ExtensibilityGlobals’
and ‘ExtensibilityAddIns’ by default.  If you set the corresponding
property, it will override the default section.  For example, setting
‘VS_GLOBAL_SECTION_POST_ExtensibilityGlobals’ will override the default
contents of the ‘ExtensibilityGlobals’ section, while keeping
ExtensibilityAddIns on its default.  However, CMake will always add a
‘SolutionGuid’ to the ‘ExtensibilityGlobals’ section if it is not
specified explicitly.

19.2.31 VS_GLOBAL_SECTION_PRE_<section>
---------------------------------------

Specify a preSolution global section in Visual Studio.

Setting a property like this generates an entry of the following form in
the solution file:

     GlobalSection(<section>) = preSolution
       <contents based on property value>
     EndGlobalSection

The property must be set to a semicolon-separated list of ‘key=value’
pairs.  Each such pair will be transformed into an entry in the solution
global section.  Whitespace around key and value is ignored.  List
elements which do not contain an equal sign are skipped.

This property only works for Visual Studio 9 and above; it is ignored on
other generators.  The property only applies when set on a directory
whose ‘CMakeLists.txt’ contains a project() command.

19.2.32 VS_STARTUP_PROJECT
--------------------------

New in version 3.6.

Specify the default startup project in a Visual Studio solution.

The Visual Studio Generators create a ‘.sln’ file for each
directory whose ‘CMakeLists.txt’ file calls the project().
command.  Set this property in the same directory as a project()
command call (e.g.  in the top-level ‘CMakeLists.txt’ file) to
specify the default startup project for the corresponding solution file.

The property must be set to the name of an existing target.  This will
cause that project to be listed first in the generated solution file
causing Visual Studio to make it the startup project if the solution has
never been opened before.

If this property is not specified, then the ‘ALL_BUILD’ project will be
the default.

19.3 Properties on Targets
==========================

19.3.1 ADDITIONAL_CLEAN_FILES
-----------------------------

New in version 3.15.

A ;-list of files or directories that will be removed as a
part of the global ‘clean’ target.  It can be used to specify files and
directories that are generated as part of building the target or that
are directly associated with the target in some way (e.g.  created as a
result of running the target).

For custom targets, if such files can be captured as outputs or
byproducts instead, then that should be preferred over adding them to
this property.  If an additional clean file is used by multiple targets
or isn’t target-specific, then the ADDITIONAL_CLEAN_FILES.
directory property may be the more appropriate property to use.

Relative paths are allowed and are interpreted relative to the current
binary directory.

Contents of ‘ADDITIONAL_CLEAN_FILES’ may use generator expressions.

This property only works for the Ninja and the Makefile
generators.  It is ignored by other generators.

19.3.2 AIX_EXPORT_ALL_SYMBOLS
-----------------------------

New in version 3.17.

On AIX, CMake automatically exports all symbols from shared libraries,
and from executables with the ENABLE_EXPORTS target property
set.  Explicitly disable this boolean property to suppress the behavior
and export no symbols by default.  In this case it is expected that the
project will use other means to export some symbols.

This property is initialized by the value of the
CMAKE_AIX_EXPORT_ALL_SYMBOLS variable if it is set when a target
is created.

19.3.3 ALIAS_GLOBAL
-------------------

New in version 3.18.

Read-only property indicating of whether an ALIAS target is
globally visible.

The boolean value of this property is ‘TRUE’ for aliases to
IMPORTED targets created with the ‘GLOBAL’ options to
add_executable() or add_library(), ‘FALSE’ otherwise.  It
is undefined for targets built within the project.

     Note: Promoting an IMPORTED target from ‘LOCAL’ to
     ‘GLOBAL’ scope by changing the value or IMPORTED_GLOBAL.
     target property do not change the scope of local aliases.

19.3.4 ALIASED_TARGET
---------------------

Name of target aliased by this target.

If this is an Alias Target, this property contains the name
of the target aliased.

19.3.5 ANDROID_ANT_ADDITIONAL_OPTIONS
-------------------------------------

New in version 3.4.

Set the additional options for Android Ant build system.  This is a
string value containing all command line options for the Ant build.
This property is initialized by the value of the
CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS variable if it is set when a
target is created.

19.3.6 ANDROID_API
------------------

New in version 3.1.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this property sets the Android target API version
(e.g.  ‘15’).  The version number must be a positive decimal integer.
This property is initialized by the value of the
CMAKE_ANDROID_API variable if it is set when a target is created.

19.3.7 ANDROID_API_MIN
----------------------

New in version 3.2.

Set the Android MIN API version (e.g.  ‘9’).  The version number must be
a positive decimal integer.  This property is initialized by the value
of the CMAKE_ANDROID_API_MIN variable if it is set when a
target is created.  Native code builds using this API version.

19.3.8 ANDROID_ARCH
-------------------

New in version 3.4.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this property sets the Android target architecture.

This is a string property that could be set to the one of the following
values:

   * ‘armv7-a’: “ARMv7-A (armv7-a)”

   * ‘armv7-a-hard’: “ARMv7-A, hard-float ABI (armv7-a)”

   * ‘arm64-v8a’: “ARMv8-A, 64bit (arm64-v8a)”

   * ‘x86’: “x86 (x86)”

   * ‘x86_64’: “x86_64 (x86_64)”

This property is initialized by the value of the
CMAKE_ANDROID_ARCH variable if it is set when a target is created.

19.3.9 ANDROID_ASSETS_DIRECTORIES
---------------------------------

New in version 3.4.

Set the Android assets directories to copy into the main assets folder
before build.  This a string property that contains the directory paths
separated by semicolon.  This property is initialized by the value of
the CMAKE_ANDROID_ASSETS_DIRECTORIES variable if it is set
when a target is created.

19.3.10 ANDROID_GUI
-------------------

New in version 3.1.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this property specifies whether to build an
executable as an application package on Android.

When this property is set to true the executable when built for Android
will be created as an application package.  This property is initialized
by the value of the CMAKE_ANDROID_GUI variable if it is set
when a target is created.

Add the ‘AndroidManifest.xml’ source file explicitly to the target
add_executable() command invocation to specify the root directory
of the application package source.

19.3.11 ANDROID_JAR_DEPENDENCIES
--------------------------------

New in version 3.4.

Set the Android property that specifies JAR dependencies.  This is a
string value property.  This property is initialized by the value of the
CMAKE_ANDROID_JAR_DEPENDENCIES variable if it is set when a
target is created.

19.3.12 ANDROID_JAR_DIRECTORIES
-------------------------------

New in version 3.4.

Set the Android property that specifies directories to search for the
JAR libraries.

This a string property that contains the directory paths separated by
semicolons.  This property is initialized by the value of the
CMAKE_ANDROID_JAR_DIRECTORIES variable if it is set when a target
is created.

Contents of ‘ANDROID_JAR_DIRECTORIES’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.

19.3.13 ANDROID_JAVA_SOURCE_DIR
-------------------------------

New in version 3.4.

Set the Android property that defines the Java source code root
directories.  This a string property that contains the directory paths
separated by semicolon.  This property is initialized by the value of
the CMAKE_ANDROID_JAVA_SOURCE_DIR variable if it is set when
a target is created.

19.3.14 ANDROID_NATIVE_LIB_DEPENDENCIES
---------------------------------------

New in version 3.4.

Set the Android property that specifies the .so dependencies.  This is a
string property.

This property is initialized by the value of the
CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES variable if it is set when a
target is created.

Contents of ‘ANDROID_NATIVE_LIB_DEPENDENCIES’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.

19.3.15 ANDROID_NATIVE_LIB_DIRECTORIES
--------------------------------------

New in version 3.4.

Set the Android property that specifies directories to search for the
‘.so’ libraries.

This a string property that contains the directory paths separated by
semicolons.

This property is initialized by the value of the
CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES variable if it is set when a
target is created.

Contents of ‘ANDROID_NATIVE_LIB_DIRECTORIES’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.

19.3.16 ANDROID_PROCESS_MAX
---------------------------

New in version 3.4.

Set the Android property that defines the maximum number of a parallel
Android NDK compiler processes (e.g.  ‘4’).  This property is
initialized by the value of the CMAKE_ANDROID_PROCESS_MAX.
variable if it is set when a target is created.

19.3.17 ANDROID_PROGUARD
------------------------

New in version 3.4.

When this property is set to true that enables the ProGuard tool to
shrink, optimize, and obfuscate the code by removing unused code and
renaming classes, fields, and methods with semantically obscure names.
This property is initialized by the value of the
CMAKE_ANDROID_PROGUARD variable if it is set when a target is
created.

19.3.18 ANDROID_PROGUARD_CONFIG_PATH
------------------------------------

New in version 3.4.

Set the Android property that specifies the location of the ProGuard
config file.  Leave empty to use the default one.  This a string
property that contains the path to ProGuard config file.  This property
is initialized by the value of the
CMAKE_ANDROID_PROGUARD_CONFIG_PATH variable if it is set when a
target is created.

19.3.19 ANDROID_SECURE_PROPS_PATH
---------------------------------

New in version 3.4.

Set the Android property that states the location of the secure
properties file.  This is a string property that contains the file path.
This property is initialized by the value of the
CMAKE_ANDROID_SECURE_PROPS_PATH variable if it is set when a
target is created.

19.3.20 ANDROID_SKIP_ANT_STEP
-----------------------------

New in version 3.4.

Set the Android property that defines whether or not to skip the Ant
build step.  This is a boolean property initialized by the value of the
CMAKE_ANDROID_SKIP_ANT_STEP variable if it is set when a
target is created.

19.3.21 ANDROID_STL_TYPE
------------------------

New in version 3.4.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this property specifies the type of STL support for
the project.  This is a string property that could set to the one of the
following values:

‘none’

     No C++ Support

‘system’

     Minimal C++ without STL

‘gabi++_static’

     GAbi++ Static

‘gabi++_shared’

     GAbi++ Shared

‘gnustl_static’

     GNU libstdc++ Static

‘gnustl_shared’

     GNU libstdc++ Shared

‘stlport_static’

     STLport Static

‘stlport_shared’

     STLport Shared

This property is initialized by the value of the
CMAKE_ANDROID_STL_TYPE variable if it is set when a target is
created.

19.3.22 ARCHIVE_OUTPUT_DIRECTORY
--------------------------------

Output directory in which to build ARCHIVE target files.

This property specifies the directory into which archive target files
should be built.  The property value may use generator expressions.
Multi-configuration generators (VS, Xcode) append a
per-configuration subdirectory to the specified directory unless a
generator expression is used.

This property is initialized by the value of the variable
CMAKE_ARCHIVE_OUTPUT_DIRECTORY if it is set when a target is created.

See also the ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> target
property.

19.3.23 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
-----------------------------------------

Per-configuration output directory for ARCHIVE target files.

This is a per-configuration version of the
ARCHIVE_OUTPUT_DIRECTORY target property, but multi-configuration
generators (VS, Xcode) do NOT append a per-configuration subdirectory to
the specified directory.  This property is initialized by the value of
the CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> variable if it
is set when a target is created.

Contents of ‘ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>’ may use generator expressions.

19.3.24 ARCHIVE_OUTPUT_NAME
---------------------------

Output name for ARCHIVE target files.

This property specifies the base name for archive target files.  It
overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG>.
properties.

See also the ARCHIVE_OUTPUT_NAME_<CONFIG> target property.

19.3.25 ARCHIVE_OUTPUT_NAME_<CONFIG>
------------------------------------

Per-configuration output name for ARCHIVE target files.

This is the configuration-specific version of the
ARCHIVE_OUTPUT_NAME target property.

19.3.26 AUTOGEN_BUILD_DIR
-------------------------

New in version 3.9.

Directory where AUTOMOC, AUTOUIC and
AUTORCC generate files for the target.

The directory is created on demand and automatically added to the
ADDITIONAL_CLEAN_FILES target property.

When unset or empty the directory ‘<dir>/<target-name>_autogen’ is used
where ‘<dir>’ is CMAKE_CURRENT_BINARY_DIR and
‘<target-name>’ is NAME.

By default AUTOGEN_BUILD_DIR is unset.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.27 AUTOGEN_ORIGIN_DEPENDS
------------------------------

New in version 3.14.

Switch for forwarding origin target dependencies to the corresponding
‘_autogen’ target.

Targets which have their AUTOMOC or AUTOUIC.
property ‘ON’ have a corresponding ‘_autogen’ target which generates
‘moc’ and ‘uic’ files.  As this ‘_autogen’ target is created at
generate-time, it is not possible to define dependencies of it using
e.g.  see add_dependencies().  Instead the
AUTOGEN_ORIGIN_DEPENDS target property decides whether the origin
target dependencies should be forwarded to the ‘_autogen’ target or not.

By default AUTOGEN_ORIGIN_DEPENDS is initialized from
CMAKE_AUTOGEN_ORIGIN_DEPENDS which is ‘ON’ by default.

In total the dependencies of the ‘_autogen’ target are composed from

   - forwarded origin target dependencies (enabled by default via
     AUTOGEN_ORIGIN_DEPENDS)

   - additional user defined dependencies from
     AUTOGEN_TARGET_DEPENDS.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.27.1 Note
..............

Disabling AUTOGEN_ORIGIN_DEPENDS is useful to avoid building
of origin target dependencies when building the ‘_autogen’ target only.
This is especially interesting when a global autogen target.
is enabled.

When the ‘_autogen’ target doesn’t require all the origin target’s
dependencies, and AUTOGEN_ORIGIN_DEPENDS is disabled, it
might be necessary to extend AUTOGEN_TARGET_DEPENDS to add
missing dependencies.

19.3.28 AUTOGEN_PARALLEL
------------------------

New in version 3.11.

Number of parallel ‘moc’ or ‘uic’ processes to start when using
AUTOMOC and AUTOUIC.

The custom ‘<origin>_autogen’ target starts a number of threads of which
each one parses a source file and on demand starts a ‘moc’ or ‘uic’
process.  ‘AUTOGEN_PARALLEL’ controls how many parallel threads (and
therefore ‘moc’ or ‘uic’ processes) are started.

   - An empty (or unset) value or the string ‘AUTO’ sets the number of
     threads/processes to the number of physical CPUs on the host
     system.

   - A positive non zero integer value sets the exact thread/process
     count.

   - Otherwise a single thread/process is started.

By default ‘AUTOGEN_PARALLEL’ is initialized from
CMAKE_AUTOGEN_PARALLEL.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.29 AUTOGEN_TARGET_DEPENDS
------------------------------

Additional target dependencies of the corresponding ‘_autogen’ target.

Targets which have their AUTOMOC or AUTOUIC.
property ‘ON’ have a corresponding ‘_autogen’ target which generates
‘moc’ and ‘uic’ files.  As this ‘_autogen’ target is created at
generate-time, it is not possible to define dependencies of it using
e.g.  see add_dependencies().  Instead the
AUTOGEN_TARGET_DEPENDS target property can be set to a
;-list of additional dependencies for the ‘_autogen’ target.
Dependencies can be target names or file names.

In total the dependencies of the ‘_autogen’ target are composed from

   - forwarded origin target dependencies (enabled by default via
     AUTOGEN_ORIGIN_DEPENDS)

   - additional user defined dependencies from
     AUTOGEN_TARGET_DEPENDS.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.29.1 Use cases
...................

If AUTOMOC or AUTOUIC depends on a file that is
either

   - a GENERATED non C++ file (e.g.  a GENERATED.
     ‘.json’ or ‘.ui’ file) or

   - a GENERATED. C++ file that isn’t recognized by
     AUTOMOC and AUTOUIC because it’s skipped by
     SKIP_AUTOMOC, SKIP_AUTOUIC, SKIP_AUTOGEN
     or CMP0071 or

   - a file that isn’t in the origin target’s sources

it must be added to AUTOGEN_TARGET_DEPENDS.

19.3.30 AUTOMOC
---------------

Should the target be processed with auto-moc (for Qt projects).

AUTOMOC is a boolean specifying whether CMake will handle
the Qt ‘moc’ preprocessor automatically, i.e.  without having to use the
QT4_WRAP_CPP() or ‘QT5_WRAP_CPP()’ macro.  Currently Qt4 and
Qt5 are supported.

This property is initialized by the value of the CMAKE_AUTOMOC
variable if it is set when a target is created.

When this property is set ‘ON’, CMake will scan the header and source
files at build time and invoke ‘moc’ accordingly.

19.3.30.1 Header file processing
................................

At configuration time, a list of header files that should be scanned by
AUTOMOC is computed from the target’s sources.

   - All header files in the target’s sources are added to the scan
     list.

   - For all C++ source files ‘<source_base>.<source_extension>’ in the
     target’s sources, CMake searches for

        - a regular header with the same base name
          (‘<source_base>.<header_extention>’) and

        - a private header with the same base name and a ‘_p’ suffix
          (‘<source_base>_p.<header_extention>’)

     and adds these to the scan list.

At build time, CMake scans each unknown or modified header file from the
list and searches for

   - a Qt macro from AUTOMOC_MACRO_NAMES,

   - additional file dependencies from the ‘FILE’ argument of a
     ‘Q_PLUGIN_METADATA’ macro and

   - additional file dependencies detected by filters defined in
     AUTOMOC_DEPEND_FILTERS.

If a Qt macro is found, then the header will be compiled by the ‘moc’ to
the output file ‘moc_<base_name>.cpp’.  The complete output file path is
described in the section Output file location.

The header will be ‘moc’ compiled again if a file from the additional
file dependencies changes.

Header ‘moc’ output files ‘moc_<base_name>.cpp’ can be included in
source files.  In the section Including header moc files in sources
there is more information on that topic.

19.3.30.2 Source file processing
................................

At build time, CMake scans each unknown or modified C++ source file from
the target’s sources for

   - a Qt macro from AUTOMOC_MACRO_NAMES,

   - includes of header ‘moc’ files (see Including header moc files in sources),

   - additional file dependencies from the ‘FILE’ argument of a
     ‘Q_PLUGIN_METADATA’ macro and

   - additional file dependencies detected by filters defined in
     AUTOMOC_DEPEND_FILTERS.

If a Qt macro is found, then the C++ source file
‘<base>.<source_extension>’ is expected to as well contain an include
statement

     #include <<base>.moc> // or
     #include "<base>.moc"

The source file then will be compiled by the ‘moc’ to the output file
‘<base>.moc’.  A description of the complete output file path is in
section Output file location.

The source will be ‘moc’ compiled again if a file from the additional
file dependencies changes.

19.3.30.3 Including header moc files in sources
...............................................

A source file can include the ‘moc’ output file of a header
‘<header_base>.<header_extension>’ by using an include statement of the
form

     #include <moc_<header_base>.cpp> // or
     #include "moc_<header_base>.cpp"

If the ‘moc’ output file of a header is included by a source, it will be
generated in a different location than if it was not included.  This is
described in the section Output file location.

19.3.30.4 Output file location
..............................

19.3.30.5 Included moc output files
...................................

‘moc’ output files that are included by a source file will be generated
in

   - ‘<AUTOGEN_BUILD_DIR>/include’ for single configuration generators
     or in

   - ‘<AUTOGEN_BUILD_DIR>/include_<CONFIG>’ for multi configuration
     generators.

Where ‘<AUTOGEN_BUILD_DIR>’ is the value of the target property
AUTOGEN_BUILD_DIR.

The include directory is automatically added to the target’s
INCLUDE_DIRECTORIES.

19.3.30.6 Not included moc output files
.......................................

‘moc’ output files that are not included in a source file will be
generated in

   - ‘<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM>’ for single
     configuration generators or in,

   - ‘<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM>’ for
     multi configuration generators.

Where ‘<SOURCE_DIR_CHECKSUM>’ is a checksum computed from the relative
parent directory path of the ‘moc’ input file.  This scheme allows to
have ‘moc’ input files with the same name in different directories.

All not included ‘moc’ output files will be included automatically by
the CMake generated file

   - ‘<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp’,

which is added to the target’s sources.

19.3.30.7 Qt version detection
..............................

AUTOMOC enabled targets need to know the Qt major and minor
version they’re working with.  The major version usually is provided by
the ‘INTERFACE_QT_MAJOR_VERSION’ property of the ‘Qt[45]Core’ library,
that the target links to.  To find the minor version, CMake builds a
list of available Qt versions from

   - ‘Qt5Core_VERSION_MAJOR’ and ‘Qt5Core_VERSION_MINOR’ variables
     (usually set by ‘find_package(Qt5...)’)

   - ‘Qt5Core_VERSION_MAJOR’ and ‘Qt5Core_VERSION_MINOR’ directory
     properties

   - ‘QT_VERSION_MAJOR’ and ‘QT_VERSION_MINOR’ variables (usually set by
     ‘find_package(Qt4...)’)

   - ‘QT_VERSION_MAJOR’ and ‘QT_VERSION_MINOR’ directory properties

in the context of the add_executable() or
add_library() call.

Assumed ‘INTERFACE_QT_MAJOR_VERSION’ is a valid number, the first entry
in the list with a matching major version is taken.  If no matching
major version was found, an error is generated.  If
‘INTERFACE_QT_MAJOR_VERSION’ is not a valid number, the first entry in
the list is taken.

A ‘find_package(Qt[45]...)’ call sets the
‘QT/Qt5Core_VERSION_MAJOR/MINOR’ variables.  If the call is in a
different context than the add_executable() or
add_library() call, e.g.  in a function, then the version variables
might not be available to the AUTOMOC enabled target.  In
that case the version variables can be forwarded from the
‘find_package(Qt[45]...)’ calling context to the add_executable()
or add_library() calling context as directory properties.
The following Qt5 example demonstrates the procedure.

     function (add_qt5_client)
       find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets)
       ...
       set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
         PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}")
       set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
         PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}")
       ...
     endfunction ()
     ...
     add_qt5_client()
     add_executable(myTarget main.cpp)
     target_link_libraries(myTarget Qt5::QtWidgets)
     set_property(TARGET myTarget PROPERTY AUTOMOC ON)

19.3.30.8 Modifiers
...................

See AUTOMOC_EXECUTABLE.: The ‘moc’ executable will be detected
automatically, but can be forced to a certain binary using this target
property.

See AUTOMOC_MOC_OPTIONS.: Additional command line options for
‘moc’ can be set in this target property.

See AUTOMOC_MACRO_NAMES.: This list of Qt macro names can be
extended to search for additional macros in headers and sources.

See AUTOMOC_DEPEND_FILTERS.: ‘moc’ dependency file names can be
extracted from headers or sources by defining file name filters in this
target property.

See AUTOMOC_COMPILER_PREDEFINES.: Compiler pre definitions for
‘moc’ are written to the ‘moc_predefs.h’ file.  The generation of this
file can be enabled or disabled in this target property.

See SKIP_AUTOMOC.: Sources and headers can be excluded from
AUTOMOC processing by setting this source file property.

See SKIP_AUTOGEN.: Source files can be excluded from
AUTOMOC, AUTOUIC and AUTORCC processing by
setting this source file property.

See AUTOGEN_SOURCE_GROUP.: This global property can be used to
group files generated by AUTOMOC or AUTORCC.
together in an IDE, e.g.  in MSVS.

See AUTOGEN_TARGETS_FOLDER.: This global property can be used to
group AUTOMOC, AUTOUIC and AUTORCC.
targets together in an IDE, e.g.  in MSVS.

See CMAKE_GLOBAL_AUTOGEN_TARGET.: A global ‘autogen’ target, that
depends on all AUTOMOC or AUTOUIC generated
‘<ORIGIN>_autogen’ targets in the project, will be generated when this
variable is ‘ON’.

See AUTOGEN_PARALLEL.: This target property controls the number
of ‘moc’ or ‘uic’ processes to start in parallel during builds.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.31 AUTOMOC_COMPILER_PREDEFINES
-----------------------------------

New in version 3.10.

Boolean value used by AUTOMOC to determine if the compiler
pre definitions file ‘moc_predefs.h’ should be generated.

CMake generates a ‘moc_predefs.h’ file with compiler pre definitions
from the output of the command defined in
CMAKE_CXX_COMPILER_PREDEFINES_COMMAND when

   - AUTOMOC is enabled,

   - AUTOMOC_COMPILER_PREDEFINES is enabled,

   - CMAKE_CXX_COMPILER_PREDEFINES_COMMAND isn’t empty and

   - the Qt version is greater or equal 5.8.

The ‘moc_predefs.h’ file, which is generated in AUTOGEN_BUILD_DIR,
is passed to ‘moc’ as the argument to the ‘--include’ option.

By default AUTOMOC_COMPILER_PREDEFINES is initialized from
CMAKE_AUTOMOC_COMPILER_PREDEFINES, which is ON by default.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.32 AUTOMOC_DEPEND_FILTERS
------------------------------

New in version 3.9.

Filter definitions used by AUTOMOC to extract file names
from a source file that are registered as additional dependencies for
the ‘moc’ file of the source file.

Filters are defined as ‘KEYWORD;REGULAR_EXPRESSION’ pairs.  First the
file content is searched for ‘KEYWORD’.  If it is found at least once,
then file names are extracted by successively searching for
‘REGULAR_EXPRESSION’ and taking the first match group.

The file name found in the first match group is searched for

   - first in the vicinity of the source file

   - and afterwards in the target’s INCLUDE_DIRECTORIES.

If any of the extracted files changes, then the ‘moc’ file for the
source file gets rebuilt even when the source file itself doesn’t
change.

If any of the extracted files is GENERATED or if it is not
in the target’s sources, then it might be necessary to add it to the
‘_autogen’ target dependencies.  See AUTOGEN_TARGET_DEPENDS.
for reference.

By default AUTOMOC_DEPEND_FILTERS is initialized from
CMAKE_AUTOMOC_DEPEND_FILTERS, which is empty by default.

From Qt 5.15.0 on this variable is ignored as moc is able to output the
correct dependencies.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.32.1 Example 1
...................

A header file ‘my_class.hpp’ uses a custom macro ‘JSON_FILE_MACRO’ which
is defined in an other header ‘macros.hpp’.  We want the ‘moc’ file of
‘my_class.hpp’ to depend on the file name argument of ‘JSON_FILE_MACRO’:

     // my_class.hpp
     class My_Class : public QObject
     {
       Q_OBJECT
       JSON_FILE_MACRO ( "info.json" )
     ...
     };

In ‘CMakeLists.txt’ we add a filter to
CMAKE_AUTOMOC_DEPEND_FILTERS like this:

     list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
       "JSON_FILE_MACRO"
       "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
     )

We assume ‘info.json’ is a plain (not GENERATED) file that
is listed in the target’s source.  Therefore we do not need to add it to
AUTOGEN_TARGET_DEPENDS.

19.3.32.2 Example 2
...................

In the target ‘my_target’ a header file ‘complex_class.hpp’ uses a
custom macro ‘JSON_BASED_CLASS’ which is defined in an other header
‘macros.hpp’:

     // macros.hpp
     ...
     #define JSON_BASED_CLASS(name, json) \
     class name : public QObject \
     { \
       Q_OBJECT \
       Q_PLUGIN_METADATA(IID "demo" FILE json) \
       name() {} \
     };
     ...

     // complex_class.hpp
     #pragma once
     JSON_BASED_CLASS(Complex_Class, "meta.json")
     // end of file

Since ‘complex_class.hpp’ doesn’t contain a ‘Q_OBJECT’ macro it would be
ignored by AUTOMOC.  We change this by adding
‘JSON_BASED_CLASS’ to CMAKE_AUTOMOC_MACRO_NAMES.:

     list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")

We want the ‘moc’ file of ‘complex_class.hpp’ to depend on ‘meta.json’.
So we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS.:

     list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
       "JSON_BASED_CLASS"
       "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
     )

Additionally we assume ‘meta.json’ is GENERATED which is why
we have to add it to AUTOGEN_TARGET_DEPENDS.:

     set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")

19.3.33 AUTOMOC_EXECUTABLE
--------------------------

New in version 3.14.

AUTOMOC_EXECUTABLE is file path pointing to the ‘moc’
executable to use for AUTOMOC enabled files.  Setting this
property will make CMake skip the automatic detection of the ‘moc’
binary as well as the sanity-tests normally run to ensure that the
binary is available and working as expected.

Usually this property does not need to be set.  Only consider this
property if auto-detection of ‘moc’ can not work – e.g.  because you are
building the ‘moc’ binary as part of your project.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.34 AUTOMOC_MACRO_NAMES
---------------------------

New in version 3.10.

A semicolon-separated list list of macro names used by
AUTOMOC to determine if a C++ file needs to be processed by ‘moc’.

This property is only used if the AUTOMOC property is ‘ON’
for this target.

When running AUTOMOC, CMake searches for the strings listed
in AUTOMOC_MACRO_NAMES in C++ source and header files.  If
any of the strings is found

   - as the first non space string on a new line or

   - as the first non space string after a ‘{’ on a new line,

then the file will be processed by ‘moc’.

By default AUTOMOC_MACRO_NAMES is initialized from
CMAKE_AUTOMOC_MACRO_NAMES.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.34.1 Example
.................

In this case the ‘Q_OBJECT’ macro is hidden inside another macro called
‘CUSTOM_MACRO’.  To let CMake know that source files that contain
‘CUSTOM_MACRO’ need to be ‘moc’ processed, we call:

     set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")

19.3.35 AUTOMOC_MOC_OPTIONS
---------------------------

Additional options for ‘moc’ when using AUTOMOC.

This property is only used if the AUTOMOC property is ‘ON’
for this target.  In this case, it holds additional command line options
which will be used when ‘moc’ is executed during the build, i.e.  it is
equivalent to the optional ‘OPTIONS’ argument of the
qt4_wrap_cpp() macro.

This property is initialized by the value of the
CMAKE_AUTOMOC_MOC_OPTIONS variable if it is set when a target is
created, or an empty string otherwise.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.36 AUTOMOC_PATH_PREFIX
---------------------------

New in version 3.16.

When this property is ‘ON’, CMake will generate the ‘-p’ path prefix
option for ‘moc’ on AUTOMOC enabled Qt targets.

To generate the path prefix, CMake tests if the header compiled by ‘moc’
is in any of the target include directories.  If so, CMake
will compute the relative path accordingly.  If the header is not in the
include directories, CMake will omit the ‘-p’ path prefix
option.  ‘moc’ usually generates a relative include path in that case.

AUTOMOC_PATH_PREFIX is initialized from the variable
CMAKE_AUTOMOC_PATH_PREFIX, which is ‘OFF’ by default.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.36.1 Reproducible builds
.............................

For reproducible builds it is recommended to keep headers that are ‘moc’
compiled in one of the target include directories and set
AUTOMOC_PATH_PREFIX to ‘ON’.  This ensures that:

   - ‘moc’ output files are identical on different build setups,

   - ‘moc’ output files will compile correctly when the source and/or
     build directory is a symbolic link.

19.3.37 AUTORCC
---------------

Should the target be processed with auto-rcc (for Qt projects).

AUTORCC is a boolean specifying whether CMake will handle
the Qt ‘rcc’ code generator automatically, i.e.  without having to use
the QT4_ADD_RESOURCES() or ‘QT5_ADD_RESOURCES()’ macro.
Currently Qt4 and Qt5 are supported.

When this property is ‘ON’, CMake will handle ‘.qrc’ files added as
target sources at build time and invoke ‘rcc’ accordingly.  This
property is initialized by the value of the CMAKE_AUTORCC.
variable if it is set when a target is created.

By default AUTORCC is processed by a custom command.
If the ‘.qrc’ file is GENERATED, a custom target
is used instead.

When there are multiple ‘.qrc’ files with the same name, CMake will
generate unspecified unique output file names for ‘rcc’.  Therefore, if
‘Q_INIT_RESOURCE()’ or ‘Q_CLEANUP_RESOURCE()’ need to be used, the
‘.qrc’ file name must be unique.

19.3.37.1 Modifiers
...................

See AUTORCC_EXECUTABLE.: The ‘rcc’ executable will be detected
automatically, but can be forced to a certain binary by setting this
target property.

See AUTORCC_OPTIONS.: Additional command line options for ‘rcc’
can be set via this target property.  The corresponding
AUTORCC_OPTIONS source file property can be used to specify
options to be applied only to a specific ‘.qrc’ file.

See SKIP_AUTORCC.: ‘.qrc’ files can be excluded from
AUTORCC processing by setting this source file property.

See SKIP_AUTOGEN.: Source files can be excluded from
AUTOMOC, AUTOUIC and AUTORCC processing by
setting this source file property.

See AUTOGEN_SOURCE_GROUP.: This global property can be used to
group files generated by AUTOMOC or AUTORCC.
together in an IDE, e.g.  in MSVS.

See AUTOGEN_TARGETS_FOLDER.: This global property can be used to
group AUTOMOC, AUTOUIC and AUTORCC.
targets together in an IDE, e.g.  in MSVS.

See CMAKE_GLOBAL_AUTORCC_TARGET.: A global ‘autorcc’ target that
depends on all AUTORCC targets in the project will be
generated when this variable is ‘ON’.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.38 AUTORCC_EXECUTABLE
--------------------------

New in version 3.14.

AUTORCC_EXECUTABLE is file path pointing to the ‘rcc’
executable to use for AUTORCC enabled files.  Setting this
property will make CMake skip the automatic detection of the ‘rcc’
binary as well as the sanity-tests normally run to ensure that the
binary is available and working as expected.

Usually this property does not need to be set.  Only consider this
property if auto-detection of ‘rcc’ can not work – e.g.  because you are
building the ‘rcc’ binary as part of your project.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.39 AUTORCC_OPTIONS
-----------------------

Additional options for ‘rcc’ when using AUTORCC.

This property holds additional command line options which will be used
when ‘rcc’ is executed during the build via AUTORCC, i.e.  it
is equivalent to the optional ‘OPTIONS’ argument of the
qt4_add_resources() macro.

This property is initialized by the value of the
CMAKE_AUTORCC_OPTIONS variable if it is set when a target is
created, or an empty string otherwise.

The options set on the target may be overridden by
AUTORCC_OPTIONS set on the ‘.qrc’ source file.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.39.1 EXAMPLE
.................

     # ...
     set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9")
     # ...

19.3.40 AUTOUIC
---------------

Should the target be processed with auto-uic (for Qt projects).

AUTOUIC is a boolean specifying whether CMake will handle
the Qt ‘uic’ code generator automatically, i.e.  without having to use
the QT4_WRAP_UI() or ‘QT5_WRAP_UI()’ macro.  Currently Qt4
and Qt5 are supported.

This property is initialized by the value of the CMAKE_AUTOUIC
variable if it is set when a target is created.

When this property is ‘ON’, CMake will scan the header and source files
at build time and invoke ‘uic’ accordingly.

19.3.40.1 Header and source file processing
...........................................

At build time, CMake scans each header and source file from the target’s
sources for include statements of the form

     #include "ui_<ui_base>.h"

Once such an include statement is found in a file, CMake searches for
the ‘uic’ input file ‘<ui_base>.ui’

   - in the vicinity of the file and

   - in the AUTOUIC_SEARCH_PATHS of the target.

If the ‘<ui_base>.ui’ file was found, ‘uic’ is called on it to generate
‘ui_<ui_base>.h’ in the directory

   - ‘<AUTOGEN_BUILD_DIR>/include’ for single configuration generators
     or in

   - ‘<AUTOGEN_BUILD_DIR>/include_<CONFIG>’ for multi configuration
     generators.

Where ‘<AUTOGEN_BUILD_DIR>’ is the value of the target property
AUTOGEN_BUILD_DIR.

The include directory is automatically added to the target’s
INCLUDE_DIRECTORIES.

19.3.40.2 Modifiers
...................

See AUTOUIC_EXECUTABLE.: The ‘uic’ executable will be detected
automatically, but can be forced to a certain binary using this target
property.

See AUTOUIC_OPTIONS.: Additional command line options for ‘uic’
can be set via this target property.  The corresponding
AUTOUIC_OPTIONS source file property can be used to specify
options to be applied only to a specific ‘<base_name>.ui’ file.

See SKIP_AUTOUIC.: Source files can be excluded from
AUTOUIC processing by setting this source file property.

See SKIP_AUTOGEN.: Source files can be excluded from
AUTOMOC, AUTOUIC and AUTORCC processing by
setting this source file property.

See AUTOGEN_TARGETS_FOLDER.: This global property can be used to
group AUTOMOC, AUTOUIC and AUTORCC.
targets together in an IDE, e.g.  in MSVS.

See CMAKE_GLOBAL_AUTOGEN_TARGET.: A global ‘autogen’ target, that
depends on all AUTOMOC or AUTOUIC generated
‘<ORIGIN>_autogen’ targets in the project, will be generated when this
variable is ‘ON’.

See AUTOGEN_PARALLEL.: This target property controls the number
of ‘moc’ or ‘uic’ processes to start in parallel during builds.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.41 AUTOUIC_EXECUTABLE
--------------------------

New in version 3.14.

AUTOUIC_EXECUTABLE is file path pointing to the ‘uic’
executable to use for AUTOUIC enabled files.  Setting this
property will make CMake skip the automatic detection of the ‘uic’
binary as well as the sanity-tests normally run to ensure that the
binary is available and working as expected.

Usually this property does not need to be set.  Only consider this
property if auto-detection of ‘uic’ can not work – e.g.  because you are
building the ‘uic’ binary as part of your project.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.42 AUTOUIC_OPTIONS
-----------------------

Additional options for ‘uic’ when using AUTOUIC.

This property holds additional command line options which will be used
when ‘uic’ is executed during the build via AUTOUIC, i.e.  it
is equivalent to the optional ‘OPTIONS’ argument of the
qt4_wrap_ui() macro.

This property is initialized by the value of the
CMAKE_AUTOUIC_OPTIONS variable if it is set when a target is
created, or an empty string otherwise.

The options set on the target may be overridden by
AUTOUIC_OPTIONS set on the ‘.ui’ source file.

This property may use “generator expressions” with the syntax ‘$<...>’.
See the cmake-generator-expressions(7) manual for available
expressions.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.42.1 EXAMPLE
.................

     # ...
     set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection")
     # ...

19.3.43 AUTOUIC_SEARCH_PATHS
----------------------------

New in version 3.9.

Search path list used by AUTOUIC to find included ‘.ui’
files.

This property is initialized by the value of the
CMAKE_AUTOUIC_SEARCH_PATHS variable if it is set when a target is
created.  Otherwise it is empty.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

19.3.44 BINARY_DIR
------------------

New in version 3.4.

This read-only property reports the value of the
CMAKE_CURRENT_BINARY_DIR variable in the directory in which the
target was defined.

19.3.45 BUILD_RPATH
-------------------

New in version 3.8.

A semicolon-separated list specifying runtime path (‘RPATH’)
entries to add to binaries linked in the build tree (for platforms that
support it).  The entries will `not' be used for binaries in the install
tree.  See also the INSTALL_RPATH target property.

This property is initialized by the value of the variable
CMAKE_BUILD_RPATH if it is set when a target is created.

This property supports generator expressions.

19.3.46 BUILD_RPATH_USE_ORIGIN
------------------------------

New in version 3.14.

Whether to use relative paths for the build ‘RPATH’.

This property is initialized by the value of the variable
CMAKE_BUILD_RPATH_USE_ORIGIN.

On platforms that support runtime paths (‘RPATH’) with the ‘$ORIGIN’
token, setting this property to ‘TRUE’ enables relative paths in the
build ‘RPATH’ for executables and shared libraries that point to shared
libraries in the same build tree.

Normally the build ‘RPATH’ of a binary contains absolute paths to the
directory of each shared library it links to.  The ‘RPATH’ entries for
directories contained within the build tree can be made relative to
enable relocatable builds and to help achieve reproducible builds by
omitting the build directory from the build environment.

This property has no effect on platforms that do not support the
‘$ORIGIN’ token in ‘RPATH’, or when the CMAKE_SKIP_RPATH.
variable is set.  The runtime path set through the BUILD_RPATH
target property is also unaffected by this property.

19.3.47 BUILD_WITH_INSTALL_NAME_DIR
-----------------------------------

New in version 3.9.

‘BUILD_WITH_INSTALL_NAME_DIR’ is a boolean specifying whether the macOS
‘install_name’ of a target in the build tree uses the directory given by
INSTALL_NAME_DIR.  This setting only applies to targets on
macOS.

This property is initialized by the value of the variable
CMAKE_BUILD_WITH_INSTALL_NAME_DIR if it is set when a target is
created.

If this property is not set and policy CMP0068 is not ‘NEW’,
the value of BUILD_WITH_INSTALL_RPATH is used in its place.

19.3.48 BUILD_WITH_INSTALL_RPATH
--------------------------------

‘BUILD_WITH_INSTALL_RPATH’ is a boolean specifying whether to link the
target in the build tree with the INSTALL_RPATH.  This takes
precedence over SKIP_BUILD_RPATH and avoids the need for
relinking before installation.

This property is initialized by the value of the
CMAKE_BUILD_WITH_INSTALL_RPATH variable if it is set when a target
is created.

If policy CMP0068 is not ‘NEW’, this property also controls
use of INSTALL_NAME_DIR in the build tree on macOS. Either
way, the BUILD_WITH_INSTALL_NAME_DIR target property takes
precedence.

19.3.49 BUNDLE
--------------

This target is a ‘CFBundle’ on the macOS.

If a module library target has this property set to true it will be
built as a ‘CFBundle’ when built on the mac.  It will have the directory
structure required for a ‘CFBundle’ and will be suitable to be used for
creating Browser Plugins or other application resources.

19.3.50 BUNDLE_EXTENSION
------------------------

The file extension used to name a BUNDLE, a FRAMEWORK,
or a MACOSX_BUNDLE target on the macOS and iOS.

The default value is ‘bundle’, ‘framework’, or ‘app’ for the respective
target types.

19.3.51 C_EXTENSIONS
--------------------

New in version 3.1.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be
used.  For some compilers, this results in adding a flag such as
‘-std=gnu11’ instead of ‘-std=c11’ to the compile line.  This property
is ‘ON’ by default.  The basic C standard level is controlled by the
C_STANDARD target property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_C_EXTENSIONS variable if it is set when a target is created.

19.3.52 C_STANDARD
------------------

New in version 3.1.

The C standard whose features are requested to build this target.

This property specifies the C standard whose features are requested to
build this target.  For some compilers, this results in adding a flag
such as ‘-std=gnu11’ to the compile line.  For compilers that have no
notion of a C standard level, such as Microsoft Visual C++ before VS
16.7, this property has no effect.

Supported values are ‘90’, ‘99’ and ‘11’.

If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead.
This means that using:

     set_property(TARGET tgt PROPERTY C_STANDARD 11)

with a compiler which does not support ‘-std=gnu11’ or an equivalent
flag will not result in an error or warning, but will instead add the
‘-std=gnu99’ or ‘-std=gnu90’ flag if supported.  This “decay” behavior
may be controlled with the C_STANDARD_REQUIRED target
property.  Additionally, the C_EXTENSIONS target property
may be used to control whether compiler-specific extensions are enabled
on a per-target basis.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_C_STANDARD
variable if it is set when a target is created.

19.3.53 C_STANDARD_REQUIRED
---------------------------

New in version 3.1.

Boolean describing whether the value of C_STANDARD is a
requirement.

If this property is set to ‘ON’, then the value of the C_STANDARD
target property is treated as a requirement.  If this property is
‘OFF’ or unset, the C_STANDARD target property is treated as
optional and may “decay” to a previous standard if the requested is not
available.  For compilers that have no notion of a C standard level,
such as Microsoft Visual C++ before VS 16.7, this property has no
effect.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_C_STANDARD_REQUIRED variable if it is set when a target is
created.

19.3.54 COMMON_LANGUAGE_RUNTIME
-------------------------------

New in version 3.12.

By setting this target property, the target is configured to build with
‘C++/CLI’ support.

The Visual Studio generator defines the ‘clr’ parameter depending on the
value of ‘COMMON_LANGUAGE_RUNTIME’:

   * property not set: native C++ (i.e.  default)

   * property set but empty: mixed unmanaged/managed C++

   * property set to any non empty value: managed C++

Supported values: ‘""’, ‘"pure"’, ‘"safe"’

This property is only evaluated Visual Studio Generators for
VS 2010 and above.

To be able to build managed C++ targets with VS 2017 and above the
component ‘C++/CLI support’ must be installed, which may not be done by
default.

See also IMPORTED_COMMON_LANGUAGE_RUNTIME.

19.3.55 COMPATIBLE_INTERFACE_BOOL
---------------------------------

Properties which must be compatible with their link interface

The ‘COMPATIBLE_INTERFACE_BOOL’ property may contain a list of
properties for this target which must be consistent when evaluated as a
boolean with the ‘INTERFACE’ variant of the property in all linked
dependees.  For example, if a property ‘FOO’ appears in the list, then
for each dependee, the ‘INTERFACE_FOO’ property content in all of its
dependencies must be consistent with each other, and with the ‘FOO’
property in the depender.

Consistency in this sense has the meaning that if the property is set,
then it must have the same boolean value as all others, and if the
property is not set, then it is ignored.

Note that for each dependee, the set of properties specified in this
property must not intersect with the set specified in any of the other
Compatible Interface Properties.

19.3.56 COMPATIBLE_INTERFACE_NUMBER_MAX
---------------------------------------

Properties whose maximum value from the link interface will be used.

The ‘COMPATIBLE_INTERFACE_NUMBER_MAX’ property may contain a list of
properties for this target whose maximum value may be read at generate
time when evaluated in the ‘INTERFACE’ variant of the property in all
linked dependees.  For example, if a property ‘FOO’ appears in the list,
then for each dependee, the ‘INTERFACE_FOO’ property content in all of
its dependencies will be compared with each other and with the ‘FOO’
property in the depender.  When reading the ‘FOO’ property at generate
time, the maximum value will be returned.  If the property is not set,
then it is ignored.

Note that for each dependee, the set of properties specified in this
property must not intersect with the set specified in any of the other
Compatible Interface Properties.

19.3.57 COMPATIBLE_INTERFACE_NUMBER_MIN
---------------------------------------

Properties whose maximum value from the link interface will be used.

The ‘COMPATIBLE_INTERFACE_NUMBER_MIN’ property may contain a list of
properties for this target whose minimum value may be read at generate
time when evaluated in the ‘INTERFACE’ variant of the property of all
linked dependees.  For example, if a property ‘FOO’ appears in the list,
then for each dependee, the ‘INTERFACE_FOO’ property content in all of
its dependencies will be compared with each other and with the ‘FOO’
property in the depender.  When reading the ‘FOO’ property at generate
time, the minimum value will be returned.  If the property is not set,
then it is ignored.

Note that for each dependee, the set of properties specified in this
property must not intersect with the set specified in any of the other
Compatible Interface Properties.

19.3.58 COMPATIBLE_INTERFACE_STRING
-----------------------------------

Properties which must be string-compatible with their link interface

The ‘COMPATIBLE_INTERFACE_STRING’ property may contain a list of
properties for this target which must be the same when evaluated as a
string in the ‘INTERFACE’ variant of the property all linked dependees.
For example, if a property ‘FOO’ appears in the list, then for each
dependee, the ‘INTERFACE_FOO’ property content in all of its
dependencies must be equal with each other, and with the ‘FOO’ property
in the depender.  If the property is not set, then it is ignored.

Note that for each dependee, the set of properties specified in this
property must not intersect with the set specified in any of the other
Compatible Interface Properties.

19.3.59 COMPILE_DEFINITIONS
---------------------------

Preprocessor definitions for compiling a target’s sources.

The ‘COMPILE_DEFINITIONS’ property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ‘VAR’ or ‘VAR=value’.
Function-style definitions are not supported.  CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).

CMake will automatically drop some definitions that are not supported by
the native build tool.

Disclaimer: Most native build tools have poor support for escaping
certain values.  CMake has work-arounds for many cases but some values
may just not be possible to pass correctly.  If a value does not seem to
be escaped correctly, do not attempt to work-around the problem by
adding escape sequences to the value.  Your work-around may break in a
future version of CMake that has improved escape support.  Instead
consider defining the macro in a (configured) header file.  Then report
the limitation.  Known limitations include:

     #          - broken almost everywhere
     ;          - broken in VS IDE 7.0 and Borland Makefiles
     ,          - broken in VS IDE
     %          - broken in some cases in NMake
     & |        - broken in some cases on MinGW
     ^ < > \"   - broken in most Make tools on Windows

CMake does not reject these values outright because they do work in some
cases.  Use with caution.

Contents of ‘COMPILE_DEFINITIONS’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

The corresponding COMPILE_DEFINITIONS_<CONFIG> property may
be set to specify per-configuration definitions.  Generator expressions
should be preferred instead of setting the alternative property.

19.3.60 COMPILE_FEATURES
------------------------

New in version 3.1.

Compiler features enabled for this target.

The list of features in this property are a subset of the features
listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, and CMAKE_CXX_COMPILE_FEATURES
variables.

Contents of ‘COMPILE_FEATURES’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the
cmake-compile-features(7) manual for information on compile
features and a list of supported compilers.

19.3.61 COMPILE_FLAGS
---------------------

Additional flags to use when compiling this target’s sources.

The ‘COMPILE_FLAGS’ property sets additional compiler flags used to
build sources within the target.  Use COMPILE_DEFINITIONS to
pass additional preprocessor definitions.

This property is deprecated.  Use the COMPILE_OPTIONS.
property or the target_compile_options() command instead.

19.3.62 COMPILE_OPTIONS
-----------------------

List of options to pass to the compiler.

This property holds a semicolon-separated list of options
specified so far for its target.  Use the
target_compile_options() command to append more options.

This property is initialized by the COMPILE_OPTIONS.
directory property when a target is created, and is used by the
generators to set the options for the compiler.

Contents of ‘COMPILE_OPTIONS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.3.63 COMPILE_PDB_NAME
------------------------

New in version 3.1.

Output name for the MS debug symbol ‘.pdb’ file generated by the
compiler while building source files.

This property specifies the base name for the debug symbols file.  If
not set, the default is unspecified.

     Note: The compiler-generated program database files are specified
     by the ‘/Fd’ compiler flag and are not the same as linker-generated
     program database files specified by the ‘/pdb’ linker flag.  Use
     the PDB_NAME property to specify the latter.

19.3.64 COMPILE_PDB_NAME_<CONFIG>
---------------------------------

New in version 3.1.

Per-configuration output name for the MS debug symbol ‘.pdb’ file
generated by the compiler while building source files.

This is the configuration-specific version of COMPILE_PDB_NAME.

     Note: The compiler-generated program database files are specified
     by the ‘/Fd’ compiler flag and are not the same as linker-generated
     program database files specified by the ‘/pdb’ linker flag.  Use
     the PDB_NAME_<CONFIG> property to specify the latter.

19.3.65 COMPILE_PDB_OUTPUT_DIRECTORY
------------------------------------

New in version 3.1.

Output directory for the MS debug symbol ‘.pdb’ file generated by the
compiler while building source files.

This property specifies the directory into which the MS debug symbols
will be placed by the compiler.  This property is initialized by the
value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY variable if
it is set when a target is created.

     Note: The compiler-generated program database files are specified
     by the ‘/Fd’ compiler flag and are not the same as linker-generated
     program database files specified by the ‘/pdb’ linker flag.  Use
     the PDB_OUTPUT_DIRECTORY property to specify the
     latter.

19.3.66 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
---------------------------------------------

New in version 3.1.

Per-configuration output directory for the MS debug symbol ‘.pdb’ file
generated by the compiler while building source files.

This is a per-configuration version of
COMPILE_PDB_OUTPUT_DIRECTORY, but multi-configuration generators
(Visual Studio, Xcode) do NOT append a per-configuration subdirectory to
the specified directory.  This property is initialized by the value of
the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if
it is set when a target is created.

     Note: The compiler-generated program database files are specified
     by the ‘/Fd’ compiler flag and are not the same as linker-generated
     program database files specified by the ‘/pdb’ linker flag.  Use
     the PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify
     the latter.

19.3.67 <CONFIG>_OUTPUT_NAME
----------------------------

Old per-configuration target file base name.  Use
OUTPUT_NAME_<CONFIG> instead.

This is a configuration-specific version of the OUTPUT_NAME.
target property.

19.3.68 <CONFIG>_POSTFIX
------------------------

Postfix to append to the target file name for configuration <CONFIG>.

When building with configuration <CONFIG> the value of this property is
appended to the target file name built on disk.  For non-executable
targets, this property is initialized by the value of the variable
CMAKE_<CONFIG>_POSTFIX if it is set when a target is created.  This
property is ignored on the Mac for Frameworks and App Bundles.

For macOS see also the FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
target property.

19.3.69 CROSSCOMPILING_EMULATOR
-------------------------------

New in version 3.3.

Use the given emulator to run executables created when crosscompiling.
This command will be added as a prefix to add_test(),
add_custom_command(), and add_custom_target() commands
for built target system executables.

If this property contains a semicolon-separated list, then the
first value is the command and remaining values are its arguments.

This property is initialized by the value of the
CMAKE_CROSSCOMPILING_EMULATOR variable if it is set when a target
is created.

19.3.70 CUDA_ARCHITECTURES
--------------------------

New in version 3.18.

List of architectures to generate device code for.

An architecture can be suffixed by either ‘-real’ or ‘-virtual’ to
specify the kind of architecture to generate code for.  If no suffix is
given then code is generated for both real and virtual architectures.

A non-empty false value (e.g.  ‘OFF’) disables adding architectures.
This is intended to support packagers and rare cases where full control
over the passed flags is required.

This property is initialized by the value of the
CMAKE_CUDA_ARCHITECTURES variable if it is set when a target is
created.

The ‘CUDA_ARCHITECTURES’ target property must be set to a non-empty
value on targets that compile CUDA sources, or it is an error.  See
policy CMP0104.

19.3.70.1 Examples
..................

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72)

Generates code for real and virtual architectures ‘30’, ‘50’ and ‘72’.

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)

Generates code for real architecture ‘70’ and virtual architecture ‘72’.

     set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)

CMake will not pass any architecture flags to the compiler.

19.3.71 CUDA_EXTENSIONS
-----------------------

New in version 3.8.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be
used.  For some compilers, this results in adding a flag such as
‘-std=gnu++11’ instead of ‘-std=c++11’ to the compile line.  This
property is ‘ON’ by default.  The basic CUDA/C++ standard level is
controlled by the CUDA_STANDARD target property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CUDA_EXTENSIONS variable if it is set when a target is
created.

19.3.72 CUDA_PTX_COMPILATION
----------------------------

New in version 3.9.

Compile CUDA sources to ‘.ptx’ files instead of ‘.obj’ files within
Object Libraries.

For example:

     add_library(myptx OBJECT a.cu b.cu)
     set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)

19.3.73 CUDA_RESOLVE_DEVICE_SYMBOLS
-----------------------------------

New in version 3.9.

CUDA only: Enables device linking for the specific library target where
required.

If set, this will tell the required compilers to enable device linking
on the library target.  Device linking is an additional link step
required by some CUDA compilers when CUDA_SEPARABLE_COMPILATION
is enabled.  Normally device linking is deferred until a shared
library or executable is generated, allowing for multiple static
libraries to resolve device symbols at the same time when they are used
by a shared library or executable.

By default static library targets have this property is disabled, while
shared, module, and executable targets have this property enabled.

Note that device linking is not supported for Object Libraries.

For instance:

     set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)

19.3.74 CUDA_RUNTIME_LIBRARY
----------------------------

New in version 3.17.

Select the CUDA runtime library for use by compilers targeting the CUDA
language.

The allowed case insensitive values are:

‘None’

     Link with ‘-cudart=none’ or equivalent flag(s) to use no CUDA
     runtime library.

‘Shared’

     Link with ‘-cudart=shared’ or equivalent flag(s) to use a
     dynamically-linked CUDA runtime library.

‘Static’

     Link with ‘-cudart=static’ or equivalent flag(s) to use a
     statically-linked CUDA runtime library.

Contents of ‘CUDA_RUNTIME_LIBRARY’ may use generator expressions.

If that property is not set then CMake uses an appropriate default value
based on the compiler to select the CUDA runtime library.

     Note: This property has effect only when the ‘CUDA’ language is
     enabled.  To control the CUDA runtime linking when only using the
     CUDA SDK with the ‘C’ or ‘C++’ language we recommend using the
     FindCUDAToolkit module.

19.3.75 CUDA_SEPARABLE_COMPILATION
----------------------------------

New in version 3.8.

CUDA only: Enables separate compilation of device code

If set this will enable separable compilation for all CUDA files for the
given target.

For instance:

     set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)

This property is initialized by the value of the
CMAKE_CUDA_SEPARABLE_COMPILATION variable if it is set when a
target is created.

19.3.76 CUDA_STANDARD
---------------------

New in version 3.8.

The CUDA/C++ standard whose features are requested to build this target.

This property specifies the CUDA/C++ standard whose features are
requested to build this target.  For some compilers, this results in
adding a flag such as ‘-std=gnu++11’ to the compile line.

Supported values are ‘98’, ‘03’, ‘11’, ‘14’, ‘17’, ‘20’.

If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead.
This means that using:

     set_property(TARGET tgt PROPERTY CUDA_STANDARD 11)

with a compiler which does not support ‘-std=gnu++11’ or an equivalent
flag will not result in an error or warning, but will instead add the
‘-std=gnu++98’ flag if supported.  This “decay” behavior may be
controlled with the CUDA_STANDARD_REQUIRED target property.
Additionally, the CUDA_EXTENSIONS target property may be
used to control whether compiler-specific extensions are enabled on a
per-target basis.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CUDA_STANDARD variable if it is set when a target is
created.

19.3.77 CUDA_STANDARD_REQUIRED
------------------------------

New in version 3.8.

Boolean describing whether the value of CUDA_STANDARD is a
requirement.

If this property is set to ‘ON’, then the value of the
CUDA_STANDARD target property is treated as a requirement.  If
this property is ‘OFF’ or unset, the CUDA_STANDARD target
property is treated as optional and may “decay” to a previous standard
if the requested is not available.  For compilers that have no notion of
a standard level, such as MSVC 1800 (Visual Studio 2013) and lower, this
has no effect.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CUDA_STANDARD_REQUIRED variable if it is set when a target
is created.

19.3.78 CXX_EXTENSIONS
----------------------

New in version 3.1.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be
used.  For some compilers, this results in adding a flag such as
‘-std=gnu++11’ instead of ‘-std=c++11’ to the compile line.  This
property is ‘ON’ by default.  The basic C++ standard level is controlled
by the CXX_STANDARD target property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CXX_EXTENSIONS variable if it is set when a target is
created.

19.3.79 CXX_STANDARD
--------------------

New in version 3.1.

The C++ standard whose features are requested to build this target.

This property specifies the C++ standard whose features are requested to
build this target.  For some compilers, this results in adding a flag
such as ‘-std=gnu++11’ to the compile line.  For compilers that have no
notion of a standard level, such as Microsoft Visual C++ before 2015
Update 3, this has no effect.

Supported values are ‘98’, ‘11’, ‘14’, ‘17’, and ‘20’.

If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead.
This means that using:

     set_property(TARGET tgt PROPERTY CXX_STANDARD 11)

with a compiler which does not support ‘-std=gnu++11’ or an equivalent
flag will not result in an error or warning, but will instead add the
‘-std=gnu++98’ flag if supported.  This “decay” behavior may be
controlled with the CXX_STANDARD_REQUIRED target property.
Additionally, the CXX_EXTENSIONS target property may be used
to control whether compiler-specific extensions are enabled on a
per-target basis.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CXX_STANDARD variable if it is set when a target is created.

19.3.80 CXX_STANDARD_REQUIRED
-----------------------------

New in version 3.1.

Boolean describing whether the value of CXX_STANDARD is a
requirement.

If this property is set to ‘ON’, then the value of the
CXX_STANDARD target property is treated as a requirement.  If this
property is ‘OFF’ or unset, the CXX_STANDARD target property
is treated as optional and may “decay” to a previous standard if the
requested is not available.  For compilers that have no notion of a
standard level, such as MSVC 1800 (Visual Studio 2013) and lower, this
has no effect.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_CXX_STANDARD_REQUIRED variable if it is set when a target is
created.

19.3.81 DEBUG_POSTFIX
---------------------

See target property <CONFIG>_POSTFIX.

This property is a special case of the more-general
<CONFIG>_POSTFIX property for the ‘DEBUG’ configuration.

19.3.82 DEFINE_SYMBOL
---------------------

Define a symbol when compiling this target’s sources.

‘DEFINE_SYMBOL’ sets the name of the preprocessor symbol defined when
compiling sources in a shared library.  If not set here then it is set
to ‘target_EXPORTS’ by default (with some substitutions if the target is
not a valid C identifier).  This is useful for headers to know whether
they are being included from inside their library or outside to properly
setup dllexport/dllimport decorations.

19.3.83 DEPLOYMENT_ADDITIONAL_FILES
-----------------------------------

New in version 3.13.

Set the WinCE project ‘AdditionalFiles’ in ‘DeploymentTool’ in ‘.vcproj’
files generated by the Visual Studio 9 2008 generator.  This
is useful when you want to debug on remote WinCE device.  Specify
additional files that will be copied to the device.  For example:

     set_property(TARGET ${TARGET} PROPERTY
       DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0"
       "german.lng|local_folder|remote_folder|0")

produces:

     <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... />

19.3.84 DEPLOYMENT_REMOTE_DIRECTORY
-----------------------------------

New in version 3.6.

Set the WinCE project ‘RemoteDirectory’ in ‘DeploymentTool’ and
‘RemoteExecutable’ in ‘DebuggerTool’ in ‘.vcproj’ files generated by the
Visual Studio 9 2008 generator.  This is useful when you
want to debug on remote WinCE device.  For example:

     set_property(TARGET ${TARGET} PROPERTY
       DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage")

produces:

     <DeploymentTool RemoteDirectory="\FlashStorage" ... />
     <DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... />

19.3.85 DEPRECATION
-------------------

New in version 3.17.

Deprecation message from imported target’s developer.

‘DEPRECATION’ is the message regarding a deprecation status to be
displayed to downstream users of a target.

19.3.86 DISABLE_PRECOMPILE_HEADERS
----------------------------------

New in version 3.16.

Disables the precompilation of header files specified by
PRECOMPILE_HEADERS property.

If the property is not set, CMake will use the value provided by
CMAKE_DISABLE_PRECOMPILE_HEADERS.

19.3.87 DOTNET_TARGET_FRAMEWORK
-------------------------------

New in version 3.17.

Specify the .NET target framework.

Used to specify the .NET target framework for C++/CLI and C#.  For
example: ‘netcoreapp2.1’.

This property is only evaluated for Visual Studio Generators.
VS 2010 and above.

Can be initialized for all targets using the variable
CMAKE_DOTNET_TARGET_FRAMEWORK.

19.3.88 DOTNET_TARGET_FRAMEWORK_VERSION
---------------------------------------

New in version 3.12.

Specify the .NET target framework version.

Used to specify the .NET target framework version for C++/CLI and C#.
For example: ‘v4.5’.

This property is only evaluated for Visual Studio Generators.
VS 2010 and above.

To initialize this variable for all targets set
CMAKE_DOTNET_TARGET_FRAMEWORK or
CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.  If both are set, the latter
is ignored.

19.3.89 EchoString
------------------

A message to be displayed when the target is built.

A message to display on some generators (such as Makefile Generators)
when the target is built.

19.3.90 ENABLE_EXPORTS
----------------------

Specify whether an executable exports symbols for loadable modules.

Normally an executable does not export any symbols because it is the
final program.  It is possible for an executable to export symbols to be
used by loadable modules.  When this property is set to true CMake will
allow other targets to “link” to the executable with the
target_link_libraries() command.  On all platforms a target-level
dependency on the executable is created for targets that link to it.
Handling of the executable on the link lines of the loadable modules
varies by platform:

   * On Windows-based systems (including Cygwin) an “import library” is
     created along with the executable to list the exported symbols.
     Loadable modules link to the import library to get the symbols.

   * On macOS, loadable modules link to the executable itself using the
     ‘-bundle_loader’ flag.

   * On AIX, a linker “import file” is created along with the executable
     to list the exported symbols for import when linking other targets.
     Loadable modules link to the import file to get the symbols.

   * On other platforms, loadable modules are simply linked without
     referencing the executable since the dynamic loader will
     automatically bind symbols when the module is loaded.

This property is initialized by the value of the variable
CMAKE_ENABLE_EXPORTS if it is set when a target is created.

19.3.91 EXCLUDE_FROM_ALL
------------------------

Set this target property to a true (or false) value to exclude (or
include) the target from the “all” target of the containing directory
and its ancestors.  If excluded, running e.g.  ‘make’ in the containing
directory or its ancestors will not build the target by default.

If this target property is not set then the target will be included in
the “all” target of the containing directory.  Furthermore, it will be
included in the “all” target of its ancestor directories unless the
EXCLUDE_FROM_ALL directory property is set.

With ‘EXCLUDE_FROM_ALL’ set to false or not set at all, the target will
be brought up to date as part of doing a ‘make install’ or its
equivalent for the CMake generator being used.

If a target has ‘EXCLUDE_FROM_ALL’ set to true, it may still be listed
in an install(TARGETS) command, but the user is responsible
for ensuring that the target’s build artifacts are not missing or
outdated when an install is performed.

This property may use “generator expressions” with the syntax ‘$<...>’.
See the cmake-generator-expressions(7) manual for available
expressions.

Only the “Ninja Multi-Config” generator supports a property value that
varies by configuration.  For all other generators the value of this
property must be the same for all configurations.

19.3.92 EXCLUDE_FROM_DEFAULT_BUILD
----------------------------------

Exclude target from ‘Build Solution’.

This property is only used by Visual Studio generators.  When set to
‘TRUE’, the target will not be built when you press ‘Build Solution’.

19.3.93 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
-------------------------------------------

Per-configuration version of target exclusion from ‘Build Solution’.

This is the configuration-specific version of
EXCLUDE_FROM_DEFAULT_BUILD.  If the generic
EXCLUDE_FROM_DEFAULT_BUILD is also set on a target,
‘EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>’ takes precedence in configurations
for which it has a value.

19.3.94 EXPORT_NAME
-------------------

Exported name for target files.

This sets the name for the ‘IMPORTED’ target generated by the
install(EXPORT) and export() commands.  If not set,
the logical target name is used by default.

19.3.95 EXPORT_PROPERTIES
-------------------------

New in version 3.12.

List additional properties to export for a target.

This property contains a list of property names that should be exported
by the install(EXPORT) and export() commands.
By default only a limited number of properties are exported.  This
property can be used to additionally export other properties as well.

Properties starting with ‘INTERFACE_’ or ‘IMPORTED_’ are not allowed as
they are reserved for internal CMake use.

Properties containing generator expressions are also not allowed.

     Note: Since CMake 3.19, see Interface Libraries may have
     arbitrary target properties.  If a project exports an interface
     library with custom properties, the resulting package may not work
     with dependents configured by older versions of CMake that reject
     the custom properties.

19.3.96 FOLDER
--------------

Set the folder name.  Use to organize targets in an IDE.

Targets with no ‘FOLDER’ property will appear as top level entities in
IDEs like Visual Studio.  Targets with the same ‘FOLDER’ property value
will appear next to each other in a folder of that name.  To nest
folders, use ‘FOLDER’ values such as ‘GUI/Dialogs’ with ‘/’ characters
separating folder levels.

This property is initialized by the value of the variable
CMAKE_FOLDER if it is set when a target is created.

19.3.97 Fortran_FORMAT
----------------------

Set to ‘FIXED’ or ‘FREE’ to indicate the Fortran source layout.

This property tells CMake whether the Fortran source files in a target
use fixed-format or free-format.  CMake will pass the corresponding
format flag to the compiler.  Use the source-specific ‘Fortran_FORMAT’
property to change the format of a specific source file.  If the
variable CMAKE_Fortran_FORMAT is set when a target is
created its value is used to initialize this property.

19.3.98 Fortran_MODULE_DIRECTORY
--------------------------------

Specify output directory for Fortran modules provided by the target.

If the target contains Fortran source files that provide modules and the
compiler supports a module output directory this specifies the directory
in which the modules will be placed.  When this property is not set the
modules will be placed in the build directory corresponding to the
target’s source directory.  If the variable
CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its
value is used to initialize this property.

When using one of the Visual Studio Generators with the
Intel Fortran plugin installed in Visual Studio, a subdirectory named
after the configuration will be appended to the path where modules are
created.  For example, if ‘Fortran_MODULE_DIRECTORY’ is set to
‘C:/some/path’, modules will end up in ‘C:/some/path/Debug’ (or
‘C:/some/path/Release’ etc.)  when an Intel Fortran ‘.vfproj’ file is
generated, and in ‘C:/some/path’ when any other generator is used.

Note that some compilers will automatically search the module output
directory for modules USEd during compilation but others will not.  If
your sources USE modules their location must be specified by
INCLUDE_DIRECTORIES regardless of this property.

19.3.99 Fortran_PREPROCESS
--------------------------

New in version 3.18.

Control whether the Fortran source file should be unconditionally
preprocessed.

If unset or empty, rely on the compiler to determine whether the file
should be preprocessed.  If explicitly set to ‘OFF’ then the file does
not need to be preprocessed.  If explicitly set to ‘ON’, then the file
does need to be preprocessed as part of the compilation step.

When using the Ninja generator, all source files are first
preprocessed in order to generate module dependency information.
Setting this property to ‘OFF’ will make ‘Ninja’ skip this step.

Use the source-specific Fortran_PREPROCESS property if a
single file needs to be preprocessed.  If the variable
CMAKE_Fortran_PREPROCESS is set when a target is created its value
is used to initialize this property.

     Note: For some compilers, ‘NAG’, ‘PGI’ and ‘Solaris Studio’,
     setting this to ‘OFF’ will have no effect.

19.3.100 FRAMEWORK
------------------

Build ‘SHARED’ or ‘STATIC’ library as Framework Bundle on the macOS and
iOS.

If such a library target has this property set to ‘TRUE’ it will be
built as a framework when built on the macOS and iOS. It will have the
directory structure required for a framework and will be suitable to be
used with the ‘-framework’ option.  This property is initialized by the
value of the CMAKE_FRAMEWORK variable if it is set when a
target is created.

To customize ‘Info.plist’ file in the framework, use
MACOSX_FRAMEWORK_INFO_PLIST target property.

For macOS see also the FRAMEWORK_VERSION target property.

Example of creation ‘dynamicFramework’:

     add_library(dynamicFramework SHARED
                 dynamicFramework.c
                 dynamicFramework.h
     )
     set_target_properties(dynamicFramework PROPERTIES
       FRAMEWORK TRUE
       FRAMEWORK_VERSION C
       MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework
       MACOSX_FRAMEWORK_INFO_PLIST Info.plist
       # "current version" in semantic format in Mach-O binary file
       VERSION 16.4.0
       # "compatibility version" in semantic format in Mach-O binary file
       SOVERSION 1.0.0
       PUBLIC_HEADER dynamicFramework.h
       XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer"
     )

19.3.101 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
------------------------------------------------

New in version 3.18.

Postfix to append to the framework file name for configuration
‘<CONFIG>’, when using a multi-config generator (like Xcode and Ninja
Multi-Config).

When building with configuration ‘<CONFIG>’ the value of this property
is appended to the framework file name built on disk.

For example, given a framework called ‘my_fw’, a value of ‘_debug’ for
the ‘FRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG’ property, and ‘Debug;Release’
in CMAKE_CONFIGURATION_TYPES, the following relevant files
would be created for the ‘Debug’ and ‘Release’ configurations:

   - ‘Release/my_fw.framework/my_fw’

   - ‘Release/my_fw.framework/Versions/A/my_fw’

   - ‘Debug/my_fw.framework/my_fw_debug’

   - ‘Debug/my_fw.framework/Versions/A/my_fw_debug’

For framework targets, this property is initialized by the value of the
CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> variable if it
is set when a target is created.

This property is ignored for non-framework targets, and when using
single config generators.

19.3.102 FRAMEWORK_VERSION
--------------------------

New in version 3.4.

Version of a framework created using the FRAMEWORK target
property (e.g.  ‘A’).

This property only affects macOS, as iOS doesn’t have versioned
directory structure.

19.3.103 GENERATOR_FILE_NAME
----------------------------

Generator’s file for this target.

An internal property used by some generators to record the name of the
project or dsp file associated with this target.  Note that at configure
time, this property is only set for targets created by
include_external_msproject().

19.3.104 GHS_INTEGRITY_APP
--------------------------

New in version 3.14.

‘ON’ / ‘OFF’ boolean to determine if an executable target should be
treated as an ‘Integrity Application’.

If no value is set and if a ‘.int’ file is added as a source file to the
executable target it will be treated as an ‘Integrity Application’.

Supported on Green Hills MULTI.

19.3.105 GHS_NO_SOURCE_GROUP_FILE
---------------------------------

New in version 3.14.

‘ON’ / ‘OFF’ boolean to control if the project file for a target should
be one single file or multiple files.

The default behavior or when the property is ‘OFF’ is to generate a
project file for the target and then a sub-project file for each source
group.

When this property is ‘ON’ or if CMAKE_GHS_NO_SOURCE_GROUP_FILE
is ‘ON’ then only a single project file is generated for the
target.

Supported on Green Hills MULTI.

19.3.106 GNUtoMS
----------------

Convert GNU import library (‘.dll.a’) to MS format (‘.lib’).

When linking a shared library or executable that exports symbols using
GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert
the import library (‘.dll.a’) from GNU to MS format (‘.lib’).  Both
import libraries will be installed by install(TARGETS) and
exported by install(EXPORT) and export() to be
linked by applications with either GNU- or MS-compatible tools.

If the variable ‘CMAKE_GNUtoMS’ is set when a target is created its
value is used to initialize this property.  The variable must be set
prior to the first command that enables a language such as
project() or enable_language().  CMake provides the
variable as an option to the user automatically when configuring on
Windows with GNU tools.

19.3.107 HAS_CXX
----------------

Link the target using the C++ linker tool (obsolete).

This is equivalent to setting the LINKER_LANGUAGE property
to ‘CXX’.

19.3.108 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
-------------------------------------------

Specify ‘#include’ line transforms for dependencies in a target.

This property specifies rules to transform macro-like ‘#include’ lines
during implicit dependency scanning of C and C++ source files.  The list
of rules must be semicolon-separated with each entry of the form
‘A_MACRO(%)=value-with-%’ (the ‘%’ must be literal).  During dependency
scanning occurrences of ‘A_MACRO(...)’ on ‘#include’ lines will be
replaced by the value given with the macro argument substituted for ‘%’.
For example, the entry

     MYDIR(%)=<mydir/%>

will convert lines of the form

     #include MYDIR(myheader.h)

to

     #include <mydir/myheader.h>

allowing the dependency to be followed.

This property applies to sources in the target on which it is set.

19.3.109 IMPORTED
-----------------

Read-only indication of whether a target is ‘IMPORTED’.

The boolean value of this property is ‘True’ for targets created with
the ‘IMPORTED’ option to add_executable() or
add_library().  It is ‘False’ for targets built within the project.

19.3.110 IMPORTED_COMMON_LANGUAGE_RUNTIME
-----------------------------------------

New in version 3.12.

Property to define if the target uses ‘C++/CLI’.

Ignored for non-imported targets.

See also the COMMON_LANGUAGE_RUNTIME target property.

19.3.111 IMPORTED_CONFIGURATIONS
--------------------------------

Configurations provided for an IMPORTED target.

Set this to the list of configuration names available for an IMPORTED
target.  The names correspond to configurations defined in the project
from which the target is imported.  If the importing project uses a
different set of configurations the names may be mapped using the
MAP_IMPORTED_CONFIG_<CONFIG> property.  Ignored for non-imported
targets.

19.3.112 IMPORTED_GLOBAL
------------------------

New in version 3.11.

Indication of whether an IMPORTED target is globally
visible.

The boolean value of this property is True for targets created with the
‘IMPORTED’ ‘GLOBAL’ options to add_executable() or
add_library().  It is always False for targets built within the
project.

For targets created with the ‘IMPORTED’ option to
add_executable() or add_library() but without the
additional option ‘GLOBAL’ this is False, too.  However, setting this
property for such a locally ‘IMPORTED’ target to True promotes that
target to global scope.  This promotion can only be done in the same
directory where that ‘IMPORTED’ target was created in the first place.

     Note: Once an imported target has been made global, it cannot be
     changed back to non-global.  Therefore, if a project sets this
     property, it may only provide a value of True.  CMake will issue an
     error if the project tries to set the property to a non-True value,
     even if the value was already False.

     Note: Local ALIAS targets created before promoting an
     IMPORTED target from ‘LOCAL’ to ‘GLOBAL’, keep their
     initial scope (see ALIAS_GLOBAL target property).

19.3.113 IMPORTED_IMPLIB
------------------------

Full path to the import library for an ‘IMPORTED’ target.

Set this to the location of the ‘.lib’ part of a Windows DLL, or on AIX
set it to an import file created for executables that export symbols
(see the ENABLE_EXPORTS target property).  Ignored for
non-imported targets.

19.3.114 IMPORTED_IMPLIB_<CONFIG>
---------------------------------

<CONFIG>-specific version of IMPORTED_IMPLIB property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.115 IMPORTED_LIBNAME
-------------------------

New in version 3.8.

Specify the link library name for an imported. See
Interface Library.

An interface library builds no library file itself but does specify
usage requirements for its consumers.  The ‘IMPORTED_LIBNAME’ property
may be set to specify a single library name to be placed on the link
line in place of the interface library target name as a requirement for
using the interface.

This property is intended for use in naming libraries provided by a
platform SDK for which the full path to a library file may not be known.
The value may be a plain library name such as ‘foo’ but may `not' be a
path (e.g.  ‘/usr/lib/libfoo.so’) or a flag (e.g.  ‘-Wl,...’).  The name
is never treated as a library target name even if it happens to name
one.

The ‘IMPORTED_LIBNAME’ property is allowed only on imported.
Interface Libraries and is rejected on targets of other
types (for which the IMPORTED_LOCATION target property may
be used).

19.3.116 IMPORTED_LIBNAME_<CONFIG>
----------------------------------

New in version 3.8.

<CONFIG>-specific version of IMPORTED_LIBNAME property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.117 IMPORTED_LINK_DEPENDENT_LIBRARIES
------------------------------------------

Dependent shared libraries of an imported shared library.

Shared libraries may be linked to other shared libraries as part of
their implementation.  On some platforms the linker searches for the
dependent libraries of shared libraries they are including in the link.
Set this property to the list of dependent shared libraries of an
imported library.  The list should be disjoint from the list of
interface libraries in the INTERFACE_LINK_LIBRARIES.
property.  On platforms requiring dependent shared libraries to be found
at link time CMake uses this list to add appropriate files or paths to
the link command line.  Ignored for non-imported targets.

19.3.118 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
---------------------------------------------------

<CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.

Configuration names correspond to those provided by the project from
which the target is imported.  If set, this property completely
overrides the generic property for the named configuration.

19.3.119 IMPORTED_LINK_INTERFACE_LANGUAGES
------------------------------------------

Languages compiled into an ‘IMPORTED’ static library.

Set this to the list of languages of source files compiled to produce a
‘STATIC IMPORTED’ library (such as ‘C’ or ‘CXX’).  CMake accounts for
these languages when computing how to link a target to the imported
library.  For example, when a C executable links to an imported C++
static library CMake chooses the C++ linker to satisfy language runtime
dependencies of the static library.

This property is ignored for targets that are not ‘STATIC’ libraries.
This property is ignored for non-imported targets.

19.3.120 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
---------------------------------------------------

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.

Configuration names correspond to those provided by the project from
which the target is imported.  If set, this property completely
overrides the generic property for the named configuration.

19.3.121 IMPORTED_LINK_INTERFACE_LIBRARIES
------------------------------------------

Transitive link interface of an ‘IMPORTED’ target.

Set this to the list of libraries whose interface is included when an
‘IMPORTED’ library target is linked to another target.  The libraries
will be included on the link line for the target.  Unlike the
LINK_INTERFACE_LIBRARIES property, this property applies to all
imported target types, including ‘STATIC’ libraries.  This property is
ignored for non-imported targets.

This property is ignored if the target also has a non-empty
INTERFACE_LINK_LIBRARIES property.

This property is deprecated.  Use INTERFACE_LINK_LIBRARIES.
instead.

19.3.122 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
---------------------------------------------------

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.

Configuration names correspond to those provided by the project from
which the target is imported.  If set, this property completely
overrides the generic property for the named configuration.

This property is ignored if the target also has a non-empty
INTERFACE_LINK_LIBRARIES property.

This property is deprecated.  Use INTERFACE_LINK_LIBRARIES.
instead.

19.3.123 IMPORTED_LINK_INTERFACE_MULTIPLICITY
---------------------------------------------

Repetition count for cycles of ‘IMPORTED’ static libraries.

This is LINK_INTERFACE_MULTIPLICITY for ‘IMPORTED’ targets.

19.3.124 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
------------------------------------------------------

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY.

If set, this property completely overrides the generic property for the
named configuration.

19.3.125 IMPORTED_LOCATION
--------------------------

Full path to the main file on disk for an ‘IMPORTED’ target.

Set this to the location of an ‘IMPORTED’ target file on disk.  For
executables this is the location of the executable file.  For bundles on
macOS this is the location of the executable file inside
‘Contents/MacOS’ under the application bundle folder.  For ‘STATIC’
libraries and modules this is the location of the library or module.
For ‘SHARED’ libraries on non-DLL platforms this is the location of the
shared library.  For frameworks on macOS this is the location of the
library file symlink just inside the framework folder.  For DLLs this is
the location of the ‘.dll’ part of the library.  For ‘UNKNOWN’ libraries
this is the location of the file to be linked.  Ignored for non-imported
targets.

The ‘IMPORTED_LOCATION’ target property may be overridden for a given
configuration ‘<CONFIG>’ by the configuration-specific
IMPORTED_LOCATION_<CONFIG> target property.  Furthermore, the
MAP_IMPORTED_CONFIG_<CONFIG> target property may be used to
map between a project’s configurations and those of an imported target.
If none of these is set then the name of any other configuration listed
in the IMPORTED_CONFIGURATIONS target property may be
selected and its IMPORTED_LOCATION_<CONFIG> value used.

To get the location of an imported target read one of the
LOCATION or ‘LOCATION_<CONFIG>’ properties.

For platforms with import libraries (e.g.  Windows) see also
IMPORTED_IMPLIB.

19.3.126 IMPORTED_LOCATION_<CONFIG>
-----------------------------------

<CONFIG>-specific version of IMPORTED_LOCATION property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.127 IMPORTED_NO_SONAME
---------------------------

Specifies that an ‘IMPORTED’ shared library target has no ‘soname’.

Set this property to true for an imported shared library file that has
no ‘soname’ field.  CMake may adjust generated link commands for some
platforms to prevent the linker from using the path to the library in
place of its missing ‘soname’.  Ignored for non-imported targets.

19.3.128 IMPORTED_NO_SONAME_<CONFIG>
------------------------------------

<CONFIG>-specific version of IMPORTED_NO_SONAME property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.129 IMPORTED_OBJECTS
-------------------------

New in version 3.9.

A semicolon-separated list of absolute paths to the object
files on disk for an imported. See object library.

Ignored for non-imported targets.

Projects may skip ‘IMPORTED_OBJECTS’ if the configuration-specific
property IMPORTED_OBJECTS_<CONFIG> is set instead.

19.3.130 IMPORTED_OBJECTS_<CONFIG>
----------------------------------

New in version 3.9.

<CONFIG>-specific version of IMPORTED_OBJECTS property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.131 IMPORTED_SONAME
------------------------

The ‘soname’ of an ‘IMPORTED’ target of shared library type.

Set this to the ‘soname’ embedded in an imported shared library.  This
is meaningful only on platforms supporting the feature.  Ignored for
non-imported targets.

19.3.132 IMPORTED_SONAME_<CONFIG>
---------------------------------

<CONFIG>-specific version of IMPORTED_SONAME property.

Configuration names correspond to those provided by the project from
which the target is imported.

19.3.133 IMPORT_PREFIX
----------------------

What comes before the import library name.

Similar to the target property PREFIX, but used for import
libraries (typically corresponding to a ‘DLL’) instead of regular
libraries.  A target property that can be set to override the prefix
(such as ‘lib’) on an import library name.

19.3.134 IMPORT_SUFFIX
----------------------

What comes after the import library name.

Similar to the target property SUFFIX, but used for import
libraries (typically corresponding to a ‘DLL’) instead of regular
libraries.  A target property that can be set to override the suffix
(such as ‘.lib’) on an import library name.

19.3.135 INCLUDE_DIRECTORIES
----------------------------

List of preprocessor include file search directories.

This property specifies the list of directories given so far to the
target_include_directories() command.  In addition to
accepting values from that command, values may be set directly on any
target using the set_property() command.  A target gets its
initial value for this property from the value of the
INCLUDE_DIRECTORIES directory property.  Both directory and target
property values are adjusted by calls to the
include_directories() command.

The value of this property is used by the generators to set the include
paths for the compiler.

Relative paths should not be added to this property directly.  Use one
of the commands above instead to handle relative paths.

Contents of ‘INCLUDE_DIRECTORIES’ may use
cmake-generator-expressions(7) with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available
expressions.  See the cmake-buildsystem(7) manual for more on
defining buildsystem properties.

19.3.136 INSTALL_NAME_DIR
-------------------------

macOS directory name for installed targets.

‘INSTALL_NAME_DIR’ is a string specifying the directory portion of the
“install_name” field of shared libraries on macOS to use in the
installed targets.

This property is initialized by the value of the variable
CMAKE_INSTALL_NAME_DIR if it is set when a target is created.

This property supports generator expressions.  In particular,
the ‘$<INSTALL_PREFIX>’ generator expression can be used to set the
directory relative to the install-time prefix.

19.3.137 INSTALL_REMOVE_ENVIRONMENT_RPATH
-----------------------------------------

New in version 3.16.

Controls whether toolchain-defined rpaths should be removed during
installation.

When a target is being installed, CMake may need to rewrite its rpath
information.  This occurs when the install rpath (as specified by the
INSTALL_RPATH target property) has different contents to the
rpath that the target was built with.  Some toolchains insert their own
rpath contents into the binary as part of the build.  By default, CMake
will preserve those extra inserted contents in the install rpath.  For
those scenarios where such toolchain-inserted entries need to be
discarded during install, set the ‘INSTALL_REMOVE_ENVIRONMENT_RPATH’
target property to true.

This property is initialized by the value of
CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH when the target is created.

19.3.138 INSTALL_RPATH
----------------------

The rpath to use for installed targets.

A semicolon-separated list specifying the rpath to use in installed
targets (for platforms that support it).  This property is initialized
by the value of the variable CMAKE_INSTALL_RPATH if it is
set when a target is created.

Because the rpath may contain ‘${ORIGIN}’, which coincides with CMake
syntax, the contents of ‘INSTALL_RPATH’ are properly escaped in the
‘cmake_install.cmake’ script (see policy CMP0095)

This property supports generator expressions.

19.3.139 INSTALL_RPATH_USE_LINK_PATH
------------------------------------

Add paths to linker search and installed rpath.

‘INSTALL_RPATH_USE_LINK_PATH’ is a boolean that if set to ‘True’ will
append to the runtime search path (rpath) of installed binaries any
directories outside the project that are in the linker search path or
contain linked library files.  The directories are appended after the
value of the INSTALL_RPATH target property.

This property is initialized by the value of the variable
CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a target is
created.

19.3.140 INTERFACE_AUTOUIC_OPTIONS
----------------------------------

List of interface options to pass to uic.

Targets may populate this property to publish the options required to
use when invoking ‘uic’.  Consuming targets can add entries to their own
AUTOUIC_OPTIONS property such as
‘$<TARGET_PROPERTY:foo,INTERFACE_AUTOUIC_OPTIONS>’ to use the uic
options specified in the interface of ‘foo’.  This is done automatically
by the target_link_libraries() command.

This property supports generator expressions.  See the
cmake-generator-expressions(7) manual for available expressions.

19.3.141 INTERFACE_COMPILE_DEFINITIONS
--------------------------------------

List of public compile definitions requirements for a library.

Targets may populate this property to publish the compile definitions
required to compile against the headers for the target.  The
target_compile_definitions() command populates this property with
values given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may
also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_COMPILE_DEFINITIONS’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7). -manual for more on defining
buildsystem properties.

19.3.142 INTERFACE_COMPILE_FEATURES
-----------------------------------

New in version 3.1.

List of public compile features requirements for a library.

Targets may populate this property to publish the compile features
required to compile against the headers for the target.  The
target_compile_features() command populates this property with
values given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may
also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_COMPILE_FEATURES’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7). -manual for more on defining buildsystem
properties.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

19.3.143 INTERFACE_COMPILE_OPTIONS
----------------------------------

List of public compile options requirements for a library.

Targets may populate this property to publish the compile options
required to compile against the headers for the target.  The
target_compile_options() command populates this property with
values given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may
also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_COMPILE_OPTIONS’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7). -manual for more on defining buildsystem
properties.

19.3.144 INTERFACE_INCLUDE_DIRECTORIES
--------------------------------------

List of public include directories requirements for a library.

Targets may populate this property to publish the include directories
required to compile against the headers for the target.  The
target_include_directories() command populates this property with
values given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may
also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_INCLUDE_DIRECTORIES’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7). -manual for more on defining
buildsystem properties.

Include directories usage requirements commonly differ between the
build-tree and the install-tree.  The ‘BUILD_INTERFACE’ and
‘INSTALL_INTERFACE’ generator expressions can be used to describe
separate usage requirements based on the usage location.  Relative paths
are allowed within the ‘INSTALL_INTERFACE’ expression and are
interpreted relative to the installation prefix.  For example:

     target_include_directories(mylib INTERFACE
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
       $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
     )

19.3.144.1 Creating Relocatable Packages
........................................

Note that it is not advisable to populate the ‘INSTALL_INTERFACE’ of the
‘INTERFACE_INCLUDE_DIRECTORIES’ of a target with absolute paths to the
include directories of dependencies.  That would hard-code into
installed packages the include directory paths for dependencies `as
found on the machine the package was made on'.

The ‘INSTALL_INTERFACE’ of the ‘INTERFACE_INCLUDE_DIRECTORIES’ is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target
property.  Those dependencies should themselves be targets that specify
their own header locations in ‘INTERFACE_INCLUDE_DIRECTORIES’.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

19.3.145 INTERFACE_LINK_DEPENDS
-------------------------------

New in version 3.13.

Additional public interface files on which a target binary depends for
linking.

This property is supported only by Ninja and Makefile Generators.
It is intended to specify dependencies on “linker
scripts” for custom Makefile link rules.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_LINK_DEPENDS’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7). -manual for more on defining buildsystem
properties.

Link dependency files usage requirements commonly differ between the
build-tree and the install-tree.  The ‘BUILD_INTERFACE’ and
‘INSTALL_INTERFACE’ generator expressions can be used to describe
separate usage requirements based on the usage location.  Relative paths
are allowed within the ‘INSTALL_INTERFACE’ expression and are
interpreted relative to the installation prefix.  For example:

     set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript>
       $<INSTALL_INTERFACE:mylinkscript>  # <prefix>/mylinkscript
     )

19.3.146 INTERFACE_LINK_DIRECTORIES
-----------------------------------

New in version 3.13.

List of public link directories requirements for a library.

Targets may populate this property to publish the link directories
required to compile against the headers for the target.  The
target_link_directories() command populates this property with
values given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may
also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_LINK_DIRECTORIES’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7). -manual for more on defining buildsystem
properties.

19.3.147 INTERFACE_LINK_LIBRARIES
---------------------------------

List public interface libraries for a library.

This property contains the list of transitive link dependencies.  When
the target is linked into another target using the
target_link_libraries() command, the libraries listed (and
recursively their link interface libraries) will be provided to the
other target also.  This property is overridden by the
LINK_INTERFACE_LIBRARIES or
LINK_INTERFACE_LIBRARIES_<CONFIG> property if policy
CMP0022 is ‘OLD’ or unset.

Contents of ‘INTERFACE_LINK_LIBRARIES’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

     Note: A call to target_link_libraries(<target> ...) may
     update this property on ‘<target>’.  If ‘<target>’ was not created
     in the same directory as the call then
     target_link_libraries() will wrap each entry with the form
     ‘::@(directory-id);...;::@’, where the ‘::@’ is literal and the
     ‘(directory-id)’ is unspecified.  This tells the generators that
     the named libraries must be looked up in the scope of the caller
     rather than in the scope in which the ‘<target>’ was created.
     Valid directory ids are stripped on export by the
     install(EXPORT) and export() commands.

19.3.147.1 Creating Relocatable Packages
........................................

Note that it is not advisable to populate the ‘INTERFACE_LINK_LIBRARIES’
of a target with absolute paths to dependencies.  That would hard-code
into installed packages the library file paths for dependencies `as
found on the machine the package was made on'.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

19.3.148 INTERFACE_LINK_OPTIONS
-------------------------------

New in version 3.13.

List of public link options requirements for a library.

Targets may populate this property to publish the link options required
to compile against the headers for the target.  The
target_link_options() command populates this property with values
given to the ‘PUBLIC’ and ‘INTERFACE’ keywords.  Projects may also get
and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the build properties of the consumer.

Contents of ‘INTERFACE_LINK_OPTIONS’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7). -manual for more on defining buildsystem
properties.

19.3.149 INTERFACE_POSITION_INDEPENDENT_CODE
--------------------------------------------

Whether consumers need to create a position-independent target

The ‘INTERFACE_POSITION_INDEPENDENT_CODE’ property informs consumers of
this target whether they must set their POSITION_INDEPENDENT_CODE
property to ‘ON’.  If this property is set to ‘ON’, then the
POSITION_INDEPENDENT_CODE property on all consumers will be set to
‘ON’.  Similarly, if this property is set to ‘OFF’, then the
POSITION_INDEPENDENT_CODE property on all consumers will be set to
‘OFF’.  If this property is undefined, then consumers will determine
their POSITION_INDEPENDENT_CODE property by other means.
Consumers must ensure that the targets that they link to have a
consistent requirement for their ‘INTERFACE_POSITION_INDEPENDENT_CODE’
property.

Contents of ‘INTERFACE_POSITION_INDEPENDENT_CODE’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

19.3.150 INTERFACE_PRECOMPILE_HEADERS
-------------------------------------

New in version 3.16.

List of interface header files to precompile into consuming targets.

Targets may populate this property to publish the header files for
consuming targets to precompile.  The target_precompile_headers()
command populates this property with values given to the ‘PUBLIC’
and ‘INTERFACE’ keywords.  Projects may also get and set the property
directly.  See the discussion in target_precompile_headers().
for guidance on appropriate use of this property for installed or
exported targets.

Contents of ‘INTERFACE_PRECOMPILE_HEADERS’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

19.3.151 INTERFACE_SOURCES
--------------------------

New in version 3.1.

List of interface sources to compile into consuming targets.

Targets may populate this property to publish the sources for consuming
targets to compile.  The target_sources() command populates
this property with values given to the ‘PUBLIC’ and ‘INTERFACE’
keywords.  Projects may also get and set the property directly.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to determine the sources of the consumer.

Contents of ‘INTERFACE_SOURCES’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.3.152 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
---------------------------------------------

List of public system include directories for a library.

Targets may populate this property to publish the include directories
which contain system headers, and therefore should not result in
compiler warnings.  The target_include_directories(SYSTEM).
command signature populates this property with values given to the
‘PUBLIC’ and ‘INTERFACE’ keywords.

Projects may also get and set the property directly, but must be aware
that adding directories to this property does not make those directories
used during compilation.  Adding directories to this property marks
directories as ‘SYSTEM’ which otherwise would be used in a non-‘SYSTEM’
manner.  This can appear similar to ‘duplication’, so prefer the
high-level target_include_directories(SYSTEM) command and
avoid setting the property by low-level means.

When target dependencies are specified using
target_link_libraries(), CMake will read this property from all
target dependencies to mark the same include directories as containing
system headers.

Contents of ‘INTERFACE_SYSTEM_INCLUDE_DIRECTORIES’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

19.3.153 INTERPROCEDURAL_OPTIMIZATION
-------------------------------------

Enable interprocedural optimization for a target.

If set to true, enables interprocedural optimizations if they are known
to be supported by the compiler.  Depending on value of
policy CMP0069, the error will be reported or ignored, if
interprocedural optimization is enabled but not supported.

This property is initialized by the
CMAKE_INTERPROCEDURAL_OPTIMIZATION variable if it is set when a
target is created.

19.3.154 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
----------------------------------------------

Per-configuration interprocedural optimization for a target.

This is a per-configuration version of
INTERPROCEDURAL_OPTIMIZATION.  If set, this property overrides the
generic property for the named configuration.

This property is initialized by the
CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> variable if it is set
when a target is created.

19.3.155 IOS_INSTALL_COMBINED
-----------------------------

New in version 3.5.

Build a combined (device and simulator) target when installing.

When this property is set to set to false (which is the default) then it
will either be built with the device SDK or the simulator SDK depending
on the SDK set.  But if this property is set to true then the target
will at install time also be built for the corresponding SDK and
combined into one library.

     Note: If a selected architecture is available for both: device SDK
     and simulator SDK it will be built for the SDK selected by
     CMAKE_OSX_SYSROOT and removed from the corresponding SDK.

This feature requires at least Xcode version 6.

19.3.156 ISPC_HEADER_DIRECTORY
------------------------------

New in version 3.19.

Specify relative output directory for ISPC headers provided by the
target.

If the target contains ISPC source files, this specifies the directory
in which the generated headers will be placed.  Relative paths are
treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
When this property is not set, the headers will be placed a
generator defined build directory.  If the variable
CMAKE_ISPC_HEADER_DIRECTORY is set when a target is created its
value is used to initialize this property.

19.3.157 ISPC_HEADER_SUFFIX
---------------------------

New in version 3.19.2.

Specify output suffix to be used for ISPC generated headers provided by
the target.

This property is initialized by the value of the
CMAKE_ISPC_HEADER_SUFFIX variable if it is set when a target is
created.

If the target contains ISPC source files, this specifies the header
suffix to be used for the generated headers.

The default value is ‘_ispc.h’.

19.3.158 ISPC_INSTRUCTION_SETS
------------------------------

New in version 3.19.

List of instruction set architectures to generate code for.

This property is initialized by the value of the
CMAKE_ISPC_INSTRUCTION_SETS variable if it is set when a target is
created.

The ‘ISPC_INSTRUCTION_SETS’ target property must be used when generating
for multiple instruction sets so that CMake can track what object files
will be generated.

19.3.158.1 Examples
...................

     set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835)

Generates code for avx2 and avx512skx target architectures.

19.3.159 JOB_POOL_COMPILE
-------------------------

Ninja only: Pool used for compiling.

The number of parallel compile processes could be limited by defining
pools with the global JOB_POOLS property and then specifying
here the pool name.

For instance:

     set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs)

This property is initialized by the value of
CMAKE_JOB_POOL_COMPILE.

19.3.160 JOB_POOL_LINK
----------------------

Ninja only: Pool used for linking.

The number of parallel link processes could be limited by defining pools
with the global JOB_POOLS property and then specifying here
the pool name.

For instance:

     set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs)

This property is initialized by the value of CMAKE_JOB_POOL_LINK.

19.3.161 JOB_POOL_PRECOMPILE_HEADER
-----------------------------------

New in version 3.17.

Ninja only: Pool used for generating pre-compiled headers.

The number of parallel compile processes could be limited by defining
pools with the global JOB_POOLS property and then specifying
here the pool name.

For instance:

     set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs)

This property is initialized by the value of
CMAKE_JOB_POOL_PRECOMPILE_HEADER.

If neither JOB_POOL_PRECOMPILE_HEADER nor
CMAKE_JOB_POOL_PRECOMPILE_HEADER are set then
JOB_POOL_COMPILE will be used for this task.

19.3.162 LABELS
---------------

Specify a list of text labels associated with a target.

Target label semantics are currently unspecified.

19.3.163 <LANG>_CLANG_TIDY
--------------------------

New in version 3.6.

This property is implemented only when ‘<LANG>’ is ‘C’ or ‘CXX’.

Specify a semicolon-separated list containing a command line
for the ‘clang-tidy’ tool.  The Makefile Generators and the
Ninja generator will run this tool along with the compiler
and report a warning if the tool reports any problems.

This property is initialized by the value of the
CMAKE_<LANG>_CLANG_TIDY variable if it is set when a target is
created.

19.3.164 <LANG>_COMPILER_LAUNCHER
---------------------------------

New in version 3.4.

This property is implemented only when ‘<LANG>’ is ‘C’, ‘CXX’,
‘Fortran’, ‘ISPC’, ‘OBJC’, ‘OBJCXX’, or ‘CUDA’.

Specify a semicolon-separated list containing a command line
for a compiler launching tool.  The Makefile Generators and
the Ninja generator will run this tool and pass the compiler
and its arguments to the tool.  Some example tools are distcc and
ccache.

This property is initialized by the value of the
CMAKE_<LANG>_COMPILER_LAUNCHER variable if it is set when a target
is created.

19.3.165 <LANG>_CPPCHECK
------------------------

New in version 3.10.

This property is supported only when ‘<LANG>’ is ‘C’ or ‘CXX’.

Specify a semicolon-separated list containing a command line
for the ‘cppcheck’ static analysis tool.  The Makefile Generators
and the Ninja generator will run ‘cppcheck’ along with
the compiler and report any problems.  If the command-line specifies the
exit code options to ‘cppcheck’ then the build will fail if the tool
returns non-zero.

This property is initialized by the value of the
CMAKE_<LANG>_CPPCHECK variable if it is set when a target is
created.

19.3.166 <LANG>_CPPLINT
-----------------------

New in version 3.8.

This property is supported only when ‘<LANG>’ is ‘C’ or ‘CXX’.

Specify a semicolon-separated list containing a command line
for the ‘cpplint’ style checker.  The Makefile Generators and
the Ninja generator will run ‘cpplint’ along with the
compiler and report any problems.

This property is initialized by the value of the
CMAKE_<LANG>_CPPLINT variable if it is set when a target is
created.

19.3.167 <LANG>_INCLUDE_WHAT_YOU_USE
------------------------------------

New in version 3.3.

This property is implemented only when ‘<LANG>’ is ‘C’ or ‘CXX’.

Specify a semicolon-separated list containing a command line
for the ‘include-what-you-use’ tool.  The Makefile Generators.
and the Ninja generator will run this tool along with the
compiler and report a warning if the tool reports any problems.

This property is initialized by the value of the
CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE variable if it is set when a
target is created.

19.3.168 <LANG>_VISIBILITY_PRESET
---------------------------------

Value for symbol visibility compile flags

The ‘<LANG>_VISIBILITY_PRESET’ property determines the value passed in a
visibility related compile option, such as ‘-fvisibility=’ for ‘<LANG>’.
This property affects compilation in sources of all types of targets
(subject to policy CMP0063).

This property is initialized by the value of the
CMAKE_<LANG>_VISIBILITY_PRESET variable if it is set when a target
is created.

19.3.169 LIBRARY_OUTPUT_DIRECTORY
---------------------------------

Output directory in which to build LIBRARY target files.

This property specifies the directory into which library target files
should be built.  The property value may use generator expressions.
Multi-configuration generators (VS, Xcode) append a
per-configuration subdirectory to the specified directory unless a
generator expression is used.

This property is initialized by the value of the variable
CMAKE_LIBRARY_OUTPUT_DIRECTORY if it is set when a target is created.

See also the LIBRARY_OUTPUT_DIRECTORY_<CONFIG> target
property.

19.3.170 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
------------------------------------------

Per-configuration output directory for LIBRARY target files.

This is a per-configuration version of the
LIBRARY_OUTPUT_DIRECTORY target property, but multi-configuration
generators (see Visual Studio Generators, Xcode) do
NOT append a per-configuration subdirectory to the specified directory.
This property is initialized by the value of the
CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when
a target is created.

Contents of ‘LIBRARY_OUTPUT_DIRECTORY_<CONFIG>’ may use generator expressions.

19.3.171 LIBRARY_OUTPUT_NAME
----------------------------

Output name for LIBRARY target files.

This property specifies the base name for library target files.  It
overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG>.
properties.

See also the LIBRARY_OUTPUT_NAME_<CONFIG> target property.

19.3.172 LIBRARY_OUTPUT_NAME_<CONFIG>
-------------------------------------

Per-configuration output name for LIBRARY target files.

This is the configuration-specific version of the
LIBRARY_OUTPUT_NAME target property.

19.3.173 LINK_DEPENDS
---------------------

Additional files on which a target binary depends for linking.

Specifies a semicolon-separated list of full-paths to files on which the
link rule for this target depends.  The target binary will be linked if
any of the named files is newer than it.

This property is supported only by Ninja and Makefile Generators.
It is intended to specify dependencies on “linker
scripts” for custom Makefile link rules.

Contents of ‘LINK_DEPENDS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.3.174 LINK_DEPENDS_NO_SHARED
-------------------------------

Do not depend on linked shared library files.

Set this property to true to tell CMake generators not to add file-level
dependencies on the shared library files linked by this target.
Modification to the shared libraries will not be sufficient to re-link
this target.  Logical target-level dependencies will not be affected so
the linked shared libraries will still be brought up to date before this
target is built.

This property is initialized by the value of the variable
CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created.

19.3.175 LINK_DIRECTORIES
-------------------------

New in version 3.13.

List of directories to use for the link step of shared library, module
and executable targets.

This property holds a semicolon-separated list of directories
specified so far for its target.  Use the
target_link_directories() command to append more search
directories.

This property is initialized by the LINK_DIRECTORIES.
directory property when a target is created, and is used by the
generators to set the search directories for the linker.

Contents of ‘LINK_DIRECTORIES’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

19.3.176 LINK_FLAGS
-------------------

Additional flags to use when linking this target if it is a shared
library, module library, or an executable.  Static libraries need to use
STATIC_LIBRARY_OPTIONS or STATIC_LIBRARY_FLAGS.
properties.

The ‘LINK_FLAGS’ property, managed as a string, can be used to add extra
flags to the link step of a target.  See LINK_FLAGS_<CONFIG>.
will add to the configuration ‘<CONFIG>’, for example, ‘DEBUG’,
‘RELEASE’, ‘MINSIZEREL’, ‘RELWITHDEBINFO’, …

     Note: This property has been superseded by LINK_OPTIONS.
     property.

19.3.177 LINK_FLAGS_<CONFIG>
----------------------------

Per-configuration linker flags for a ‘SHARED’ library, ‘MODULE’ or
‘EXECUTABLE’ target.

This is the configuration-specific version of LINK_FLAGS.

     Note: This property has been superseded by LINK_OPTIONS.
     property.

19.3.178 LINK_INTERFACE_LIBRARIES
---------------------------------

List public interface libraries for a shared library or executable.

By default linking to a shared library target transitively links to
targets with which the library itself was linked.  For an executable
with exports (see the ENABLE_EXPORTS target property) no
default transitive link dependencies are used.  This property replaces
the default transitive link dependencies with an explicit list.  When
the target is linked into another target using the
target_link_libraries() command, the libraries listed (and
recursively their link interface libraries) will be provided to the
other target also.  If the list is empty then no transitive link
dependencies will be incorporated when this target is linked into
another target even if the default set is non-empty.  This property is
initialized by the value of the CMAKE_LINK_INTERFACE_LIBRARIES
variable if it is set when a target is created.  This property is
ignored for ‘STATIC’ libraries.

This property is overridden by the INTERFACE_LINK_LIBRARIES.
property if policy CMP0022 is ‘NEW’.

This property is deprecated.  Use INTERFACE_LINK_LIBRARIES.
instead.

19.3.178.1 Creating Relocatable Packages
........................................

Note that it is not advisable to populate the ‘LINK_INTERFACE_LIBRARIES’
of a target with absolute paths to dependencies.  That would hard-code
into installed packages the library file paths for dependencies `as
found on the machine the package was made on'.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

19.3.179 LINK_INTERFACE_LIBRARIES_<CONFIG>
------------------------------------------

Per-configuration list of public interface libraries for a target.

This is the configuration-specific version of
LINK_INTERFACE_LIBRARIES.  If set, this property completely
overrides the generic property for the named configuration.

This property is overridden by the INTERFACE_LINK_LIBRARIES.
property if policy CMP0022 is ‘NEW’.

This property is deprecated.  Use INTERFACE_LINK_LIBRARIES.
instead.

19.3.179.1 Creating Relocatable Packages
........................................

Note that it is not advisable to populate the
‘LINK_INTERFACE_LIBRARIES_<CONFIG>’ of a target with absolute paths to
dependencies.  That would hard-code into installed packages the library
file paths for dependencies `as found on the machine the package was
made on'.

See the Creating Relocatable Packages section of the
cmake-packages(7) manual for discussion of additional care that must
be taken when specifying usage requirements while creating packages for
redistribution.

19.3.180 LINK_INTERFACE_MULTIPLICITY
------------------------------------

Repetition count for ‘STATIC’ libraries with cyclic dependencies.

When linking to a ‘STATIC’ library target with cyclic dependencies the
linker may need to scan more than once through the archives in the
strongly connected component of the dependency graph.  CMake by default
constructs the link line so that the linker will scan through the
component at least twice.  This property specifies the minimum number of
scans if it is larger than the default.  CMake uses the largest value
specified by any target in a component.

19.3.181 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
---------------------------------------------

Per-configuration repetition count for cycles of ‘STATIC’ libraries.

This is the configuration-specific version of
LINK_INTERFACE_MULTIPLICITY.  If set, this property completely
overrides the generic property for the named configuration.

19.3.182 LINK_LIBRARIES
-----------------------

List of direct link dependencies.

This property specifies the list of libraries or targets which will be
used for linking.  In addition to accepting values from the
target_link_libraries() command, values may be set directly on any
target using the set_property() command.

The value of this property is used by the generators to set the link
libraries for the compiler.

Contents of ‘LINK_LIBRARIES’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

     Note: A call to target_link_libraries(<target> ...) may
     update this property on ‘<target>’.  If ‘<target>’ was not created
     in the same directory as the call then
     target_link_libraries() will wrap each entry with the form
     ‘::@(directory-id);...;::@’, where the ‘::@’ is literal and the
     ‘(directory-id)’ is unspecified.  This tells the generators that
     the named libraries must be looked up in the scope of the caller
     rather than in the scope in which the ‘<target>’ was created.
     Valid directory ids are stripped on export by the
     install(EXPORT) and export() commands.

19.3.183 LINK_OPTIONS
---------------------

New in version 3.13.

List of options to use for the link step of shared library, module and
executable targets as well as the device link step.  Targets that are
static libraries need to use the STATIC_LIBRARY_OPTIONS.
target property.

These options are used for both normal linking and device linking (see
policy CMP0105).  To control link options for normal and
device link steps, ‘$<HOST_LINK>’ and ‘$<DEVICE_LINK>’ generator expressions
can be used.

This property holds a semicolon-separated list of options
specified so far for its target.  Use the target_link_options()
command to append more options.

This property is initialized by the LINK_OPTIONS directory
property when a target is created, and is used by the generators to set
the options for the compiler.

Contents of ‘LINK_OPTIONS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  See the cmake-buildsystem(7)
manual for more on defining buildsystem properties.

     Note: This property must be used in preference to LINK_FLAGS
     property.

19.3.184 LINK_SEARCH_END_STATIC
-------------------------------

End a link line such that static system libraries are used.

Some linkers support switches such as ‘-Bstatic’ and ‘-Bdynamic’ to
determine whether to use static or shared libraries for ‘-lXXX’ options.
CMake uses these options to set the link type for libraries whose full
paths are not known or (in some cases) are in implicit link directories
for the platform.  By default CMake adds an option at the end of the
library list (if necessary) to set the linker search type back to its
starting type.  This property switches the final linker search type to
‘-Bstatic’ regardless of how it started.

This property is initialized by the value of the variable
CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is
created.

See also LINK_SEARCH_START_STATIC.

19.3.185 LINK_SEARCH_START_STATIC
---------------------------------

Assume the linker looks for static libraries by default.

Some linkers support switches such as ‘-Bstatic’ and ‘-Bdynamic’ to
determine whether to use static or shared libraries for ‘-lXXX’ options.
CMake uses these options to set the link type for libraries whose full
paths are not known or (in some cases) are in implicit link directories
for the platform.  By default the linker search type is assumed to be
‘-Bdynamic’ at the beginning of the library list.  This property
switches the assumption to ‘-Bstatic’.  It is intended for use when
linking an executable statically (e.g.  with the GNU ‘-static’ option).

This property is initialized by the value of the variable

     CMAKE_LINK_SEARCH_START_STATIC if it is set when a
     target is created.

See also LINK_SEARCH_END_STATIC.

19.3.186 LINK_WHAT_YOU_USE
--------------------------

New in version 3.7.

This is a boolean option that when set to ‘TRUE’ will automatically run
‘ldd -r -u’ on the target after it is linked.  In addition, the linker
flag ‘-Wl,--no-as-needed’ will be passed to the target with the link
command so that all libraries specified on the command line will be
linked into the target.  This will result in the link producing a list
of libraries that provide no symbols used by this target but are being
linked to it.  This is only applicable to executable and shared library
targets and will only work when ld and ldd accept the flags used.

This property is initialized by the value of the
CMAKE_LINK_WHAT_YOU_USE variable if it is set when a target is
created.

19.3.187 LINKER_LANGUAGE
------------------------

Specifies language whose compiler will invoke the linker.

For executables, shared libraries, and modules, this sets the language
whose compiler is used to link the target (such as “C” or “CXX”).  A
typical value for an executable is the language of the source file
providing the program entry point (main).  If not set, the language with
the highest linker preference value is the default.  See documentation
of CMAKE_<LANG>_LINKER_PREFERENCE variables.

If this property is not set by the user, it will be calculated at
generate-time by CMake.

19.3.188 LOCATION
-----------------

Read-only location of a target on disk.

For an imported target, this read-only property returns the value of the
‘LOCATION_<CONFIG>’ property for an unspecified configuration ‘<CONFIG>’
provided by the target.

For a non-imported target, this property is provided for compatibility
with CMake 2.4 and below.  It was meant to get the location of an
executable target’s output file for use in add_custom_command().
The path may contain a build-system-specific portion that is
replaced at build time with the configuration getting built (such as
‘$(ConfigurationName)’ in VS). In CMake 2.6 and above
add_custom_command() automatically recognizes a target name in its
‘COMMAND’ and ‘DEPENDS’ options and computes the target location.  In
CMake 2.8.4 and above add_custom_command() recognizes
generator expressions to refer to target locations anywhere in the
command.  Therefore this property is not needed for creating custom
commands.

Do not set properties that affect the location of a target after reading
this property.  These include properties whose names match
‘(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?’,
‘(IMPLIB_)?(PREFIX|SUFFIX)’, or “LINKER_LANGUAGE”.  Failure to follow
this rule is not diagnosed and leaves the location of the target
undefined.

19.3.189 LOCATION_<CONFIG>
--------------------------

Read-only property providing a target location on disk.

A read-only property that indicates where a target’s main file is
located on disk for the configuration ‘<CONFIG>’.  The property is
defined only for library and executable targets.  An imported target may
provide a set of configurations different from that of the importing
project.  By default CMake looks for an exact-match but otherwise uses
an arbitrary available configuration.  Use the
MAP_IMPORTED_CONFIG_<CONFIG> property to map imported
configurations explicitly.

Do not set properties that affect the location of a target after reading
this property.  These include properties whose names match
‘(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?’,
‘(IMPLIB_)?(PREFIX|SUFFIX)’, or LINKER_LANGUAGE.  Failure to
follow this rule is not diagnosed and leaves the location of the target
undefined.

19.3.190 MACHO_COMPATIBILITY_VERSION
------------------------------------

New in version 3.17.

What compatibility version number is this target for Mach-O binaries.

For shared libraries on Mach-O systems (e.g.  macOS, iOS) the
‘MACHO_COMPATIBILITY_VERSION’ property corresponds to the `compatibility
version' and MACHO_CURRENT_VERSION corresponds to the
`current version'.  These are both embedded in the shared library binary
and can be checked with the ‘otool -L <binary>’ command.

It should be noted that the MACHO_CURRENT_VERSION and
‘MACHO_COMPATIBILITY_VERSION’ properties do not affect the file names or
version-related symlinks that CMake generates for the library.  The
VERSION and SOVERSION target properties still
control the file and symlink names.  The ‘install_name’ is also still
controlled by SOVERSION.

When MACHO_CURRENT_VERSION and
‘MACHO_COMPATIBILITY_VERSION’ are not given, see VERSION and
SOVERSION are used for the version details to be embedded in
the binaries respectively.  The MACHO_CURRENT_VERSION and
‘MACHO_COMPATIBILITY_VERSION’ properties only need to be given if the
project needs to decouple the file and symlink naming from the version
details embedded in the binaries (e.g.  to match libtool conventions).

19.3.191 MACHO_CURRENT_VERSION
------------------------------

New in version 3.17.

What current version number is this target for Mach-O binaries.

For shared libraries on Mach-O systems (e.g.  macOS, iOS) the
MACHO_COMPATIBILITY_VERSION property corresponds to the
`compatibility version' and ‘MACHO_CURRENT_VERSION’ corresponds to the
`current version'.  These are both embedded in the shared library binary
and can be checked with the ‘otool -L <binary>’ command.

It should be noted that the ‘MACHO_CURRENT_VERSION’ and
MACHO_COMPATIBILITY_VERSION properties do not affect the file
names or version-related symlinks that CMake generates for the library.
The VERSION and SOVERSION target properties
still control the file and symlink names.  The ‘install_name’ is also
still controlled by SOVERSION.

When ‘MACHO_CURRENT_VERSION’ and MACHO_COMPATIBILITY_VERSION
are not given, see VERSION and SOVERSION are
used for the version details to be embedded in the binaries
respectively.  The ‘MACHO_CURRENT_VERSION’ and
MACHO_COMPATIBILITY_VERSION properties only need to be given if
the project needs to decouple the file and symlink naming from the
version details embedded in the binaries (e.g.  to match libtool
conventions).

19.3.192 MACOSX_BUNDLE
----------------------

Build an executable as an Application Bundle on macOS or iOS.

When this property is set to ‘TRUE’ the executable when built on macOS
or iOS will be created as an application bundle.  This makes it a GUI
executable that can be launched from the Finder.  See the
MACOSX_BUNDLE_INFO_PLIST target property for information about
creation of the ‘Info.plist’ file for the application bundle.  This
property is initialized by the value of the variable
CMAKE_MACOSX_BUNDLE if it is set when a target is created.

19.3.193 MACOSX_BUNDLE_INFO_PLIST
---------------------------------

Specify a custom ‘Info.plist’ template for a macOS and iOS Application
Bundle.

An executable target with MACOSX_BUNDLE enabled will be
built as an application bundle on macOS. By default its ‘Info.plist’
file is created by configuring a template called
‘MacOSXBundleInfo.plist.in’ located in the CMAKE_MODULE_PATH.
This property specifies an alternative template file name which may be a
full path.

The following target properties may be set to specify content to be
configured into the file:

‘MACOSX_BUNDLE_BUNDLE_NAME’

     Sets ‘CFBundleName’.

‘MACOSX_BUNDLE_BUNDLE_VERSION’

     Sets ‘CFBundleVersion’.

‘MACOSX_BUNDLE_COPYRIGHT’

     Sets ‘NSHumanReadableCopyright’.

‘MACOSX_BUNDLE_GUI_IDENTIFIER’

     Sets ‘CFBundleIdentifier’.

‘MACOSX_BUNDLE_ICON_FILE’

     Sets ‘CFBundleIconFile’.

‘MACOSX_BUNDLE_INFO_STRING’

     Sets ‘CFBundleGetInfoString’.

‘MACOSX_BUNDLE_LONG_VERSION_STRING’

     Sets ‘CFBundleLongVersionString’.

‘MACOSX_BUNDLE_SHORT_VERSION_STRING’

     Sets ‘CFBundleShortVersionString’.

CMake variables of the same name may be set to affect all targets in a
directory that do not have each specific property set.  If a custom
‘Info.plist’ is specified by this property it may of course hard-code
all the settings instead of using the target properties.

19.3.194 MACOSX_FRAMEWORK_INFO_PLIST
------------------------------------

Specify a custom ‘Info.plist’ template for a macOS and iOS Framework.

A library target with FRAMEWORK enabled will be built as a
framework on macOS. By default its ‘Info.plist’ file is created by
configuring a template called ‘MacOSXFrameworkInfo.plist.in’ located in
the CMAKE_MODULE_PATH.  This property specifies an
alternative template file name which may be a full path.

The following target properties may be set to specify content to be
configured into the file:

‘MACOSX_FRAMEWORK_BUNDLE_VERSION’

     Sets ‘CFBundleVersion’.

‘MACOSX_FRAMEWORK_ICON_FILE’

     Sets ‘CFBundleIconFile’.

‘MACOSX_FRAMEWORK_IDENTIFIER’

     Sets ‘CFBundleIdentifier’.

‘MACOSX_FRAMEWORK_SHORT_VERSION_STRING’

     Sets ‘CFBundleShortVersionString’.

CMake variables of the same name may be set to affect all targets in a
directory that do not have each specific property set.  If a custom
‘Info.plist’ is specified by this property it may of course hard-code
all the settings instead of using the target properties.

19.3.195 MACOSX_RPATH
---------------------

Whether this target on macOS or iOS is located at runtime using rpaths.

When this property is set to ‘TRUE’, the directory portion of the
‘install_name’ field of this shared library will be ‘@rpath’ unless
overridden by INSTALL_NAME_DIR.  This indicates the shared
library is to be found at runtime using runtime paths (rpaths).

This property is initialized by the value of the variable
CMAKE_MACOSX_RPATH if it is set when a target is created.

Runtime paths will also be embedded in binaries using this target and
can be controlled by the INSTALL_RPATH target property on
the target linking to this target.

Policy CMP0042 was introduced to change the default value of
‘MACOSX_RPATH’ to ‘TRUE’.  This is because use of ‘@rpath’ is a more
flexible and powerful alternative to ‘@executable_path’ and
‘@loader_path’.

19.3.196 MANUALLY_ADDED_DEPENDENCIES
------------------------------------

New in version 3.8.

Get manually added dependencies to other top-level targets.

This read-only property can be used to query all dependencies that were
added for this target with the add_dependencies() command.

19.3.197 MAP_IMPORTED_CONFIG_<CONFIG>
-------------------------------------

Map from project configuration to imported target.’s
configuration.

Set this to the list of configurations of an imported target that may be
used for the current project’s ‘<CONFIG>’ configuration.  Targets
imported from another project may not provide the same set of
configuration names available in the current project.  Setting this
property tells CMake what imported configurations are suitable for use
when building the ‘<CONFIG>’ configuration.  The first configuration in
the list found to be provided by the imported target (i.e.  via
IMPORTED_LOCATION_<CONFIG> for the mapped-to ‘<CONFIG>’) is
selected.  As a special case, an empty list element refers to the
configuration-less imported target location (i.e.  see
IMPORTED_LOCATION).

If this property is set and no matching configurations are available,
then the imported target is considered to be not found.  This property
is ignored for non-imported targets.

This property is initialized by the value of the
CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable if it is set when a
target is created.

19.3.197.1 Example
..................

For example creating imported C++ library ‘foo’:

     add_library(foo STATIC IMPORTED)

Use ‘foo_debug’ path for ‘Debug’ build type:

     set_property(
       TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG
       )

     set_target_properties(foo PROPERTIES
       IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
       IMPORTED_LOCATION_DEBUG "${foo_debug}"
       )

Use ‘foo_release’ path for ‘Release’ build type:

     set_property(
       TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE
       )

     set_target_properties(foo PROPERTIES
       IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
       IMPORTED_LOCATION_RELEASE "${foo_release}"
       )

Use ‘Release’ version of library for ‘MinSizeRel’ and ‘RelWithDebInfo’
build types:

     set_target_properties(foo PROPERTIES
       MAP_IMPORTED_CONFIG_MINSIZEREL Release
       MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
       )

19.3.198 MSVC_RUNTIME_LIBRARY
-----------------------------

New in version 3.15.

Select the MSVC runtime library for use by compilers targeting the MSVC
ABI.

The allowed values are:

‘MultiThreaded’

     Compile with ‘-MT’ or equivalent flag(s) to use a multi-threaded
     statically-linked runtime library.

‘MultiThreadedDLL’

     Compile with ‘-MD’ or equivalent flag(s) to use a multi-threaded
     dynamically-linked runtime library.

‘MultiThreadedDebug’

     Compile with ‘-MTd’ or equivalent flag(s) to use a multi-threaded
     statically-linked runtime library.

‘MultiThreadedDebugDLL’

     Compile with ‘-MDd’ or equivalent flag(s) to use a multi-threaded
     dynamically-linked runtime library.

The value is ignored on non-MSVC compilers but an unsupported value will
be rejected as an error when using a compiler targeting the MSVC ABI.

The value may also be the empty string (‘""’) in which case no runtime
library selection flag will be added explicitly by CMake.  Note that
with Visual Studio Generators the native build system may
choose to add its own default runtime library selection flag.

Use generator expressions to support per-configuration
specification.  For example, the code:

     add_executable(foo foo.c)
     set_property(TARGET foo PROPERTY
       MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")

selects for the target ‘foo’ a multi-threaded statically-linked runtime
library with or without debug information depending on the
configuration.

If this property is not set then CMake uses the default value
‘MultiThreaded$<$<CONFIG:Debug>:Debug>DLL’ to select a MSVC runtime
library.

     Note: This property has effect only when policy CMP0091.
     is set to ‘NEW’ prior to the first project() or
     enable_language() command that enables a language using a
     compiler targeting the MSVC ABI.

19.3.199 NAME
-------------

Logical name for the target.

Read-only logical name for the target as used by CMake.

19.3.200 NO_SONAME
------------------

Whether to set ‘soname’ when linking a shared library.

Enable this boolean property if a generated ‘SHARED’ library should not
have ‘soname’ set.  Default is to set ‘soname’ on all shared libraries
as long as the platform supports it.  Generally, use this property only
for leaf private libraries or plugins.  If you use it on normal shared
libraries which other targets link against, on some platforms a linker
will insert a full path to the library (as specified at link time) into
the dynamic section of the dependent binary.  Therefore, once installed,
dynamic loader may eventually fail to locate the library for the binary.

19.3.201 NO_SYSTEM_FROM_IMPORTED
--------------------------------

Do not treat include directories from the interfaces of consumed
Imported Targets as ‘SYSTEM’.

The contents of the INTERFACE_INCLUDE_DIRECTORIES target
property of imported targets are treated as ‘SYSTEM’ includes by
default.  If this property is enabled on a target, compilation of
sources in that target will not treat the contents of the
‘INTERFACE_INCLUDE_DIRECTORIES’ of consumed imported targets as system
includes.

This property is initialized by the value of the
CMAKE_NO_SYSTEM_FROM_IMPORTED variable if it is set when a target
is created.

19.3.202 OBJC_EXTENSIONS
------------------------

New in version 3.16.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be
used.  For some compilers, this results in adding a flag such as
‘-std=gnu11’ instead of ‘-std=c11’ to the compile line.  This property
is ‘ON’ by default.  The basic OBJC standard level is controlled by the
OBJC_STANDARD target property.

If the property is not set, and the project has set the
C_EXTENSIONS, the value of C_EXTENSIONS is set for
OBJC_EXTENSIONS.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_OBJC_EXTENSIONS variable if it is set when a target is
created.

19.3.203 OBJC_STANDARD
----------------------

New in version 3.16.

The OBJC standard whose features are requested to build this target.

This property specifies the OBJC standard whose features are requested
to build this target.  For some compilers, this results in adding a flag
such as ‘-std=gnu11’ to the compile line.

Supported values are ‘90’, ‘99’ and ‘11’.

If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead.
This means that using:

     set_property(TARGET tgt PROPERTY OBJC_STANDARD 11)

with a compiler which does not support ‘-std=gnu11’ or an equivalent
flag will not result in an error or warning, but will instead add the
‘-std=gnu99’ or ‘-std=gnu90’ flag if supported.  This “decay” behavior
may be controlled with the OBJC_STANDARD_REQUIRED target
property.  Additionally, the OBJC_EXTENSIONS target property
may be used to control whether compiler-specific extensions are enabled
on a per-target basis.

If the property is not set, and the project has set the
C_STANDARD, the value of C_STANDARD is set for
OBJC_STANDARD.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_OBJC_STANDARD variable if it is set when a target is
created.

19.3.204 OBJC_STANDARD_REQUIRED
-------------------------------

New in version 3.16.

Boolean describing whether the value of OBJC_STANDARD is a
requirement.

If this property is set to ‘ON’, then the value of the
OBJC_STANDARD target property is treated as a requirement.  If
this property is ‘OFF’ or unset, the OBJC_STANDARD target
property is treated as optional and may “decay” to a previous standard
if the requested is not available.

If the property is not set, and the project has set the
C_STANDARD_REQUIRED, the value of C_STANDARD_REQUIRED.
is set for OBJC_STANDARD_REQUIRED.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_OBJC_STANDARD_REQUIRED variable if it is set when a target
is created.

19.3.205 OBJCXX_EXTENSIONS
--------------------------

New in version 3.16.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be
used.  For some compilers, this results in adding a flag such as
‘-std=gnu++11’ instead of ‘-std=c++11’ to the compile line.  This
property is ‘ON’ by default.  The basic ObjC++ standard level is
controlled by the OBJCXX_STANDARD target property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

If the property is not set, and the project has set the
CXX_EXTENSIONS, the value of CXX_EXTENSIONS is set for
OBJCXX_EXTENSIONS.

This property is initialized by the value of the
CMAKE_OBJCXX_EXTENSIONS variable if it is set when a target is
created.

19.3.206 OBJCXX_STANDARD
------------------------

New in version 3.16.

The ObjC++ standard whose features are requested to build this target.

This property specifies the ObjC++ standard whose features are requested
to build this target.  For some compilers, this results in adding a flag
such as ‘-std=gnu++11’ to the compile line.

Supported values are ‘98’, ‘11’, ‘14’, ‘17’, and ‘20’.

If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead.
This means that using:

     set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11)

with a compiler which does not support ‘-std=gnu++11’ or an equivalent
flag will not result in an error or warning, but will instead add the
‘-std=gnu++98’ flag if supported.  This “decay” behavior may be
controlled with the OBJCXX_STANDARD_REQUIRED target
property.  Additionally, the OBJCXX_EXTENSIONS target
property may be used to control whether compiler-specific extensions are
enabled on a per-target basis.

If the property is not set, and the project has set the
CXX_STANDARD, the value of CXX_STANDARD is set for
OBJCXX_STANDARD.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_OBJCXX_STANDARD variable if it is set when a target is
created.

19.3.207 OBJCXX_STANDARD_REQUIRED
---------------------------------

New in version 3.16.

Boolean describing whether the value of OBJCXX_STANDARD is a
requirement.

If this property is set to ‘ON’, then the value of the
OBJCXX_STANDARD target property is treated as a requirement.  If
this property is ‘OFF’ or unset, the OBJCXX_STANDARD target
property is treated as optional and may “decay” to a previous standard
if the requested is not available.

If the property is not set, and the project has set the
CXX_STANDARD_REQUIRED, the value of CXX_STANDARD_REQUIRED
is set for OBJCXX_STANDARD_REQUIRED.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

This property is initialized by the value of the
CMAKE_OBJCXX_STANDARD_REQUIRED variable if it is set when a target
is created.

19.3.208 OPTIMIZE_DEPENDENCIES
------------------------------

New in version 3.19.

Activates dependency optimization of static and object libraries.

When this property is set to true, some dependencies for a static or
object library may be removed at generation time if they are not
necessary to build the library, since static and object libraries don’t
actually link against anything.

If a static or object library has dependency optimization enabled, it
first discards all dependencies.  Then, it looks through all of the
direct and indirect dependencies that it initially had, and adds them
back if they meet any of the following criteria:

   * The dependency was added to the library by
     add_dependencies().

   * The dependency was added to the library through a source file in
     the library generated by a custom command that uses the dependency.

   * The dependency has any ‘PRE_BUILD’, ‘PRE_LINK’, or ‘POST_BUILD’
     custom commands associated with it.

   * The dependency contains any source files that were generated by a
     custom command.

   * The dependency contains any languages which produce side effects
     that are relevant to the library.  Currently, all languages except
     C, C++, Objective-C, Objective-C++, assembly, and CUDA are assumed
     to produce side effects.  However, side effects from one language
     are assumed not to be relevant to another (for example, a Fortran
     library is assumed to not have any side effects that are relevant
     for a Swift library.)

As an example, assume you have a static Fortran library which depends on
a static C library, which in turn depends on a static Fortran library.
The top-level Fortran library has optimization enabled, but the middle C
library does not.  If you build the top Fortran library, the bottom
Fortran library will also build, but not the middle C library, since the
C library does not have any side effects that are relevant for the
Fortran library.  However, if you build the middle C library, the bottom
Fortran library will also build, even though it does not have any side
effects that are relevant to the C library, since the C library does not
have optimization enabled.

This property is initialized by the value of the
CMAKE_OPTIMIZE_DEPENDENCIES variable when the target is created.

19.3.209 OSX_ARCHITECTURES
--------------------------

Target specific architectures for macOS.

The ‘OSX_ARCHITECTURES’ property sets the target binary architecture for
targets on macOS (‘-arch’).  This property is initialized by the value
of the variable CMAKE_OSX_ARCHITECTURES if it is set when a
target is created.  Use OSX_ARCHITECTURES_<CONFIG> to set
the binary architectures on a per-configuration basis, where ‘<CONFIG>’
is an upper-case name (e.g.  ‘OSX_ARCHITECTURES_DEBUG’).

19.3.210 OSX_ARCHITECTURES_<CONFIG>
-----------------------------------

Per-configuration macOS and iOS binary architectures for a target.

This property is the configuration-specific version of
OSX_ARCHITECTURES.

19.3.211 OUTPUT_NAME
--------------------

Output name for target files.

This sets the base name for output files created for an executable or
library target.  If not set, the logical target name is used by default
during generation.  The value is not set by default during
configuration.

Contents of ‘OUTPUT_NAME’ and the variants listed below may use
generator expressions.

See also the variants:

   * OUTPUT_NAME_<CONFIG>.

   * ARCHIVE_OUTPUT_NAME_<CONFIG>.

   * ARCHIVE_OUTPUT_NAME.

   * LIBRARY_OUTPUT_NAME_<CONFIG>.

   * LIBRARY_OUTPUT_NAME.

   * RUNTIME_OUTPUT_NAME_<CONFIG>.

   * RUNTIME_OUTPUT_NAME.

19.3.212 OUTPUT_NAME_<CONFIG>
-----------------------------

Per-configuration target file base name.

This is the configuration-specific version of the OUTPUT_NAME
target property.

19.3.213 PCH_WARN_INVALID
-------------------------

New in version 3.18.

When this property is set to true, the precompile header compiler
options will contain a compiler flag which should warn about invalid
precompiled headers e.g.  ‘-Winvalid-pch’ for GNU compiler.

This property is initialized by the value of the
CMAKE_PCH_WARN_INVALID variable if it is set when a target is
created.  If that variable is not set, the property defaults to ‘ON’.

19.3.214 PCH_INSTANTIATE_TEMPLATES
----------------------------------

New in version 3.19.

When this property is set to true, the precompiled header compiler
options will contain a flag to instantiate templates during the
generation of the PCH if supported.  This can significantly improve
compile times.  Supported in Clang since version 11.

This property is initialized by the value of the
CMAKE_PCH_INSTANTIATE_TEMPLATES variable if it is set when a
target is created.  If that variable is not set, the property defaults
to ‘ON’.

19.3.215 PDB_NAME
-----------------

Output name for the MS debug symbol ‘.pdb’ file generated by the linker
for an executable or shared library target.

This property specifies the base name for the debug symbols file.  If
not set, the OUTPUT_NAME target property value or logical
target name is used by default.

     Note: This property does not apply to STATIC library targets
     because no linker is invoked to produce them so they have no
     linker-generated ‘.pdb’ file containing debug symbols.

     The linker-generated program database files are specified by the
     ‘/pdb’ linker flag and are not the same as compiler-generated
     program database files specified by the ‘/Fd’ compiler flag.  Use
     the COMPILE_PDB_NAME property to specify the latter.

19.3.216 PDB_NAME_<CONFIG>
--------------------------

Per-configuration output name for the MS debug symbol ‘.pdb’ file
generated by the linker for an executable or shared library target.

This is the configuration-specific version of PDB_NAME.

     Note: This property does not apply to STATIC library targets
     because no linker is invoked to produce them so they have no
     linker-generated ‘.pdb’ file containing debug symbols.

     The linker-generated program database files are specified by the
     ‘/pdb’ linker flag and are not the same as compiler-generated
     program database files specified by the ‘/Fd’ compiler flag.  Use
     the COMPILE_PDB_NAME_<CONFIG> property to specify the
     latter.

19.3.217 PDB_OUTPUT_DIRECTORY
-----------------------------

Output directory for the MS debug symbols ‘.pdb’ file generated by the
linker for an executable or shared library target.

This property specifies the directory into which the MS debug symbols
will be placed by the linker.  The property value may use
generator expressions.  Multi-configuration generators append a
per-configuration subdirectory to the specified directory unless a
generator expression is used.

This property is initialized by the value of the
CMAKE_PDB_OUTPUT_DIRECTORY variable if it is set when a target is
created.

     Note: This property does not apply to STATIC library targets
     because no linker is invoked to produce them so they have no
     linker-generated ‘.pdb’ file containing debug symbols.

     The linker-generated program database files are specified by the
     ‘/pdb’ linker flag and are not the same as compiler-generated
     program database files specified by the ‘/Fd’ compiler flag.  Use
     the COMPILE_PDB_OUTPUT_DIRECTORY property to specify
     the latter.

19.3.218 PDB_OUTPUT_DIRECTORY_<CONFIG>
--------------------------------------

Per-configuration output directory for the MS debug symbol ‘.pdb’ file
generated by the linker for an executable or shared library target.

This is a per-configuration version of PDB_OUTPUT_DIRECTORY,
but multi-configuration generators (see Visual Studio Generators,
Xcode) do NOT append a per-configuration subdirectory to the
specified directory.  This property is initialized by the value of the
CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set
when a target is created.

Contents of ‘PDB_OUTPUT_DIRECTORY_<CONFIG>’ may use generator expressions.

     Note: This property does not apply to STATIC library targets
     because no linker is invoked to produce them so they have no
     linker-generated ‘.pdb’ file containing debug symbols.

     The linker-generated program database files are specified by the
     ‘/pdb’ linker flag and are not the same as compiler-generated
     program database files specified by the ‘/Fd’ compiler flag.  Use
     the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property to
     specify the latter.

19.3.219 POSITION_INDEPENDENT_CODE
----------------------------------

Whether to create a position-independent target

The ‘POSITION_INDEPENDENT_CODE’ property determines whether position
independent executables or shared libraries will be created.  This
property is ‘True’ by default for ‘SHARED’ and ‘MODULE’ library targets
and ‘False’ otherwise.  This property is initialized by the value of the
CMAKE_POSITION_INDEPENDENT_CODE variable if it is set when a
target is created.

     Note: For executable targets, the link step is controlled by the
     CMP0083 policy and the CheckPIESupported.
     module.

19.3.220 PRECOMPILE_HEADERS
---------------------------

New in version 3.16.

List of header files to precompile.

This property holds a semicolon-separated list of header
files to precompile specified so far for its target.  Use the
target_precompile_headers() command to append more header files.

This property supports generator expressions.

19.3.221 PRECOMPILE_HEADERS_REUSE_FROM
--------------------------------------

New in version 3.16.

Target from which to reuse the precompiled headers build artifact.

See the second signature of target_precompile_headers().
command for more detailed information.

19.3.222 PREFIX
---------------

What comes before the library name.

A target property that can be set to override the prefix (such as ‘lib’)
on a library name.

19.3.223 PRIVATE_HEADER
-----------------------

Specify private header files in a FRAMEWORK shared library
target.

Shared library targets marked with the FRAMEWORK property
generate frameworks on macOS, iOS and normal shared libraries on other
platforms.  This property may be set to a list of header files to be
placed in the PrivateHeaders directory inside the framework folder.  On
non-Apple platforms these headers may be installed using the
‘PRIVATE_HEADER’ option to the install(TARGETS) command.

19.3.224 PROJECT_LABEL
----------------------

Change the name of a target in an IDE.

Can be used to change the name of the target in an IDE like Visual
Studio.

19.3.225 PUBLIC_HEADER
----------------------

Specify public header files in a FRAMEWORK shared library
target.

Shared library targets marked with the FRAMEWORK property
generate frameworks on macOS, iOS and normal shared libraries on other
platforms.  This property may be set to a list of header files to be
placed in the ‘Headers’ directory inside the framework folder.  On
non-Apple platforms these headers may be installed using the
‘PUBLIC_HEADER’ option to the install(TARGETS) command.

19.3.226 RESOURCE
-----------------

Specify resource files in a FRAMEWORK or BUNDLE.

Target marked with the FRAMEWORK or BUNDLE.
property generate framework or application bundle (both macOS and iOS is
supported) or normal shared libraries on other platforms.  This property
may be set to a list of files to be placed in the corresponding
directory (eg.  ‘Resources’ directory for macOS) inside the bundle.  On
non-Apple platforms these files may be installed using the ‘RESOURCE’
option to the install(TARGETS) command.

Following example of Application Bundle:

     add_executable(ExecutableTarget
       addDemo.c
       resourcefile.txt
       appresourcedir/appres.txt)

     target_link_libraries(ExecutableTarget heymath mul)

     set(RESOURCE_FILES
       resourcefile.txt
       appresourcedir/appres.txt)

     set_target_properties(ExecutableTarget PROPERTIES
       MACOSX_BUNDLE TRUE
       MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget
       RESOURCE "${RESOURCE_FILES}")

will produce flat structure for iOS systems:

     ExecutableTarget.app
       appres.txt
       ExecutableTarget
       Info.plist
       resourcefile.txt

For macOS systems it will produce following directory structure:

     ExecutableTarget.app/
       Contents
         Info.plist
         MacOS
           ExecutableTarget
         Resources
           appres.txt
           resourcefile.txt

For Linux, such CMake script produce following files:

     ExecutableTarget
     Resources
       appres.txt
       resourcefile.txt

19.3.227 RULE_LAUNCH_COMPILE
----------------------------

Specify a launcher for compile rules.

See the global property of the same name for details.  This overrides
the global and directory property for a target.

19.3.228 RULE_LAUNCH_CUSTOM
---------------------------

Specify a launcher for custom rules.

See the global property of the same name for details.  This overrides
the global and directory property for a target.

19.3.229 RULE_LAUNCH_LINK
-------------------------

Specify a launcher for link rules.

See the global property of the same name for details.  This overrides
the global and directory property for a target.

19.3.230 RUNTIME_OUTPUT_DIRECTORY
---------------------------------

Output directory in which to build RUNTIME target files.

This property specifies the directory into which runtime target files
should be built.  The property value may use generator expressions.
Multi-configuration generators (VS, Xcode) append a
per-configuration subdirectory to the specified directory unless a
generator expression is used.

This property is initialized by the value of the variable
CMAKE_RUNTIME_OUTPUT_DIRECTORY if it is set when a target is created.

See also the RUNTIME_OUTPUT_DIRECTORY_<CONFIG> target
property.

19.3.231 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
------------------------------------------

Per-configuration output directory for RUNTIME target files.

This is a per-configuration version of the
RUNTIME_OUTPUT_DIRECTORY target property, but multi-configuration
generators (see Visual Studio Generators, Xcode) do
NOT append a per-configuration subdirectory to the specified directory.
This property is initialized by the value of the
CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> variable if it is set
when a target is created.

Contents of ‘RUNTIME_OUTPUT_DIRECTORY_<CONFIG>’ may use generator expressions.

19.3.232 RUNTIME_OUTPUT_NAME
----------------------------

Output name for RUNTIME target files.

This property specifies the base name for runtime target files.  It
overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG>.
properties.

See also the RUNTIME_OUTPUT_NAME_<CONFIG> target property.

19.3.233 RUNTIME_OUTPUT_NAME_<CONFIG>
-------------------------------------

Per-configuration output name for RUNTIME target files.

This is the configuration-specific version of the
RUNTIME_OUTPUT_NAME target property.

19.3.234 SKIP_BUILD_RPATH
-------------------------

Should rpaths be used for the build tree.

‘SKIP_BUILD_RPATH’ is a boolean specifying whether to skip automatic
generation of an rpath allowing the target to run from the build tree.
This property is initialized by the value of the variable
CMAKE_SKIP_BUILD_RPATH if it is set when a target is created.

19.3.235 SOURCE_DIR
-------------------

New in version 3.4.

This read-only property reports the value of the
CMAKE_CURRENT_SOURCE_DIR variable in the directory in which the
target was defined.

19.3.236 SOURCES
----------------

Source names specified for a target.

List of sources specified for a target.

19.3.237 SOVERSION
------------------

What version number is this target.

For shared libraries VERSION and ‘SOVERSION’ can be used to
specify the build version and API version respectively.  When building
or installing appropriate symlinks are created if the platform supports
symlinks and the linker supports so-names.  If only one of both is
specified the missing is assumed to have the same version number.
‘SOVERSION’ is ignored if NO_SONAME property is set.

19.3.237.1 Windows Versions
...........................

For shared libraries and executables on Windows the VERSION.
attribute is parsed to extract a ‘<major>.<minor>’ version number.
These numbers are used as the image version of the binary.

19.3.237.2 Mach-O Versions
..........................

For shared libraries and executables on Mach-O systems (e.g.  macOS,
iOS), the ‘SOVERSION’ property corresponds to the `compatibility
version' and VERSION corresponds to the `current version'
(unless Mach-O specific overrides are provided, as discussed below).
See the FRAMEWORK target property for an example.

For shared libraries, the MACHO_COMPATIBILITY_VERSION and
MACHO_CURRENT_VERSION properties can be used to override
the `compatibility version' and `current version' respectively.  Note
that ‘SOVERSION’ will still be used to form the ‘install_name’ and both
‘SOVERSION’ and VERSION may also affect the file and symlink
names.

Versions of Mach-O binaries may be checked with the ‘otool -L <binary>’
command.

19.3.238 STATIC_LIBRARY_FLAGS
-----------------------------

Archiver (or MSVC librarian) flags for a static library target.  Targets
that are shared libraries, modules, or executables need to use the
LINK_OPTIONS or LINK_FLAGS target properties.

The ‘STATIC_LIBRARY_FLAGS’ property, managed as a string, can be used to
add extra flags to the link step of a static library target.
STATIC_LIBRARY_FLAGS_<CONFIG> will add to the configuration
‘<CONFIG>’, for example, ‘DEBUG’, ‘RELEASE’, ‘MINSIZEREL’,
‘RELWITHDEBINFO’, …

     Note: This property has been superseded by
     STATIC_LIBRARY_OPTIONS property.

19.3.239 STATIC_LIBRARY_FLAGS_<CONFIG>
--------------------------------------

Per-configuration archiver (or MSVC librarian) flags for a static
library target.

This is the configuration-specific version of
STATIC_LIBRARY_FLAGS.

     Note: This property has been superseded by
     STATIC_LIBRARY_OPTIONS property.

19.3.240 STATIC_LIBRARY_OPTIONS
-------------------------------

New in version 3.13.

Archiver (or MSVC librarian) flags for a static library target.  Targets
that are shared libraries, modules, or executables need to use the
LINK_OPTIONS target property.

This property holds a semicolon-separated list of options
specified so far for its target.  Use set_target_properties()
or set_property() commands to set its content.

Contents of ‘STATIC_LIBRARY_OPTIONS’ may use “generator expressions”
with the syntax ‘$<...>’.  See the cmake-generator-expressions(7)
manual for available expressions.  See the
cmake-buildsystem(7) manual for more on defining buildsystem
properties.

     Note: This property must be used in preference to
     STATIC_LIBRARY_FLAGS property.

19.3.241 SUFFIX
---------------

What comes after the target name.

A target property that can be set to override the suffix (such as ‘.so’
or ‘.exe’) on the name of a library, module or executable.

19.3.242 Swift_DEPENDENCIES_FILE
--------------------------------

New in version 3.15.

This property sets the path for the Swift dependency file (swiftdep) for
the target.  If one is not specified, it will default to
‘<TARGET>.swiftdeps’.

19.3.243 Swift_LANGUAGE_VERSION
-------------------------------

New in version 3.16.

This property sets the language version for the Swift sources in the
target.  If one is not specified, it will default to
‘<CMAKE_Swift_LANGUAGE_VERSION>’ if specified, otherwise it is the
latest version supported by the compiler.

19.3.244 Swift_MODULE_DIRECTORY
-------------------------------

New in version 3.15.

Specify output directory for Swift modules provided by the target.

If the target contains Swift source files, this specifies the directory
in which the modules will be placed.  When this property is not set, the
modules will be placed in the build directory corresponding to the
target’s source directory.  If the variable
CMAKE_Swift_MODULE_DIRECTORY is set when a target is created its
value is used to initialise this property.

19.3.245 Swift_MODULE_NAME
--------------------------

New in version 3.15.

This property specifies the name of the Swift module.  It is defaulted
to the name of the target.

19.3.246 TYPE
-------------

The type of the target.

This read-only property can be used to test the type of the given
target.  It will be one of ‘STATIC_LIBRARY’, ‘MODULE_LIBRARY’,
‘SHARED_LIBRARY’, ‘OBJECT_LIBRARY’, ‘INTERFACE_LIBRARY’, ‘EXECUTABLE’ or
one of the internal target types.

19.3.247 UNITY_BUILD
--------------------

New in version 3.16.

When this property is set to true, the target source files will be
combined into batches for faster compilation.  This is done by creating
a (set of) unity sources which ‘#include’ the original sources, then
compiling these unity sources instead of the originals.  This is known
as a `Unity' or `Jumbo' build.

CMake provides different algorithms for selecting which sources are
grouped together into a `bucket'.  Algorithm selection is decided by the
UNITY_BUILD_MODE target property, which has the following
acceptable values:

   * ‘BATCH’ When in this mode CMake determines which files are grouped
     together.  The UNITY_BUILD_BATCH_SIZE property
     controls the upper limit on how many sources can be combined per
     unity source file.

   * ‘GROUP’ When in this mode each target explicitly specifies how to
     group source files.  Each source file that has the same
     UNITY_GROUP value will be grouped together.  Any sources
     that don’t have this property will be compiled individually.  The
     UNITY_BUILD_BATCH_SIZE property is ignored when using
     this mode.

If no explicit UNITY_BUILD_MODE has been specified, CMake
will default to ‘BATCH’.

Unity builds are not currently supported for all languages.  CMake
version 3.19.2 supports combining ‘C’ and ‘CXX’ source files.  For
targets that mix source files from more than one language, CMake will
separate the languages such that each generated unity source file only
contains sources for a single language.

This property is initialized by the value of the
CMAKE_UNITY_BUILD variable when a target is created.

     Note: Projects should not directly set the ‘UNITY_BUILD’ property
     or its associated CMAKE_UNITY_BUILD variable to true.
     Depending on the capabilities of the build machine and compiler
     used, it might or might not be appropriate to enable unity builds.
     Therefore, this feature should be under developer control, which
     would normally be through the developer choosing whether or not to
     set the CMAKE_UNITY_BUILD variable on the
     cmake(1) command line or some other equivalent method.
     However, it IS recommended to set the ‘UNITY_BUILD’ target property
     to false if it is known that enabling unity builds for the target
     can lead to problems.

19.3.247.1 ODR (One definition rule) errors
...........................................

When multiple source files are included into one source file, as is done
for unity builds, it can potentially lead to ODR errors.  CMake provides
a number of measures to help address such problems:

   * Any source file that has a non-empty COMPILE_OPTIONS,
     COMPILE_DEFINITIONS, COMPILE_FLAGS, or
     INCLUDE_DIRECTORIES source property will not be combined into
     a unity source.

   * Projects can prevent an individual source file from being combined
     into a unity source by setting its
     SKIP_UNITY_BUILD_INCLUSION source property to true.  This
     can be a more effective way to prevent problems with specific files
     than disabling unity builds for an entire target.

   * The UNITY_BUILD_CODE_BEFORE_INCLUDE and
     UNITY_BUILD_CODE_AFTER_INCLUDE target properties can be used
     to inject code into the unity source files before and after every
     ‘#include’ statement.

   * The order of source files added to the target via commands like
     add_library(), add_executable() or
     target_sources() will be preserved in the generated unity
     source files.  This can be used to manually enforce a specific
     grouping based on the UNITY_BUILD_BATCH_SIZE target
     property.

19.3.248 UNITY_BUILD_BATCH_SIZE
-------------------------------

New in version 3.16.

Specifies the maximum number of source files that can be combined into
any one unity source file when unity builds are enabled by the
UNITY_BUILD target property.  The original source files will be
distributed across as many unity source files as necessary to honor this
limit.

The initial value for this property is taken from the
CMAKE_UNITY_BUILD_BATCH_SIZE variable when the target is created.
If that variable has not been set, the initial value will be 8.

The batch size needs to be selected carefully.  If set too high, the
size of the combined source files could result in the compiler using
excessive memory or hitting other similar limits.  In extreme cases,
this can even result in build failure.  On the other hand, if the batch
size is too low, there will be little gain in build performance.

Although strongly discouraged, the batch size may be set to a value of 0
to combine all the sources for the target into a single unity file,
regardless of how many sources are involved.  This runs the risk of
creating an excessively large unity source file and negatively impacting
the build performance, so a value of 0 is not generally recommended.

19.3.249 UNITY_BUILD_CODE_AFTER_INCLUDE
---------------------------------------

New in version 3.16.

Code snippet which is included verbatim by the UNITY_BUILD.
feature just after every ‘#include’ statement in the generated unity
source files.  For example:

     set(after [[
     #if defined(NOMINMAX)
     #undef NOMINMAX
     #endif
     ]])
     set_target_properties(myTarget PROPERTIES
       UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
     )

See also UNITY_BUILD_CODE_BEFORE_INCLUDE.

19.3.250 UNITY_BUILD_CODE_BEFORE_INCLUDE
----------------------------------------

New in version 3.16.

Code snippet which is included verbatim by the UNITY_BUILD.
feature just before every ‘#include’ statement in the generated unity
source files.  For example:

     set(before [[
     #if !defined(NOMINMAX)
     #define NOMINMAX
     #endif
     ]])
     set_target_properties(myTarget PROPERTIES
       UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
     )

See also UNITY_BUILD_CODE_AFTER_INCLUDE.

19.3.251 UNITY_BUILD_MODE
-------------------------

New in version 3.18.

CMake provides different algorithms for selecting which sources are
grouped together into a `bucket'.  Selection is decided by this
property, which has the following acceptable values:

‘BATCH’

     When in this mode CMake determines which files are grouped
     together.  The UNITY_BUILD_BATCH_SIZE property
     controls the upper limit on how many sources can be combined per
     unity source file.

     Example usage:

          add_library(example_library
                      source1.cxx
                      source2.cxx
                      source3.cxx
                      source4.cxx)

          set_target_properties(example_library PROPERTIES
                                UNITY_BUILD_MODE BATCH
                                UNITY_BUILD_BATCH_SIZE 2
                                )

‘GROUP’

     When in this mode each target explicitly specifies how to group
     source files.  Each source file that has the same
     UNITY_GROUP value will be grouped together.  Any sources
     that don’t have this property will be compiled individually.  The
     UNITY_BUILD_BATCH_SIZE property is ignored when using
     this mode.

     Example usage:

          add_library(example_library
                      source1.cxx
                      source2.cxx
                      source3.cxx
                      source4.cxx)

          set_target_properties(example_library PROPERTIES
                                UNITY_BUILD_MODE GROUP
                                )

          set_source_files_properties(source1.cxx source2.cxx source3.cxx
                                      PROPERTIES UNITY_GROUP "bucket1"
                                      )
          set_source_files_properties(source4.cxx
                                      PROPERTIES UNITY_GROUP "bucket2"
                                      )

If no explicit UNITY_BUILD_MODE has been specified, CMake
will default to ‘BATCH’.

19.3.252 VERSION
----------------

What version number is this target.

For shared libraries ‘VERSION’ and SOVERSION can be used to
specify the build version and API version respectively.  When building
or installing appropriate symlinks are created if the platform supports
symlinks and the linker supports so-names.  If only one of both is
specified the missing is assumed to have the same version number.  For
executables ‘VERSION’ can be used to specify the build version.  When
building or installing appropriate symlinks are created if the platform
supports symlinks.

19.3.252.1 Windows Versions
...........................

For shared libraries and executables on Windows the ‘VERSION’ attribute
is parsed to extract a ‘<major>.<minor>’ version number.  These numbers
are used as the image version of the binary.

19.3.252.2 Mach-O Versions
..........................

For shared libraries and executables on Mach-O systems (e.g.  macOS,
iOS), the SOVERSION property corresponds to the
`compatibility version' and ‘VERSION’ corresponds to the `current
version' (unless Mach-O specific overrides are provided, as discussed
below).  See the FRAMEWORK target property for an example.

For shared libraries, the MACHO_COMPATIBILITY_VERSION and
MACHO_CURRENT_VERSION properties can be used to override
the `compatibility version' and `current version' respectively.  Note
that SOVERSION will still be used to form the ‘install_name’
and both SOVERSION and ‘VERSION’ may also affect the file
and symlink names.

Versions of Mach-O binaries may be checked with the ‘otool -L <binary>’
command.

19.3.253 VISIBILITY_INLINES_HIDDEN
----------------------------------

Whether to add a compile flag to hide symbols of inline functions

The ‘VISIBILITY_INLINES_HIDDEN’ property determines whether a flag for
hiding symbols for inline functions, such as
‘-fvisibility-inlines-hidden’, should be used when invoking the
compiler.  This property affects compilation in sources of all types of
targets (subject to policy CMP0063).

This property is initialized by the value of the
CMAKE_VISIBILITY_INLINES_HIDDEN variable if it is set when a
target is created.

19.3.254 VS_CONFIGURATION_TYPE
------------------------------

New in version 3.6.

Visual Studio project configuration type.

Sets the ‘ConfigurationType’ attribute for a generated Visual Studio
project.  The property value may use generator expressions.
If this property is set, it overrides the default setting that is based
on the target type (e.g.  ‘StaticLibrary’, ‘Application’, …).

Supported on Visual Studio Generators for VS 2010 and
higher.

19.3.255 VS_DEBUGGER_COMMAND
----------------------------

New in version 3.12.

Sets the local debugger command for Visual Studio C++ targets.  The
property value may use generator expressions.  This is defined
in ‘<LocalDebuggerCommand>’ in the Visual Studio project file.

This property only works for Visual Studio 2010 and above; it is ignored
on other generators.

19.3.256 VS_DEBUGGER_COMMAND_ARGUMENTS
--------------------------------------

New in version 3.13.

Sets the local debugger command line arguments for Visual Studio C++
targets.  The property value may use generator expressions.
This is defined in ‘<LocalDebuggerCommandArguments>’ in the Visual
Studio project file.

This property only works for Visual Studio 2010 and above; it is ignored
on other generators.

19.3.257 VS_DEBUGGER_ENVIRONMENT
--------------------------------

New in version 3.13.

Sets the local debugger environment for Visual Studio C++ targets.  The
property value may use generator expressions.  This is defined
in ‘<LocalDebuggerEnvironment>’ in the Visual Studio project file.

This property only works for Visual Studio 2010 and above; it is ignored
on other generators.

19.3.258 VS_DEBUGGER_WORKING_DIRECTORY
--------------------------------------

New in version 3.8.

Sets the local debugger working directory for Visual Studio C++ targets.
The property value may use generator expressions.  This is
defined in ‘<LocalDebuggerWorkingDirectory>’ in the Visual Studio
project file.

This property only works for Visual Studio 2010 and above; it is ignored
on other generators.

19.3.259 VS_DESKTOP_EXTENSIONS_VERSION
--------------------------------------

New in version 3.4.

Visual Studio Windows 10 Desktop Extensions Version

Specifies the version of the Desktop Extensions that should be included
in the target.  For example ‘10.0.10240.0’.  If the value is not
specified, the Desktop Extensions will not be included.  To use the same
version of the extensions as the Windows 10 SDK that is being used, you
can use the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.
variable.

19.3.260 VS_DOTNET_DOCUMENTATION_FILE
-------------------------------------

New in version 3.17.

Visual Studio managed project .NET documentation output

Sets the target XML documentation file output.

19.3.261 VS_DOTNET_REFERENCE_<refname>
--------------------------------------

New in version 3.8.

Visual Studio managed project .NET reference with name ‘<refname>’ and
hint path.

Adds one .NET reference to generated Visual Studio project.  The
reference will have the name ‘<refname>’ and will point to the assembly
given as value of the property.

See also VS_DOTNET_REFERENCES and
VS_DOTNET_REFERENCES_COPY_LOCAL.

19.3.262 VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>
--------------------------------------------------------

New in version 3.10.

Defines an XML property ‘<tagname>’ for a .NET reference ‘<refname>’.

Reference properties can be set for .NET references which are defined by
the target properties VS_DOTNET_REFERENCES,
VS_DOTNET_REFERENCE_<refname> and also for project references to
other C# targets which are established by target_link_libraries().

This property is only applicable to C# targets and Visual Studio
generators 2010 and later.

19.3.263 VS_DOTNET_REFERENCES
-----------------------------

Visual Studio managed project .NET references

Adds one or more semicolon-delimited .NET references to a generated
Visual Studio project.  For example, “System;System.Windows.Forms”.

19.3.264 VS_DOTNET_REFERENCES_COPY_LOCAL
----------------------------------------

New in version 3.8.

Sets the `Copy Local' property for all .NET hint references in the
target

Boolean property to enable/disable copying of .NET hint references to
output directory.  The default is ‘ON’.

19.3.265 VS_DOTNET_TARGET_FRAMEWORK_VERSION
-------------------------------------------

Specify the .NET target framework version.

Used to specify the .NET target framework version for C++/CLI. For
example, “v4.5”.

This property is deprecated and should not be used anymore.  Use
DOTNET_TARGET_FRAMEWORK or DOTNET_TARGET_FRAMEWORK_VERSION
instead.

19.3.266 VS_DPI_AWARE
---------------------

New in version 3.16.

Set the Manifest Tool -> Input and Output -> DPI Awareness in the Visual
Studio target project properties.

Valid values are ‘PerMonitor’, ‘ON’, or ‘OFF’.

For example:

     add_executable(myproject myproject.cpp)
     set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor")

19.3.267 VS_GLOBAL_KEYWORD
--------------------------

Visual Studio project keyword for VS 10 (2010) and newer.

Sets the “keyword” attribute for a generated Visual Studio project.
Defaults to “Win32Proj”.  You may wish to override this value with
“ManagedCProj”, for example, in a Visual Studio managed C++ unit test
project.

Use the VS_KEYWORD target property to set the keyword for
Visual Studio 9 (2008) and older.

19.3.268 VS_GLOBAL_PROJECT_TYPES
--------------------------------

Visual Studio project type(s).

Can be set to one or more UUIDs recognized by Visual Studio to indicate
the type of project.  This value is copied verbatim into the generated
project file.  Example for a managed C++ unit testing project:

     {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}

UUIDs are semicolon-delimited.

19.3.269 VS_GLOBAL_ROOTNAMESPACE
--------------------------------

Visual Studio project root namespace.

Sets the “RootNamespace” attribute for a generated Visual Studio
project.  The attribute will be generated only if this is set.

19.3.270 VS_GLOBAL_<variable>
-----------------------------

Visual Studio project-specific global variable.

Tell the Visual Studio generator to set the global variable ‘<variable>’
to a given value in the generated Visual Studio project.  Ignored on
other generators.  Qt integration works better if VS_GLOBAL_QtVersion is
set to the version FindQt4.cmake found.  For example, “4.7.3”

19.3.271 VS_IOT_EXTENSIONS_VERSION
----------------------------------

New in version 3.4.

Visual Studio Windows 10 IoT Extensions Version

Specifies the version of the IoT Extensions that should be included in
the target.  For example ‘10.0.10240.0’.  If the value is not specified,
the IoT Extensions will not be included.  To use the same version of the
extensions as the Windows 10 SDK that is being used, you can use the
CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.

19.3.272 VS_IOT_STARTUP_TASK
----------------------------

New in version 3.4.

Visual Studio Windows 10 IoT Continuous Background Task

Specifies that the target should be compiled as a Continuous Background
Task library.

19.3.273 VS_JUST_MY_CODE_DEBUGGING
----------------------------------

New in version 3.15.

Enable Just My Code with Visual Studio debugger.

Supported on Visual Studio Generators for VS 2010 and
higher, see Makefile Generators and the Ninja.
generators.

This property is initialized by the
CMAKE_VS_JUST_MY_CODE_DEBUGGING variable if it is set when a
target is created.

19.3.274 VS_KEYWORD
-------------------

Visual Studio project keyword for VS 9 (2008) and older.

Can be set to change the visual studio keyword, for example Qt
integration works better if this is set to Qt4VSv1.0.

Use the VS_GLOBAL_KEYWORD target property to set the
keyword for Visual Studio 10 (2010) and newer.

19.3.275 VS_MOBILE_EXTENSIONS_VERSION
-------------------------------------

New in version 3.4.

Visual Studio Windows 10 Mobile Extensions Version

Specifies the version of the Mobile Extensions that should be included
in the target.  For example ‘10.0.10240.0’.  If the value is not
specified, the Mobile Extensions will not be included.  To use the same
version of the extensions as the Windows 10 SDK that is being used, you
can use the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.
variable.

19.3.276 VS_NO_SOLUTION_DEPLOY
------------------------------

New in version 3.15.

Specify that the target should not be marked for deployment to a Windows
CE or Windows Phone device in the generated Visual Studio solution.

Be default, all EXE and shared library (DLL) targets are marked to
deploy to the target device in the generated Visual Studio solution.

Generator expressions are supported.

There are reasons one might want to exclude a target / generated project
from deployment:

   - The library or executable may not be necessary in the primary
     deploy/debug scenario, and excluding from deployment saves time in
     the develop/download/debug cycle.

   - There may be insufficient space on the target device to accommodate
     all of the build products.

   - Visual Studio 2013 requires a target device IP address be entered
     for each target marked for deployment.  For large numbers of
     targets, this can be tedious.  NOTE: Visual Studio `will' deploy
     all project dependencies of a project tagged for deployment to the
     IP address configured for that project even if those dependencies
     are not tagged for deployment.

19.3.276.1 Example 1
....................

This shows setting the variable for the target foo.

     add_library(foo SHARED foo.cpp)
     set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON)

19.3.276.2 Example 2
....................

This shows setting the variable for the Release configuration only.

     add_library(foo SHARED foo.cpp)
     set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>")

19.3.277 VS_PACKAGE_REFERENCES
------------------------------

New in version 3.15.

Visual Studio package references for nuget.

Adds one or more semicolon-delimited package references to a generated
Visual Studio project.  The version of the package will be underscore
delimited.  For example, ‘boost_1.7.0;nunit_3.12.*’.

     set_property(TARGET ${TARGET_NAME} PROPERTY
       VS_PACKAGE_REFERENCES "boost_1.7.0")

19.3.278 VS_PLATFORM_TOOLSET
----------------------------

New in version 3.18.

Overrides the platform toolset used to build a target.

Only supported when the compiler used by the given toolset is the same
as the compiler used to build the whole source tree.

This is especially useful to create driver projects with the toolsets
“WindowsUserModeDriver10.0” or “WindowsKernelModeDriver10.0”.

19.3.279 VS_PROJECT_IMPORT
--------------------------

New in version 3.15.

Visual Studio managed project imports

Adds to a generated Visual Studio project one or more
semicolon-delimited paths to .props files needed when building projects
from some NuGet packages.  For example,
‘my_packages_path/MyPackage.1.0.0/build/MyPackage.props’.

19.3.280 VS_SCC_AUXPATH
-----------------------

Visual Studio Source Code Control Aux Path.

Can be set to change the visual studio source code control auxpath
property.

19.3.281 VS_SCC_LOCALPATH
-------------------------

Visual Studio Source Code Control Local Path.

Can be set to change the visual studio source code control local path
property.

19.3.282 VS_SCC_PROJECTNAME
---------------------------

Visual Studio Source Code Control Project.

Can be set to change the visual studio source code control project name
property.

19.3.283 VS_SCC_PROVIDER
------------------------

Visual Studio Source Code Control Provider.

Can be set to change the visual studio source code control provider
property.

19.3.284 VS_SDK_REFERENCES
--------------------------

New in version 3.7.

Visual Studio project SDK references.  Specify a
semicolon-separated list of SDK references to be added to a
generated Visual Studio project, e.g.  ‘Microsoft.AdMediatorWindows81,
Version=1.0’.

19.3.285 VS_SOLUTION_DEPLOY
---------------------------

New in version 3.18.

Specify that the target should be marked for deployment when not
targeting Windows CE, Windows Phone or a Windows Store application.

If the target platform doesn’t support deployment, this property won’t
have any effect.

Generator expressions are supported.

19.3.285.1 Examples
...................

Always deploy target ‘foo’:

     add_executable(foo SHARED foo.cpp)
     set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)

Deploy target ‘foo’ for all configurations except ‘Release’:

     add_executable(foo SHARED foo.cpp)
     set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")

19.3.286 VS_SOURCE_SETTINGS_<tool>
----------------------------------

New in version 3.18.

Set any item metadata on all non-built files that use <tool>.

Takes a list of ‘Key=Value’ pairs.  Tells the Visual Studio generator to
set ‘Key’ to ‘Value’ as item metadata on all non-built files that use
‘<tool>’.

For example:

     set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")

will set ‘Key’ to ‘Value’ and ‘Key2’ to ‘Value2’ for all non-built files
that use ‘FXCompile’.

Generator expressions are supported.

19.3.287 VS_USER_PROPS
----------------------

New in version 3.8.

Sets the user props file to be included in the visual studio C++ project
file.  The standard path is
‘$(UserRootDir)\\Microsoft.Cpp.$(Platform).user.props’, which is in most
cases the same as
‘%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.Win32.user.props’
or
‘%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.x64.user.props’.

The ‘*.user.props’ files can be used for Visual Studio wide
configuration which is independent from cmake.

19.3.288 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
-----------------------------------------------

New in version 3.4.

Visual Studio Windows Target Platform Minimum Version

For Windows 10.  Specifies the minimum version of the OS that is being
targeted.  For example ‘10.0.10240.0’.  If the value is not specified,
the value of CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION will
be used on WindowsStore projects otherwise the target platform minimum
version will not be specified for the project.

19.3.289 VS_WINRT_COMPONENT
---------------------------

New in version 3.1.

Mark a target as a Windows Runtime component for the Visual Studio
generator.  Compile the target with ‘C++/CX’ language extensions for
Windows Runtime.  For ‘SHARED’ and ‘MODULE’ libraries, this also defines
the ‘_WINRT_DLL’ preprocessor macro.

     Note: Currently this is implemented only by Visual Studio
     generators.  Support may be added to other generators in the
     future.

19.3.290 VS_WINRT_EXTENSIONS
----------------------------

Deprecated.  Use VS_WINRT_COMPONENT instead.  This property
was an experimental partial implementation of that one.

19.3.291 VS_WINRT_REFERENCES
----------------------------

Visual Studio project Windows Runtime Metadata references

Adds one or more semicolon-delimited WinRT references to a generated
Visual Studio project.  For example, “Windows;Windows.UI.Core”.

19.3.292 WIN32_EXECUTABLE
-------------------------

Build an executable with a WinMain entry point on windows.

When this property is set to true the executable when linked on Windows
will be created with a WinMain() entry point instead of just main().
This makes it a GUI executable instead of a console application.  See
the CMAKE_MFC_FLAG variable documentation to configure use
of the Microsoft Foundation Classes (MFC) for WinMain executables.  This
property is initialized by the value of the
CMAKE_WIN32_EXECUTABLE variable if it is set when a target is
created.

This property supports generator expressions, except if the
target is managed (contains C# code.)

19.3.293 WINDOWS_EXPORT_ALL_SYMBOLS
-----------------------------------

New in version 3.4.

This property is implemented only for MS-compatible tools on Windows.

Enable this boolean property to automatically create a module definition
(‘.def’) file with all global symbols found in the input ‘.obj’ files
for a ‘SHARED’ library (or executable with ENABLE_EXPORTS)
on Windows.  The module definition file will be passed to the linker
causing all symbols to be exported from the ‘.dll’.  For global `data'
symbols, ‘__declspec(dllimport)’ must still be used when compiling
against the code in the ‘.dll’.  All other function symbols will be
automatically exported and imported by callers.  This simplifies porting
projects to Windows by reducing the need for explicit ‘dllexport’
markup, even in ‘C++’ classes.

When this property is enabled, zero or more ‘.def’ files may also be
specified as source files of the target.  The exports named by these
files will be merged with those detected from the object files to
generate a single module definition file to be passed to the linker.
This can be used to export symbols from a ‘.dll’ that are not in any of
its object files but are added by the linker from dependencies (e.g.
‘msvcrt.lib’).

This property is initialized by the value of the
CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS variable if it is set when a
target is created.

19.3.294 XCODE_ATTRIBUTE_<an-attribute>
---------------------------------------

Set Xcode target attributes directly.

Tell the Xcode generator to set ‘<an-attribute>’ to a given
value in the generated Xcode project.  Ignored on other generators.

See the CMAKE_XCODE_ATTRIBUTE_<an-attribute> variable to
set attributes on all targets in a directory tree.

Contents of ‘XCODE_ATTRIBUTE_<an-attribute>’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

19.3.295 XCODE_EXPLICIT_FILE_TYPE
---------------------------------

New in version 3.8.

Set the Xcode ‘explicitFileType’ attribute on its reference to a target.
CMake computes a default based on target type but can be told explicitly
with this property.

See also XCODE_PRODUCT_TYPE.

19.3.296 XCODE_GENERATE_SCHEME
------------------------------

New in version 3.15.

If enabled, the Xcode generator will generate schema files.
These are useful to invoke analyze, archive, build-for-testing and test
actions from the command line.

This property is initialized by the value of the variable
CMAKE_XCODE_GENERATE_SCHEME if it is set when a target is
created.

The following target properties overwrite the default of the
corresponding settings on the “Diagnostic” tab for each schema file.
Each of those is initialized by the respective ‘CMAKE_’ variable at
target creation time.

   - XCODE_SCHEME_ADDRESS_SANITIZER.

   - XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.

   - XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.

   - XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.

   - XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.

   - XCODE_SCHEME_GUARD_MALLOC.

   - XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.

   - XCODE_SCHEME_MALLOC_GUARD_EDGES.

   - XCODE_SCHEME_MALLOC_SCRIBBLE.

   - XCODE_SCHEME_MALLOC_STACK.

   - XCODE_SCHEME_THREAD_SANITIZER.

   - XCODE_SCHEME_THREAD_SANITIZER_STOP.

   - XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.

   - XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.

   - XCODE_SCHEME_ZOMBIE_OBJECTS.

The following target properties will be applied on the “Info”,
“Arguments”, and “Options” tab:

   - XCODE_SCHEME_ARGUMENTS.

   - XCODE_SCHEME_DEBUG_AS_ROOT.

   - XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.

   - XCODE_SCHEME_ENVIRONMENT.

   - XCODE_SCHEME_EXECUTABLE.

   - XCODE_SCHEME_WORKING_DIRECTORY.

19.3.297 XCODE_LINK_BUILD_PHASE_MODE
------------------------------------

New in version 3.19.

When using the Xcode generator, libraries to be linked will
be specified in the Xcode project file using either the “Link Binary
With Libraries” build phase or directly as linker flags.  The former
allows Xcode to manage build paths, which may be necessary when creating
Xcode archives because it may use different build paths to a regular
build.

This property controls usage of “Link Binary With Libraries” build phase
for a target that is an app bundle, executable, shared library, shared
framework or a module library.

Possible values are:

   * ‘NONE’ The libraries will be linked by specifying the linker flags
     directly.

   * ‘BUILT_ONLY’ The “Link Binary With Libraries” build phase will be
     used to link to another target under the following conditions:

        - The target to be linked to is a regular non-imported,
          non-interface library target.

        - The output directory of the target being built has not been
          changed from its default (see RUNTIME_OUTPUT_DIRECTORY
          and LIBRARY_OUTPUT_DIRECTORY).

   * ‘KNOWN_LOCATION’ The “Link Binary With Libraries” build phase will
     be used to link to another target under the same conditions as with
     ‘BUILT_ONLY’ and also: - Imported library targets except those of
     type ‘UNKNOWN’.  - Any non-target library specified directly with a
     path.

For all other cases, the libraries will be linked by specifying the
linker flags directly.

     Warning: Libraries linked using “Link Binary With Libraries” are
     linked after the ones linked through regular linker flags.  This
     order should be taken into account when different static libraries
     contain symbols with the same name, as the former ones will take
     precedence over the latter.

     Warning: If two or more directories contain libraries with
     identical file names and some libraries are linked from those
     directories, the library search path lookup will end up linking
     libraries from the first directory.  This is a known limitation of
     Xcode.

This property is initialized by the value of the
CMAKE_XCODE_LINK_BUILD_PHASE_MODE variable if it is set when a
target is created.

19.3.298 XCODE_PRODUCT_TYPE
---------------------------

New in version 3.8.

Set the Xcode ‘productType’ attribute on its reference to a target.
CMake computes a default based on target type but can be told explicitly
with this property.

See also XCODE_EXPLICIT_FILE_TYPE.

19.3.299 XCODE_SCHEME_ADDRESS_SANITIZER
---------------------------------------

New in version 3.13.

Whether to enable ‘Address Sanitizer’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER if it is set when a target
is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.300 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
--------------------------------------------------------

New in version 3.13.

Whether to enable ‘Detect use of stack after return’ in the Diagnostics
section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN if it is
set when a target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.301 XCODE_SCHEME_ARGUMENTS
-------------------------------

New in version 3.13.

Specify command line arguments that should be added to the Arguments
section of the generated Xcode scheme.

If set to a list of arguments those will be added to the scheme.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.302 XCODE_SCHEME_DEBUG_AS_ROOT
-----------------------------------

New in version 3.15.

Whether to debug the target as ‘root’.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.303 XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
-----------------------------------------------

New in version 3.16.

Whether to enable ‘Allow debugging when using document Versions Browser’
in the Options section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING if it is set when a
target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.304 XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
-------------------------------------------------

New in version 3.13.

Whether to disable the ‘Main Thread Checker’ in the Diagnostics section
of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER if it is set when
a target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.305 XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
-------------------------------------------

New in version 3.13.

Whether to enable ‘Dynamic Library Loads’ in the Diagnostics section of
the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS if it is set when a
target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.306 XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
----------------------------------------------

New in version 3.13.

Whether to enable ‘Dynamic Linker API usage’ in the Diagnostics section
of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE if it is set when a
target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.307 XCODE_SCHEME_ENVIRONMENT
---------------------------------

New in version 3.13.

Specify environment variables that should be added to the Arguments
section of the generated Xcode scheme.

If set to a list of environment variables and values of the form
‘MYVAR=value’ those environment variables will be added to the scheme.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.308 XCODE_SCHEME_EXECUTABLE
--------------------------------

New in version 3.13.

Specify path to executable in the Info section of the generated Xcode
scheme.  If not set the schema generator will select the current target
if it is actually executable.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.309 XCODE_SCHEME_GUARD_MALLOC
----------------------------------

New in version 3.13.

Whether to enable ‘Guard Malloc’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_GUARD_MALLOC if it is set when a target is
created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.310 XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
----------------------------------------------

New in version 3.13.

Whether to enable the ‘Main Thread Checker’ option ‘Pause on issues’ in
the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP if it is set when a
target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.311 XCODE_SCHEME_MALLOC_GUARD_EDGES
----------------------------------------

New in version 3.13.

Whether to enable ‘Malloc Guard Edges’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES if it is set when a target
is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.312 XCODE_SCHEME_MALLOC_SCRIBBLE
-------------------------------------

New in version 3.13.

Whether to enable ‘Malloc Scribble’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE if it is set when a target is
created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.313 XCODE_SCHEME_MALLOC_STACK
----------------------------------

New in version 3.13.

Whether to enable ‘Malloc Stack’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_MALLOC_STACK if it is set when a target is
created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.314 XCODE_SCHEME_THREAD_SANITIZER
--------------------------------------

New in version 3.13.

Whether to enable ‘Thread Sanitizer’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_THREAD_SANITIZER if it is set when a target is
created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.315 XCODE_SCHEME_THREAD_SANITIZER_STOP
-------------------------------------------

New in version 3.13.

Whether to enable ‘Thread Sanitizer - Pause on issues’ in the
Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP if it is set when a
target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.316 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
---------------------------------------------------

New in version 3.13.

Whether to enable ‘Undefined Behavior Sanitizer’ in the Diagnostics
section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER if it is set
when a target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.317 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
--------------------------------------------------------

New in version 3.13.

Whether to enable ‘Undefined Behavior Sanitizer’ option ‘Pause on
issues’ in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP if it is
set when a target is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.318 XCODE_SCHEME_WORKING_DIRECTORY
---------------------------------------

New in version 3.17.

Specify the ‘Working Directory’ of the `Run' and `Profile' actions in
the generated Xcode scheme.  In case the value contains generator
expressions those are evaluated.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_WORKING_DIRECTORY if it is set when a target
is created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.319 XCODE_SCHEME_ZOMBIE_OBJECTS
------------------------------------

New in version 3.13.

Whether to enable ‘Zombie Objects’ in the Diagnostics section of the
generated Xcode scheme.

This property is initialized by the value of the variable
CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS if it is set when a target is
created.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

19.3.320 XCTEST
---------------

New in version 3.3.

This target is a XCTest CFBundle on the Mac.

This property will usually get set via the xctest_add_bundle()
macro in FindXCTest module.

If a module library target has this property set to true it will be
built as a CFBundle when built on the Mac.  It will have the directory
structure required for a CFBundle.

This property depends on BUNDLE to be effective.

19.4 Properties on Tests
========================

19.4.1 ATTACHED_FILES
---------------------

Attach a list of files to a dashboard submission.

Set this property to a list of files that will be encoded and submitted
to the dashboard as an addition to the test result.

19.4.2 ATTACHED_FILES_ON_FAIL
-----------------------------

Attach a list of files to a dashboard submission if the test fails.

Same as ATTACHED_FILES, but these files will only be
included if the test does not pass.

19.4.3 COST
-----------

This property describes the cost of a test.  When parallel testing is
enabled, tests in the test set will be run in descending order of cost.
Projects can explicitly define the cost of a test by setting this
property to a floating point value.

When the cost of a test is not defined by the project, see ctest.
will initially use a default cost of ‘0’.  It computes a weighted
average of the cost each time a test is run and uses that as an improved
estimate of the cost for the next run.  The more a test is re-run in the
same build directory, the more representative the cost should become.

19.4.4 DEPENDS
--------------

Specifies that this test should only be run after the specified list of
tests.

Set this to a list of tests that must finish before this test is run.
The results of those tests are not considered, the dependency
relationship is purely for order of execution (i.e.  it is really just a
`run after' relationship).  Consider using test fixtures with setup
tests if a dependency with successful completion is required (see
FIXTURES_REQUIRED).

19.4.4.1 Examples
.................

     add_test(NAME baseTest1 ...)
     add_test(NAME baseTest2 ...)
     add_test(NAME dependsTest12 ...)

     set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2")
     # dependsTest12 runs after baseTest1 and baseTest2, even if they fail

19.4.5 DISABLED
---------------

New in version 3.9.

If set to ‘True’, the test will be skipped and its status will be ‘Not
Run’.  A ‘DISABLED’ test will not be counted in the total number of
tests and its completion status will be reported to CDash as ‘Disabled’.

A ‘DISABLED’ test does not participate in test fixture dependency
resolution.  If a ‘DISABLED’ test has fixture requirements defined in
its FIXTURES_REQUIRED property, it will not cause setup or
cleanup tests for those fixtures to be added to the test set.

If a test with the FIXTURES_SETUP property set is
‘DISABLED’, the fixture behavior will be as though that setup test was
passing and any test case requiring that fixture will still run.

19.4.6 ENVIRONMENT
------------------

Specify environment variables that should be defined for running a test.

If set to a list of environment variables and values of the form
‘MYVAR=value’ those environment variables will be defined while running
the test.  The environment is restored to its previous state after the
test is done.

19.4.7 FAIL_REGULAR_EXPRESSION
------------------------------

If the output matches this regular expression the test will fail.

If set, if the output matches one of specified regular expressions, the
test will fail.  Example:

     set_tests_properties(mytest PROPERTIES
       FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
     )

‘FAIL_REGULAR_EXPRESSION’ expects a list of regular expressions.

19.4.8 FIXTURES_CLEANUP
-----------------------

New in version 3.7.

Specifies a list of fixtures for which the test is to be treated as a
cleanup test.  These fixture names are distinct from test case names and
are not required to have any similarity to the names of tests associated
with them.

Fixture cleanup tests are ordinary tests with all of the usual test
functionality.  Setting the ‘FIXTURES_CLEANUP’ property for a test has
two primary effects:

   - CTest will ensure the test executes after all other tests which
     list any of the fixtures in its FIXTURES_REQUIRED.
     property.

   - If CTest is asked to run only a subset of tests (e.g.  using
     regular expressions or the ‘--rerun-failed’ option) and the cleanup
     test is not in the set of tests to run, it will automatically be
     added if any tests in the set require any fixture listed in
     ‘FIXTURES_CLEANUP’.

A cleanup test can have multiple fixtures listed in its
‘FIXTURES_CLEANUP’ property.  It will execute only once for the whole
CTest run, not once for each fixture.  A fixture can also have more than
one cleanup test defined.  If there are multiple cleanup tests for a
fixture, projects can control their order with the usual DEPENDS
test property if necessary.

A cleanup test is allowed to require other fixtures, but not any fixture
listed in its ‘FIXTURES_CLEANUP’ property.  For example:

     # Ok: Dependent fixture is different to cleanup
     set_tests_properties(cleanupFoo PROPERTIES
       FIXTURES_CLEANUP  Foo
       FIXTURES_REQUIRED Bar
     )

     # Error: cannot require same fixture as cleanup
     set_tests_properties(cleanupFoo PROPERTIES
       FIXTURES_CLEANUP  Foo
       FIXTURES_REQUIRED Foo
     )

Cleanup tests will execute even if setup or regular tests for that
fixture fail or are skipped.

See FIXTURES_REQUIRED for a more complete discussion of how
to use test fixtures.

19.4.9 FIXTURES_REQUIRED
------------------------

New in version 3.7.

Specifies a list of fixtures the test requires.  Fixture names are case
sensitive and they are not required to have any similarity to test
names.

Fixtures are a way to attach setup and cleanup tasks to a set of tests.
If a test requires a given fixture, then all tests marked as setup tasks
for that fixture will be executed first (once for the whole set of
tests, not once per test requiring the fixture).  After all tests
requiring a particular fixture have completed, CTest will ensure all
tests marked as cleanup tasks for that fixture are then executed.  Tests
are marked as setup tasks with the FIXTURES_SETUP property
and as cleanup tasks with the FIXTURES_CLEANUP property.
If any of a fixture’s setup tests fail, all tests listing that fixture
in their ‘FIXTURES_REQUIRED’ property will not be executed.  The cleanup
tests for the fixture will always be executed, even if some setup tests
fail.

When CTest is asked to execute only a subset of tests (e.g.  by the use
of regular expressions or when run with the ‘--rerun-failed’ command
line option), it will automatically add any setup or cleanup tests for
fixtures required by any of the tests that are in the execution set.
This behavior can be overridden with the ‘-FS’, ‘-FC’ and ‘-FA’ command
line options to ctest(1) if desired.

Since setup and cleanup tasks are also tests, they can have an ordering
specified by the DEPENDS test property just like any other
tests.  This can be exploited to implement setup or cleanup using
multiple tests for a single fixture to modularise setup or cleanup
logic.

The concept of a fixture is different to that of a resource specified by
RESOURCE_LOCK, but they may be used together.  A fixture
defines a set of tests which share setup and cleanup requirements,
whereas a resource lock has the effect of ensuring a particular set of
tests do not run in parallel.  Some situations may need both, such as
setting up a database, serialising test access to that database and
deleting the database again at the end.  For such cases, tests would
populate both ‘FIXTURES_REQUIRED’ and RESOURCE_LOCK to
combine the two behaviours.  Names used for RESOURCE_LOCK.
have no relationship with names of fixtures, so note that a resource
lock does not imply a fixture and vice versa.

Consider the following example which represents a database test scenario
similar to that mentioned above:

     add_test(NAME testsDone   COMMAND emailResults)
     add_test(NAME fooOnly     COMMAND testFoo)
     add_test(NAME dbOnly      COMMAND testDb)
     add_test(NAME dbWithFoo   COMMAND testDbWithFoo)
     add_test(NAME createDB    COMMAND initDB)
     add_test(NAME setupUsers  COMMAND userCreation)
     add_test(NAME cleanupDB   COMMAND deleteDB)
     add_test(NAME cleanupFoo  COMMAND removeFoos)

     set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)

     set_tests_properties(createDB   PROPERTIES FIXTURES_SETUP    DB)
     set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP    DB)
     set_tests_properties(cleanupDB  PROPERTIES FIXTURES_CLEANUP  DB)
     set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP  Foo)
     set_tests_properties(testsDone  PROPERTIES FIXTURES_CLEANUP  "DB;Foo")

     set_tests_properties(fooOnly    PROPERTIES FIXTURES_REQUIRED Foo)
     set_tests_properties(dbOnly     PROPERTIES FIXTURES_REQUIRED DB)
     set_tests_properties(dbWithFoo  PROPERTIES FIXTURES_REQUIRED "DB;Foo")

     set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
                          PROPERTIES RESOURCE_LOCK DbAccess)

Key points from this example:

   - Two fixtures are defined: ‘DB’ and ‘Foo’.  Tests can require a
     single fixture as ‘fooOnly’ and ‘dbOnly’ do, or they can depend on
     multiple fixtures like ‘dbWithFoo’ does.

   - A ‘DEPENDS’ relationship is set up to ensure ‘setupUsers’ happens
     after ‘createDB’, both of which are setup tests for the ‘DB’
     fixture and will therefore be executed before the ‘dbOnly’ and
     ‘dbWithFoo’ tests automatically.

   - No explicit ‘DEPENDS’ relationships were needed to make the setup
     tests run before or the cleanup tests run after the regular tests.

   - The ‘Foo’ fixture has no setup tests defined, only a single cleanup
     test.

   - ‘testsDone’ is a cleanup test for both the ‘DB’ and ‘Foo’ fixtures.
     Therefore, it will only execute once regular tests for both
     fixtures have finished (i.e.  after ‘fooOnly’, ‘dbOnly’ and
     ‘dbWithFoo’).  No ‘DEPENDS’ relationship was specified for
     ‘testsDone’, so it is free to run before, after or concurrently
     with other cleanup tests for either fixture.

   - The setup and cleanup tests never list the fixtures they are for in
     their own ‘FIXTURES_REQUIRED’ property, as that would result in a
     dependency on themselves and be considered an error.

19.4.10 FIXTURES_SETUP
----------------------

New in version 3.7.

Specifies a list of fixtures for which the test is to be treated as a
setup test.  These fixture names are distinct from test case names and
are not required to have any similarity to the names of tests associated
with them.

Fixture setup tests are ordinary tests with all of the usual test
functionality.  Setting the ‘FIXTURES_SETUP’ property for a test has two
primary effects:

   - CTest will ensure the test executes before any other test which
     lists the fixture name(s) in its FIXTURES_REQUIRED.
     property.

   - If CTest is asked to run only a subset of tests (e.g.  using
     regular expressions or the ‘--rerun-failed’ option) and the setup
     test is not in the set of tests to run, it will automatically be
     added if any tests in the set require any fixture listed in
     ‘FIXTURES_SETUP’.

A setup test can have multiple fixtures listed in its ‘FIXTURES_SETUP’
property.  It will execute only once for the whole CTest run, not once
for each fixture.  A fixture can also have more than one setup test
defined.  If there are multiple setup tests for a fixture, projects can
control their order with the usual DEPENDS test property if
necessary.

A setup test is allowed to require other fixtures, but not any fixture
listed in its ‘FIXTURES_SETUP’ property.  For example:

     # Ok: dependent fixture is different to setup
     set_tests_properties(setupFoo PROPERTIES
       FIXTURES_SETUP    Foo
       FIXTURES_REQUIRED Bar
     )

     # Error: cannot require same fixture as setup
     set_tests_properties(setupFoo PROPERTIES
       FIXTURES_SETUP    Foo
       FIXTURES_REQUIRED Foo
     )

If any of a fixture’s setup tests fail, none of the tests listing that
fixture in its FIXTURES_REQUIRED property will be run.
Cleanup tests will, however, still be executed.

See FIXTURES_REQUIRED for a more complete discussion of how
to use test fixtures.

19.4.11 LABELS
--------------

Specify a list of text labels associated with a test.

The list is reported in dashboard submissions.

19.4.12 MEASUREMENT
-------------------

Specify a ‘CDASH’ measurement and value to be reported for a test.

If set to a name then that name will be reported to ‘CDASH’ as a named
measurement with a value of ‘1’.  You may also specify a value by
setting ‘MEASUREMENT’ to ‘measurement=value’.

19.4.13 PASS_REGULAR_EXPRESSION
-------------------------------

The output must match this regular expression for the test to pass.

If set, the test output will be checked against the specified regular
expressions and at least one of the regular expressions has to match,
otherwise the test will fail.  Example:

     set_tests_properties(mytest PROPERTIES
       PASS_REGULAR_EXPRESSION "TestPassed;All ok"
     )

‘PASS_REGULAR_EXPRESSION’ expects a list of regular expressions.

19.4.14 PROCESSOR_AFFINITY
--------------------------

New in version 3.12.

Set to a true value to ask CTest to launch the test process with CPU
affinity for a fixed set of processors.  If enabled and supported for
the current platform, CTest will choose a set of processors to place in
the CPU affinity mask when launching the test process.  The number of
processors in the set is determined by the PROCESSORS test
property or the number of processors available to CTest, whichever is
smaller.  The set of processors chosen will be disjoint from the
processors assigned to other concurrently running tests that also have
the ‘PROCESSOR_AFFINITY’ property enabled.

19.4.15 PROCESSORS
------------------

Set to specify how many process slots this test requires.  If not set,
the default is ‘1’ processor.

Denotes the number of processors that this test will require.  This is
typically used for MPI tests, and should be used in conjunction with the
ctest_test(). ‘PARALLEL_LEVEL’ option.

This will also be used to display a weighted test timing result in label
and subproject summaries in the command line output of ctest(1).
The wall clock time for the test run will be multiplied by this
property to give a better idea of how much cpu resource CTest allocated
for the test.

See also the PROCESSOR_AFFINITY test property.

19.4.16 REQUIRED_FILES
----------------------

List of files required to run the test.  The filenames are relative to
the test WORKING_DIRECTORY unless an absolute path is
specified.

If set to a list of files, the test will not be run unless all of the
files exist.

19.4.16.1 Examples
..................

Suppose that ‘test.txt’ is created by test ‘baseTest’ and ‘none.txt’
does not exist:

     add_test(NAME baseTest ...)   # Assumed to create test.txt
     add_test(NAME fileTest ...)

     # The following ensures that if baseTest is successful, test.txt will
     # have been created before fileTest is run
     set_tests_properties(fileTest PROPERTIES
       DEPENDS baseTest
       REQUIRED_FILES test.txt
     )

     add_test(NAME notRunTest ...)

     # The following makes notRunTest depend on two files. Nothing creates
     # the none.txt file, so notRunTest will fail with status "Not Run".
     set_tests_properties(notRunTest PROPERTIES
       REQUIRED_FILES "test.txt;none.txt"
     )

The above example demonstrates how ‘REQUIRED_FILES’ works, but it is not
the most robust way to implement test ordering with failure detection.
For that, test fixtures are a better alternative (see
FIXTURES_REQUIRED).

19.4.17 RESOURCE_GROUPS
-----------------------

New in version 3.16.

Specify resources required by a test, grouped in a way that is
meaningful to the test.  See resource allocation for more
information on how this property integrates into the CTest resource
allocation feature.

The ‘RESOURCE_GROUPS’ property is a semicolon-separated list.
of group descriptions.  Each entry consists of an optional number of
groups using the description followed by a series of resource
requirements for those groups.  These requirements (and the number of
groups) are separated by commas.  The resource requirements consist of
the name of a resource type, followed by a colon, followed by an
unsigned integer specifying the number of slots required on one resource
of the given type.

The ‘RESOURCE_GROUPS’ property tells CTest what resources a test expects
to use grouped in a way meaningful to the test.  The test itself must
read the environment variables to determine which resources
have been allocated to each group.  For example, each group may
correspond to a process the test will spawn when executed.

Consider the following example:

     add_test(NAME MyTest COMMAND MyExe)
     set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
       "2,gpus:2"
       "gpus:4,crypto_chips:2")

In this example, there are two group descriptions (implicitly separated
by a semicolon.)  The content of the first description is ‘2,gpus:2’.
This description specifies 2 groups, each of which requires 2 slots from
a single GPU. The content of the second description is
‘gpus:4,crypto_chips:2’.  This description does not specify a group
count, so a default of 1 is assumed.  This single group requires 4 slots
from a single GPU and 2 slots from a single cryptography chip.  In
total, 3 resource groups are specified for this test, each with its own
unique requirements.

Note that the number of slots following the resource type specifies
slots from a `single' instance of the resource.  If the resource group
can tolerate receiving slots from different instances of the same
resource, it can indicate this by splitting the specification into
multiple requirements of one slot.  For example:

     add_test(NAME MyTest COMMAND MyExe)
     set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
       "gpus:1,gpus:1,gpus:1,gpus:1")

In this case, the single resource group indicates that it needs four GPU
slots, all of which may come from separate GPUs (though they don’t have
to; CTest may still assign slots from the same GPU.)

When CTest sets the environment variables for a test, it
assigns a group number based on the group description, starting at 0 on
the left and the number of groups minus 1 on the right.  For example, in
the example above, the two groups in the first description would have
IDs of 0 and 1, and the single group in the second description would
have an ID of 2.

Both the ‘RESOURCE_GROUPS’ and RESOURCE_LOCK properties
serve similar purposes, but they are distinct and orthogonal.  Resources
specified by ‘RESOURCE_GROUPS’ do not affect RESOURCE_LOCK,
and vice versa.  Whereas RESOURCE_LOCK is a simpler
property that is used for locking one global resource, ‘RESOURCE_GROUPS’
is a more advanced property that allows multiple tests to simultaneously
use multiple resources of the same type, specifying their requirements
in a fine-grained manner.

19.4.18 RESOURCE_LOCK
---------------------

Specify a list of resources that are locked by this test.

If multiple tests specify the same resource lock, they are guaranteed
not to run concurrently.

See also FIXTURES_REQUIRED if the resource requires any
setup or cleanup steps.

Both the RESOURCE_GROUPS and ‘RESOURCE_LOCK’ properties serve
similar purposes, but they are distinct and orthogonal.  Resources
specified by RESOURCE_GROUPS do not affect ‘RESOURCE_LOCK’,
and vice versa.  Whereas ‘RESOURCE_LOCK’ is a simpler property that is
used for locking one global resource, see RESOURCE_GROUPS is a
more advanced property that allows multiple tests to simultaneously use
multiple resources of the same type, specifying their requirements in a
fine-grained manner.

19.4.19 RUN_SERIAL
------------------

Do not run this test in parallel with any other test.

Use this option in conjunction with the ctest_test ‘PARALLEL_LEVEL’
option to specify that this test should not be run in parallel with any
other tests.

19.4.20 SKIP_REGULAR_EXPRESSION
-------------------------------

New in version 3.16.

If the output matches this regular expression the test will be marked as
skipped.

If set, if the output matches one of specified regular expressions, the
test will be marked as skipped.  Example:

     set_property(TEST mytest PROPERTY
       SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped"
     )

‘SKIP_REGULAR_EXPRESSION’ expects a list of regular expressions.

See also the SKIP_RETURN_CODE property.

19.4.21 SKIP_RETURN_CODE
------------------------

Return code to mark a test as skipped.

Sometimes only a test itself can determine if all requirements for the
test are met.  If such a situation should not be considered a hard
failure a return code of the process can be specified that will mark the
test as ‘Not Run’ if it is encountered.  Valid values are in the range
of 0 to 255, inclusive.

See also the SKIP_REGULAR_EXPRESSION property.

19.4.22 TIMEOUT
---------------

How many seconds to allow for this test.

This property if set will limit a test to not take more than the
specified number of seconds to run.  If it exceeds that the test process
will be killed and ctest will move to the next test.  This setting takes
precedence over CTEST_TEST_TIMEOUT.

19.4.23 TIMEOUT_AFTER_MATCH
---------------------------

New in version 3.6.

Change a test’s timeout duration after a matching line is encountered in
its output.

19.4.23.1 Usage
...............

     add_test(mytest ...)
     set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}")

19.4.23.2 Description
.....................

Allow a test ‘seconds’ to complete after ‘regex’ is encountered in its
output.

When the test outputs a line that matches ‘regex’ its start time is
reset to the current time and its timeout duration is changed to
‘seconds’.  Prior to this, the timeout duration is determined by the
TIMEOUT property or the CTEST_TEST_TIMEOUT.
variable if either of these are set.  Because the test’s start time is
reset, its execution time will not include any time that was spent
waiting for the matching output.

TIMEOUT_AFTER_MATCH is useful for avoiding spurious
timeouts when your test must wait for some system resource to become
available before it can execute.  Set TIMEOUT to a longer
duration that accounts for resource acquisition and use
TIMEOUT_AFTER_MATCH to control how long the actual test is
allowed to run.

If the required resource can be controlled by CTest you should use
RESOURCE_LOCK instead of TIMEOUT_AFTER_MATCH.  This
property should be used when only the test itself can determine when its
required resources are available.

19.4.24 WILL_FAIL
-----------------

If set to true, this will invert the pass/fail flag of the test.

This property can be used for tests that are expected to fail and return
a non zero return code.

19.4.25 WORKING_DIRECTORY
-------------------------

The directory from which the test executable will be called.

If this is not set, the test will be run with the working directory set
to the binary directory associated with where the test was created (i.e.
the CMAKE_CURRENT_BINARY_DIR for where add_test().
was called).

19.5 Properties on Source Files
===============================

19.5.1 ABSTRACT
---------------

Is this source file an abstract class.

A property on a source file that indicates if the source file represents
a class that is abstract.  This only makes sense for languages that have
a notion of an abstract class and it is only used by some tools that
wrap classes into other languages.

19.5.2 AUTORCC_OPTIONS
----------------------

Additional options for ‘rcc’ when using AUTORCC.

This property holds additional command line options which will be used
when ‘rcc’ is executed during the build via AUTORCC, i.e.  it
is equivalent to the optional ‘OPTIONS’ argument of the
qt4_add_resources() macro.

By default it is empty.

The options set on the ‘.qrc’ source file may override
AUTORCC_OPTIONS set on the target.

19.5.2.1 EXAMPLE
................

     # ...
     set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9")
     # ...

19.5.3 AUTOUIC_OPTIONS
----------------------

Additional options for ‘uic’ when using AUTOUIC.

This property holds additional command line options which will be used
when ‘uic’ is executed during the build via AUTOUIC, i.e.  it
is equivalent to the optional ‘OPTIONS’ argument of the
qt4_wrap_ui() macro.

By default it is empty.

The options set on the ‘.ui’ source file may override
AUTOUIC_OPTIONS set on the target.

19.5.3.1 EXAMPLE
................

     # ...
     set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection")
     # ...

19.5.4 COMPILE_DEFINITIONS
--------------------------

Preprocessor definitions for compiling a source file.

The ‘COMPILE_DEFINITIONS’ property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ‘VAR’ or ‘VAR=value’.
Function-style definitions are not supported.  CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).  This
property may be set on a per-configuration basis using the name
‘COMPILE_DEFINITIONS_<CONFIG>’ where ‘<CONFIG>’ is an upper-case name
(ex.  ‘COMPILE_DEFINITIONS_DEBUG’).

CMake will automatically drop some definitions that are not supported by
the native build tool.  Xcode does not support per-configuration
definitions on source files.

Disclaimer: Most native build tools have poor support for escaping
certain values.  CMake has work-arounds for many cases but some values
may just not be possible to pass correctly.  If a value does not seem to
be escaped correctly, do not attempt to work-around the problem by
adding escape sequences to the value.  Your work-around may break in a
future version of CMake that has improved escape support.  Instead
consider defining the macro in a (configured) header file.  Then report
the limitation.  Known limitations include:

     #          - broken almost everywhere
     ;          - broken in VS IDE 7.0 and Borland Makefiles
     ,          - broken in VS IDE
     %          - broken in some cases in NMake
     & |        - broken in some cases on MinGW
     ^ < > \"   - broken in most Make tools on Windows

CMake does not reject these values outright because they do work in some
cases.  Use with caution.

Contents of ‘COMPILE_DEFINITIONS’ may use
cmake-generator-expressions(7) with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available
expressions.  However, see Xcode does not support per-config
per-source settings, so expressions that depend on the build
configuration are not allowed with that generator.

Generator expressions should be preferred instead of setting the
alternative per-configuration property.

19.5.5 COMPILE_FLAGS
--------------------

Additional flags to be added when compiling this source file.

The ‘COMPILE_FLAGS’ property, managed as a string, sets additional
compiler flags used to build source files.  Use
COMPILE_DEFINITIONS to pass additional preprocessor definitions.

Contents of ‘COMPILE_FLAGS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  However, see Xcode does not
support per-config per-source settings, so expressions that depend on
the build configuration are not allowed with that generator.

     Note: This property has been superseded by the
     COMPILE_OPTIONS property.

19.5.6 COMPILE_OPTIONS
----------------------

New in version 3.11.

List of additional options to pass to the compiler.

This property holds a semicolon-separated list of options and
will be added to the list of compile flags when this source file builds.

Contents of ‘COMPILE_OPTIONS’ may use “generator expressions” with the
syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  However, see Xcode does not
support per-config per-source settings, so expressions that depend on
the build configuration are not allowed with that generator.

Usage example:

     set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer")

Related properties:

   * Prefer this property over COMPILE_FLAGS.

   * Use COMPILE_DEFINITIONS to pass additional preprocessor
     definitions.

   * Use INCLUDE_DIRECTORIES to pass additional include
     directories.

Related commands:

   * add_compile_options() for directory-wide settings

   * target_compile_options() for target-specific settings

19.5.7 EXTERNAL_OBJECT
----------------------

If set to true then this is an object file.

If this property is set to ‘True’ then the source file is really an
object file and should not be compiled.  It will still be linked into
the target though.

19.5.8 Fortran_FORMAT
---------------------

Set to ‘FIXED’ or ‘FREE’ to indicate the Fortran source layout.

This property tells CMake whether a given Fortran source file uses
fixed-format or free-format.  CMake will pass the corresponding format
flag to the compiler.  Consider using the target-wide
Fortran_FORMAT property if all source files in a target share the
same format.

     Note: For some compilers, ‘NAG’, ‘PGI’ and ‘Solaris Studio’,
     setting this to ‘OFF’ will have no effect.

19.5.9 Fortran_PREPROCESS
-------------------------

New in version 3.18.

Control whether the Fortran source file should be unconditionally
preprocessed.

If unset or empty, rely on the compiler to determine whether the file
should be preprocessed.  If explicitly set to ‘OFF’ then the file does
not need to be preprocessed.  If explicitly set to ‘ON’, then the file
does need to be preprocessed as part of the compilation step.

When using the Ninja generator, all source files are first
preprocessed in order to generate module dependency information.
Setting this property to ‘OFF’ will make ‘Ninja’ skip this step.

Consider using the target-wide Fortran_PREPROCESS property
if all source files in a target need to be preprocessed.

19.5.10 GENERATED
-----------------

Is this source file generated as part of the build or CMake process.

Tells the internal CMake engine that a source file is generated by an
outside process such as another build step, or the execution of CMake
itself.  This information is then used to exempt the file from any
existence or validity checks.

Any file that is

   - created by the execution of commands such as
     add_custom_command() and file(GENERATE).

   - listed as one of the ‘BYPRODUCTS’ of an add_custom_command()
     or add_custom_target() command, or

   - created by a CMake ‘AUTOGEN’ operation such as AUTOMOC,
     AUTORCC, or AUTOUIC.

will be marked with the ‘GENERATED’ property.

When a generated file created as the ‘OUTPUT’ of an
add_custom_command() command is explicitly listed as a source file
for any target in the same directory scope (which usually means the same
‘CMakeLists.txt’ file), CMake will automatically create a dependency to
make sure the file is generated before building that target.

The Makefile Generators will remove ‘GENERATED’ files during
‘make clean’.

Generated sources may be hidden in some IDE tools, while in others they
might be shown.  For the special case of sources generated by CMake’s
AUTOMOC or AUTORCC functionality, the
AUTOGEN_SOURCE_GROUP, AUTOMOC_SOURCE_GROUP and
AUTORCC_SOURCE_GROUP target properties may influence where the
generated sources are grouped in the project’s file lists.

19.5.11 HEADER_FILE_ONLY
------------------------

Is this source file only a header file.

A property on a source file that indicates if the source file is a
header file with no associated implementation.  This is set
automatically based on the file extension and is used by CMake to
determine if certain dependency information should be computed.

By setting this property to ‘ON’, you can disable compilation of the
given source file, even if it should be compiled because it is part of
the library’s/executable’s sources.

This is useful if you have some source files which you somehow
pre-process, and then add these pre-processed sources via
add_library() or add_executable().  Normally, in IDE,
there would be no reference of the original sources, only of these
pre-processed sources.  So by setting this property for all the original
source files to ‘ON’, and then either calling add_library().
or add_executable() while passing both the pre-processed
sources and the original sources, or by using target_sources()
to add original source files will do exactly what would one expect,
i.e.  the original source files would be visible in IDE, and will not be
built.

19.5.12 INCLUDE_DIRECTORIES
---------------------------

New in version 3.11.

List of preprocessor include file search directories.

This property holds a semicolon-separated list of paths and
will be added to the list of include directories when this source file
builds.  These directories will take precedence over directories defined
at target level except for Xcode generator due to technical
limitations.

Relative paths should not be added to this property directly.

Contents of ‘INCLUDE_DIRECTORIES’ may use “generator expressions” with
the syntax ‘$<...>’.  See the cmake-generator-expressions(7).
manual for available expressions.  However, see Xcode does not
support per-config per-source settings, so expressions that depend on
the build configuration are not allowed with that generator.

19.5.13 KEEP_EXTENSION
----------------------

Make the output file have the same extension as the source file.

If this property is set then the file extension of the output file will
be the same as that of the source file.  Normally the output file
extension is computed based on the language of the source file, for
example ‘.cxx’ will go to a ‘.o’ extension.

19.5.14 LABELS
--------------

Specify a list of text labels associated with a source file.

This property has meaning only when the source file is listed in a
target whose ‘LABELS’ property is also set.  No other semantics are
currently specified.

19.5.15 LANGUAGE
----------------

What programming language is the file.

A property that can be set to indicate what programming language the
source file is.  If it is not set the language is determined based on
the file extension.  Typical values are ‘CXX’ (i.e.  C++), ‘C’,
‘CSharp’, ‘CUDA’, ‘Fortran’, ‘ISPC’, and ‘ASM’.  Setting this property
for a file means this file will be compiled.  Do not set this for
headers or files that should not be compiled.

19.5.16 LOCATION
----------------

The full path to a source file.

A read only property on a SOURCE FILE that contains the full path to the
source file.

19.5.17 MACOSX_PACKAGE_LOCATION
-------------------------------

Place a source file inside a Application Bundle ( see MACOSX_BUNDLE),
Core Foundation Bundle ( see BUNDLE), or Framework Bundle
( see FRAMEWORK).  It is applicable for macOS and iOS.

Executable targets with the MACOSX_BUNDLE property set are
built as macOS or iOS application bundles on Apple platforms.  Shared
library targets with the FRAMEWORK property set are built as
macOS or iOS frameworks on Apple platforms.  Module library targets with
the BUNDLE property set are built as macOS ‘CFBundle’
bundles on Apple platforms.  Source files listed in the target with this
property set will be copied to a directory inside the bundle or
framework content folder specified by the property value.  For macOS
Application Bundles the content folder is ‘<name>.app/Contents’.  For
macOS Frameworks the content folder is
‘<name>.framework/Versions/<version>’.  For macOS CFBundles the content
folder is ‘<name>.bundle/Contents’ (unless the extension is changed).
See the PUBLIC_HEADER, PRIVATE_HEADER, and
RESOURCE target properties for specifying files meant for
‘Headers’, ‘PrivateHeaders’, or ‘Resources’ directories.

If the specified location is equal to ‘Resources’, the resulting
location will be the same as if the RESOURCE property had
been used.  If the specified location is a sub-folder of ‘Resources’, it
will be placed into the respective sub-folder.  Note: For iOS Apple uses
a flat bundle layout where no ‘Resources’ folder exist.  Therefore CMake
strips the ‘Resources’ folder name from the specified location.

19.5.18 OBJECT_DEPENDS
----------------------

Additional files on which a compiled object file depends.

Specifies a semicolon-separated list of full-paths to files
on which any object files compiled from this source file depend.  On
Makefile Generators and the Ninja generator an
object file will be recompiled if any of the named files is newer than
it.  Visual Studio Generators and the Xcode.
generator cannot implement such compilation dependencies.

This property need not be used to specify the dependency of a source
file on a generated header file that it includes.  Although the property
was originally introduced for this purpose, it is no longer necessary.
If the generated header file is created by a custom command in the same
target as the source file, the automatic dependency scanning process
will recognize the dependency.  If the generated header file is created
by another target, an inter-target dependency should be created with the
add_dependencies() command (if one does not already exist
due to linking relationships).

19.5.19 OBJECT_OUTPUTS
----------------------

Additional outputs for a Ninja or Makefile Generators
rule.

Additional outputs created by compilation of this source file.  If any
of these outputs is missing the object will be recompiled.  This is
supported only on the Ninja and Makefile Generators
and will be ignored on other generators.

This property supports generator expressions.

19.5.20 SKIP_AUTOGEN
--------------------

New in version 3.8.

Exclude the source file from AUTOMOC, AUTOUIC and
AUTORCC processing (for Qt projects).

For finer exclusion control see SKIP_AUTOMOC,
SKIP_AUTOUIC and SKIP_AUTORCC.

19.5.20.1 EXAMPLE
.................

     # ...
     set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
     # ...

19.5.21 SKIP_AUTOMOC
--------------------

New in version 3.8.

Exclude the source file from AUTOMOC processing (for Qt
projects).

For broader exclusion control see SKIP_AUTOGEN.

19.5.21.1 EXAMPLE
.................

     # ...
     set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
     # ...

19.5.22 SKIP_AUTORCC
--------------------

New in version 3.8.

Exclude the source file from AUTORCC processing (for Qt
projects).

For broader exclusion control see SKIP_AUTOGEN.

19.5.22.1 EXAMPLE
.................

     # ...
     set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
     # ...

19.5.23 SKIP_AUTOUIC
--------------------

New in version 3.8.

Exclude the source file from AUTOUIC processing (for Qt
projects).

SKIP_AUTOUIC can be set on C++ header and source files and
on ‘.ui’ files.

For broader exclusion control see SKIP_AUTOGEN.

19.5.23.1 EXAMPLE
.................

     # ...
     set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
     set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON)
     set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON)
     # ...

19.5.24 SKIP_PRECOMPILE_HEADERS
-------------------------------

New in version 3.16.

Is this source file skipped by PRECOMPILE_HEADERS feature.

This property helps with build problems that one would run into when
using the PRECOMPILE_HEADERS feature.

One example would be the usage of Objective-C (‘*.m’) files, and
Objective-C++ (‘*.mm’) files, which lead to compilation failure because
they are treated (in case of Ninja / Makefile generator) as C, and CXX
respectively.  The precompile headers are not compatible between
languages.

19.5.25 SKIP_UNITY_BUILD_INCLUSION
----------------------------------

New in version 3.16.

Setting this property to true ensures the source file will be skipped by
unity builds when its associated target has its UNITY_BUILD.
property set to true.  The source file will instead be compiled on its
own in the same way as it would with unity builds disabled.

This property helps with “ODR (One definition rule)” problems where
combining a particular source file with others might lead to build
errors or other unintended side effects.

19.5.26 Swift_DEPENDENCIES_FILE
-------------------------------

New in version 3.15.

This property sets the path for the Swift dependency file (swiftdeps)
for the source.  If one is not specified, it will default to
‘<OBJECT>.swiftdeps’.

19.5.27 Swift_DIAGNOSTICS_FILE
------------------------------

New in version 3.15.

This property controls where the Swift diagnostics are serialized.

19.5.28 SYMBOLIC
----------------

Is this just a name for a rule.

If ‘SYMBOLIC’ (boolean) is set to ‘True’ the build system will be
informed that the source file is not actually created on disk but
instead used as a symbolic name for a build rule.

19.5.29 UNITY_GROUP
-------------------

New in version 3.18.

This property controls which `bucket' the source will be part of when
the UNITY_BUILD_MODE is set to ‘GROUP’.

19.5.30 VS_COPY_TO_OUT_DIR
--------------------------

New in version 3.8.

Sets the ‘<CopyToOutputDirectory>’ tag for a source file in a Visual
Studio project file.  Valid values are ‘Never’, ‘Always’ and
‘PreserveNewest’.

19.5.31 VS_CSHARP_<tagname>
---------------------------

New in version 3.8.

Visual Studio and CSharp source-file-specific configuration.

Tell the Visual Studio generators to set the source file tag
‘<tagname>’ to a given value in the generated Visual Studio CSharp
project.  Ignored on other generators and languages.  This property can
be used to define dependencies between source files or set any other
Visual Studio specific parameters.

Example usage:

     set_source_files_property(<filename>
              PROPERTIES
              VS_CSHARP_DependentUpon <other file>
              VS_CSHARP_SubType "Form")

19.5.32 VS_DEPLOYMENT_CONTENT
-----------------------------

New in version 3.1.

Mark a source file as content for deployment with a Windows Phone or
Windows Store application when built with a Visual Studio generators.
The value must evaluate to either ‘1’ or ‘0’ and may
use generator expressions to make the choice based on the
build configuration.  The ‘.vcxproj’ file entry for the source file will
be marked either ‘DeploymentContent’ or ‘ExcludedFromBuild’ for values
‘1’ and ‘0’, respectively.

19.5.33 VS_DEPLOYMENT_LOCATION
------------------------------

New in version 3.1.

Specifies the deployment location for a content source file with a
Windows Phone or Windows Store application when built with a
Visual Studio generators.  This property is only applicable when
using VS_DEPLOYMENT_CONTENT.  The value represent the path
relative to the app package and applies to all configurations.

19.5.34 VS_INCLUDE_IN_VSIX
--------------------------

New in version 3.8.

Boolean property to specify if the file should be included within a VSIX
(Visual Studio Integration Extension) extension package.  This is needed
for development of Visual Studio extensions.

19.5.35 VS_RESOURCE_GENERATOR
-----------------------------

New in version 3.8.

This property allows to specify the resource generator to be used on
this file.  It defaults to ‘PublicResXFileCodeGenerator’ if not set.

This property only applies to C# projects.

19.5.36 VS_SETTINGS
-------------------

New in version 3.18.

Set any item metadata on a non-built file.

Takes a list of ‘Key=Value’ pairs.  Tells the Visual Studio generator to
set ‘Key’ to ‘Value’ as item metadata on the file.

For example:

     set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2")

will set ‘Key’ to ‘Value’ and ‘Key2’ to ‘Value2’ on the ‘file.hlsl’ item
as metadata.

Generator expressions are supported.

19.5.37 VS_SHADER_DISABLE_OPTIMIZATIONS
---------------------------------------

New in version 3.11.

Disable compiler optimizations for an ‘.hlsl’ source file.  This adds
the ‘-Od’ flag to the command line for the FxCompiler tool.  Specify the
value ‘true’ for this property to disable compiler optimizations.

19.5.38 VS_SHADER_ENABLE_DEBUG
------------------------------

New in version 3.11.

Enable debugging information for an ‘.hlsl’ source file.  This adds the
‘-Zi’ flag to the command line for the FxCompiler tool.  Specify the
value ‘true’ to generate debugging information for the compiled shader.

19.5.39 VS_SHADER_ENTRYPOINT
----------------------------

New in version 3.1.

Specifies the name of the entry point for the shader of a ‘.hlsl’ source
file.

19.5.40 VS_SHADER_FLAGS
-----------------------

New in version 3.2.

Set additional Visual Studio shader flags of a ‘.hlsl’ source file.

19.5.41 VS_SHADER_MODEL
-----------------------

New in version 3.1.

Specifies the shader model of a ‘.hlsl’ source file.  Some shader types
can only be used with recent shader models

19.5.42 VS_SHADER_OBJECT_FILE_NAME
----------------------------------

New in version 3.12.

Specifies a file name for the compiled shader object file for an ‘.hlsl’
source file.  This adds the ‘-Fo’ flag to the command line for the
FxCompiler tool.

19.5.43 VS_SHADER_OUTPUT_HEADER_FILE
------------------------------------

New in version 3.10.

Set filename for output header file containing object code of a ‘.hlsl’
source file.

19.5.44 VS_SHADER_TYPE
----------------------

New in version 3.1.

Set the Visual Studio shader type of a ‘.hlsl’ source file.

19.5.45 VS_SHADER_VARIABLE_NAME
-------------------------------

New in version 3.10.

Set name of variable in header file containing object code of a ‘.hlsl’
source file.

19.5.46 VS_TOOL_OVERRIDE
------------------------

New in version 3.7.

Override the default Visual Studio tool that will be applied to the
source file with a new tool not based on the extension of the file.

19.5.47 VS_XAML_TYPE
--------------------

New in version 3.3.

Mark a Extensible Application Markup Language (XAML) source file as a
different type than the default ‘Page’.  The most common usage would be
to set the default ‘App.xaml’ file as ‘ApplicationDefinition’.

19.5.48 WRAP_EXCLUDE
--------------------

Exclude this source file from any code wrapping techniques.

Some packages can wrap source files into alternate languages to provide
additional functionality.

For example, C++ code can be wrapped into Java or Python, using SWIG. If
‘WRAP_EXCLUDE’ is set to ‘True’, that indicates that this source file
should not be wrapped.

19.5.49 XCODE_EXPLICIT_FILE_TYPE
--------------------------------

New in version 3.1.

Set the Xcode. ‘explicitFileType’ attribute on its reference
to a source file.  CMake computes a default based on file extension but
can be told explicitly with this property.

See also XCODE_LAST_KNOWN_FILE_TYPE.

19.5.50 XCODE_FILE_ATTRIBUTES
-----------------------------

New in version 3.7.

Add values to the Xcode. ‘ATTRIBUTES’ setting on its
reference to a source file.  Among other things, this can be used to set
the role on a ‘.mig’ file:

     set_source_files_properties(defs.mig
         PROPERTIES
             XCODE_FILE_ATTRIBUTES "Client;Server"
     )

19.5.51 XCODE_LAST_KNOWN_FILE_TYPE
----------------------------------

New in version 3.1.

Set the Xcode. ‘lastKnownFileType’ attribute on its reference
to a source file.  CMake computes a default based on file extension but
can be told explicitly with this property.

See also XCODE_EXPLICIT_FILE_TYPE, which is preferred over
this property if set.

19.6 Properties on Cache Entries
================================

19.6.1 ADVANCED
---------------

True if entry should be hidden by default in GUIs.

This is a boolean value indicating whether the entry is considered
interesting only for advanced configuration.  The
mark_as_advanced() command modifies this property.

19.6.2 HELPSTRING
-----------------

Help associated with entry in GUIs.

This string summarizes the purpose of an entry to help users set it
through a CMake GUI.

19.6.3 MODIFIED
---------------

Internal management property.  Do not set or get.

This is an internal cache entry property managed by CMake to track
interactive user modification of entries.  Ignore it.

19.6.4 STRINGS
--------------

Enumerate possible ‘STRING’ entry values for GUI selection.

For cache entries with type ‘STRING’, this enumerates a set of values.
CMake GUIs may use this to provide a selection widget instead of a
generic string entry field.  This is for convenience only.  CMake does
not enforce that the value matches one of those listed.

19.6.5 TYPE
-----------

Widget type for entry in GUIs.

Cache entry values are always strings, but CMake GUIs present widgets to
help users set values.  The GUIs use this property as a hint to
determine the widget type.  Valid ‘TYPE’ values are:

     BOOL          = Boolean ON/OFF value.
     PATH          = Path to a directory.
     FILEPATH      = Path to a file.
     STRING        = Generic string value.
     INTERNAL      = Do not present in GUI at all.
     STATIC        = Value managed by CMake, do not change.
     UNINITIALIZED = Type not yet specified.

Generally the ‘TYPE’ of a cache entry should be set by the command which
creates it ( see set(), option(), find_library(),
etc.).

19.6.6 VALUE
------------

Value of a cache entry.

This property maps to the actual value of a cache entry.  Setting this
property always sets the value without checking, so use with care.

19.7 Properties on Installed Files
==================================

19.7.1 CPACK_DESKTOP_SHORTCUTS
------------------------------

New in version 3.3.

Species a list of shortcut names that should be created on the ‘Desktop’
for this file.

The property is currently only supported by the CPack WIX Generator.

19.7.2 CPACK_NEVER_OVERWRITE
----------------------------

New in version 3.1.

Request that this file not be overwritten on install or reinstall.

The property is currently only supported by the CPack WIX Generator.

19.7.3 CPACK_PERMANENT
----------------------

New in version 3.1.

Request that this file not be removed on uninstall.

The property is currently only supported by the CPack WIX Generator.

19.7.4 CPACK_START_MENU_SHORTCUTS
---------------------------------

New in version 3.3.

Species a list of shortcut names that should be created in the ‘Start
Menu’ for this file.

The property is currently only supported by the CPack WIX Generator.

19.7.5 CPACK_STARTUP_SHORTCUTS
------------------------------

New in version 3.3.

Species a list of shortcut names that should be created in the ‘Startup’
folder for this file.

The property is currently only supported by the CPack WIX Generator.

19.7.6 CPACK_WIX_ACL
--------------------

New in version 3.1.

Specifies access permissions for files or directories installed by a WiX
installer.

The property can contain multiple list entries, each of which has to
match the following format.

     <user>[@<domain>]=<permission>[,<permission>]

‘<user>’ and ‘<domain>’ specify the windows user and domain for which
the ‘<Permission>’ element should be generated.

‘<permission>’ is any of the YesNoType attributes listed here:

     http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html

The property is currently only supported by the CPack WIX Generator.

19.8 Deprecated Properties on Directories
=========================================

19.8.1 ADDITIONAL_MAKE_CLEAN_FILES
----------------------------------

Deprecated since version 3.15: Use ADDITIONAL_CLEAN_FILES.
instead.

Additional files to remove during the clean stage.

A ;-list of files that will be removed as a part of the ‘make
clean’ target.

Arguments to ADDITIONAL_MAKE_CLEAN_FILES may use
generator expressions.

This property only works for the Makefile generators.  It is ignored on
other generators.

19.8.2 COMPILE_DEFINITIONS_<CONFIG>
-----------------------------------

Ignored.  See CMake Policy CMP0043.

Per-configuration preprocessor definitions in a directory.

This is the configuration-specific version of COMPILE_DEFINITIONS
where ‘<CONFIG>’ is an upper-case name (ex.
‘COMPILE_DEFINITIONS_DEBUG’).

This property will be initialized in each directory by its value in the
directory’s parent.

Contents of ‘COMPILE_DEFINITIONS_<CONFIG>’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

Generator expressions should be preferred instead of setting this
property.

19.8.3 TEST_INCLUDE_FILE
------------------------

Deprecated.  Use TEST_INCLUDE_FILES instead.

A cmake file that will be included when ctest is run.

If you specify ‘TEST_INCLUDE_FILE’, that file will be included and
processed when ctest is run on the directory.

19.9 Deprecated Properties on Targets
=====================================

19.9.1 COMPILE_DEFINITIONS_<CONFIG>
-----------------------------------

Ignored.  See CMake Policy CMP0043.

Per-configuration preprocessor definitions on a target.

This is the configuration-specific version of COMPILE_DEFINITIONS
where ‘<CONFIG>’ is an upper-case name (ex.
‘COMPILE_DEFINITIONS_DEBUG’).

Contents of ‘COMPILE_DEFINITIONS_<CONFIG>’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

Generator expressions should be preferred instead of setting this
property.

19.9.2 POST_INSTALL_SCRIPT
--------------------------

Deprecated install support.

The PRE_INSTALL_SCRIPT and ‘POST_INSTALL_SCRIPT’ properties
are the old way to specify CMake scripts to run before and after
installing a target.  They are used only when the old ‘INSTALL_TARGETS’
command is used to install the target.  Use the install().
command instead.

19.9.3 PRE_INSTALL_SCRIPT
-------------------------

Deprecated install support.

The ‘PRE_INSTALL_SCRIPT’ and POST_INSTALL_SCRIPT properties
are the old way to specify CMake scripts to run before and after
installing a target.  They are used only when the old ‘INSTALL_TARGETS’
command is used to install the target.  Use the install().
command instead.

19.10 Deprecated Properties on Source Files
===========================================

19.10.1 COMPILE_DEFINITIONS_<CONFIG>
------------------------------------

Ignored.  See CMake Policy CMP0043.

Per-configuration preprocessor definitions on a source file.

This is the configuration-specific version of COMPILE_DEFINITIONS.
Note that Xcode does not support per-configuration
source file flags so this property will be ignored by the Xcode
generator.

20 cmake-qt(7)
**************

20.1 Introduction
=================

CMake can find and use Qt 4 and Qt 5 libraries.  The Qt 4 libraries are
found by the FindQt4 find-module shipped with CMake, whereas
the Qt 5 libraries are found using “Config-file Packages” shipped with
Qt 5.  See cmake-packages(7) for more information about CMake
packages, and see the Qt cmake manual(1) for your Qt version.

Qt 4 and Qt 5 may be used together in the same CMake buildsystem.:

     cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)

     project(Qt4And5)

     set(CMAKE_AUTOMOC ON)

     find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
     add_executable(publisher publisher.cpp)
     target_link_libraries(publisher Qt5::Widgets Qt5::DBus)

     find_package(Qt4 REQUIRED)
     add_executable(subscriber subscriber.cpp)
     target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)

A CMake target may not link to both Qt 4 and Qt 5.  A diagnostic is
issued if this is attempted or results from transitive target dependency
evaluation.

   ---------- Footnotes ----------

   (1) http://qt-project.org/doc/qt-5/cmake-manual.html

20.2 Qt Build Tools
===================

Qt relies on some bundled tools for code generation, such as ‘moc’ for
meta-object code generation, ‘uic’ for widget layout and population, and
‘rcc’ for virtual file system content generation.  These tools may be
automatically invoked by cmake(1) if the appropriate
conditions are met.  The automatic tool invocation may be used with both
Qt 4 and Qt 5.

20.2.1 AUTOMOC
--------------

The AUTOMOC target property controls whether cmake(1)
inspects the C++ files in the target to determine if they require
‘moc’ to be run, and to create rules to execute ‘moc’ at the appropriate
time.

If a macro from AUTOMOC_MACRO_NAMES is found in a header
file, ‘moc’ will be run on the file.  The result will be put into a file
named according to ‘moc_<basename>.cpp’.  If the macro is found in a C++
implementation file, the moc output will be put into a file named
according to ‘<basename>.moc’, following the Qt conventions.  The
‘<basename>.moc’ must be included by the user in the C++ implementation
file with a preprocessor ‘#include’.

Included ‘moc_*.cpp’ and ‘*.moc’ files will be generated in the
‘<AUTOGEN_BUILD_DIR>/include’ directory which is automatically added to
the target’s INCLUDE_DIRECTORIES.

   * This differs from CMake 3.7 and below; see their documentation for
     details.

   * For multi configuration generators, the include
     directory is ‘<AUTOGEN_BUILD_DIR>/include_<CONFIG>’.

   * See AUTOGEN_BUILD_DIR.

Not included ‘moc_<basename>.cpp’ files will be generated in custom
folders to avoid name collisions and included in a separate
‘<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp’ file which is compiled into
the target.

   * See AUTOGEN_BUILD_DIR.

The ‘moc’ command line will consume the COMPILE_DEFINITIONS.
and INCLUDE_DIRECTORIES target properties from the target it
is being invoked for, and for the appropriate build configuration.

The AUTOMOC target property may be pre-set for all following
targets by setting the CMAKE_AUTOMOC variable.  The
AUTOMOC_MOC_OPTIONS target property may be populated to set
options to pass to ‘moc’.  The CMAKE_AUTOMOC_MOC_OPTIONS.
variable may be populated to pre-set the options for all following
targets.

Additional macro names to search for can be added to
AUTOMOC_MACRO_NAMES.

Additional ‘moc’ dependency file names can be extracted from source code
by using AUTOMOC_DEPEND_FILTERS.

Source C++ files can be excluded from AUTOMOC processing by
enabling SKIP_AUTOMOC or the broader SKIP_AUTOGEN.

20.2.2 AUTOUIC
--------------

The AUTOUIC target property controls whether cmake(1)
inspects the C++ files in the target to determine if they require
‘uic’ to be run, and to create rules to execute ‘uic’ at the appropriate
time.

If a preprocessor ‘#include’ directive is found which matches
‘<path>ui_<basename>.h’, and a ‘<basename>.ui’ file exists, then ‘uic’
will be executed to generate the appropriate file.  The ‘<basename>.ui’
file is searched for in the following places

  1. ‘<source_dir>/<basename>.ui’

  2. ‘<source_dir>/<path><basename>.ui’

  3. ‘<AUTOUIC_SEARCH_PATHS>/<basename>.ui’

  4. ‘<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui’

where ‘<source_dir>’ is the directory of the C++ file and
AUTOUIC_SEARCH_PATHS is a list of additional search paths.

The generated generated ‘ui_*.h’ files are placed in the
‘<AUTOGEN_BUILD_DIR>/include’ directory which is automatically added to
the target’s INCLUDE_DIRECTORIES.

   * This differs from CMake 3.7 and below; see their documentation for
     details.

   * For multi configuration generators, the include
     directory is ‘<AUTOGEN_BUILD_DIR>/include_<CONFIG>’.

   * See AUTOGEN_BUILD_DIR.

The AUTOUIC target property may be pre-set for all following
targets by setting the CMAKE_AUTOUIC variable.  The
AUTOUIC_OPTIONS target property may be populated to set options to
pass to ‘uic’.  The CMAKE_AUTOUIC_OPTIONS variable may be
populated to pre-set the options for all following targets.  The
AUTOUIC_OPTIONS source file property may be set on the
‘<basename>.ui’ file to set particular options for the file.  This
overrides options from the AUTOUIC_OPTIONS target property.

A target may populate the INTERFACE_AUTOUIC_OPTIONS target
property with options that should be used when invoking ‘uic’.  This
must be consistent with the AUTOUIC_OPTIONS target property
content of the depender target.  The
CMAKE_DEBUG_TARGET_PROPERTIES variable may be used to track the
origin target of such INTERFACE_AUTOUIC_OPTIONS.  This means
that a library which provides an alternative translation system for Qt
may specify options which should be used when running ‘uic’:

     add_library(KI18n klocalizedstring.cpp)
     target_link_libraries(KI18n Qt5::Core)

     # KI18n uses the tr2i18n() function instead of tr().  That function is
     # declared in the klocalizedstring.h header.
     set(autouic_options
       -tr tr2i18n
       -include klocalizedstring.h
     )

     set_property(TARGET KI18n APPEND PROPERTY
       INTERFACE_AUTOUIC_OPTIONS ${autouic_options}
     )

A consuming project linking to the target exported from upstream
automatically uses appropriate options when ‘uic’ is run by
AUTOUIC, as a result of linking with the IMPORTED.
target:

     set(CMAKE_AUTOUIC ON)
     # Uses a libwidget.ui file:
     add_library(LibWidget libwidget.cpp)
     target_link_libraries(LibWidget
       KF5::KI18n
       Qt5::Widgets
     )

Source files can be excluded from AUTOUIC processing by
enabling SKIP_AUTOUIC or the broader SKIP_AUTOGEN.

20.2.3 AUTORCC
--------------

The AUTORCC target property controls whether cmake(1)
creates rules to execute ‘rcc’ at the appropriate time on source
files which have the suffix ‘.qrc’.

     add_executable(myexe main.cpp resource_file.qrc)

The AUTORCC target property may be pre-set for all following
targets by setting the CMAKE_AUTORCC variable.  The
AUTORCC_OPTIONS target property may be populated to set options to
pass to ‘rcc’.  The CMAKE_AUTORCC_OPTIONS variable may be
populated to pre-set the options for all following targets.  The
AUTORCC_OPTIONS source file property may be set on the
‘<name>.qrc’ file to set particular options for the file.  This
overrides options from the AUTORCC_OPTIONS target property.

Source files can be excluded from AUTORCC processing by
enabling SKIP_AUTORCC or the broader SKIP_AUTOGEN.

20.3 The ‘<ORIGIN>_autogen’ target
==================================

The ‘moc’ and ‘uic’ tools are executed as part of a synthesized
‘<ORIGIN>_autogen’ custom target generated by CMake.  By
default that ‘<ORIGIN>_autogen’ target inherits the dependencies of the
‘<ORIGIN>’ target (see AUTOGEN_ORIGIN_DEPENDS).  Target
dependencies may be added to the ‘<ORIGIN>_autogen’ target by adding
them to the AUTOGEN_TARGET_DEPENDS target property.

20.4 Visual Studio Generators
=============================

When using the Visual Studio generators, CMake generates a
‘PRE_BUILD’ custom command instead of the ‘<ORIGIN>_autogen’
custom target. (for AUTOMOC and AUTOUIC).
This isn’t always possible though and an ‘<ORIGIN>_autogen’
custom target is used, when either

   - the ‘<ORIGIN>’ target depends on GENERATED files which
     aren’t excluded from AUTOMOC and AUTOUIC by
     SKIP_AUTOMOC, SKIP_AUTOUIC,
     SKIP_AUTOGEN or CMP0071.

   - AUTOGEN_TARGET_DEPENDS lists a source file

   - CMAKE_GLOBAL_AUTOGEN_TARGET is enabled

20.5 qtmain.lib on Windows
==========================

The Qt 4 and 5 IMPORTED targets for the QtGui libraries
specify that the qtmain.lib static library shipped with Qt will be
linked by all dependent executables which have the
WIN32_EXECUTABLE enabled.

To disable this behavior, enable the ‘Qt5_NO_LINK_QTMAIN’ target
property for Qt 5 based targets or ‘QT4_NO_LINK_QTMAIN’ target property
for Qt 4 based targets.

     add_executable(myexe WIN32 main.cpp)
     target_link_libraries(myexe Qt4::QtGui)

     add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp)
     set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON)
     target_link_libraries(main_no_qtmain Qt4::QtGui)

21 cmake-server(7)
******************

Deprecated since version 3.15: This will be removed from a future
version of CMake.  Clients should use the cmake-file-api(7).
instead.

21.1 Introduction
=================

cmake(1) is capable of providing semantic information about
CMake code it executes to generate a buildsystem.  If executed with the
‘-E server’ command line options, it starts in a long running mode and
allows a client to request the available information via a JSON
protocol.

The protocol is designed to be useful to IDEs, refactoring tools, and
other tools which have a need to understand the buildsystem in entirety.

A single cmake-buildsystem(7) may describe buildsystem
contents and build properties which differ based on
generation-time context including:

   * The Platform (eg, Windows, APPLE, Linux).

   * The build configuration (eg, Debug, Release, Coverage).

   * The Compiler (eg, MSVC, GCC, Clang) and compiler version.

   * The language of the source files compiled.

   * Available compile features (eg CXX variadic templates).

   * CMake policies.

The protocol aims to provide information to tooling to satisfy several
needs:

  1. Provide a complete and easily parsed source of all information
     relevant to the tooling as it relates to the source code.  There
     should be no need for tooling to parse generated buildsystems to
     access include directories or compile definitions for example.

  2. Semantic information about the CMake buildsystem itself.

  3. Provide a stable interface for reading the information in the CMake
     cache.

  4. Information for determining when cmake needs to be re-run as a
     result of file changes.

21.2 Operation
==============

Start cmake(1) in the server command mode, supplying the path
to the build directory to process:

     cmake -E server (--debug|--pipe=<NAMED_PIPE>)

The server will communicate using stdin/stdout (with the ‘--debug’
parameter) or using a named pipe (with the ‘--pipe=<NAMED_PIPE>’
parameter).  Note that “named pipe” refers to a local domain socket on
Unix and to a named pipe on Windows.

When connecting to the server (via named pipe or by starting it in
‘--debug’ mode), the server will reply with a hello message:

     [== "CMake Server" ==[
     {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
     ]== "CMake Server" ==]

Messages sent to and from the process are wrapped in magic strings:

     [== "CMake Server" ==[
     {
       ... some JSON message ...
     }
     ]== "CMake Server" ==]

The server is now ready to accept further requests via the named pipe or
stdin.

21.3 Debugging
==============

CMake server mode can be asked to provide statistics on execution times,
etc.  or to dump a copy of the response into a file.  This is done
passing a “debug” JSON object as a child of the request.

The debug object supports the “showStats” key, which takes a boolean and
makes the server mode return a “zzzDebug” object with stats as part of
its response.  “dumpToFile” takes a string value and will cause the
cmake server to copy the response into the given filename.

This is a response from the cmake server with “showStats” set to true:

     [== "CMake Server" ==[
     {
       "cookie":"",
       "errorMessage":"Waiting for type \"handshake\".",
       "inReplyTo":"unknown",
      "type":"error",
       "zzzDebug": {
         "dumpFile":"/tmp/error.txt",
         "jsonSerialization":0.011016,
         "size":111,
         "totalTime":0.025995
       }
     }
     ]== "CMake Server" ==]

The server has made a copy of this response into the file /tmp/error.txt
and took 0.011 seconds to turn the JSON response into a string, and it
took 0.025 seconds to process the request in total.  The reply has a
size of 111 bytes.

21.4 Protocol API
=================

21.4.1 General Message Layout
-----------------------------

All messages need to have a “type” value, which identifies the type of
message that is passed back or forth.  E.g.  the initial message sent by
the server is of type “hello”.  Messages without a type will generate an
response of type “error”.

All requests sent to the server may contain a “cookie” value.  This
value will he handed back unchanged in all responses triggered by the
request.

All responses will contain a value “inReplyTo”, which may be empty in
case of parse errors, but will contain the type of the request message
in all other cases.

21.4.1.1 Type “reply”
.....................

This type is used by the server to reply to requests.

The message may – depending on the type of the original request –
contain values.

Example:

     [== "CMake Server" ==[
     {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
     ]== "CMake Server" ==]

21.4.1.2 Type “error”
.....................

This type is used to return an error condition to the client.  It will
contain an “errorMessage”.

Example:

     [== "CMake Server" ==[
     {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
     ]== "CMake Server" ==]

21.4.1.3 Type “progress”
........................

When the server is busy for a long time, it is polite to send back
replies of type “progress” to the client.  These will contain a
“progressMessage” with a string describing the action currently taking
place as well as “progressMinimum”, “progressMaximum” and
“progressCurrent” with integer values describing the range of progress.

Messages of type “progress” will be followed by more “progress” messages
or with a message of type “reply” or “error” that complete the request.

“progress” messages may not be emitted after the “reply” or “error”
message for the request that triggered the responses was delivered.

21.4.1.4 Type “message”
.......................

A message is triggered when the server processes a request and produces
some form of output that should be displayed to the user.  A Message has
a “message” with the actual text to display as well as a “title” with a
suggested dialog box title.

Example:

     [== "CMake Server" ==[
     {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
     ]== "CMake Server" ==]

21.4.1.5 Type “signal”
......................

The server can send signals when it detects changes in the system state.
Signals are of type “signal”, have an empty “cookie” and “inReplyTo”
field and always have a “name” set to show which signal was sent.

21.4.2 Specific Signals
-----------------------

The cmake server may sent signals with the following names:

21.4.2.1 “dirty” Signal
.......................

The “dirty” signal is sent whenever the server determines that the
configuration of the project is no longer up-to-date.  This happens when
any of the files that have an influence on the build system is changed.

The “dirty” signal may look like this:

     [== "CMake Server" ==[
     {
       "cookie":"",
       "inReplyTo":"",
       "name":"dirty",
       "type":"signal"}
     ]== "CMake Server" ==]

21.4.2.2 “fileChange” Signal
............................

The “fileChange” signal is sent whenever a watched file is changed.  It
contains the “path” that has changed and a list of “properties” with the
kind of change that was detected.  Possible changes are “change” and
“rename”.

The “fileChange” signal looks like this:

     [== "CMake Server" ==[
     {
       "cookie":"",
       "inReplyTo":"",
       "name":"fileChange",
       "path":"/absolute/CMakeLists.txt",
       "properties":["change"],
       "type":"signal"}
     ]== "CMake Server" ==]

21.4.3 Specific Message Types
-----------------------------

21.4.3.1 Type “hello”
.....................

The initial message send by the cmake server on startup is of type
“hello”.  This is the only message ever sent by the server that is not
of type “reply”, “progress” or “error”.

It will contain “supportedProtocolVersions” with an array of server
protocol versions supported by the cmake server.  These are JSON objects
with “major” and “minor” keys containing non-negative integer values.
Some versions may be marked as experimental.  These will contain the
“isExperimental” key set to true.  Enabling these requires a special
command line argument when starting the cmake server mode.

Within a “major” version all “minor” versions are fully backwards
compatible.  New “minor” versions may introduce functionality in such a
way that existing clients of the same “major” version will continue to
work, provided they ignore keys in the output that they do not know
about.

Example:

     [== "CMake Server" ==[
     {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
     ]== "CMake Server" ==]

21.4.3.2 Type “handshake”
.........................

The first request that the client may send to the server is of type
“handshake”.

This request needs to pass one of the “supportedProtocolVersions” of the
“hello” type response received earlier back to the server in the
“protocolVersion” field.  Giving the “major” version of the requested
protocol version will make the server use the latest minor version of
that protocol.  Use this if you do not explicitly need to depend on a
specific minor version.

Protocol version 1.0 requires the following attributes to be set:

        * “sourceDirectory” with a path to the sources

        * “buildDirectory” with a path to the build directory

        * “generator” with the generator name

        * “extraGenerator” (optional!)  with the extra generator to be
          used

        * “platform” with the generator platform (if supported by the
          generator)

        * “toolset” with the generator toolset (if supported by the
          generator)

Protocol version 1.2 makes all but the build directory optional,
provided there is a valid cache in the build directory that contains all
the other information already.

Example:

     [== "CMake Server" ==[
     {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
      "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
      "generator":"Ninja"}
     ]== "CMake Server" ==]

which will result in a response type “reply”:

     [== "CMake Server" ==[
     {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
     ]== "CMake Server" ==]

indicating that the server is ready for action.

21.4.3.3 Type “globalSettings”
..............................

This request can be sent after the initial handshake.  It will return a
JSON structure with information on cmake state.

Example:

     [== "CMake Server" ==[
     {"type":"globalSettings"}
     ]== "CMake Server" ==]

which will result in a response type “reply”:

     [== "CMake Server" ==[
     {
       "buildDirectory": "/tmp/test-build",
       "capabilities": {
         "generators": [
           {
             "extraGenerators": [],
             "name": "Watcom WMake",
             "platformSupport": false,
             "toolsetSupport": false
           },
           <...>
         ],
         "serverMode": false,
         "version": {
           "isDirty": false,
           "major": 3,
           "minor": 6,
           "patch": 20160830,
           "string": "3.6.20160830-gd6abad",
           "suffix": "gd6abad"
         }
       },
       "checkSystemVars": false,
       "cookie": "",
       "extraGenerator": "",
       "generator": "Ninja",
       "debugOutput": false,
       "inReplyTo": "globalSettings",
       "sourceDirectory": "/home/code/cmake",
       "trace": false,
       "traceExpand": false,
       "type": "reply",
       "warnUninitialized": false,
       "warnUnused": false,
       "warnUnusedCli": true
     }
     ]== "CMake Server" ==]

21.4.3.4 Type “setGlobalSettings”
.................................

This request can be sent to change the global settings attributes.
Unknown attributes are going to be ignored.  Read-only attributes
reported by “globalSettings” are all capabilities, buildDirectory,
generator, extraGenerator and sourceDirectory.  Any attempt to set these
will be ignored, too.

All other settings will be changed.

The server will respond with an empty reply message or an error.

Example:

     [== "CMake Server" ==[
     {"type":"setGlobalSettings","debugOutput":true}
     ]== "CMake Server" ==]

CMake will reply to this with:

     [== "CMake Server" ==[
     {"inReplyTo":"setGlobalSettings","type":"reply"}
     ]== "CMake Server" ==]

21.4.3.5 Type “configure”
.........................

This request will configure a project for build.

To configure a build directory already containing cmake files, it is
enough to set “buildDirectory” via “setGlobalSettings”.  To create a
fresh build directory you also need to set “currentGenerator” and
“sourceDirectory” via “setGlobalSettings” in addition to
“buildDirectory”.

You may a list of strings to “configure” via the “cacheArguments” key.
These strings will be interpreted similar to command line arguments
related to cache handling that are passed to the cmake command line
client.

Example:

     [== "CMake Server" ==[
     {"type":"configure", "cacheArguments":["-Dsomething=else"]}
     ]== "CMake Server" ==]

CMake will reply like this (after reporting progress for some time):

     [== "CMake Server" ==[
     {"cookie":"","inReplyTo":"configure","type":"reply"}
     ]== "CMake Server" ==]

21.4.3.6 Type “compute”
.......................

This request will generate build system files in the build directory and
is only available after a project was successfully “configure”d.

Example:

     [== "CMake Server" ==[
     {"type":"compute"}
     ]== "CMake Server" ==]

CMake will reply (after reporting progress information):

     [== "CMake Server" ==[
     {"cookie":"","inReplyTo":"compute","type":"reply"}
     ]== "CMake Server" ==]

21.4.3.7 Type “codemodel”
.........................

The “codemodel” request can be used after a project was “compute”d
successfully.

It will list the complete project structure as it is known to cmake.

The reply will contain a key “configurations”, which will contain a list
of configuration objects.  Configuration objects are used to destinquish
between different configurations the build directory might have enabled.
While most generators only support one configuration, others might
support several.

Each configuration object can have the following keys:

“name”

     contains the name of the configuration.  The name may be empty.

“projects”

     contains a list of project objects, one for each build project.

Project objects define one (sub-)project defined in the cmake build
system.

Each project object can have the following keys:

“name”

     contains the (sub-)projects name.

“minimumCMakeVersion”

     contains the minimum cmake version allowed for this project, null
     if the project doesn’t specify one.

“hasInstallRule”

     true if the project contains any install rules, false otherwise.

“sourceDirectory”

     contains the current source directory

“buildDirectory”

     contains the current build directory.

“targets”

     contains a list of build system target objects.

Target objects define individual build targets for a certain
configuration.

Each target object can have the following keys:

“name”

     contains the name of the target.

“type”

     defines the type of build of the target.  Possible values are
     “STATIC_LIBRARY”, “MODULE_LIBRARY”, “SHARED_LIBRARY”,
     “OBJECT_LIBRARY”, “EXECUTABLE”, “UTILITY” and “INTERFACE_LIBRARY”.

“fullName”

     contains the full name of the build result (incl.  extensions,
     etc.).

“sourceDirectory”

     contains the current source directory.

“buildDirectory”

     contains the current build directory.

“isGeneratorProvided”

     true if the target is auto-created by a generator, false otherwise

“hasInstallRule”

     true if the target contains any install rules, false otherwise.

“installPaths”

     full path to the destination directories defined by target install
     rules.

“artifacts”

     with a list of build artifacts.  The list is sorted with the most
     important artifacts first (e.g.  a .DLL file is listed before a
     .PDB file on windows).

“linkerLanguage”

     contains the language of the linker used to produce the artifact.

“linkLibraries”

     with a list of libraries to link to.  This value is encoded in the
     system’s native shell format.

“linkFlags”

     with a list of flags to pass to the linker.  This value is encoded
     in the system’s native shell format.

“linkLanguageFlags”

     with the flags for a compiler using the linkerLanguage.  This value
     is encoded in the system’s native shell format.

“frameworkPath”

     with the framework path (on Apple computers).  This value is
     encoded in the system’s native shell format.

“linkPath”

     with the link path.  This value is encoded in the system’s native
     shell format.

“sysroot”

     with the sysroot path.

“fileGroups”

     contains the source files making up the target.

FileGroups are used to group sources using similar settings together.

Each fileGroup object may contain the following keys:

“language”

     contains the programming language used by all files in the group.

“compileFlags”

     with a string containing all the flags passed to the compiler when
     building any of the files in this group.  This value is encoded in
     the system’s native shell format.

“includePath”

     with a list of include paths.  Each include path is an object
     containing a “path” with the actual include path and “isSystem”
     with a bool value informing whether this is a normal include or a
     system include.  This value is encoded in the system’s native shell
     format.

“defines”

     with a list of defines in the form “SOMEVALUE” or “SOMEVALUE=42”.
     This value is encoded in the system’s native shell format.

“sources”

     with a list of source files.

All file paths in the fileGroup are either absolute or relative to the
sourceDirectory of the target.

Example:

     [== "CMake Server" ==[
     {"type":"codemodel"}
     ]== "CMake Server" ==]

CMake will reply:

     [== "CMake Server" ==[
     {
       "configurations": [
         {
           "name": "",
           "projects": [
             {
               "buildDirectory": "/tmp/build/Source/CursesDialog/form",
               "name": "CMAKE_FORM",
               "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
               "targets": [
                 {
                   "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
                   "buildDirectory": "/tmp/build/Source/CursesDialog/form",
                   "fileGroups": [
                     {
                       "compileFlags": "  -std=gnu11",
                       "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
                       "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
                       "isGenerated": false,
                       "language": "C",
                       "sources": [ "fld_arg.c", <...> ]
                     }
                   ],
                   "fullName": "libcmForm.a",
                   "linkerLanguage": "C",
                   "name": "cmForm",
                   "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
                   "type": "STATIC_LIBRARY"
                 }
               ]
             },
             <...>
           ]
         }
       ],
       "cookie": "",
       "inReplyTo": "codemodel",
       "type": "reply"
     }
     ]== "CMake Server" ==]

21.4.3.8 Type “ctestInfo”
.........................

The “ctestInfo” request can be used after a project was “compute”d
successfully.

It will list the complete project test structure as it is known to
cmake.

The reply will contain a key “configurations”, which will contain a list
of configuration objects.  Configuration objects are used to destinquish
between different configurations the build directory might have enabled.
While most generators only support one configuration, others might
support several.

Each configuration object can have the following keys:

“name”

     contains the name of the configuration.  The name may be empty.

“projects”

     contains a list of project objects, one for each build project.

Project objects define one (sub-)project defined in the cmake build
system.

Each project object can have the following keys:

“name”

     contains the (sub-)projects name.

“ctestInfo”

     contains a list of test objects.

Each test object can have the following keys:

“ctestName”

     contains the name of the test.

“ctestCommand”

     contains the test command.

“properties”

     contains a list of test property objects.

Each test property object can have the following keys:

“key”

     contains the test property key.

“value”

     contains the test property value.

21.4.3.9 Type “cmakeInputs”
...........................

The “cmakeInputs” requests will report files used by CMake as part of
the build system itself.

This request is only available after a project was successfully
“configure”d.

Example:

     [== "CMake Server" ==[
     {"type":"cmakeInputs"}
     ]== "CMake Server" ==]

CMake will reply with the following information:

     [== "CMake Server" ==[
     {"buildFiles":
       [
         {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
         {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
         {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
       ],
       "cmakeRootDirectory":"/usr/lib/cmake",
       "sourceDirectory":"/home/code/src/cmake",
       "cookie":"",
       "inReplyTo":"cmakeInputs",
       "type":"reply"
     }
     ]== "CMake Server" ==]

All file names are either relative to the top level source directory or
absolute.

The list of files which “isCMake” set to true are part of the cmake
installation.

The list of files witch “isTemporary” set to true are part of the build
directory and will not survive the build directory getting cleaned out.

21.4.3.10 Type “cache”
......................

The “cache” request will list the cached configuration values.

Example:

     [== "CMake Server" ==[
     {"type":"cache"}
     ]== "CMake Server" ==]

CMake will respond with the following output:

     [== "CMake Server" ==[
     {
       "cookie":"","inReplyTo":"cache","type":"reply",
       "cache":
       [
         {
           "key":"SOMEVALUE",
           "properties":
           {
             "ADVANCED":"1",
             "HELPSTRING":"This is not helpful"
           }
           "type":"STRING",
           "value":"TEST"}
       ]
     }
     ]== "CMake Server" ==]

The output can be limited to a list of keys by passing an array of key
names to the “keys” optional field of the “cache” request.

21.4.3.11 Type “fileSystemWatchers”
...................................

The server can watch the filesystem for changes.  The
“fileSystemWatchers” command will report on the files and directories
watched.

Example:

     [== "CMake Server" ==[
     {"type":"fileSystemWatchers"}
     ]== "CMake Server" ==]

CMake will respond with the following output:

     [== "CMake Server" ==[
     {
       "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
       "watchedFiles": [ "/absolute/path" ],
       "watchedDirectories": [ "/absolute" ]
     }
     ]== "CMake Server" ==]

22 cmake-toolchains(7)
**********************

22.1 Introduction
=================

CMake uses a toolchain of utilities to compile, link libraries and
create archives, and other tasks to drive the build.  The toolchain
utilities available are determined by the languages enabled.  In normal
builds, CMake automatically determines the toolchain for host builds
based on system introspection and defaults.  In cross-compiling
scenarios, a toolchain file may be specified with information about
compiler and utility paths.

22.2 Languages
==============

Languages are enabled by the project() command.
Language-specific built-in variables, such as CMAKE_CXX_COMPILER,
see CMAKE_CXX_COMPILER_ID etc are set by invoking the
project() command.  If no project command is in the top-level
CMakeLists file, one will be implicitly generated.  By default the
enabled languages are ‘C’ and ‘CXX’:

     project(C_Only C)

A special value of ‘NONE’ can also be used with the project()
command to enable no languages:

     project(MyProject NONE)

The enable_language() command can be used to enable
languages after the project() command:

     enable_language(CXX)

When a language is enabled, CMake finds a compiler for that language,
and determines some information, such as the vendor and version of the
compiler, the target architecture and bitwidth, the location of
corresponding utilities etc.

The ENABLED_LANGUAGES global property contains the languages
which are currently enabled.

22.3 Variables and Properties
=============================

Several variables relate to the language components of a toolchain which
are enabled.  CMAKE_<LANG>_COMPILER is the full path to the
compiler used for ‘<LANG>’.  CMAKE_<LANG>_COMPILER_ID is the
identifier used by CMake for the compiler and
CMAKE_<LANG>_COMPILER_VERSION is the version of the compiler.

The CMAKE_<LANG>_FLAGS variables and the
configuration-specific equivalents contain flags that will be added to
the compile command when compiling a file of a particular language.

As the linker is invoked by the compiler driver, CMake needs a way to
determine which compiler to use to invoke the linker.  This is
calculated by the LANGUAGE of source files in the target,
and in the case of static libraries, the language of the dependent
libraries.  The choice CMake makes may be overridden with the
LINKER_LANGUAGE target property.

22.4 Toolchain Features
=======================

CMake provides the try_compile() command and wrapper macros
such as CheckCXXSourceCompiles, CheckCXXSymbolExists
and CheckIncludeFile to test capability and
availability of various toolchain features.  These APIs test the
toolchain in some way and cache the result so that the test does not
have to be performed again the next time CMake runs.

Some toolchain features have built-in handling in CMake, and do not
require compile-tests.  For example, see POSITION_INDEPENDENT_CODE
allows specifying that a target should be built as
position-independent code, if the compiler supports that feature.  The
<LANG>_VISIBILITY_PRESET and
VISIBILITY_INLINES_HIDDEN target properties add flags for hidden
visibility, if supported by the compiler.

22.5 Cross Compiling
====================

If cmake(1) is invoked with the command line parameter
‘-DCMAKE_TOOLCHAIN_FILE=path/to/file’, the file will be loaded early to
set values for the compilers.  The CMAKE_CROSSCOMPILING.
variable is set to true when CMake is cross-compiling.

Note that using the CMAKE_SOURCE_DIR or
CMAKE_BINARY_DIR variables inside a toolchain file is typically
undesirable.  The toolchain file is used in contexts where these
variables have different values when used in different places (e.g.  as
part of a call to try_compile()).  In most cases, where there
is a need to evaluate paths inside a toolchain file, the more
appropriate variable to use would be CMAKE_CURRENT_LIST_DIR,
since it always has an unambiguous, predictable value.

22.5.1 Cross Compiling for Linux
--------------------------------

A typical cross-compiling toolchain for Linux has content such as:

     set(CMAKE_SYSTEM_NAME Linux)
     set(CMAKE_SYSTEM_PROCESSOR arm)

     set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs)
     set(CMAKE_STAGING_PREFIX /home/devel/stage)

     set(tools /home/devel/gcc-4.7-linaro-rpi-gnueabihf)
     set(CMAKE_C_COMPILER ${tools}/bin/arm-linux-gnueabihf-gcc)
     set(CMAKE_CXX_COMPILER ${tools}/bin/arm-linux-gnueabihf-g++)

     set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
     set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
     set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
     set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

The CMAKE_SYSTEM_NAME is the CMake-identifier of the target
platform to build for.

The CMAKE_SYSTEM_PROCESSOR is the CMake-identifier of the
target architecture to build for.

The CMAKE_SYSROOT is optional, and may be specified if a
sysroot is available.

The CMAKE_STAGING_PREFIX is also optional.  It may be used
to specify a path on the host to install to.  The
CMAKE_INSTALL_PREFIX is always the runtime installation location,
even when cross-compiling.

The CMAKE_<LANG>_COMPILER variables may be set to full
paths, or to names of compilers to search for in standard locations.
For toolchains that do not support linking binaries without custom flags
or scripts one may set the CMAKE_TRY_COMPILE_TARGET_TYPE.
variable to ‘STATIC_LIBRARY’ to tell CMake not to try to link
executables during its checks.

CMake ‘find_*’ commands will look in the sysroot, and the
CMAKE_FIND_ROOT_PATH entries by default in all cases, as well as
looking in the host system root prefix.  Although this can be controlled
on a case-by-case basis, when cross-compiling, it can be useful to
exclude looking in either the host or the target for particular
artifacts.  Generally, includes, libraries and packages should be found
in the target system prefixes, whereas executables which must be run as
part of the build should be found only on the host and not on the
target.  This is the purpose of the ‘CMAKE_FIND_ROOT_PATH_MODE_*’
variables.

22.5.2 Cross Compiling for the Cray Linux Environment
-----------------------------------------------------

Cross compiling for compute nodes in the Cray Linux Environment can be
done without needing a separate toolchain file.  Specifying
‘-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment’ on the CMake command line
will ensure that the appropriate build settings and search paths are
configured.  The platform will pull its configuration from the current
environment variables and will configure a project to use the compiler
wrappers from the Cray Programming Environment’s ‘PrgEnv-*’ modules if
present and loaded.

The default configuration of the Cray Programming Environment is to only
support static libraries.  This can be overridden and shared libraries
enabled by setting the ‘CRAYPE_LINK_TYPE’ environment variable to
‘dynamic’.

Running CMake without specifying CMAKE_SYSTEM_NAME will run
the configure step in host mode assuming a standard Linux environment.
If not overridden, the ‘PrgEnv-*’ compiler wrappers will end up getting
used, which if targeting the either the login node or compute node, is
likely not the desired behavior.  The exception to this would be if you
are building directly on a NID instead of cross-compiling from a login
node.  If trying to build software for a login node, you will need to
either first unload the currently loaded ‘PrgEnv-*’ module or explicitly
tell CMake to use the system compilers in ‘/usr/bin’ instead of the Cray
wrappers.  If instead targeting a compute node is desired, just specify
the CMAKE_SYSTEM_NAME as mentioned above.

22.5.3 Cross Compiling using Clang
----------------------------------

Some compilers such as Clang are inherently cross compilers.  The
CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value to those
supported compilers when compiling:

     set(CMAKE_SYSTEM_NAME Linux)
     set(CMAKE_SYSTEM_PROCESSOR arm)

     set(triple arm-linux-gnueabihf)

     set(CMAKE_C_COMPILER clang)
     set(CMAKE_C_COMPILER_TARGET ${triple})
     set(CMAKE_CXX_COMPILER clang++)
     set(CMAKE_CXX_COMPILER_TARGET ${triple})

Similarly, some compilers do not ship their own supplementary utilities
such as linkers, but provide a way to specify the location of the
external toolchain which will be used by the compiler driver.  The
CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN variable can be set in a
toolchain file to pass the path to the compiler driver.

22.5.4 Cross Compiling for QNX
------------------------------

As the Clang compiler the QNX QCC compile is inherently a cross
compiler.  And the CMAKE_<LANG>_COMPILER_TARGET can be set
to pass a value to those supported compilers when compiling:

     set(CMAKE_SYSTEM_NAME QNX)

     set(arch gcc_ntoarmv7le)

     set(CMAKE_C_COMPILER qcc)
     set(CMAKE_C_COMPILER_TARGET ${arch})
     set(CMAKE_CXX_COMPILER QCC)
     set(CMAKE_CXX_COMPILER_TARGET ${arch})

     set(CMAKE_SYSROOT $ENV{QNX_TARGET})

22.5.5 Cross Compiling for Windows CE
-------------------------------------

Cross compiling for Windows CE requires the corresponding SDK being
installed on your system.  These SDKs are usually installed under
‘C:/Program Files (x86)/Windows CE Tools/SDKs’.

A toolchain file to configure a Visual Studio generator for Windows CE
may look like this:

     set(CMAKE_SYSTEM_NAME WindowsCE)

     set(CMAKE_SYSTEM_VERSION 8.0)
     set(CMAKE_SYSTEM_PROCESSOR arm)

     set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0
     set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310)

The CMAKE_GENERATOR_PLATFORM tells the generator which SDK to
use.  Further CMAKE_SYSTEM_VERSION tells the generator what
version of Windows CE to use.  Currently version 8.0 (Windows Embedded
Compact 2013) is supported out of the box.  Other versions may require
one to set CMAKE_GENERATOR_TOOLSET to the correct value.

22.5.6 Cross Compiling for Windows 10 Universal Applications
------------------------------------------------------------

A toolchain file to configure a Visual Studio generator for a Windows 10
Universal Application may look like this:

     set(CMAKE_SYSTEM_NAME WindowsStore)
     set(CMAKE_SYSTEM_VERSION 10.0)

A Windows 10 Universal Application targets both Windows Store and
Windows Phone.  Specify the CMAKE_SYSTEM_VERSION variable
to be ‘10.0’ to build with the latest available Windows 10 SDK. Specify
a more specific version (e.g.  ‘10.0.10240.0’ for RTM) to build with the
corresponding SDK.

22.5.7 Cross Compiling for Windows Phone
----------------------------------------

A toolchain file to configure a Visual Studio generator for Windows
Phone may look like this:

     set(CMAKE_SYSTEM_NAME WindowsPhone)
     set(CMAKE_SYSTEM_VERSION 8.1)

22.5.8 Cross Compiling for Windows Store
----------------------------------------

A toolchain file to configure a Visual Studio generator for Windows
Store may look like this:

     set(CMAKE_SYSTEM_NAME WindowsStore)
     set(CMAKE_SYSTEM_VERSION 8.1)

22.5.9 Cross Compiling for Android
----------------------------------

A toolchain file may configure cross-compiling for Android by setting
the CMAKE_SYSTEM_NAME variable to ‘Android’.  Further
configuration is specific to the Android development environment to be
used.

For Visual Studio Generators, CMake expects NVIDIA Nsight Tegra Visual Studio Edition
or the Visual Studio tools for Android
to be installed.  See those sections for
further configuration details.

For Makefile Generators and the Ninja generator,
CMake expects one of these environments:

   * NDK.

   * Standalone Toolchain.

CMake uses the following steps to select one of the environments:

   * If the CMAKE_ANDROID_NDK variable is set, the NDK at
     the specified location will be used.

   * Else, if the CMAKE_ANDROID_STANDALONE_TOOLCHAIN.
     variable is set, the Standalone Toolchain at the specified location
     will be used.

   * Else, if the CMAKE_SYSROOT variable is set to a
     directory of the form ‘<ndk>/platforms/android-<api>/arch-<arch>’,
     the ‘<ndk>’ part will be used as the value of
     CMAKE_ANDROID_NDK and the NDK will be used.

   * Else, if the CMAKE_SYSROOT variable is set to a
     directory of the form ‘<standalone-toolchain>/sysroot’, the
     ‘<standalone-toolchain>’ part will be used as the value of
     CMAKE_ANDROID_STANDALONE_TOOLCHAIN and the Standalone
     Toolchain will be used.

   * Else, if a cmake variable ‘ANDROID_NDK’ is set it will be used as
     the value of CMAKE_ANDROID_NDK, and the NDK will be
     used.

   * Else, if a cmake variable ‘ANDROID_STANDALONE_TOOLCHAIN’ is set, it
     will be used as the value of
     CMAKE_ANDROID_STANDALONE_TOOLCHAIN, and the Standalone
     Toolchain will be used.

   * Else, if an environment variable ‘ANDROID_NDK_ROOT’ or
     ‘ANDROID_NDK’ is set, it will be used as the value of
     CMAKE_ANDROID_NDK, and the NDK will be used.

   * Else, if an environment variable ‘ANDROID_STANDALONE_TOOLCHAIN’ is
     set then it will be used as the value of
     CMAKE_ANDROID_STANDALONE_TOOLCHAIN, and the Standalone
     Toolchain will be used.

   * Else, an error diagnostic will be issued that neither the NDK or
     Standalone Toolchain can be found.

22.5.9.1 Cross Compiling for Android with the NDK
.................................................

A toolchain file may configure Makefile Generators,
Ninja Generators, or Visual Studio Generators to target
Android for cross-compiling.

Configure use of an Android NDK with the following variables:

CMAKE_SYSTEM_NAME.

     Set to ‘Android’.  Must be specified to enable cross compiling for
     Android.

See CMAKE_SYSTEM_VERSION.

     Set to the Android API level.  If not specified, the value is
     determined as follows:

        * If the CMAKE_ANDROID_API variable is set, its
          value is used as the API level.

        * If the CMAKE_SYSROOT variable is set, the API
          level is detected from the NDK directory structure containing
          the sysroot.

        * Otherwise, the latest API level available in the NDK is used.

See CMAKE_ANDROID_ARCH_ABI.

     Set to the Android ABI (architecture).  If not specified, this
     variable will default to ‘armeabi’.  The CMAKE_ANDROID_ARCH
     variable will be computed from ‘CMAKE_ANDROID_ARCH_ABI’
     automatically.  Also see the CMAKE_ANDROID_ARM_MODE.
     and CMAKE_ANDROID_ARM_NEON variables.

See CMAKE_ANDROID_NDK.

     Set to the absolute path to the Android NDK root directory.  A
     ‘${CMAKE_ANDROID_NDK}/platforms’ directory must exist.  If not
     specified, a default for this variable will be chosen as specified
     above.

See CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.

     Set to a true value to use the deprecated per-api-level headers
     instead of the unified headers.  If not specified, the default will
     be false unless using a NDK that does not provide unified headers.

See CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.

     On NDK r19 or above, this variable must be unset or set to ‘clang’.
     On NDK r18 or below, set this to the version of the NDK toolchain
     to be selected as the compiler.  If not specified, the default will
     be the latest available GCC toolchain.

See CMAKE_ANDROID_STL_TYPE.

     Set to specify which C++ standard library to use.  If not
     specified, a default will be selected as described in the variable
     documentation.

The following variables will be computed and provided automatically:

CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX.

     The absolute path prefix to the binutils in the NDK toolchain.

See CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.

     The host platform suffix of the binutils in the NDK toolchain.

For example, a toolchain file might contain:

     set(CMAKE_SYSTEM_NAME Android)
     set(CMAKE_SYSTEM_VERSION 21) # API level
     set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
     set(CMAKE_ANDROID_NDK /path/to/android-ndk)
     set(CMAKE_ANDROID_STL_TYPE gnustl_static)

Alternatively one may specify the values without a toolchain file:

     $ cmake ../src \
       -DCMAKE_SYSTEM_NAME=Android \
       -DCMAKE_SYSTEM_VERSION=21 \
       -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
       -DCMAKE_ANDROID_NDK=/path/to/android-ndk \
       -DCMAKE_ANDROID_STL_TYPE=gnustl_static

22.5.9.2 Cross Compiling for Android with a Standalone Toolchain
................................................................

A toolchain file may configure Makefile Generators or the
Ninja generator to target Android for cross-compiling using a
standalone toolchain.

Configure use of an Android standalone toolchain with the following
variables:

CMAKE_SYSTEM_NAME.

     Set to ‘Android’.  Must be specified to enable cross compiling for
     Android.

See CMAKE_ANDROID_STANDALONE_TOOLCHAIN.

     Set to the absolute path to the standalone toolchain root
     directory.  A ‘${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot’
     directory must exist.  If not specified, a default for this
     variable will be chosen as specified above.

See CMAKE_ANDROID_ARM_MODE.

     When the standalone toolchain targets ARM, optionally set this to
     ‘ON’ to target 32-bit ARM instead of 16-bit Thumb.  See variable
     documentation for details.

See CMAKE_ANDROID_ARM_NEON.

     When the standalone toolchain targets ARM v7, optionally set thisto
     ‘ON’ to target ARM NEON devices.  See variable documentation for
     details.

The following variables will be computed and provided automatically:

CMAKE_SYSTEM_VERSION.

     The Android API level detected from the standalone toolchain.

See CMAKE_ANDROID_ARCH_ABI.

     The Android ABI detected from the standalone toolchain.

See CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX.

     The absolute path prefix to the ‘binutils’ in the standalone
     toolchain.

See CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.

     The host platform suffix of the ‘binutils’ in the standalone
     toolchain.

For example, a toolchain file might contain:

     set(CMAKE_SYSTEM_NAME Android)
     set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)

Alternatively one may specify the values without a toolchain file:

     $ cmake ../src \
       -DCMAKE_SYSTEM_NAME=Android \
       -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain

22.5.9.3 Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
...................................................................................

A toolchain file to configure one of the Visual Studio Generators
to build using NVIDIA Nsight Tegra targeting Android may look like
this:

     set(CMAKE_SYSTEM_NAME Android)

The CMAKE_GENERATOR_TOOLSET may be set to select the Nsight
Tegra “Toolchain Version” value.

See also target properties:

   * ANDROID_ANT_ADDITIONAL_OPTIONS.

   * ANDROID_API_MIN.

   * ANDROID_API.

   * ANDROID_ARCH.

   * ANDROID_ASSETS_DIRECTORIES.

   * ANDROID_GUI.

   * ANDROID_JAR_DEPENDENCIES.

   * ANDROID_JAR_DIRECTORIES.

   * ANDROID_JAVA_SOURCE_DIR.

   * ANDROID_NATIVE_LIB_DEPENDENCIES.

   * ANDROID_NATIVE_LIB_DIRECTORIES.

   * ANDROID_PROCESS_MAX.

   * ANDROID_PROGUARD_CONFIG_PATH.

   * ANDROID_PROGUARD.

   * ANDROID_SECURE_PROPS_PATH.

   * ANDROID_SKIP_ANT_STEP.

   * ANDROID_STL_TYPE.

22.5.10 Cross Compiling for iOS, tvOS, or watchOS
-------------------------------------------------

For cross-compiling to iOS, tvOS, or watchOS, the Xcode.
generator is recommended.  The Unix Makefiles or Ninja
generators can also be used, but they require the project to handle
more areas like target CPU selection and code signing.

Any of the three systems can be targeted by setting the
CMAKE_SYSTEM_NAME variable to a value from the table below.  By
default, the latest Device SDK is chosen.  As for all Apple platforms, a
different SDK (e.g.  a simulator) can be selected by setting the
CMAKE_OSX_SYSROOT variable, although this should rarely be
necessary (see Switching Between Device and Simulator.
below).  A list of available SDKs can be obtained by running ‘xcodebuild
-showsdks’.

OS          CMAKE_SYSTEM_NAME     Device SDK (default)     Simulator SDK

--------------------------------------------------------------------------------

iOS         iOS                   iphoneos                 iphonesimulator

tvOS        tvOS                  appletvos                appletvsimulator

watchOS     watchOS               watchos                  watchsimulator

For example, to create a CMake configuration for iOS, the following
command is sufficient:

     cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS

Variable CMAKE_OSX_ARCHITECTURES can be used to set
architectures for both device and simulator.  Variable
CMAKE_OSX_DEPLOYMENT_TARGET can be used to set an iOS/tvOS/watchOS
deployment target.

Next configuration will install fat 5 architectures iOS library and add
the ‘-miphoneos-version-min=9.3’/‘-mios-simulator-version-min=9.3’ flags
to the compiler:

     $ cmake -S. -B_builds -GXcode \
         -DCMAKE_SYSTEM_NAME=iOS \
         "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \
         -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \
         -DCMAKE_INSTALL_PREFIX=`pwd`/_install \
         -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \
         -DCMAKE_IOS_INSTALL_COMBINED=YES

Example:

     # CMakeLists.txt
     cmake_minimum_required(VERSION 3.14)
     project(foo)
     add_library(foo foo.cpp)
     install(TARGETS foo DESTINATION lib)

Install:

     $ cmake --build _builds --config Release --target install

Check library:

     $ lipo -info _install/lib/libfoo.a
     Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64

     $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS
           cmd LC_VERSION_MIN_IPHONEOS
       cmdsize 16
       version 9.3

22.5.10.1 Code Signing
......................

Some build artifacts for the embedded Apple platforms require mandatory
code signing.  If the Xcode generator is being used and code
signing is required or desired, the development team ID can be specified
via the ‘CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM’ CMake variable.  This
team ID will then be included in the generated Xcode project.  By
default, CMake avoids the need for code signing during the internal
configuration phase (i.e compiler ID and feature detection).

22.5.10.2 Switching Between Device and Simulator
................................................

When configuring for any of the embedded platforms, one can target
either real devices or the simulator.  Both have their own separate SDK,
but CMake only supports specifying a single SDK for the configuration
phase.  This means the developer must select one or the other at
configuration time.  When using the Xcode generator, this is
less of a limitation because Xcode still allows you to build for either
a device or a simulator, even though configuration was only performed
for one of the two.  From within the Xcode IDE, builds are performed for
the selected “destination” platform.  When building from the command
line, the desired sdk can be specified directly by passing a ‘-sdk’
option to the underlying build tool (‘xcodebuild’).  For example:

     $ cmake --build ... -- -sdk iphonesimulator

Please note that checks made during configuration were performed against
the configure-time SDK and might not hold true for other SDKs.  Commands
like find_package(), find_library(), etc.  store
and use details only for the configured SDK/platform, so they can be
problematic if wanting to switch between device and simulator builds.
You can follow the next rules to make device + simulator configuration
work:

   - Use explicit ‘-l’ linker flag, e.g.  ‘target_link_libraries(foo
     PUBLIC "-lz")’

   - Use explicit ‘-framework’ linker flag, e.g.
     ‘target_link_libraries(foo PUBLIC "-framework CoreFoundation")’

   - Use find_package() only for libraries installed with
     CMAKE_IOS_INSTALL_COMBINED feature

23 cmake-variables(7)
*********************

This page documents variables that are provided by CMake or have meaning
to CMake when set by project code.

For general information on variables, see the Variables.
section in the cmake-language manual.

     Note: CMake reserves identifiers that:

        * begin with ‘CMAKE_’ (upper-, lower-, or mixed-case), or

        * begin with ‘_CMAKE_’ (upper-, lower-, or mixed-case), or

        * begin with ‘_’ followed by the name of any CMake Command.

23.1 Variables that Provide Information
=======================================

23.1.1 CMAKE_AR
---------------

Name of archiving tool for static libraries.

This specifies the name of the program that creates archive or static
libraries.

23.1.2 CMAKE_ARGC
-----------------

Number of command line arguments passed to CMake in script mode.

When run in -P script mode, CMake sets this variable to the
number of command line arguments.  See also CMAKE_ARGV0, ‘1’,
‘2’ …

23.1.3 CMAKE_ARGV0
------------------

Command line argument passed to CMake in script mode.

When run in -P script mode, CMake sets this variable to the
first command line argument.  It then also sets ‘CMAKE_ARGV1’,
‘CMAKE_ARGV2’, … and so on, up to the number of command line arguments
given.  See also CMAKE_ARGC.

23.1.4 CMAKE_BINARY_DIR
-----------------------

The path to the top level of the build tree.

This is the full path to the top level of the current CMake build tree.
For an in-source build, this would be the same as
CMAKE_SOURCE_DIR.

When run in -P script mode, CMake sets the variables
CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR,
CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR.
to the current working directory.

23.1.5 CMAKE_BUILD_TOOL
-----------------------

This variable exists only for backwards compatibility.  It contains the
same value as CMAKE_MAKE_PROGRAM.  Use that variable instead.

23.1.6 CMAKE_CACHE_MAJOR_VERSION
--------------------------------

Major version of CMake used to create the ‘CMakeCache.txt’ file

This stores the major version of CMake used to write a CMake cache file.
It is only different when a different version of CMake is run on a
previously created cache file.

23.1.7 CMAKE_CACHE_MINOR_VERSION
--------------------------------

Minor version of CMake used to create the ‘CMakeCache.txt’ file

This stores the minor version of CMake used to write a CMake cache file.
It is only different when a different version of CMake is run on a
previously created cache file.

23.1.8 CMAKE_CACHE_PATCH_VERSION
--------------------------------

Patch version of CMake used to create the ‘CMakeCache.txt’ file

This stores the patch version of CMake used to write a CMake cache file.
It is only different when a different version of CMake is run on a
previously created cache file.

23.1.9 CMAKE_CACHEFILE_DIR
--------------------------

The directory with the ‘CMakeCache.txt’ file.

This is the full path to the directory that has the ‘CMakeCache.txt’
file in it.  This is the same as CMAKE_BINARY_DIR.

23.1.10 CMAKE_CFG_INTDIR
------------------------

Build-time reference to per-configuration output subdirectory.

For native build systems supporting multiple configurations in the build
tree (such as Visual Studio Generators and Xcode),
the value is a reference to a build-time variable specifying the
name of the per-configuration output subdirectory.  On Makefile Generators
this evaluates to ‘.’ because there is only one
configuration in a build tree.  Example values:

     $(ConfigurationName) = Visual Studio 9
     $(Configuration)     = Visual Studio 10
     $(CONFIGURATION)     = Xcode
     .                    = Make-based tools
     .                    = Ninja
     ${CONFIGURATION}     = Ninja Multi-Config

Note that this variable only has limited support on Ninja Multi-Config.
It is recommended that you use the ‘$<CONFIG>’
generator expression instead.

Since these values are evaluated by the native build system, this
variable is suitable only for use in command lines that will be
evaluated at build time.  Example of intended usage:

     add_executable(mytool mytool.c)
     add_custom_command(
       OUTPUT out.txt
       COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
               ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
       DEPENDS mytool in.txt
       )
     add_custom_target(drive ALL DEPENDS out.txt)

Note that ‘CMAKE_CFG_INTDIR’ is no longer necessary for this purpose but
has been left for compatibility with existing projects.  Instead
add_custom_command() recognizes executable target names in its
‘COMMAND’ option, so
‘${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool’ can be replaced
by just ‘mytool’.

This variable is read-only.  Setting it is undefined behavior.  In
multi-configuration build systems the value of this variable is passed
as the value of preprocessor symbol ‘CMAKE_INTDIR’ to the compilation of
all source files.

23.1.11 CMAKE_COMMAND
---------------------

The full path to the cmake(1) executable.

This is the full path to the CMake executable cmake(1) which
is useful from custom commands that want to use the ‘cmake -E’ option
for portable system commands.  (e.g.  ‘/usr/local/bin/cmake’)

23.1.12 CMAKE_CPACK_COMMAND
---------------------------

New in version 3.13.

Full path to cpack(1) command installed with CMake.

This is the full path to the CPack executable cpack(1) which
is useful from custom commands that want to use the cmake(1).
‘-E’ option for portable system commands.

23.1.13 CMAKE_CROSSCOMPILING
----------------------------

Intended to indicate whether CMake is cross compiling, but note
limitations discussed below.

This variable will be set to true by CMake if the
CMAKE_SYSTEM_NAME variable has been set manually (i.e.  in a
toolchain file or as a cache entry from the cmake command
line).  In most cases, manually setting CMAKE_SYSTEM_NAME.
will only be done when cross compiling, since it will otherwise be given
the same value as CMAKE_HOST_SYSTEM_NAME if not manually
set, which is correct for the non-cross-compiling case.  In the event
that CMAKE_SYSTEM_NAME is manually set to the same value as
CMAKE_HOST_SYSTEM_NAME, then ‘CMAKE_CROSSCOMPILING’ will
still be set to true.

Another case to be aware of is that builds targeting Apple platforms
other than macOS are handled differently to other cross compiling
scenarios.  Rather than relying on CMAKE_SYSTEM_NAME to
select the target platform, Apple device builds use
CMAKE_OSX_SYSROOT to select the appropriate SDK, which indirectly
determines the target platform.  Furthermore, when using the
Xcode generator, developers can switch between device and
simulator builds at build time rather than having a single choice at
configure time, so the concept of whether the build is cross compiling
or not is more complex.  Therefore, the use of ‘CMAKE_CROSSCOMPILING’ is
not recommended for projects targeting Apple devices.

23.1.14 CMAKE_CROSSCOMPILING_EMULATOR
-------------------------------------

New in version 3.3.

This variable is only used when CMAKE_CROSSCOMPILING is on.
It should point to a command on the host system that can run executable
built for the target system.

If this variable contains a semicolon-separated list, then the
first value is the command and remaining values are its arguments.

The command will be used to run try_run() generated
executables, which avoids manual population of the ‘TryRunResults.cmake’
file.

It is also used as the default value for the
CROSSCOMPILING_EMULATOR target property of executables.

23.1.15 CMAKE_CTEST_COMMAND
---------------------------

Full path to ctest(1) command installed with CMake.

This is the full path to the CTest executable ctest(1) which
is useful from custom commands that want to use the cmake(1).
‘-E’ option for portable system commands.

23.1.16 CMAKE_CURRENT_BINARY_DIR
--------------------------------

The path to the binary directory currently being processed.

This the full path to the build directory that is currently being
processed by cmake.  Each directory added by add_subdirectory()
will create a binary directory in the build tree, and as it is
being processed this variable will be set.  For in-source builds this is
the current source directory being processed.

When run in -P script mode, CMake sets the variables
CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR,
CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR.
to the current working directory.

23.1.17 CMAKE_CURRENT_FUNCTION
------------------------------

New in version 3.17.

When executing code inside a function(), this variable
contains the name of the current function.  It can be useful for
diagnostic or debug messages.

See also CMAKE_CURRENT_FUNCTION_LIST_DIR,
CMAKE_CURRENT_FUNCTION_LIST_FILE and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

23.1.18 CMAKE_CURRENT_FUNCTION_LIST_DIR
---------------------------------------

New in version 3.17.

When executing code inside a function(), this variable
contains the full directory of the listfile that defined the current
function.

It is quite common practice in CMake for modules to use some additional
files, such as templates to be copied in after substituting CMake
variables.  In such cases, a function needs to know where to locate
those files in a way that doesn’t depend on where the function is
called.  Without ‘CMAKE_CURRENT_FUNCTION_LIST_DIR’, the code to do that
would typically use the following pattern:

     set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")

     function(foo)
       configure_file(
         "${_THIS_MODULE_BASE_DIR}/some.template.in"
         some.output
       )
     endfunction()

Using ‘CMAKE_CURRENT_FUNCTION_LIST_DIR’ inside the function instead
eliminates the need for the extra variable which would otherwise be
visible outside the function’s scope.  The above example can be written
in the more concise and more robust form:

     function(foo)
       configure_file(
         "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
         some.output
       )
     endfunction()

See also CMAKE_CURRENT_FUNCTION,
CMAKE_CURRENT_FUNCTION_LIST_FILE and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

23.1.19 CMAKE_CURRENT_FUNCTION_LIST_FILE
----------------------------------------

New in version 3.17.

When executing code inside a function(), this variable
contains the full path to the listfile that defined the current
function.

See also CMAKE_CURRENT_FUNCTION,
CMAKE_CURRENT_FUNCTION_LIST_DIR and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

23.1.20 CMAKE_CURRENT_FUNCTION_LIST_LINE
----------------------------------------

New in version 3.17.

When executing code inside a function(), this variable
contains the line number in the listfile where the current function was
defined.

See also CMAKE_CURRENT_FUNCTION,
CMAKE_CURRENT_FUNCTION_LIST_DIR and
CMAKE_CURRENT_FUNCTION_LIST_FILE.

23.1.21 CMAKE_CURRENT_LIST_DIR
------------------------------

Full directory of the listfile currently being processed.

As CMake processes the listfiles in your project this variable will
always be set to the directory where the listfile which is currently
being processed ( see CMAKE_CURRENT_LIST_FILE) is located.  The
value has dynamic scope.  When CMake starts processing commands in a
source file it sets this variable to the directory where this file is
located.  When CMake finishes processing commands from the file it
restores the previous value.  Therefore the value of the variable inside
a macro or function is the directory of the file invoking the
bottom-most entry on the call stack, not the directory of the file
containing the macro or function definition.

See also CMAKE_CURRENT_LIST_FILE.

23.1.22 CMAKE_CURRENT_LIST_FILE
-------------------------------

Full path to the listfile currently being processed.

As CMake processes the listfiles in your project this variable will
always be set to the one currently being processed.  The value has
dynamic scope.  When CMake starts processing commands in a source file
it sets this variable to the location of the file.  When CMake finishes
processing commands from the file it restores the previous value.
Therefore the value of the variable inside a macro or function is the
file invoking the bottom-most entry on the call stack, not the file
containing the macro or function definition.

See also CMAKE_PARENT_LIST_FILE.

23.1.23 CMAKE_CURRENT_LIST_LINE
-------------------------------

The line number of the current file being processed.

This is the line number of the file currently being processed by cmake.

If CMake is currently processing deferred calls scheduled by the
cmake_language(DEFER) command, this variable evaluates to
‘DEFERRED’ instead of a specific line number.

23.1.24 CMAKE_CURRENT_SOURCE_DIR
--------------------------------

The path to the source directory currently being processed.

This the full path to the source directory that is currently being
processed by cmake.

When run in -P script mode, CMake sets the variables
CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR,
CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR.
to the current working directory.

23.1.25 CMAKE_DEBUG_TARGET_PROPERTIES
-------------------------------------

Enables tracing output for target properties.

This variable can be populated with a list of properties to generate
debug output for when evaluating target properties.  Currently it can
only be used when evaluating:

   * AUTOUIC_OPTIONS.

   * COMPILE_DEFINITIONS.

   * COMPILE_FEATURES.

   * COMPILE_OPTIONS.

   * INCLUDE_DIRECTORIES.

   * LINK_DIRECTORIES.

   * LINK_OPTIONS.

   * POSITION_INDEPENDENT_CODE.

   * SOURCES.

target properties and any other property listed in
COMPATIBLE_INTERFACE_STRING and other ‘COMPATIBLE_INTERFACE_’
properties.  It outputs an origin for each entry in the target property.
Default is unset.

23.1.26 CMAKE_DIRECTORY_LABELS
------------------------------

New in version 3.10.

Specify labels for the current directory.

This is used to initialize the LABELS directory property.

23.1.27 CMAKE_DL_LIBS
---------------------

Name of library containing ‘dlopen’ and ‘dlclose’.

The name of the library that has ‘dlopen’ and ‘dlclose’ in it, usually
‘-ldl’ on most UNIX machines.

23.1.28 CMAKE_DOTNET_TARGET_FRAMEWORK
-------------------------------------

New in version 3.17.

Default value for DOTNET_TARGET_FRAMEWORK property of
targets.

This variable is used to initialize the DOTNET_TARGET_FRAMEWORK
property on all targets.  See that target property for additional
information.

Setting ‘CMAKE_DOTNET_TARGET_FRAMEWORK’ may be necessary when working
with ‘C#’ and newer .NET framework versions to avoid referencing errors
with the ‘ALL_BUILD’ CMake target.

This variable is only evaluated for Visual Studio Generators.
VS 2010 and above.

23.1.29 CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
---------------------------------------------

New in version 3.12.

Default value for DOTNET_TARGET_FRAMEWORK_VERSION property
of targets.

This variable is used to initialize the
DOTNET_TARGET_FRAMEWORK_VERSION property on all targets.  See that
target property for additional information.  When set, see
CMAKE_DOTNET_TARGET_FRAMEWORK takes precednece over this variable.
See that variable or the associated target property
DOTNET_TARGET_FRAMEWORK for additional information.

Setting ‘CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION’ may be necessary when
working with ‘C#’ and newer .NET framework versions to avoid referencing
errors with the ‘ALL_BUILD’ CMake target.

This variable is only evaluated for Visual Studio Generators.
VS 2010 and above.

23.1.30 CMAKE_EDIT_COMMAND
--------------------------

Full path to cmake-gui(1) or ccmake(1).  Defined
only for Makefile Generators when not using an “extra”
generator for an IDE.

This is the full path to the CMake executable that can graphically edit
the cache.  For example, see cmake-gui(1) or ccmake(1).

23.1.31 CMAKE_EXECUTABLE_SUFFIX
-------------------------------

The suffix for executables on this platform.

The suffix to use for the end of an executable filename if any, ‘.exe’
on Windows.

‘CMAKE_EXECUTABLE_SUFFIX_<LANG>’ overrides this for language ‘<LANG>’.

23.1.32 CMAKE_EXTRA_GENERATOR
-----------------------------

The extra generator used to build the project.  See
cmake-generators(7).

When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime
generators, CMake generates Makefiles ( see CMAKE_GENERATOR) and
additionally project files for the respective IDE. This IDE project file
generator is stored in ‘CMAKE_EXTRA_GENERATOR’ (e.g.  ‘Eclipse CDT4’).

23.1.33 CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
-------------------------------------------

Additional suffixes for shared libraries.

Extensions for shared libraries other than that specified by
CMAKE_SHARED_LIBRARY_SUFFIX, if any.  CMake uses this to recognize
external shared library files during analysis of libraries linked by a
target.

23.1.34 CMAKE_FIND_DEBUG_MODE
-----------------------------

New in version 3.17.

Print extra find call information for the following commands to standard
error:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

Output is designed for human consumption and not for parsing.  Enabling
this variable is equivalent to using cmake. ‘--debug-find’ with
the added ability to enable debugging for a subset of find calls.

     set(CMAKE_FIND_DEBUG_MODE TRUE)
     find_program(...)
     set(CMAKE_FIND_DEBUG_MODE FALSE)

Default is unset.

23.1.35 CMAKE_FIND_PACKAGE_NAME
-------------------------------

New in version 3.1.1.

Defined by the find_package() command while loading a find
module to record the caller-specified package name.  See command
documentation for details.

23.1.36 CMAKE_FIND_PACKAGE_SORT_DIRECTION
-----------------------------------------

New in version 3.7.

The sorting direction used by CMAKE_FIND_PACKAGE_SORT_ORDER.
It can assume one of the following values:

‘DEC’

     Default.  Ordering is done in descending mode.  The highest folder
     found will be tested first.

‘ASC’

     Ordering is done in ascending mode.  The lowest folder found will
     be tested first.

If CMAKE_FIND_PACKAGE_SORT_ORDER is not set or is set to
‘NONE’ this variable has no effect.

23.1.37 CMAKE_FIND_PACKAGE_SORT_ORDER
-------------------------------------

New in version 3.7.

The default order for sorting packages found using find_package().
It can assume one of the following values:

‘NONE’

     Default.  No attempt is done to sort packages.  The first valid
     package found will be selected.

‘NAME’

     Sort packages lexicographically before selecting one.

‘NATURAL’

     Sort packages using natural order (see ‘strverscmp(3)’ manual),
     i.e.  such that contiguous digits are compared as whole numbers.

Natural sorting can be employed to return the highest version when
multiple versions of the same library are found by find_package().
For example suppose that the following libraries have been found:

   * libX-1.1.0

   * libX-1.2.9

   * libX-1.2.10

By setting ‘NATURAL’ order we can select the one with the highest
version number ‘libX-1.2.10’.

     set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
     find_package(libX CONFIG)

The sort direction can be controlled using the
CMAKE_FIND_PACKAGE_SORT_DIRECTION variable (by default decrescent,
e.g.  lib-B will be tested before lib-A).

23.1.38 CMAKE_GENERATOR
-----------------------

The generator used to build the project.  See cmake-generators(7).

The name of the generator that is being used to generate the build
files.  (e.g.  ‘Unix Makefiles’, ‘Ninja’, etc.)

The value of this variable should never be modified by project code.  A
generator may be selected via the cmake(1). ‘-G’ option,
interactively in cmake-gui(1), or via the
CMAKE_GENERATOR environment variable.

23.1.39 CMAKE_GENERATOR_INSTANCE
--------------------------------

New in version 3.11.

Generator-specific instance specification provided by user.

Some CMake generators support selection of an instance of the native
build system when multiple instances are available.  If the user
specifies an instance (e.g.  by setting this cache entry or via the
CMAKE_GENERATOR_INSTANCE environment variable), or after a
default instance is chosen when a build tree is first configured, the
value will be available in this variable.

The value of this variable should never be modified by project code.  A
toolchain file specified by the CMAKE_TOOLCHAIN_FILE.
variable may initialize ‘CMAKE_GENERATOR_INSTANCE’ as a cache entry.
Once a given build tree has been initialized with a particular value for
this variable, changing the value has undefined behavior.

Instance specification is supported only on specific generators:

   * For the Visual Studio 15 2017 generator (and above)
     this specifies the absolute path to the VS installation directory
     of the selected VS instance.

See native build system documentation for allowed instance values.

23.1.40 CMAKE_GENERATOR_PLATFORM
--------------------------------

New in version 3.1.

Generator-specific target platform specification provided by user.

Some CMake generators support a target platform name to be given to the
native build system to choose a compiler toolchain.  If the user
specifies a platform name (e.g.  via the cmake(1). ‘-A’ option
or via the CMAKE_GENERATOR_PLATFORM environment variable)
the value will be available in this variable.

The value of this variable should never be modified by project code.  A
toolchain file specified by the CMAKE_TOOLCHAIN_FILE.
variable may initialize ‘CMAKE_GENERATOR_PLATFORM’.  Once a given build
tree has been initialized with a particular value for this variable,
changing the value has undefined behavior.

Platform specification is supported only on specific generators:

   * For Visual Studio Generators with VS 2005 and above
     this specifies the target architecture.

   * For Green Hills MULTI this specifies the target
     architecture.

See native build system documentation for allowed platform names.

23.1.40.1 Visual Studio Platform Selection
..........................................

On Visual Studio Generators the selected platform name is
provided in the CMAKE_VS_PLATFORM_NAME variable.

23.1.41 CMAKE_GENERATOR_TOOLSET
-------------------------------

Native build system toolset specification provided by user.

Some CMake generators support a toolset specification to tell the native
build system how to choose a compiler.  If the user specifies a toolset
(e.g.  via the cmake(1). ‘-T’ option or via the
CMAKE_GENERATOR_TOOLSET environment variable) the value will be
available in this variable.

The value of this variable should never be modified by project code.  A
toolchain file specified by the CMAKE_TOOLCHAIN_FILE.
variable may initialize ‘CMAKE_GENERATOR_TOOLSET’.  Once a given build
tree has been initialized with a particular value for this variable,
changing the value has undefined behavior.

Toolset specification is supported only on specific generators:

   * Visual Studio Generators for VS 2010 and above

   * The Xcode generator for Xcode 3.0 and above

   * The Green Hills MULTI generator

See native build system documentation for allowed toolset names.

23.1.41.1 Visual Studio Toolset Selection
.........................................

The Visual Studio Generators support toolset specification
using one of these forms:

   * ‘toolset’

   * ‘toolset[,key=value]*’

   * ‘key=value[,key=value]*’

The ‘toolset’ specifies the toolset name.  The selected toolset name is
provided in the CMAKE_VS_PLATFORM_TOOLSET variable.

The ‘key=value’ pairs form a comma-separated list of options to specify
generator-specific details of the toolset selection.  Supported pairs
are:

‘cuda=<version>|<path>’

     Specify the CUDA toolkit version to use or the path to a standalone
     CUDA toolkit directory.  Supported by VS 2010 and above.  The
     version can only be used with the CUDA toolkit VS integration
     globally installed.  See the CMAKE_VS_PLATFORM_TOOLSET_CUDA
     and CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.
     variables.

‘host=<arch>’

     Specify the host tools architecture as ‘x64’ or ‘x86’.  Supported
     by VS 2013 and above.  See the
     CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE variable.

‘version=<version>’

     Specify the toolset version to use.  Supported by VS 2017 and above
     with the specified toolset installed.  See the
     CMAKE_VS_PLATFORM_TOOLSET_VERSION variable.

‘VCTargetsPath=<path>’

     Specify an alternative ‘VCTargetsPath’ value for Visual Studio
     project files.  This allows use of VS platform extension
     configuration files (‘.props’ and ‘.targets’) that are not
     installed with VS.

23.1.42 CMAKE_IMPORT_LIBRARY_PREFIX
-----------------------------------

The prefix for import libraries that you link to.

The prefix to use for the name of an import library if used on this
platform.

‘CMAKE_IMPORT_LIBRARY_PREFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.43 CMAKE_IMPORT_LIBRARY_SUFFIX
-----------------------------------

The suffix for import libraries that you link to.

The suffix to use for the end of an import library filename if used on
this platform.

‘CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.44 CMAKE_JOB_POOL_COMPILE
------------------------------

This variable is used to initialize the JOB_POOL_COMPILE.
property on all the targets.  See JOB_POOL_COMPILE for
additional information.

23.1.45 CMAKE_JOB_POOL_LINK
---------------------------

This variable is used to initialize the JOB_POOL_LINK.
property on all the targets.  See JOB_POOL_LINK for
additional information.

23.1.46 CMAKE_JOB_POOL_PRECOMPILE_HEADER
----------------------------------------

New in version 3.17.

This variable is used to initialize the
JOB_POOL_PRECOMPILE_HEADER property on all the targets.  See
JOB_POOL_PRECOMPILE_HEADER for additional information.

23.1.47 CMAKE_JOB_POOLS
-----------------------

New in version 3.11.

If the JOB_POOLS global property is not set, the value of
this variable is used in its place.  See JOB_POOLS for
additional information.

23.1.48 CMAKE_<LANG>_COMPILER_AR
--------------------------------

New in version 3.9.

A wrapper around ‘ar’ adding the appropriate ‘--plugin’ option for the
compiler.

See also CMAKE_AR.

23.1.49 CMAKE_<LANG>_COMPILER_RANLIB
------------------------------------

New in version 3.9.

A wrapper around ‘ranlib’ adding the appropriate ‘--plugin’ option for
the compiler.

See also CMAKE_RANLIB.

23.1.50 CMAKE_<LANG>_LINK_LIBRARY_SUFFIX
----------------------------------------

New in version 3.16.

Language-specific suffix for libraries that you link to.

The suffix to use for the end of a library filename, ‘.lib’ on Windows.

23.1.51 CMAKE_LINK_LIBRARY_SUFFIX
---------------------------------

The suffix for libraries that you link to.

The suffix to use for the end of a library filename, ‘.lib’ on Windows.

23.1.52 CMAKE_LINK_SEARCH_END_STATIC
------------------------------------

New in version 3.4.

End a link line such that static system libraries are used.

Some linkers support switches such as ‘-Bstatic’ and ‘-Bdynamic’ to
determine whether to use static or shared libraries for ‘-lXXX’ options.
CMake uses these options to set the link type for libraries whose full
paths are not known or (in some cases) are in implicit link directories
for the platform.  By default CMake adds an option at the end of the
library list (if necessary) to set the linker search type back to its
starting type.  This property switches the final linker search type to
‘-Bstatic’ regardless of how it started.

This variable is used to initialize the target property
LINK_SEARCH_END_STATIC for all targets.  If set, it’s value is
also used by the try_compile() command.

See also CMAKE_LINK_SEARCH_START_STATIC.

23.1.53 CMAKE_LINK_SEARCH_START_STATIC
--------------------------------------

New in version 3.4.

Assume the linker looks for static libraries by default.

Some linkers support switches such as ‘-Bstatic’ and ‘-Bdynamic’ to
determine whether to use static or shared libraries for ‘-lXXX’ options.
CMake uses these options to set the link type for libraries whose full
paths are not known or (in some cases) are in implicit link directories
for the platform.  By default the linker search type is assumed to be
‘-Bdynamic’ at the beginning of the library list.  This property
switches the assumption to ‘-Bstatic’.  It is intended for use when
linking an executable statically (e.g.  with the GNU ‘-static’ option).

This variable is used to initialize the target property
LINK_SEARCH_START_STATIC for all targets.  If set, it’s value is
also used by the try_compile() command.

See also CMAKE_LINK_SEARCH_END_STATIC.

23.1.54 CMAKE_MAJOR_VERSION
---------------------------

First version number component of the CMAKE_VERSION.
variable.

23.1.55 CMAKE_MAKE_PROGRAM
--------------------------

Tool that can launch the native build system.  The value may be the full
path to an executable or just the tool name if it is expected to be in
the ‘PATH’.

The tool selected depends on the CMAKE_GENERATOR used to
configure the project:

   * The Makefile Generators set this to ‘make’, ‘gmake’, or
     a generator-specific tool (e.g.  ‘nmake’ for NMake Makefiles).

     These generators store ‘CMAKE_MAKE_PROGRAM’ in the CMake cache so
     that it may be edited by the user.

   * The Ninja generator sets this to ‘ninja’.

     This generator stores ‘CMAKE_MAKE_PROGRAM’ in the CMake cache so
     that it may be edited by the user.

   * The Xcode generator sets this to ‘xcodebuild’.

     This generator prefers to lookup the build tool at build time
     rather than to store ‘CMAKE_MAKE_PROGRAM’ in the CMake cache ahead
     of time.  This is because ‘xcodebuild’ is easy to find.

     For compatibility with versions of CMake prior to 3.2, if a user or
     project explicitly adds ‘CMAKE_MAKE_PROGRAM’ to the CMake cache
     then CMake will use the specified value.

   * The Visual Studio Generators set this to the full path
     to ‘MSBuild.exe’ (VS >= 10), ‘devenv.com’ (VS 7,8,9), or
     ‘VCExpress.exe’ (VS Express 8,9).  (See also variables
     CMAKE_VS_MSBUILD_COMMAND and CMAKE_VS_DEVENV_COMMAND.

     These generators prefer to lookup the build tool at build time
     rather than to store ‘CMAKE_MAKE_PROGRAM’ in the CMake cache ahead
     of time.  This is because the tools are version-specific and can be
     located using the Windows Registry.  It is also necessary because
     the proper build tool may depend on the project content (e.g.  the
     Intel Fortran plugin to VS 10 and 11 requires ‘devenv.com’ to build
     its ‘.vfproj’ project files even though ‘MSBuild.exe’ is normally
     preferred to support the CMAKE_GENERATOR_TOOLSET).

     For compatibility with versions of CMake prior to 3.0, if a user or
     project explicitly adds ‘CMAKE_MAKE_PROGRAM’ to the CMake cache
     then CMake will use the specified value if possible.

   * The Green Hills MULTI generator sets this to the full
     path to ‘gbuild.exe(Windows)’ or ‘gbuild(Linux)’ based upon the
     toolset being used.

     Once the generator has initialized a particular value for this
     variable, changing the value has undefined behavior.

The ‘CMAKE_MAKE_PROGRAM’ variable is set for use by project code.  The
value is also used by the cmake(1). ‘--build’ and
ctest(1). ‘--build-and-test’ tools to launch the native build
process.

23.1.56 CMAKE_MATCH_COUNT
-------------------------

New in version 3.2.

The number of matches with the last regular expression.

When a regular expression match is used, CMake fills in
CMAKE_MATCH_<n> variables with the match contents.  The
‘CMAKE_MATCH_COUNT’ variable holds the number of match expressions when
these are filled.

23.1.57 CMAKE_MATCH_<n>
-----------------------

New in version 3.9.

Capture group ‘<n>’ matched by the last regular expression, for groups 0
through 9.  Group 0 is the entire match.  Groups 1 through 9 are the
subexpressions captured by ‘()’ syntax.

When a regular expression match is used, CMake fills in
‘CMAKE_MATCH_<n>’ variables with the match contents.  The
CMAKE_MATCH_COUNT variable holds the number of match expressions
when these are filled.

23.1.58 CMAKE_MINIMUM_REQUIRED_VERSION
--------------------------------------

The ‘<min>’ version of CMake given to the most recent call to the
cmake_minimum_required(VERSION) command.

23.1.59 CMAKE_MINOR_VERSION
---------------------------

Second version number component of the CMAKE_VERSION.
variable.

23.1.60 CMAKE_NETRC
-------------------

New in version 3.11.

This variable is used to initialize the ‘NETRC’ option for
file(DOWNLOAD) and file(UPLOAD) commands and the module
ExternalProject.  See those commands for additional
information.

The local option takes precedence over this variable.

23.1.61 CMAKE_NETRC_FILE
------------------------

New in version 3.11.

This variable is used to initialize the ‘NETRC_FILE’ option for
file(DOWNLOAD) and file(UPLOAD) commands and the module
ExternalProject.  See those commands for additional
information.

The local option takes precedence over this variable.

23.1.62 CMAKE_PARENT_LIST_FILE
------------------------------

Full path to the CMake file that included the current one.

While processing a CMake file loaded by include() or
find_package() this variable contains the full path to the file
including it.  The top of the include stack is always the
‘CMakeLists.txt’ for the current directory.  See also
CMAKE_CURRENT_LIST_FILE.

23.1.63 CMAKE_PATCH_VERSION
---------------------------

Third version number component of the CMAKE_VERSION.
variable.

23.1.64 CMAKE_PROJECT_DESCRIPTION
---------------------------------

New in version 3.9.

The description of the top level project.

This variable holds the description of the project as specified in the
top level CMakeLists.txt file by a project() command.  In
the event that the top level CMakeLists.txt contains multiple
project() calls, the most recently called one from that top level
CMakeLists.txt will determine the value that ‘CMAKE_PROJECT_DESCRIPTION’
contains.  For example, consider the following top level CMakeLists.txt:

     cmake_minimum_required(VERSION 3.0)
     project(First DESCRIPTION "I am First")
     project(Second DESCRIPTION "I am Second")
     add_subdirectory(sub)
     project(Third DESCRIPTION "I am Third")

And ‘sub/CMakeLists.txt’ with the following contents:

     project(SubProj DESCRIPTION "I am SubProj")
     message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")

The most recently seen project() command from the top level
CMakeLists.txt would be ‘project(Second ...)’, so this will print:

     CMAKE_PROJECT_DESCRIPTION = I am Second

To obtain the description from the most recent call to project()
in the current directory scope or above, see the
PROJECT_DESCRIPTION variable.

23.1.65 CMAKE_PROJECT_HOMEPAGE_URL
----------------------------------

New in version 3.12.

The homepage URL of the top level project.

This variable holds the homepage URL of the project as specified in the
top level CMakeLists.txt file by a project() command.  In
the event that the top level CMakeLists.txt contains multiple
project() calls, the most recently called one from that top level
CMakeLists.txt will determine the value that
‘CMAKE_PROJECT_HOMEPAGE_URL’ contains.  For example, consider the
following top level CMakeLists.txt:

     cmake_minimum_required(VERSION 3.0)
     project(First HOMEPAGE_URL "http://first.example.com")
     project(Second HOMEPAGE_URL "http://second.example.com")
     add_subdirectory(sub)
     project(Third HOMEPAGE_URL "http://third.example.com")

And ‘sub/CMakeLists.txt’ with the following contents:

     project(SubProj HOMEPAGE_URL "http://subproj.example.com")
     message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}")

The most recently seen project() command from the top level
CMakeLists.txt would be ‘project(Second ...)’, so this will print:

     CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com

To obtain the homepage URL from the most recent call to project()
in the current directory scope or above, see the
PROJECT_HOMEPAGE_URL variable.

23.1.66 CMAKE_PROJECT_NAME
--------------------------

The name of the top level project.

This variable holds the name of the project as specified in the top
level CMakeLists.txt file by a project() command.  In the
event that the top level CMakeLists.txt contains multiple
project() calls, the most recently called one from that top level
CMakeLists.txt will determine the name that ‘CMAKE_PROJECT_NAME’
contains.  For example, consider the following top level CMakeLists.txt:

     cmake_minimum_required(VERSION 3.0)
     project(First)
     project(Second)
     add_subdirectory(sub)
     project(Third)

And ‘sub/CMakeLists.txt’ with the following contents:

     project(SubProj)
     message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")

The most recently seen project() command from the top level
CMakeLists.txt would be ‘project(Second)’, so this will print:

     CMAKE_PROJECT_NAME = Second

To obtain the name from the most recent call to project() in
the current directory scope or above, see the PROJECT_NAME.
variable.

23.1.67 CMAKE_PROJECT_VERSION
-----------------------------

New in version 3.12.

The version of the top level project.

This variable holds the version of the project as specified in the top
level CMakeLists.txt file by a project() command.  In the
event that the top level CMakeLists.txt contains multiple
project() calls, the most recently called one from that top level
CMakeLists.txt will determine the value that ‘CMAKE_PROJECT_VERSION’
contains.  For example, consider the following top level CMakeLists.txt:

     cmake_minimum_required(VERSION 3.0)
     project(First VERSION 1.2.3)
     project(Second VERSION 3.4.5)
     add_subdirectory(sub)
     project(Third VERSION 6.7.8)

And ‘sub/CMakeLists.txt’ with the following contents:

     project(SubProj VERSION 1)
     message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")

The most recently seen project() command from the top level
CMakeLists.txt would be ‘project(Second ...)’, so this will print:

     CMAKE_PROJECT_VERSION = 3.4.5

To obtain the version from the most recent call to project().
in the current directory scope or above, see the PROJECT_VERSION
variable.

23.1.68 CMAKE_PROJECT_VERSION_MAJOR
-----------------------------------

New in version 3.12.

The major version of the top level project.

This variable holds the major version of the project as specified in the
top level CMakeLists.txt file by a project() command.
Please see CMAKE_PROJECT_VERSION documentation for the
behavior when multiple project() commands are used in the
sources.

23.1.69 CMAKE_PROJECT_VERSION_MINOR
-----------------------------------

New in version 3.12.

The minor version of the top level project.

This variable holds the minor version of the project as specified in the
top level CMakeLists.txt file by a project() command.
Please see CMAKE_PROJECT_VERSION documentation for the
behavior when multiple project() commands are used in the
sources.

23.1.70 CMAKE_PROJECT_VERSION_PATCH
-----------------------------------

New in version 3.12.

The patch version of the top level project.

This variable holds the patch version of the project as specified in the
top level CMakeLists.txt file by a project() command.
Please see CMAKE_PROJECT_VERSION documentation for the
behavior when multiple project() commands are used in the
sources.

23.1.71 CMAKE_PROJECT_VERSION_TWEAK
-----------------------------------

New in version 3.12.

The tweak version of the top level project.

This variable holds the tweak version of the project as specified in the
top level CMakeLists.txt file by a project() command.
Please see CMAKE_PROJECT_VERSION documentation for the
behavior when multiple project() commands are used in the
sources.

23.1.72 CMAKE_RANLIB
--------------------

Name of randomizing tool for static libraries.

This specifies name of the program that randomizes libraries on UNIX,
not used on Windows, but may be present.

23.1.73 CMAKE_ROOT
------------------

Install directory for running cmake.

This is the install root for the running CMake and the ‘Modules’
directory can be found here.  This is commonly used in this format:
‘${CMAKE_ROOT}/Modules’

23.1.74 CMAKE_RULE_MESSAGES
---------------------------

New in version 3.13.

Specify whether to report a message for each make rule.

If set in the cache it is used to initialize the value of the
RULE_MESSAGES property.  Users may disable the option in their
local build tree to disable granular messages and report only as each
target completes in Makefile builds.

23.1.75 CMAKE_SCRIPT_MODE_FILE
------------------------------

Full path to the cmake(1). ‘-P’ script file currently being
processed.

When run in cmake(1). ‘-P’ script mode, CMake sets this
variable to the full path of the script file.  When run to configure a
‘CMakeLists.txt’ file, this variable is not set.

23.1.76 CMAKE_SHARED_LIBRARY_PREFIX
-----------------------------------

The prefix for shared libraries that you link to.

The prefix to use for the name of a shared library, ‘lib’ on UNIX.

‘CMAKE_SHARED_LIBRARY_PREFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.77 CMAKE_SHARED_LIBRARY_SUFFIX
-----------------------------------

The suffix for shared libraries that you link to.

The suffix to use for the end of a shared library filename, ‘.dll’ on
Windows.

‘CMAKE_SHARED_LIBRARY_SUFFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.78 CMAKE_SHARED_MODULE_PREFIX
----------------------------------

The prefix for loadable modules that you link to.

The prefix to use for the name of a loadable module on this platform.

‘CMAKE_SHARED_MODULE_PREFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.79 CMAKE_SHARED_MODULE_SUFFIX
----------------------------------

The suffix for shared libraries that you link to.

The suffix to use for the end of a loadable module filename on this
platform

‘CMAKE_SHARED_MODULE_SUFFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.80 CMAKE_SIZEOF_VOID_P
---------------------------

Size of a ‘void’ pointer.

This is set to the size of a pointer on the target machine, and is
determined by a try compile.  If a 64-bit size is found, then the
library search path is modified to look for 64-bit libraries first.

23.1.81 CMAKE_SKIP_INSTALL_RULES
--------------------------------

Whether to disable generation of installation rules.

If ‘TRUE’, CMake will neither generate installation rules nor will it
generate ‘cmake_install.cmake’ files.  This variable is ‘FALSE’ by
default.

23.1.82 CMAKE_SKIP_RPATH
------------------------

If true, do not add run time path information.

If this is set to ‘TRUE’, then the rpath information is not added to
compiled executables.  The default is to add rpath information if the
platform supports it.  This allows for easy running from the build tree.
To omit RPATH in the install step, but not the build step, use
CMAKE_SKIP_INSTALL_RPATH instead.

23.1.83 CMAKE_SOURCE_DIR
------------------------

The path to the top level of the source tree.

This is the full path to the top level of the current CMake source tree.
For an in-source build, this would be the same as
CMAKE_BINARY_DIR.

When run in ‘-P’ script mode, CMake sets the variables
CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR,
CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR.
to the current working directory.

23.1.84 CMAKE_STATIC_LIBRARY_PREFIX
-----------------------------------

The prefix for static libraries that you link to.

The prefix to use for the name of a static library, ‘lib’ on UNIX.

‘CMAKE_STATIC_LIBRARY_PREFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.85 CMAKE_STATIC_LIBRARY_SUFFIX
-----------------------------------

The suffix for static libraries that you link to.

The suffix to use for the end of a static library filename, ‘.lib’ on
Windows.

‘CMAKE_STATIC_LIBRARY_SUFFIX_<LANG>’ overrides this for language
‘<LANG>’.

23.1.86 CMAKE_Swift_MODULE_DIRECTORY
------------------------------------

New in version 3.15.

Swift module output directory.

This variable is used to initialise the Swift_MODULE_DIRECTORY
property on all the targets.  See the target property for
additional information.

23.1.87 CMAKE_Swift_NUM_THREADS
-------------------------------

New in version 3.15.1.

Number of threads for parallel compilation for Swift targets.

This variable controls the number of parallel jobs that the swift driver
creates for building targets.  If not specified, it will default to the
number of logical CPUs on the host.

23.1.88 CMAKE_TOOLCHAIN_FILE
----------------------------

Path to toolchain file supplied to cmake(1).

This variable is specified on the command line when cross-compiling with
CMake.  It is the path to a file which is read early in the CMake run
and which specifies locations for compilers and toolchain utilities, and
other target platform and compiler related information.

23.1.89 CMAKE_TWEAK_VERSION
---------------------------

Defined to ‘0’ for compatibility with code written for older CMake
versions that may have defined higher values.

     Note: In CMake versions 2.8.2 through 2.8.12, this variable holds
     the fourth version number component of the CMAKE_VERSION
     variable.

23.1.90 CMAKE_VERBOSE_MAKEFILE
------------------------------

Enable verbose output from Makefile builds.

This variable is a cache entry initialized (to ‘FALSE’) by the
project() command.  Users may enable the option in their local
build tree to get more verbose output from Makefile builds and show each
command line as it is launched.

23.1.91 CMAKE_VERSION
---------------------

The CMake version string as three non-negative integer components
separated by ‘.’ and possibly followed by ‘-’ and other information.
The first two components represent the feature level and the third
component represents either a bug-fix level or development date.

Release versions and release candidate versions of CMake use the format:

     <major>.<minor>.<patch>[-rc<n>]

where the ‘<patch>’ component is less than ‘20000000’.  Development
versions of CMake use the format:

     <major>.<minor>.<date>[-<id>]

where the ‘<date>’ component is of format ‘CCYYMMDD’ and ‘<id>’ may
contain arbitrary text.  This represents development as of a particular
date following the ‘<major>.<minor>’ feature release.

Individual component values are also available in variables:

   * CMAKE_MAJOR_VERSION.

   * CMAKE_MINOR_VERSION.

   * CMAKE_PATCH_VERSION.

   * CMAKE_TWEAK_VERSION.

Use the if() command ‘VERSION_LESS’, ‘VERSION_GREATER’,
‘VERSION_EQUAL’, ‘VERSION_LESS_EQUAL’, or ‘VERSION_GREATER_EQUAL’
operators to compare version string values against ‘CMAKE_VERSION’ using
a component-wise test.  Version component values may be 10 or larger so
do not attempt to compare version strings as floating-point numbers.

     Note: CMake versions 2.8.2 through 2.8.12 used three components for
     the feature level.  Release versions represented the bug-fix level
     in a fourth component, i.e.
     ‘<major>.<minor>.<patch>[.<tweak>][-rc<n>]’.  Development versions
     represented the development date in the fourth component, i.e.
     ‘<major>.<minor>.<patch>.<date>[-<id>]’.

     CMake versions prior to 2.8.2 used three components for the feature
     level and had no bug-fix component.  Release versions used an
     even-valued second component, i.e.
     ‘<major>.<even-minor>.<patch>[-rc<n>]’.  Development versions used
     an odd-valued second component with the development date as the
     third component, i.e.  ‘<major>.<odd-minor>.<date>’.

     The ‘CMAKE_VERSION’ variable is defined by CMake 2.6.3 and higher.
     Earlier versions defined only the individual component variables.

23.1.92 CMAKE_VS_DEVENV_COMMAND
-------------------------------

The generators for Visual Studio 9 2008 and above set this
variable to the ‘devenv.com’ command installed with the corresponding
Visual Studio version.  Note that this variable may be empty on Visual
Studio Express editions because they do not provide this tool.

This variable is not defined by other generators even if ‘devenv.com’ is
installed on the computer.

The CMAKE_VS_MSBUILD_COMMAND is also provided for
Visual Studio 10 2010 and above.  See also the
CMAKE_MAKE_PROGRAM variable.

23.1.93 CMAKE_VS_MSBUILD_COMMAND
--------------------------------

The generators for Visual Studio 10 2010 and above set this
variable to the ‘MSBuild.exe’ command installed with the corresponding
Visual Studio version.

This variable is not defined by other generators even if ‘MSBuild.exe’
is installed on the computer.

The CMAKE_VS_DEVENV_COMMAND is also provided for the
non-Express editions of Visual Studio.  See also the
CMAKE_MAKE_PROGRAM variable.

23.1.94 CMAKE_VS_NsightTegra_VERSION
------------------------------------

New in version 3.1.

When using a Visual Studio generator with the CMAKE_SYSTEM_NAME
variable set to ‘Android’, this variable contains the version
number of the installed NVIDIA Nsight Tegra Visual Studio Edition.

23.1.95 CMAKE_VS_PLATFORM_NAME
------------------------------

New in version 3.1.

Visual Studio target platform name used by the current generator.

VS 8 and above allow project files to specify a target platform.  CMake
provides the name of the chosen platform in this variable.  See the
CMAKE_GENERATOR_PLATFORM variable for details.

See also the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.

23.1.96 CMAKE_VS_PLATFORM_NAME_DEFAULT
--------------------------------------

New in version 3.14.3.

Default for the Visual Studio target platform name for the current
generator without considering the value of the
CMAKE_GENERATOR_PLATFORM variable.  For Visual Studio Generators
for VS 2017 and below this is always ‘Win32’.  For VS
2019 and above this is based on the host platform.

See also the CMAKE_VS_PLATFORM_NAME variable.

23.1.97 CMAKE_VS_PLATFORM_TOOLSET
---------------------------------

Visual Studio Platform Toolset name.

VS 10 and above use MSBuild under the hood and support multiple compiler
toolchains.  CMake may specify a toolset explicitly, such as ‘v110’ for
VS 11 or ‘Windows7.1SDK’ for 64-bit support in VS 10 Express.  CMake
provides the name of the chosen toolset in this variable.

See the CMAKE_GENERATOR_TOOLSET variable for details.

23.1.98 CMAKE_VS_PLATFORM_TOOLSET_CUDA
--------------------------------------

New in version 3.9.

NVIDIA CUDA Toolkit version whose Visual Studio toolset to use.

The Visual Studio Generators for VS 2010 and above support
using a CUDA toolset provided by a CUDA Toolkit.  The toolset version
number may be specified by a field in CMAKE_GENERATOR_TOOLSET.
of the form ‘cuda=8.0’.  Or it is automatically detected if a path to a
standalone CUDA directory is specified in the form
‘cuda=C:\path\to\cuda’.  If none is specified CMake will choose a
default version.  CMake provides the selected CUDA toolset version in
this variable.  The value may be empty if no CUDA Toolkit with Visual
Studio integration is installed.

23.1.99 CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
-------------------------------------------------

New in version 3.16.

Path to standalone NVIDIA CUDA Toolkit (eg.  extracted from installer).

The Visual Studio Generators for VS 2010 and above support
using a standalone (non-installed) NVIDIA CUDA toolkit.  The path may be
specified by a field in CMAKE_GENERATOR_TOOLSET of the form
‘cuda=C:\path\to\cuda’.  The given directory must at least contain a
folder ‘.\nvcc’ and must provide Visual Studio integration files in path
‘.\CUDAVisualStudioIntegration\extras\
visual_studio_integration\MSBuildExtensions\’.  One can create a
standalone CUDA toolkit directory by either opening a installer with
7zip or copying the files that are extracted by the running installer.
The value may be empty if no path to a standalone CUDA Toolkit was
specified.

23.1.100 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
----------------------------------------------------

New in version 3.8.

Visual Studio preferred tool architecture.

The Visual Studio Generators for VS 2013 and above support
using either the 32-bit or 64-bit host toolchains by specifying a
‘host=x86’ or ‘host=x64’ value in the CMAKE_GENERATOR_TOOLSET.
option.  CMake provides the selected toolchain architecture preference
in this variable (‘x86’, ‘x64’, or empty).

23.1.101 CMAKE_VS_PLATFORM_TOOLSET_VERSION
------------------------------------------

New in version 3.12.

Visual Studio Platform Toolset version.

The Visual Studio Generators for VS 2017 and above allow to
select minor versions of the same toolset.  The toolset version number
may be specified by a field in CMAKE_GENERATOR_TOOLSET of the
form ‘version=14.11’.  If none is specified CMake will choose a default
toolset.  The value may be empty if no minor version was selected and
the default is used.

23.1.102 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
-------------------------------------------------

New in version 3.4.

Visual Studio Windows Target Platform Version.

When targeting Windows 10 and above Visual Studio 2015 and above support
specification of a target Windows version to select a corresponding SDK.
The CMAKE_SYSTEM_VERSION variable may be set to specify a
version.  Otherwise CMake computes a default version based on the
Windows SDK versions available.  The chosen Windows target version
number is provided in ‘CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION’.  If no
Windows 10 SDK is available this value will be empty.

One may set a ‘CMAKE_WINDOWS_KITS_10_DIR’ `environment variable' to an
absolute path to tell CMake to look for Windows 10 SDKs in a custom
location.  The specified directory is expected to contain
‘Include/10.0.*’ directories.

See also CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.

23.1.103 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
---------------------------------------------------------

New in version 3.19.

Override the Windows 10 SDK Maximum Version for VS 2015.

The CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.
variable may be set to a false value (e.g.  ‘OFF’, ‘FALSE’, or ‘0’) or
the SDK version to use as the maximum (e.g.  ‘10.0.14393.0’).  If unset,
the default depends on which version of Visual Studio is targeted by the
current generator.

This can be used in conjunction with CMAKE_SYSTEM_VERSION,
which CMake uses to select
CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.

23.1.104 CMAKE_XCODE_BUILD_SYSTEM
---------------------------------

New in version 3.19.

Xcode build system selection.

The Xcode generator defines this variable to indicate which
variant of the Xcode build system will be used.  The value is the
version of Xcode in which the corresponding build system first became
mature enough for use by CMake.  The possible values are:

‘1’

     The original Xcode build system.  This is the default when using
     Xcode 11.x or below.

‘12’

     The Xcode “new build system” introduced by Xcode 10.  It became
     mature enough for use by CMake in Xcode 12.  This is the default
     when using Xcode 12.x or above.

The ‘CMAKE_XCODE_BUILD_SYSTEM’ variable is informational and should not
be modified by project code.  See the Toolset and Build System Selection
documentation section to select the Xcode build system.

23.1.105 CMAKE_XCODE_PLATFORM_TOOLSET
-------------------------------------

Xcode compiler selection.

Xcode supports selection of a compiler from one of the
installed toolsets.  CMake provides the name of the chosen toolset in
this variable, if any is explicitly selected (e.g.  via the
cmake(1). ‘-T’ option).

23.1.106 <PROJECT-NAME>_BINARY_DIR
----------------------------------

Top level binary directory for the named project.

A variable is created with the name used in the project().
command, and is the binary directory for the project.  This can be
useful when add_subdirectory() is used to connect several
projects.

23.1.107 <PROJECT-NAME>_DESCRIPTION
-----------------------------------

New in version 3.12.

Value given to the ‘DESCRIPTION’ option of the most recent call to the
project() command with project name ‘<PROJECT-NAME>’, if
any.

23.1.108 <PROJECT-NAME>_HOMEPAGE_URL
------------------------------------

New in version 3.12.

Value given to the ‘HOMEPAGE_URL’ option of the most recent call to the
project() command with project name ‘<PROJECT-NAME>’, if
any.

23.1.109 <PROJECT-NAME>_SOURCE_DIR
----------------------------------

Top level source directory for the named project.

A variable is created with the name used in the project().
command, and is the source directory for the project.  This can be
useful when add_subdirectory() is used to connect several
projects.

23.1.110 <PROJECT-NAME>_VERSION
-------------------------------

Value given to the ‘VERSION’ option of the most recent call to the
project() command with project name ‘<PROJECT-NAME>’, if any.

See also the component-wise version variables
<PROJECT-NAME>_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MINOR,
see <PROJECT-NAME>_VERSION_PATCH, and
<PROJECT-NAME>_VERSION_TWEAK.

23.1.111 <PROJECT-NAME>_VERSION_MAJOR
-------------------------------------

First version number component of the <PROJECT-NAME>_VERSION.
variable as set by the project() command.

23.1.112 <PROJECT-NAME>_VERSION_MINOR
-------------------------------------

Second version number component of the <PROJECT-NAME>_VERSION
variable as set by the project() command.

23.1.113 <PROJECT-NAME>_VERSION_PATCH
-------------------------------------

Third version number component of the <PROJECT-NAME>_VERSION.
variable as set by the project() command.

23.1.114 <PROJECT-NAME>_VERSION_TWEAK
-------------------------------------

Fourth version number component of the <PROJECT-NAME>_VERSION
variable as set by the project() command.

23.1.115 PROJECT_BINARY_DIR
---------------------------

Full path to build directory for project.

This is the binary directory of the most recent project().
command.

23.1.116 PROJECT_DESCRIPTION
----------------------------

New in version 3.9.

Short project description given to the project command.

This is the description given to the most recently called
project() command in the current directory scope or above.  To
obtain the description of the top level project, see the
CMAKE_PROJECT_DESCRIPTION variable.

23.1.117 PROJECT_HOMEPAGE_URL
-----------------------------

New in version 3.12.

The homepage URL of the project.

This is the homepage URL given to the most recently called
project() command in the current directory scope or above.  To
obtain the homepage URL of the top level project, see the
CMAKE_PROJECT_HOMEPAGE_URL variable.

23.1.118 PROJECT_NAME
---------------------

Name of the project given to the project command.

This is the name given to the most recently called project().
command in the current directory scope or above.  To obtain the name of
the top level project, see the CMAKE_PROJECT_NAME variable.

23.1.119 PROJECT_SOURCE_DIR
---------------------------

This is the source directory of the last call to the project()
command made in the current directory scope or one of its parents.
Note, it is not affected by calls to project() made within a
child directory scope (i.e.  from within a call to
add_subdirectory() from the current scope).

23.1.120 PROJECT_VERSION
------------------------

Value given to the ‘VERSION’ option of the most recent call to the
project() command, if any.

See also the component-wise version variables
PROJECT_VERSION_MAJOR, PROJECT_VERSION_MINOR,
PROJECT_VERSION_PATCH, and PROJECT_VERSION_TWEAK.

23.1.121 PROJECT_VERSION_MAJOR
------------------------------

First version number component of the PROJECT_VERSION.
variable as set by the project() command.

23.1.122 PROJECT_VERSION_MINOR
------------------------------

Second version number component of the PROJECT_VERSION.
variable as set by the project() command.

23.1.123 PROJECT_VERSION_PATCH
------------------------------

Third version number component of the PROJECT_VERSION.
variable as set by the project() command.

23.1.124 PROJECT_VERSION_TWEAK
------------------------------

Fourth version number component of the PROJECT_VERSION.
variable as set by the project() command.

23.2 Variables that Change Behavior
===================================

23.2.1 BUILD_SHARED_LIBS
------------------------

Global flag to cause add_library() to create shared libraries
if on.

If present and true, this will cause all libraries to be built shared
unless the library was explicitly added as a static library.  This
variable is often added to projects as an option() so that
each user of a project can decide if they want to build the project
using shared or static libraries.

23.2.2 CMAKE_ABSOLUTE_DESTINATION_FILES
---------------------------------------

List of files which have been installed using an ‘ABSOLUTE DESTINATION’
path.

This variable is defined by CMake-generated ‘cmake_install.cmake’
scripts.  It can be used (read-only) by programs or scripts that source
those install scripts.  This is used by some CPack generators (e.g.
RPM).

23.2.3 CMAKE_APPBUNDLE_PATH
---------------------------

Semicolon-separated list of directories specifying a search
path for macOS application bundles used by the find_program(),
and find_package() commands.

23.2.4 CMAKE_AUTOMOC_RELAXED_MODE
---------------------------------

Deprecated since version 3.15.

Switch between strict and relaxed automoc mode.

By default, see AUTOMOC behaves exactly as described in the
documentation of the AUTOMOC target property.  When set to
‘TRUE’, it accepts more input and tries to find the correct input file
for ‘moc’ even if it differs from the documented behaviour.  In this
mode it e.g.  also checks whether a header file is intended to be
processed by moc when a ‘"foo.moc"’ file has been included.

Relaxed mode has to be enabled for KDE4 compatibility.

23.2.5 CMAKE_BACKWARDS_COMPATIBILITY
------------------------------------

Deprecated.  See CMake Policy CMP0001 documentation.

23.2.6 CMAKE_BUILD_TYPE
-----------------------

Specifies the build type on single-configuration generators.

This statically specifies what build type (configuration) will be built
in this build tree.  Possible values are empty, ‘Debug’, ‘Release’,
‘RelWithDebInfo’, ‘MinSizeRel’, … This variable is only meaningful to
single-configuration generators (such as Makefile Generators.
and Ninja) i.e.  those which choose a single configuration
when CMake runs to generate a build tree as opposed to
multi-configuration generators which offer selection of the build
configuration within the generated build environment.  There are many
per-config properties and variables (usually following clean
‘SOME_VAR_<CONFIG>’ order conventions), such as
‘CMAKE_C_FLAGS_<CONFIG>’, specified as uppercase:
‘CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]’.  For
example, in a build tree configured to build type ‘Debug’, CMake will
see to having CMAKE_C_FLAGS_DEBUG settings get added to the
CMAKE_C_FLAGS settings.  See also
CMAKE_CONFIGURATION_TYPES.

23.2.7 CMAKE_CLANG_VFS_OVERLAY
------------------------------

New in version 3.19.

When cross compiling for windows with clang-cl, this variable can be an
absolute path pointing to a clang virtual file system yaml file, which
will enable clang-cl to resolve windows header names on a case sensitive
file system.

23.2.8 CMAKE_CODEBLOCKS_COMPILER_ID
-----------------------------------

New in version 3.11.

Change the compiler id in the generated CodeBlocks project files.

CodeBlocks uses its own compiler id string which differs from
CMAKE_<LANG>_COMPILER_ID.  If this variable is left empty, CMake
tries to recognize the CodeBlocks compiler id automatically.  Otherwise
the specified string is used in the CodeBlocks project file.  See the
CodeBlocks documentation for valid compiler id strings.

Other IDEs like QtCreator that also use the CodeBlocks generator may
ignore this setting.

23.2.9 CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
----------------------------------------------

New in version 3.10.

Change the way the CodeBlocks generator creates project files.

If this variable evaluates to ‘ON’ the generator excludes from the
project file any files that are located outside the project root.

23.2.10 CMAKE_CODELITE_USE_TARGETS
----------------------------------

New in version 3.7.

Change the way the CodeLite generator creates projectfiles.

If this variable evaluates to ‘ON’ at the end of the top-level
‘CMakeLists.txt’ file, the generator creates projectfiles based on
targets rather than projects.

23.2.11 CMAKE_COLOR_MAKEFILE
----------------------------

Enables color output when using the Makefile Generators.

When enabled, the generated Makefiles will produce colored output.
Default is ‘ON’.

23.2.12 CMAKE_CONFIGURATION_TYPES
---------------------------------

Specifies the available build types on multi-config generators.

This specifies what build types (configurations) will be available such
as ‘Debug’, ‘Release’, ‘RelWithDebInfo’ etc.  This has reasonable
defaults on most platforms, but can be extended to provide other build
types.  See also CMAKE_BUILD_TYPE for details of managing
configuration data, and CMAKE_CFG_INTDIR.

23.2.13 CMAKE_DEPENDS_IN_PROJECT_ONLY
-------------------------------------

New in version 3.6.

When set to ‘TRUE’ in a directory, the build system produced by the
Makefile Generators is set up to only consider dependencies
on source files that appear either in the source or in the binary
directories.  Changes to source files outside of these directories will
not cause rebuilds.

This should be used carefully in cases where some source files are
picked up through external headers during the build.

23.2.14 CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
------------------------------------------------

Variable for disabling find_package() calls.

Every non-‘REQUIRED’ find_package() call in a project can be
disabled by setting the variable
‘CMAKE_DISABLE_FIND_PACKAGE_<PackageName>’ to ‘TRUE’.  This can be used
to build a project without an optional package, although that package is
installed.

This switch should be used during the initial CMake run.  Otherwise if
the package has already been found in a previous CMake run, the
variables which have been stored in the cache will still be there.  In
that case it is recommended to remove the cache variables for this
package from the cache using the cache editor or cmake(1). ‘-U’

23.2.15 CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
-----------------------------------------------

New in version 3.6.

This cache variable is used by the Eclipse project generator.  See
cmake-generators(7).

The Eclipse project generator generates so-called linked resources e.g.
to the subproject root dirs in the source tree or to the source files of
targets.  This can be disabled by setting this variable to FALSE.

23.2.16 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
---------------------------------------------

New in version 3.6.

This cache variable is used by the Eclipse project generator.  See
cmake-generators(7).

If this variable is set to TRUE, the Eclipse project generator will
generate an Eclipse project in CMAKE_SOURCE_DIR. .  This
project can then be used in Eclipse e.g.  for the version control
functionality.  See CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.
defaults to FALSE; so nothing is written into the source directory.

23.2.17 CMAKE_ECLIPSE_MAKE_ARGUMENTS
------------------------------------

New in version 3.6.

This cache variable is used by the Eclipse project generator.  See
cmake-generators(7).

This variable holds arguments which are used when Eclipse invokes the
make tool.  By default it is initialized to hold flags to enable
parallel builds (using -j typically).

23.2.18 CMAKE_ECLIPSE_RESOURCE_ENCODING
---------------------------------------

New in version 3.16.

This cache variable tells the Eclipse CDT4 project generator
to set the resource encoding to the given value in generated project
files.  If no value is given, no encoding will be set.

23.2.19 CMAKE_ECLIPSE_VERSION
-----------------------------

New in version 3.6.

This cache variable is used by the Eclipse project generator.  See
cmake-generators(7).

When using the Eclipse project generator, CMake tries to find the
Eclipse executable and detect the version of it.  Depending on the
version it finds, some features are enabled or disabled.  If CMake
doesn’t find Eclipse, it assumes the oldest supported version, Eclipse
Callisto (3.2).

23.2.20 CMAKE_ERROR_DEPRECATED
------------------------------

Whether to issue errors for deprecated functionality.

If ‘TRUE’, use of deprecated functionality will issue fatal errors.  If
this variable is not set, CMake behaves as if it were set to ‘FALSE’.

23.2.21 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
---------------------------------------------------

Ask ‘cmake_install.cmake’ script to error out as soon as a file with
absolute ‘INSTALL DESTINATION’ is encountered.

The fatal error is emitted before the installation of the offending file
takes place.  This variable is used by CMake-generated
‘cmake_install.cmake’ scripts.  If one sets this variable to ‘ON’ while
running the script, it may get fatal error messages from the script.

23.2.22 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
------------------------------------------

New in version 3.15.

If this variable is set to ‘STDERR’, ‘STDOUT’ or ‘NONE’ then commands in
execute_process() calls will be printed to either stderr or
stdout or not at all.

23.2.23 CMAKE_EXPORT_COMPILE_COMMANDS
-------------------------------------

New in version 3.5.

Enable/Disable output of compile commands during generation.

If enabled, generates a ‘compile_commands.json’ file containing the
exact compiler calls for all translation units of the project in
machine-readable form.  The format of the JSON file looks like:

     [
       {
         "directory": "/home/user/development/project",
         "command": "/usr/bin/c++ ... -c ../foo/foo.cc",
         "file": "../foo/foo.cc"
       },

       ...

       {
         "directory": "/home/user/development/project",
         "command": "/usr/bin/c++ ... -c ../foo/bar.cc",
         "file": "../foo/bar.cc"
       }
     ]

This is initialized by the CMAKE_EXPORT_COMPILE_COMMANDS.
environment variable.

     Note: This option is implemented only by Makefile Generators
     and the Ninja.  It is ignored on other generators.

     This option currently does not work well in combination with the
     UNITY_BUILD target property or the
     CMAKE_UNITY_BUILD variable.

23.2.24 CMAKE_EXPORT_PACKAGE_REGISTRY
-------------------------------------

New in version 3.15.

Enables the export(PACKAGE) command when CMP0090.
is set to ‘NEW’.

The export(PACKAGE) command does nothing by default.  In
some cases it is desirable to write to the user package registry, so the
‘CMAKE_EXPORT_PACKAGE_REGISTRY’ variable may be set to enable it.

If CMP0090 is `not' set to ‘NEW’ this variable does nothing,
and the CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable controls
the behavior instead.

See also Disabling the Package Registry.

23.2.25 CMAKE_EXPORT_NO_PACKAGE_REGISTRY
----------------------------------------

New in version 3.1.

Disable the export(PACKAGE) command when CMP0090.
is not set to ‘NEW’.

In some cases, for example for packaging and for system wide
installations, it is not desirable to write the user package registry.
If the ‘CMAKE_EXPORT_NO_PACKAGE_REGISTRY’ variable is enabled, the
export(PACKAGE) command will do nothing.

If CMP0090 is set to ‘NEW’ this variable does nothing, and
the CMAKE_EXPORT_PACKAGE_REGISTRY variable controls the
behavior instead.

See also Disabling the Package Registry.

23.2.26 CMAKE_FIND_APPBUNDLE
----------------------------

New in version 3.4.

This variable affects how ‘find_*’ commands choose between macOS
Application Bundles and unix-style package components.

On Darwin or systems supporting macOS Application Bundles, the
‘CMAKE_FIND_APPBUNDLE’ variable can be set to empty or one of the
following:

‘FIRST’

     Try to find application bundles before standard programs.  This is
     the default on Darwin.

‘LAST’

     Try to find application bundles after standard programs.

‘ONLY’

     Only try to find application bundles.

‘NEVER’

     Never try to find application bundles.

23.2.27 CMAKE_FIND_FRAMEWORK
----------------------------

New in version 3.4.

This variable affects how ‘find_*’ commands choose between macOS
Frameworks and unix-style package components.

On Darwin or systems supporting macOS Frameworks, the
‘CMAKE_FIND_FRAMEWORK’ variable can be set to empty or one of the
following:

‘FIRST’

     Try to find frameworks before standard libraries or headers.  This
     is the default on Darwin.

‘LAST’

     Try to find frameworks after standard libraries or headers.

‘ONLY’

     Only try to find frameworks.

‘NEVER’

     Never try to find frameworks.

23.2.28 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
--------------------------------------------

New in version 3.9.

Specify a ‘<suffix>’ to tell the find_library() command to
search in a ‘lib<suffix>’ directory before each ‘lib’ directory that
would normally be searched.

This overrides the behavior of related global properties:

   * FIND_LIBRARY_USE_LIB32_PATHS.

   * FIND_LIBRARY_USE_LIB64_PATHS.

   * FIND_LIBRARY_USE_LIBX32_PATHS.

23.2.29 CMAKE_FIND_LIBRARY_PREFIXES
-----------------------------------

Prefixes to prepend when looking for libraries.

This specifies what prefixes to add to library names when the
find_library() command looks for libraries.  On UNIX systems this
is typically ‘lib’, meaning that when trying to find the ‘foo’ library
it will look for ‘libfoo’.

23.2.30 CMAKE_FIND_LIBRARY_SUFFIXES
-----------------------------------

Suffixes to append when looking for libraries.

This specifies what suffixes to add to library names when the
find_library() command looks for libraries.  On Windows systems
this is typically ‘.lib’ and ‘.dll’, meaning that when trying to find
the ‘foo’ library it will look for ‘foo.dll’ etc.

23.2.31 CMAKE_FIND_NO_INSTALL_PREFIX
------------------------------------

Exclude the values of the CMAKE_INSTALL_PREFIX and
CMAKE_STAGING_PREFIX variables from
CMAKE_SYSTEM_PREFIX_PATH.  CMake adds these project-destination
prefixes to CMAKE_SYSTEM_PREFIX_PATH by default in order to
support building a series of dependent packages and installing them into
a common prefix.  Set ‘CMAKE_FIND_NO_INSTALL_PREFIX’ to ‘TRUE’ to
suppress this behavior.

The CMAKE_SYSTEM_PREFIX_PATH is initialized on the first
call to a project() or enable_language().
command.  Therefore one must set ‘CMAKE_FIND_NO_INSTALL_PREFIX’ before
this in order to take effect.  A user may set the variable as a cache
entry on the command line to achieve this.

Note that the prefix(es) may still be searched for other reasons, such
as being the same prefix as the CMake installation, or for being a
built-in system prefix.

23.2.32 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
----------------------------------------------

New in version 3.1.

Deprecated since version 3.16: Use the
CMAKE_FIND_USE_PACKAGE_REGISTRY variable instead.

By default this variable is not set.  If neither
CMAKE_FIND_USE_PACKAGE_REGISTRY nor
‘CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY’ is set, then
find_package() will use the User Package Registry.
unless the ‘NO_CMAKE_PACKAGE_REGISTRY’ option is provided.

‘CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY’ is ignored if
CMAKE_FIND_USE_PACKAGE_REGISTRY is set.

In some cases, for example to locate only system wide installations, it
is not desirable to use the User Package Registry when
searching for packages.  If the
CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable is ‘TRUE’, all the
find_package() commands will skip the User Package Registry
as if they were called with the
‘NO_CMAKE_PACKAGE_REGISTRY’ argument.

See also Disabling the Package Registry.

23.2.33 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
-----------------------------------------------------

New in version 3.1.

Deprecated since version 3.16: Use the
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable instead.

By default this variable is not set.  If neither
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY nor
‘CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY’ is set, then
find_package() will use the System Package Registry.
unless the ‘NO_CMAKE_SYSTEM_PACKAGE_REGISTRY’ option is provided.

‘CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY’ is ignored if
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY is set.

In some cases, it is not desirable to use the System Package Registry
when searching for packages.  If the
CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable is ‘TRUE’,
all the find_package() commands will skip the System Package Registry
as if they were called with the
‘NO_CMAKE_SYSTEM_PACKAGE_REGISTRY’ argument.

See also Disabling the Package Registry.

23.2.34 CMAKE_FIND_PACKAGE_PREFER_CONFIG
----------------------------------------

New in version 3.15.

Tell find_package() to try “Config” mode before “Module” mode
if no mode was specified.

The command find_package() operates without an explicit mode
when the reduced signature is used without the ‘MODULE’ option.  In this
case, by default, CMake first tries Module mode by searching for a
‘Find<pkg>.cmake’ module.  If it fails, CMake then searches for the
package using Config mode.

Set ‘CMAKE_FIND_PACKAGE_PREFER_CONFIG’ to ‘TRUE’ to tell
find_package() to first search using Config mode before falling
back to Module mode.

This variable may be useful when a developer has compiled a custom
version of a common library and wishes to link it to a dependent
project.  If this variable is set to ‘TRUE’, it would prevent a
dependent project’s call to find_package() from selecting the
default library located by the system’s ‘Find<pkg>.cmake’ module before
finding the developer’s custom built library.

Once this variable is set, it is the responsibility of the exported
‘<pkg>Config.cmake’ files to provide the same result variables as the
‘Find<pkg>.cmake’ modules so that dependent projects can use them
interchangeably.

23.2.35 CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
-------------------------------------------

New in version 3.14.

Set to ‘TRUE’ to tell find_package() calls to resolve
symbolic links in the value of ‘<PackageName>_DIR’.

This is helpful in use cases where the package search path points at a
proxy directory in which symlinks to the real package locations appear.
This is not enabled by default because there are also common use cases
in which the symlinks should be preserved.

23.2.36 CMAKE_FIND_PACKAGE_WARN_NO_MODULE
-----------------------------------------

Tell find_package() to warn if called without an explicit
mode.

If find_package() is called without an explicit mode option
(‘MODULE’, ‘CONFIG’, or ‘NO_MODULE’) and no ‘Find<pkg>.cmake’ module is
in CMAKE_MODULE_PATH then CMake implicitly assumes that the
caller intends to search for a package configuration file.  If no
package configuration file is found then the wording of the failure
message must account for both the case that the package is really
missing and the case that the project has a bug and failed to provide
the intended Find module.  If instead the caller specifies an explicit
mode option then the failure message can be more specific.

Set ‘CMAKE_FIND_PACKAGE_WARN_NO_MODULE’ to ‘TRUE’ to tell
find_package() to warn when it implicitly assumes Config mode.
This helps developers enforce use of an explicit mode in all calls to
find_package() within a project.

This variable has no effect if CMAKE_FIND_PACKAGE_PREFER_CONFIG
is set to ‘TRUE’.

23.2.37 CMAKE_FIND_ROOT_PATH
----------------------------

Semicolon-separated list of root paths to search on the
filesystem.

This variable is most useful when cross-compiling.  CMake uses the paths
in this list as alternative roots to find filesystem items with
find_package(), find_library() etc.

23.2.38 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
-----------------------------------------

This variable controls whether the CMAKE_FIND_ROOT_PATH and
CMAKE_SYSROOT are used by find_file() and
find_path().

If set to ‘ONLY’, then only the roots in CMAKE_FIND_ROOT_PATH
will be searched.  If set to ‘NEVER’, then the roots in
CMAKE_FIND_ROOT_PATH will be ignored and only the host system root
will be used.  If set to ‘BOTH’, then the host system paths and the
paths in CMAKE_FIND_ROOT_PATH will be searched.

23.2.39 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
-----------------------------------------

This variable controls whether the CMAKE_FIND_ROOT_PATH and
CMAKE_SYSROOT are used by find_library().

If set to ‘ONLY’, then only the roots in CMAKE_FIND_ROOT_PATH
will be searched.  If set to ‘NEVER’, then the roots in
CMAKE_FIND_ROOT_PATH will be ignored and only the host system root
will be used.  If set to ‘BOTH’, then the host system paths and the
paths in CMAKE_FIND_ROOT_PATH will be searched.

23.2.40 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
-----------------------------------------

This variable controls whether the CMAKE_FIND_ROOT_PATH and
CMAKE_SYSROOT are used by find_package().

If set to ‘ONLY’, then only the roots in CMAKE_FIND_ROOT_PATH
will be searched.  If set to ‘NEVER’, then the roots in
CMAKE_FIND_ROOT_PATH will be ignored and only the host system root
will be used.  If set to ‘BOTH’, then the host system paths and the
paths in CMAKE_FIND_ROOT_PATH will be searched.

23.2.41 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
-----------------------------------------

This variable controls whether the CMAKE_FIND_ROOT_PATH and
CMAKE_SYSROOT are used by find_program().

If set to ‘ONLY’, then only the roots in CMAKE_FIND_ROOT_PATH
will be searched.  If set to ‘NEVER’, then the roots in
CMAKE_FIND_ROOT_PATH will be ignored and only the host system root
will be used.  If set to ‘BOTH’, then the host system paths and the
paths in CMAKE_FIND_ROOT_PATH will be searched.

23.2.42 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
---------------------------------------------

New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by cmake-specific environment variables:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of ‘TRUE’.  Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

23.2.43 CMAKE_FIND_USE_CMAKE_PATH
---------------------------------

New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by cmake-specific cache variables:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of ‘TRUE’.  Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

23.2.44 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
----------------------------------------

New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by platform-specific cmake variables:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of ‘TRUE’.  Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

23.2.45 CMAKE_FIND_USE_PACKAGE_REGISTRY
---------------------------------------

New in version 3.16.

Controls the default behavior of the find_package() command
for whether or not to search paths provided by the User Package Registry.

By default this variable is not set and the behavior will fall back to
that determined by the deprecated
CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable.  If that is also
not set, then find_package() will use the User Package Registry
unless the ‘NO_CMAKE_PACKAGE_REGISTRY’ option is
provided.

This variable takes precedence over
CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY when both are set.

In some cases, for example to locate only system wide installations, it
is not desirable to use the User Package Registry when
searching for packages.  If the CMAKE_FIND_USE_PACKAGE_REGISTRY
variable is ‘FALSE’, all the find_package() commands
will skip the User Package Registry as if they were called
with the ‘NO_CMAKE_PACKAGE_REGISTRY’ argument.

See also Disabling the Package Registry and the
CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

23.2.46 CMAKE_FIND_USE_PACKAGE_ROOT_PATH
----------------------------------------

New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by <PackageName>_ROOT.
variables:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

By default this variable is not set, which is equivalent to it having a
value of ‘TRUE’.  Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_REGISTRY variables.

23.2.47 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
----------------------------------------------

New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by standard system environment variables:

   * find_program().

   * find_library().

   * find_file().

   * find_path().

   * find_package().

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of ‘TRUE’.  Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_PACKAGE_REGISTRY,
CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variables.

23.2.48 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
----------------------------------------------

New in version 3.16.

Controls searching the System Package Registry by the
find_package() command.

By default this variable is not set and the behavior will fall back to
that determined by the deprecated
CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable.  If that
is also not set, then find_package() will use the
System Package Registry unless the
‘NO_CMAKE_SYSTEM_PACKAGE_REGISTRY’ option is provided.

This variable takes precedence over
CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY when both are set.

In some cases, for example to locate only user specific installations,
it is not desirable to use the System Package Registry when
searching for packages.  If the ‘CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY’
variable is ‘FALSE’, all the find_package() commands will
skip the System Package Registry as if they were called with
the ‘NO_CMAKE_SYSTEM_PACKAGE_REGISTRY’ argument.

See also Disabling the Package Registry.

See also the CMAKE_FIND_USE_CMAKE_PATH,
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

23.2.49 CMAKE_FRAMEWORK_PATH
----------------------------

Semicolon-separated list of directories specifying a search
path for macOS frameworks used by the find_library(),
find_package(), find_path(), and find_file().
commands.

23.2.50 CMAKE_IGNORE_PATH
-------------------------

Semicolon-separated list of directories to be `ignored' by
the find_program(), find_library(),
find_file(), and find_path() commands.  This is useful
in cross-compiling environments where some system directories contain
incompatible but possibly linkable libraries.  For example, on
cross-compiled cluster environments, this allows a user to ignore
directories containing libraries meant for the front-end machine.

By default this is empty; it is intended to be set by the project.  Note
that ‘CMAKE_IGNORE_PATH’ takes a list of directory names, `not' a list
of prefixes.  To ignore paths under prefixes (‘bin’, ‘include’, ‘lib’,
etc.), specify them explicitly.

See also the CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH,
see CMAKE_INCLUDE_PATH, and CMAKE_PROGRAM_PATH.
variables.

23.2.51 CMAKE_INCLUDE_DIRECTORIES_BEFORE
----------------------------------------

Whether to append or prepend directories by default in
include_directories().

This variable affects the default behavior of the
include_directories() command.  Setting this variable to ‘ON’ is
equivalent to using the ‘BEFORE’ option in all uses of that command.

23.2.52 CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
------------------------------------------------

Whether to force prepending of project include directories.

This variable affects the order of include directories generated in
compiler command lines.  If set to ‘ON’, it causes the
CMAKE_SOURCE_DIR and the CMAKE_BINARY_DIR to appear
first.

23.2.53 CMAKE_INCLUDE_PATH
--------------------------

Semicolon-separated list of directories specifying a search
path for the find_file() and find_path().
commands.  By default it is empty, it is intended to be set by the
project.  See also CMAKE_SYSTEM_INCLUDE_PATH and
CMAKE_PREFIX_PATH.

23.2.54 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
--------------------------------------------

Default component used in install() commands.

If an install() command is used without the ‘COMPONENT’
argument, these files will be grouped into a default component.  The
name of this default install component will be taken from this variable.
It defaults to ‘Unspecified’.

23.2.55 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
---------------------------------------------------

New in version 3.11.

Default permissions for directories created implicitly during
installation of files by install() and file(INSTALL).

If ‘make install’ is invoked and directories are implicitly created they
get permissions set by
CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable or platform
specific default permissions if the variable is not set.

Implicitly created directories are created if they are not explicitly
installed by install() command but are needed to install a
file on a certain path.  Example of such locations are directories
created due to the setting of CMAKE_INSTALL_PREFIX.

Expected content of the
CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable is a list of
permissions that can be used by install() command
‘PERMISSIONS’ section.

Example usage:

     set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
          OWNER_READ
          OWNER_WRITE
          OWNER_EXECUTE
          GROUP_READ
        )

23.2.56 CMAKE_INSTALL_MESSAGE
-----------------------------

New in version 3.1.

Specify verbosity of installation script code generated by the
install() command (using the file(INSTALL) command).
For paths that are newly installed or updated, installation may print
lines like:

     -- Installing: /some/destination/path

For paths that are already up to date, installation may print lines
like:

     -- Up-to-date: /some/destination/path

The ‘CMAKE_INSTALL_MESSAGE’ variable may be set to control which
messages are printed:

‘ALWAYS’

     Print both ‘Installing’ and ‘Up-to-date’ messages.

‘LAZY’

     Print ‘Installing’ but not ‘Up-to-date’ messages.

‘NEVER’

     Print neither ‘Installing’ nor ‘Up-to-date’ messages.

Other values have undefined behavior and may not be diagnosed.

If this variable is not set, the default behavior is ‘ALWAYS’.

23.2.57 CMAKE_INSTALL_PREFIX
----------------------------

Install directory used by install().

If ‘make install’ is invoked or ‘INSTALL’ is built, this directory is
prepended onto all install directories.  This variable defaults to
‘/usr/local’ on UNIX and ‘c:/Program Files/${PROJECT_NAME}’ on Windows.
See CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT for how a
project might choose its own default.

On UNIX one can use the ‘DESTDIR’ mechanism in order to relocate the
whole installation.  See DESTDIR for more information.

The installation prefix is also added to CMAKE_SYSTEM_PREFIX_PATH
so that find_package(), find_program(),
find_library(), find_path(), and find_file().
will search the prefix for other software.

     Note: Use the GNUInstallDirs module to provide
     GNU-style options for the layout of directories within the
     installation.

23.2.58 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
---------------------------------------------------

New in version 3.7.1.

CMake sets this variable to a ‘TRUE’ value when the
CMAKE_INSTALL_PREFIX has just been initialized to its default
value, typically on the first run of CMake within a new build tree.
This can be used by project code to change the default without
overriding a user-provided value:

     if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
       set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
     endif()

23.2.59 CMAKE_LIBRARY_PATH
--------------------------

Semicolon-separated list of directories specifying a search
path for the find_library() command.  By default it is
empty, it is intended to be set by the project.  See also
CMAKE_SYSTEM_LIBRARY_PATH and CMAKE_PREFIX_PATH.

23.2.60 CMAKE_LINK_DIRECTORIES_BEFORE
-------------------------------------

New in version 3.13.

Whether to append or prepend directories by default in
link_directories().

This variable affects the default behavior of the
link_directories() command.  Setting this variable to ‘ON’ is
equivalent to using the ‘BEFORE’ option in all uses of that command.

23.2.61 CMAKE_MFC_FLAG
----------------------

Use the MFC library for an executable or dll.

Enables the use of the Microsoft Foundation Classes (MFC). It should be
set to ‘1’ for the static MFC library, and ‘2’ for the shared MFC
library.  This is used in Visual Studio project files.

Usage example:

     add_definitions(-D_AFXDLL)
     set(CMAKE_MFC_FLAG 2)
     add_executable(CMakeSetup WIN32 ${SRCS})

Contents of ‘CMAKE_MFC_FLAG’ may use generator expressions.

23.2.62 CMAKE_MAXIMUM_RECURSION_DEPTH
-------------------------------------

New in version 3.14.

Maximum recursion depth for CMake scripts.  It is intended to be set on
the command line with ‘-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>’, or within
‘CMakeLists.txt’ by projects that require a large recursion depth.
Projects that set this variable should provide the user with a way to
override it.  For example:

     # About to perform deeply recursive actions
     if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
       set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
     endif()

If it is not set, or is set to a non-integer value, a sensible default
limit is used.  If the recursion limit is reached, the script terminates
immediately with a fatal error.

Calling any of the following commands increases the recursion depth:

   * include().

   * find_package().

   * add_subdirectory().

   * try_compile().

   * ctest_read_custom_files().

   * ctest_run_script(). (unless ‘NEW_PROCESS’ is specified)

   * User-defined function().’s and macro().’s
     (note that function() and macro().
     themselves don’t increase recursion depth)

   * Reading or writing variables that are being watched by a
     variable_watch().

23.2.63 CMAKE_MESSAGE_CONTEXT
-----------------------------

New in version 3.17.

When enabled by the cmake. ‘--log-context’ command line option
or the CMAKE_MESSAGE_CONTEXT_SHOW variable, the
message() command converts the ‘CMAKE_MESSAGE_CONTEXT’ list into a
dot-separated string surrounded by square brackets and prepends it to
each line for messages of log levels ‘NOTICE’ and below.

For logging contexts to work effectively, projects should generally
‘APPEND’ and ‘POP_BACK’ an item to the current value of
‘CMAKE_MESSAGE_CONTEXT’ rather than replace it.  Projects should not
assume the message context at the top of the source tree is empty, as
there are scenarios where the context might have already been set (e.g.
hierarchical projects).

     Warning: Valid context names are restricted to anything that could
     be used as a CMake variable name.  All names that begin with an
     underscore or the string ‘cmake_’ are also reserved for use by
     CMake and should not be used by projects.

Example:

     function(bar)
       list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
       message(VERBOSE "bar VERBOSE message")
     endfunction()

     function(baz)
       list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
       message(DEBUG "baz DEBUG message")
     endfunction()

     function(foo)
       list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
       bar()
       message(TRACE "foo TRACE message")
       baz()
     endfunction()

     list(APPEND CMAKE_MESSAGE_CONTEXT "top")

     message(VERBOSE "Before `foo`")
     foo()
     message(VERBOSE "After `foo`")

     list(POP_BACK CMAKE_MESSAGE_CONTEXT)

Which results in the following output:

     -- [top] Before `foo`
     -- [top.foo.bar] bar VERBOSE message
     -- [top.foo] foo TRACE message
     -- [top.foo.baz] baz DEBUG message
     -- [top] After `foo`

23.2.64 CMAKE_MESSAGE_CONTEXT_SHOW
----------------------------------

New in version 3.17.

Setting this variable to true enables showing a context with each line
logged by the message() command (see
CMAKE_MESSAGE_CONTEXT for how the context itself is specified).

This variable is an alternative to providing the ‘--log-context’ option
on the cmake command line.  Whereas the command line option
will apply only to that one CMake run, setting
‘CMAKE_MESSAGE_CONTEXT_SHOW’ to true as a cache variable will ensure
that subsequent CMake runs will continue to show the message context.

Projects should not set ‘CMAKE_MESSAGE_CONTEXT_SHOW’.  It is intended
for users so that they may control whether or not to include context
with messages.

23.2.65 CMAKE_MESSAGE_INDENT
----------------------------

New in version 3.16.

The message() command joins the strings from this list and
for log levels of ‘NOTICE’ and below, it prepends the resultant string
to each line of the message.

Example:

     list(APPEND listVar one two three)

     message(VERBOSE [[Collected items in the "listVar":]])
     list(APPEND CMAKE_MESSAGE_INDENT "  ")

     foreach(item IN LISTS listVar)
       message(VERBOSE ${item})
     endforeach()

     list(POP_BACK CMAKE_MESSAGE_INDENT)
     message(VERBOSE "No more indent")

Which results in the following output:

     -- Collected items in the "listVar":
     --   one
     --   two
     --   three
     -- No more indent

23.2.66 CMAKE_MESSAGE_LOG_LEVEL
-------------------------------

New in version 3.17.

When set, this variable specifies the logging level used by the
message() command.  Valid values are the same as those for the
‘--log-level’ command line option of the cmake(1) program.  If
this variable is set and the ‘--log-level’ command line option is given,
the command line option takes precedence.

The main advantage to using this variable is to make a log level persist
between CMake runs.  Setting it as a cache variable will ensure that
subsequent CMake runs will continue to use the chosen log level.

Projects should not set this variable, it is intended for users so that
they may control the log level according to their own needs.

23.2.67 CMAKE_MODULE_PATH
-------------------------

Semicolon-separated list of directories specifying a search
path for CMake modules to be loaded by the include() or
find_package() commands before checking the default modules
that come with CMake.  By default it is empty, it is intended to be set
by the project.

23.2.68 CMAKE_POLICY_DEFAULT_CMP<NNNN>
--------------------------------------

Default for CMake Policy ‘CMP<NNNN>’ when it is otherwise left unset.

Commands cmake_minimum_required(VERSION) and
cmake_policy(VERSION) by default leave policies introduced after
the given version unset.  Set ‘CMAKE_POLICY_DEFAULT_CMP<NNNN>’ to ‘OLD’
or ‘NEW’ to specify the default for policy ‘CMP<NNNN>’, where ‘<NNNN>’
is the policy number.

This variable should not be set by a project in CMake code; use
cmake_policy(SET) instead.  Users running CMake may set this
variable in the cache (e.g.
‘-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>’) to set a policy not
otherwise set by the project.  Set to ‘OLD’ to quiet a policy warning
while using old behavior or to ‘NEW’ to try building the project with
new behavior.

23.2.69 CMAKE_POLICY_WARNING_CMP<NNNN>
--------------------------------------

Explicitly enable or disable the warning when CMake Policy ‘CMP<NNNN>’
is not set.  This is meaningful only for the few policies that do not
warn by default:

   * ‘CMAKE_POLICY_WARNING_CMP0025’ controls the warning for policy
     CMP0025.

   * ‘CMAKE_POLICY_WARNING_CMP0047’ controls the warning for policy
     CMP0047.

   * ‘CMAKE_POLICY_WARNING_CMP0056’ controls the warning for policy
     CMP0056.

   * ‘CMAKE_POLICY_WARNING_CMP0060’ controls the warning for policy
     CMP0060.

   * ‘CMAKE_POLICY_WARNING_CMP0065’ controls the warning for policy
     CMP0065.

   * ‘CMAKE_POLICY_WARNING_CMP0066’ controls the warning for policy
     CMP0066.

   * ‘CMAKE_POLICY_WARNING_CMP0067’ controls the warning for policy
     CMP0067.

   * ‘CMAKE_POLICY_WARNING_CMP0082’ controls the warning for policy
     CMP0082.

   * ‘CMAKE_POLICY_WARNING_CMP0089’ controls the warning for policy
     CMP0089.

   * ‘CMAKE_POLICY_WARNING_CMP0102’ controls the warning for policy
     CMP0102.

   * ‘CMAKE_POLICY_WARNING_CMP0112’ controls the warning for policy
     CMP0112.

This variable should not be set by a project in CMake code.  Project
developers running CMake may set this variable in their cache to enable
the warning (e.g.  ‘-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON’).
Alternatively, running cmake(1) with the ‘--debug-output’,
‘--trace’, or ‘--trace-expand’ option will also enable the warning.

23.2.70 CMAKE_PREFIX_PATH
-------------------------

Semicolon-separated list of directories specifying
installation `prefixes' to be searched by the find_package(),
find_program(), find_library(), find_file(),
and find_path() commands.  Each command will add
appropriate subdirectories (like ‘bin’, ‘lib’, or ‘include’) as
specified in its own documentation.

By default this is empty.  It is intended to be set by the project.

See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH,
see CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH, and
CMAKE_IGNORE_PATH.

23.2.71 CMAKE_PROGRAM_PATH
--------------------------

Semicolon-separated list of directories specifying a search
path for the find_program() command.  By default it is
empty, it is intended to be set by the project.  See also
CMAKE_SYSTEM_PROGRAM_PATH and CMAKE_PREFIX_PATH.

23.2.72 CMAKE_PROJECT_INCLUDE
-----------------------------

New in version 3.15.

A CMake language file or module to be included as the last step of all
project() command calls.  This is intended for injecting
custom code into project builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE and
CMAKE_PROJECT_INCLUDE_BEFORE variables.

23.2.73 CMAKE_PROJECT_INCLUDE_BEFORE
------------------------------------

New in version 3.15.

A CMake language file or module to be included as the first step of all
project() command calls.  This is intended for injecting
custom code into project builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE and
CMAKE_PROJECT_INCLUDE variables.

23.2.74 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
--------------------------------------------

A CMake language file or module to be included as the last step of any
project() command calls that specify ‘<PROJECT-NAME>’ as the
project name.  This is intended for injecting custom code into project
builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
CMAKE_PROJECT_INCLUDE and
CMAKE_PROJECT_INCLUDE_BEFORE variables.

23.2.75 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
---------------------------------------------------

New in version 3.17.

A CMake language file or module to be included as the first step of any
project() command calls that specify ‘<PROJECT-NAME>’ as the
project name.  This is intended for injecting custom code into project
builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
CMAKE_PROJECT_INCLUDE and CMAKE_PROJECT_INCLUDE_BEFORE.
variables.

23.2.76 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
-----------------------------------------

Don’t make the ‘install’ target depend on the ‘all’ target.

By default, the ‘install’ target depends on the ‘all’ target.  This has
the effect, that when ‘make install’ is invoked or ‘INSTALL’ is built,
first the ‘all’ target is built, then the installation starts.  If
CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is set to ‘TRUE’, this
dependency is not created, so the installation process will start
immediately, independent from whether the project has been completely
built or not.

23.2.77 CMAKE_STAGING_PREFIX
----------------------------

This variable may be set to a path to install to when cross-compiling.
This can be useful if the path in CMAKE_SYSROOT is
read-only, or otherwise should remain pristine.

The CMAKE_STAGING_PREFIX location is also used as a search
prefix by the ‘find_*’ commands.  This can be controlled by setting the
CMAKE_FIND_NO_INSTALL_PREFIX variable.

If any ‘RPATH’/‘RUNPATH’ entries passed to the linker contain the
CMAKE_STAGING_PREFIX, the matching path fragments are replaced with
the CMAKE_INSTALL_PREFIX.

23.2.78 CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
-----------------------------------------

New in version 3.8.

This variable contains a list of env vars as a list of tokens with the
syntax ‘var=value’.

Example:

     set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
        "FOO=FOO1\;FOO2\;FOON"
        "BAR=BAR1\;BAR2\;BARN"
        "BAZ=BAZ1\;BAZ2\;BAZN"
        "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN"
        "VALID="
        )

In case of malformed variables CMake will fail:

     set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
         "THIS_IS_NOT_VALID"
         )

23.2.79 CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
-----------------------------------------------

New in version 3.8.

If this variable evaluates to ‘ON’ at the end of the top-level
‘CMakeLists.txt’ file, the Sublime Text 2 extra generator
excludes the build tree from the ‘.sublime-project’ if it is inside the
source tree.

23.2.80 CMAKE_SUPPRESS_REGENERATION
-----------------------------------

New in version 3.12.

If ‘CMAKE_SUPPRESS_REGENERATION’ is ‘OFF’, which is default, then CMake
adds a special target on which all other targets depend that checks the
build system and optionally re-runs CMake to regenerate the build system
when the target specification source changes.

If this variable evaluates to ‘ON’ at the end of the top-level
‘CMakeLists.txt’ file, CMake will not add the regeneration target to the
build system or perform any build system checks.

23.2.81 CMAKE_SYSROOT
---------------------

Path to pass to the compiler in the ‘--sysroot’ flag.

The ‘CMAKE_SYSROOT’ content is passed to the compiler in the ‘--sysroot’
flag, if supported.  The path is also stripped from the
‘RPATH’/‘RUNPATH’ if necessary on installation.  The ‘CMAKE_SYSROOT’ is
also used to prefix paths searched by the ‘find_*’ commands.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

See also the CMAKE_SYSROOT_COMPILE and
CMAKE_SYSROOT_LINK variables.

23.2.82 CMAKE_SYSROOT_COMPILE
-----------------------------

New in version 3.9.

Path to pass to the compiler in the ‘--sysroot’ flag when compiling
source files.  This is the same as CMAKE_SYSROOT but is used
only for compiling sources and not linking.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

23.2.83 CMAKE_SYSROOT_LINK
--------------------------

New in version 3.9.

Path to pass to the compiler in the ‘--sysroot’ flag when linking.  This
is the same as CMAKE_SYSROOT but is used only for linking
and not compiling sources.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

23.2.84 CMAKE_SYSTEM_APPBUNDLE_PATH
-----------------------------------

New in version 3.4.

Search path for macOS application bundles used by the
find_program(), and find_package() commands.  By default
it contains the standard directories for the current system.  It is
`not' intended to be modified by the project, use
CMAKE_APPBUNDLE_PATH for this.

23.2.85 CMAKE_SYSTEM_FRAMEWORK_PATH
-----------------------------------

New in version 3.4.

Search path for macOS frameworks used by the find_library(),
find_package(), find_path(), and find_file()
commands.  By default it contains the standard directories for the
current system.  It is `not' intended to be modified by the project, use
CMAKE_FRAMEWORK_PATH for this.

23.2.86 CMAKE_SYSTEM_IGNORE_PATH
--------------------------------

Semicolon-separated list of directories to be `ignored' by
the find_program(), find_library(),
find_file(), and find_path() commands.  This is useful
in cross-compiling environments where some system directories contain
incompatible but possibly linkable libraries.  For example, on
cross-compiled cluster environments, this allows a user to ignore
directories containing libraries meant for the front-end machine.

By default this contains a list of directories containing incompatible
binaries for the host system.  See the CMAKE_IGNORE_PATH.
variable that is intended to be set by the project.

See also the CMAKE_SYSTEM_PREFIX_PATH,
CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_INCLUDE_PATH,
and CMAKE_SYSTEM_PROGRAM_PATH variables.

23.2.87 CMAKE_SYSTEM_INCLUDE_PATH
---------------------------------

Semicolon-separated list of directories specifying a search
path for the find_file() and find_path().
commands.  By default this contains the standard directories for the
current system.  It is `not' intended to be modified by the project; use
CMAKE_INCLUDE_PATH for this.  See also
CMAKE_SYSTEM_PREFIX_PATH.

23.2.88 CMAKE_SYSTEM_LIBRARY_PATH
---------------------------------

Semicolon-separated list of directories specifying a search
path for the find_library() command.  By default this
contains the standard directories for the current system.  It is `not'
intended to be modified by the project; use CMAKE_LIBRARY_PATH
for this.  See also CMAKE_SYSTEM_PREFIX_PATH.

23.2.89 CMAKE_SYSTEM_PREFIX_PATH
--------------------------------

Semicolon-separated list of directories specifying
installation `prefixes' to be searched by the find_package(),
find_program(), find_library(), find_file(),
and find_path() commands.  Each command will add
appropriate subdirectories (like ‘bin’, ‘lib’, or ‘include’) as
specified in its own documentation.

By default this contains the system directories for the current system,
the CMAKE_INSTALL_PREFIX, and the CMAKE_STAGING_PREFIX.
The installation and staging prefixes may be excluded by setting
the CMAKE_FIND_NO_INSTALL_PREFIX variable.

The system directories that are contained in ‘CMAKE_SYSTEM_PREFIX_PATH’
are locations that typically include installed software.  An example
being ‘/usr/local’ for UNIX based platforms.  In addition to standard
platform locations, CMake will also add values to
‘CMAKE_SYSTEM_PREFIX_PATH’ based on environment variables.  The
environment variables and search locations that CMake uses may evolve
over time, as platforms and their conventions also evolve.  The
following provides an indicative list of environment variables and
locations that CMake searches, but they are subject to change:

CrayLinuxEnvironment:

        * ‘ENV{SYSROOT_DIR}/’

        * ‘ENV{SYSROOT_DIR}/usr’

        * ‘ENV{SYSROOT_DIR}/usr/local’

Darwin:

        * ‘ENV{SDKROOT}/usr’ When ‘CMAKE_OSX_SYSROOT’ is not explicitly
          specified.

OpenBSD:

        * ‘ENV{LOCALBASE}’

Unix:

        * ‘ENV{CONDA_PREFIX}’ when using a conda compiler

Windows:

        * ‘ENV{ProgramW6432}’

        * ‘ENV{ProgramFiles}’

        * ‘ENV{ProgramFiles(x86)}’

        * ‘ENV{SystemDrive}/Program Files’

        * ‘ENV{SystemDrive}/Program Files (x86)’

‘CMAKE_SYSTEM_PREFIX_PATH’ is `not' intended to be modified by the
project; use CMAKE_PREFIX_PATH for this.

See also CMAKE_SYSTEM_INCLUDE_PATH,
CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH,
and CMAKE_SYSTEM_IGNORE_PATH.

23.2.90 CMAKE_SYSTEM_PROGRAM_PATH
---------------------------------

Semicolon-separated list of directories specifying a search
path for the find_program() command.  By default this
contains the standard directories for the current system.  It is `not'
intended to be modified by the project; use CMAKE_PROGRAM_PATH
for this.  See also CMAKE_SYSTEM_PREFIX_PATH.

23.2.91 CMAKE_USER_MAKE_RULES_OVERRIDE
--------------------------------------

Specify a CMake file that overrides platform information.

CMake loads the specified file while enabling support for each language
from either the project() or enable_language().
commands.  It is loaded after CMake’s builtin compiler and platform
information modules have been loaded but before the information is used.
The file may set platform information variables to override CMake’s
defaults.

This feature is intended for use only in overriding information
variables that must be set before CMake builds its first test project to
check that the compiler for a language works.  It should not be used to
load a file in cases that a normal include() will work.  Use
it only as a last resort for behavior that cannot be achieved any other
way.  For example, one may set the CMAKE_C_FLAGS_INIT.
variable to change the default value used to initialize the
CMAKE_C_FLAGS variable before it is cached.  The override file
should NOT be used to set anything that could be set after languages are
enabled, such as variables like CMAKE_RUNTIME_OUTPUT_DIRECTORY
that affect the placement of binaries.  Information set in the
file will be used for try_compile() and try_run().
builds too.

23.2.92 CMAKE_WARN_DEPRECATED
-----------------------------

Whether to issue warnings for deprecated functionality.

If not ‘FALSE’, use of deprecated functionality will issue warnings.  If
this variable is not set, CMake behaves as if it were set to ‘TRUE’.

When running cmake(1), this option can be enabled with the
‘-Wdeprecated’ option, or disabled with the ‘-Wno-deprecated’ option.

23.2.93 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
--------------------------------------------------

Ask ‘cmake_install.cmake’ script to warn each time a file with absolute
‘INSTALL DESTINATION’ is encountered.

This variable is used by CMake-generated ‘cmake_install.cmake’ scripts.
If one sets this variable to ‘ON’ while running the script, it may get
warning messages from the script.

23.2.94 CMAKE_XCODE_GENERATE_SCHEME
-----------------------------------

New in version 3.9.

If enabled, the Xcode generator will generate schema files.
These are useful to invoke analyze, archive, build-for-testing and test
actions from the command line.

This variable initializes the XCODE_GENERATE_SCHEME target
property on all targets.

23.2.95 CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
---------------------------------------------------

New in version 3.11.

If enabled, the Xcode generator will generate only a single
Xcode project file for the topmost project() command instead
of generating one for every ‘project()’ command.

This could be useful to speed up the CMake generation step for large
projects and to work-around a bug in the ‘ZERO_CHECK’ logic.

23.2.96 CMAKE_XCODE_LINK_BUILD_PHASE_MODE
-----------------------------------------

New in version 3.19.

This variable is used to initialize the
XCODE_LINK_BUILD_PHASE_MODE property on targets.  It affects the
methods that the Xcode generator uses to link different
kinds of libraries.  Its default value is ‘NONE’.

23.2.97 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
--------------------------------------------

New in version 3.13.

Whether to enable ‘Address Sanitizer’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_ADDRESS_SANITIZER
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.98 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
-------------------------------------------------------------

New in version 3.13.

Whether to enable ‘Detect use of stack after return’ in the Diagnostics
section of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN property on all
targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.99 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
----------------------------------------------------

New in version 3.16.

Whether to enable ‘Allow debugging when using document Versions Browser’
in the Options section of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.100 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
-------------------------------------------------------

New in version 3.13.

Whether to disable the ‘Main Thread Checker’ in the Diagnostics section
of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.101 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
-------------------------------------------------

New in version 3.13.

Whether to enable ‘Dynamic Library Loads’ in the Diagnostics section of
the generated Xcode scheme.

This variable initializes the XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.102 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
----------------------------------------------------

New in version 3.13.

Whether to enable ‘Dynamic Linker API usage’ in the Diagnostics section
of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.103 CMAKE_XCODE_SCHEME_ENVIRONMENT
---------------------------------------

New in version 3.17.

Specify environment variables that should be added to the Arguments
section of the generated Xcode scheme.

If set to a list of environment variables and values of the form
‘MYVAR=value’ those environment variables will be added to the scheme.

This variable initializes the XCODE_SCHEME_ENVIRONMENT.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.104 CMAKE_XCODE_SCHEME_GUARD_MALLOC
----------------------------------------

New in version 3.13.

Whether to enable ‘Guard Malloc’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_GUARD_MALLOC.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.105 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
----------------------------------------------------

New in version 3.13.

Whether to enable the ‘Main Thread Checker’ option ‘Pause on issues’ in
the Diagnostics section of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.106 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
----------------------------------------------

New in version 3.13.

Whether to enable ‘Malloc Guard Edges’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_MALLOC_GUARD_EDGES
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.107 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
-------------------------------------------

New in version 3.13.

Whether to enable ‘Malloc Scribble’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_MALLOC_SCRIBBLE.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.108 CMAKE_XCODE_SCHEME_MALLOC_STACK
----------------------------------------

New in version 3.13.

Whether to enable ‘Malloc Stack’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_MALLOC_STACK.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.109 CMAKE_XCODE_SCHEME_THREAD_SANITIZER
--------------------------------------------

New in version 3.13.

Whether to enable ‘Thread Sanitizer’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_THREAD_SANITIZER.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.110 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
-------------------------------------------------

New in version 3.13.

Whether to enable ‘Thread Sanitizer - Pause on issues’ in the
Diagnostics section of the generated Xcode scheme.

This variable initializes the XCODE_SCHEME_THREAD_SANITIZER_STOP
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.111 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
---------------------------------------------------------

New in version 3.13.

Whether to enable ‘Undefined Behavior Sanitizer’ in the Diagnostics
section of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER property on all
targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.112 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
--------------------------------------------------------------

New in version 3.13.

Whether to enable ‘Undefined Behavior Sanitizer’ option ‘Pause on
issues’ in the Diagnostics section of the generated Xcode scheme.

This variable initializes the
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP property on all
targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.113 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
---------------------------------------------

New in version 3.17.

Specify the ‘Working Directory’ of the `Run' and `Profile' actions in
the generated Xcode scheme.

This variable initializes the XCODE_SCHEME_WORKING_DIRECTORY
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.114 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
------------------------------------------

New in version 3.13.

Whether to enable ‘Zombie Objects’ in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_ZOMBIE_OBJECTS.
property on all targets.

Please refer to the XCODE_GENERATE_SCHEME target property
documentation to see all Xcode schema related properties.

23.2.115 <PackageName>_ROOT
---------------------------

New in version 3.12.

Calls to find_package(<PackageName>) will search in prefixes
specified by the ‘<PackageName>_ROOT’ CMake variable, where
‘<PackageName>’ is the name given to the find_package() call
and ‘_ROOT’ is literal.  For example, ‘find_package(Foo)’ will search
prefixes specified in the ‘Foo_ROOT’ CMake variable (if set).  See
policy CMP0074.

This variable may hold a single prefix or a semicolon-separated list
of multiple prefixes.

See also the <PackageName>_ROOT environment variable.

23.3 Variables that Describe the System
=======================================

23.3.1 ANDROID
--------------

New in version 3.7.

Set to ‘1’ when the target system ( see CMAKE_SYSTEM_NAME) is
‘Android’.

23.3.2 APPLE
------------

Set to ‘True’ when the target system is an Apple platform (macOS, iOS,
tvOS or watchOS).

23.3.3 BORLAND
--------------

‘True’ if the Borland compiler is being used.

This is set to ‘true’ if the Borland compiler is being used.

23.3.4 CMAKE_CL_64
------------------

Discouraged.  Use CMAKE_SIZEOF_VOID_P instead.

Set to a true value when using a Microsoft Visual Studio ‘cl’ compiler
that `targets' a 64-bit architecture.

23.3.5 CMAKE_COMPILER_2005
--------------------------

Using the Visual Studio 2005 compiler from Microsoft

Set to true when using the Visual Studio 2005 compiler from Microsoft.

23.3.6 CMAKE_HOST_APPLE
-----------------------

‘True’ for Apple macOS operating systems.

Set to ‘true’ when the host system is Apple macOS.

23.3.7 CMAKE_HOST_SOLARIS
-------------------------

New in version 3.6.

‘True’ for Oracle Solaris operating systems.

Set to ‘true’ when the host system is Oracle Solaris.

23.3.8 CMAKE_HOST_SYSTEM
------------------------

Composite Name of OS CMake is being run on.

This variable is the composite of CMAKE_HOST_SYSTEM_NAME and
CMAKE_HOST_SYSTEM_VERSION, e.g.
‘${CMAKE_HOST_SYSTEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}’.  If
CMAKE_HOST_SYSTEM_VERSION is not set, then this variable is the
same as CMAKE_HOST_SYSTEM_NAME.

23.3.9 CMAKE_HOST_SYSTEM_NAME
-----------------------------

Name of the OS CMake is running on.

On systems that have the uname command, this variable is set to the
output of ‘uname -s’.  ‘Linux’, ‘Windows’, and ‘Darwin’ for macOS are
the values found on the big three operating systems.

23.3.10 CMAKE_HOST_SYSTEM_PROCESSOR
-----------------------------------

The name of the CPU CMake is running on.

23.3.10.1 Windows Platforms
...........................

On Windows, this variable is set to the value of the environment
variable ‘PROCESSOR_ARCHITECTURE’.

23.3.10.2 Unix Platforms
........................

On systems that support ‘uname’, this variable is set to the output of:

   - ‘uname -m’ on GNU, Linux, Cygwin, Android, or

   - ‘arch’ on OpenBSD, or

   - on other systems,

        * ‘uname -p’ if its exit code is nonzero, or

        * ‘uname -m’ otherwise.

23.3.10.3 macOS Platforms
.........................

The value of ‘uname -m’ is used by default.

On Apple Silicon hosts, the architecture printed by ‘uname -m’ may vary
based on CMake’s own architecture and that of the invoking process tree.

New in version 3.19.2: On Apple Silicon hosts:

   * The CMAKE_APPLE_SILICON_PROCESSOR variable or the
     CMAKE_APPLE_SILICON_PROCESSOR environment variable may be set
     to specify the host architecture explicitly.

   * If CMAKE_OSX_ARCHITECTURES is not set, CMake adds
     explicit flags to tell the compiler to build for the host
     architecture so the toolchain does not have to guess based on the
     process tree’s architecture.

23.3.11 CMAKE_HOST_SYSTEM_VERSION
---------------------------------

The OS version CMake is running on.

A numeric version string for the system.  On systems that support
‘uname’, this variable is set to the output of ‘uname -r’.  On other
systems this is set to major-minor version numbers.

23.3.12 CMAKE_HOST_UNIX
-----------------------

‘True’ for UNIX and UNIX like operating systems.

Set to ‘true’ when the host system is UNIX or UNIX like (i.e.  APPLE and
CYGWIN).

23.3.13 CMAKE_HOST_WIN32
------------------------

‘True’ if the host system is running Windows, including Windows 64-bit
and MSYS.

Set to ‘false’ on Cygwin.

23.3.14 CMAKE_LIBRARY_ARCHITECTURE
----------------------------------

Target architecture library directory name, if detected.

This is the value of CMAKE_<LANG>_LIBRARY_ARCHITECTURE as
detected for one of the enabled languages.

23.3.15 CMAKE_LIBRARY_ARCHITECTURE_REGEX
----------------------------------------

Regex matching possible target architecture library directory names.

This is used to detect CMAKE_<LANG>_LIBRARY_ARCHITECTURE.
from the implicit linker search path by matching the ‘<arch>’ name.

23.3.16 CMAKE_OBJECT_PATH_MAX
-----------------------------

Maximum object file full-path length allowed by native build tools.

CMake computes for every source file an object file name that is unique
to the source file and deterministic with respect to the full path to
the source file.  This allows multiple source files in a target to share
the same name if they lie in different directories without rebuilding
when one is added or removed.  However, it can produce long full paths
in a few cases, so CMake shortens the path using a hashing scheme when
the full path to an object file exceeds a limit.  CMake has a built-in
limit for each platform that is sufficient for common tools, but some
native tools may have a lower limit.  This variable may be set to
specify the limit explicitly.  The value must be an integer no less than
128.

23.3.17 CMAKE_SYSTEM
--------------------

Composite name of operating system CMake is compiling for.

This variable is the composite of CMAKE_SYSTEM_NAME and
CMAKE_SYSTEM_VERSION, e.g.
‘${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VERSION}’.  If
CMAKE_SYSTEM_VERSION is not set, then this variable is the same
as CMAKE_SYSTEM_NAME.

23.3.18 CMAKE_SYSTEM_NAME
-------------------------

The name of the operating system for which CMake is to build.  See the
CMAKE_SYSTEM_VERSION variable for the OS version.

Note that ‘CMAKE_SYSTEM_NAME’ is not set to anything by default when
running in script mode, since it’s not building anything.

23.3.18.1 System Name for Host Builds
.....................................

‘CMAKE_SYSTEM_NAME’ is by default set to the same value as the
CMAKE_HOST_SYSTEM_NAME variable so that the build targets the host
system.

23.3.18.2 System Name for Cross Compiling
.........................................

‘CMAKE_SYSTEM_NAME’ may be set explicitly when first configuring a new
build tree in order to enable cross compiling.  In this case
the CMAKE_SYSTEM_VERSION variable must also be set
explicitly.

23.3.19 CMAKE_SYSTEM_PROCESSOR
------------------------------

The name of the CPU CMake is building for.

This variable is the same as CMAKE_HOST_SYSTEM_PROCESSOR if
you build for the host system instead of the target system when cross
compiling.

23.3.20 CMAKE_SYSTEM_VERSION
----------------------------

The version of the operating system for which CMake is to build.  See
the CMAKE_SYSTEM_NAME variable for the OS name.

23.3.20.1 System Version for Host Builds
........................................

When the CMAKE_SYSTEM_NAME variable takes its default value
then ‘CMAKE_SYSTEM_VERSION’ is by default set to the same value as the
CMAKE_HOST_SYSTEM_VERSION variable so that the build
targets the host system version.

In the case of a host build then ‘CMAKE_SYSTEM_VERSION’ may be set
explicitly when first configuring a new build tree in order to enable
targeting the build for a different version of the host operating system
than is actually running on the host.  This is allowed and not
considered cross compiling so long as the binaries built for the
specified OS version can still run on the host.

23.3.20.2 System Version for Cross Compiling
............................................

When the CMAKE_SYSTEM_NAME variable is set explicitly to
enable cross compiling then the value of
‘CMAKE_SYSTEM_VERSION’ must also be set explicitly to specify the target
system version.

23.3.21 CYGWIN
--------------

‘True’ for Cygwin.

Set to ‘true’ when using Cygwin.

23.3.22 GHS-MULTI
-----------------

New in version 3.3.

‘True’ when using Green Hills MULTI generator.

23.3.23 IOS
-----------

New in version 3.14.

Set to ‘1’ when the target system ( see CMAKE_SYSTEM_NAME) is
‘iOS’.

23.3.24 MINGW
-------------

New in version 3.2.

‘True’ when using MinGW

Set to ‘true’ when the compiler is some version of MinGW.

23.3.25 MSVC
------------

Set to ‘true’ when the compiler is some version of Microsoft Visual C++
or another compiler simulating Visual C++.  Any compiler defining
‘_MSC_VER’ is considered simulating Visual C++.

See also the MSVC_VERSION variable.

23.3.26 MSVC10
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v100’ toolset (‘cl’
version 16) or another compiler that simulates it.

23.3.27 MSVC11
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v110’ toolset (‘cl’
version 17) or another compiler that simulates it.

23.3.28 MSVC12
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v120’ toolset (‘cl’
version 18) or another compiler that simulates it.

23.3.29 MSVC14
--------------

New in version 3.1.

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v140’ or ‘v141’ toolset
(‘cl’ version 19) or another compiler that simulates it.

23.3.30 MSVC60
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using Microsoft Visual C++ 6.0.

Set to ‘true’ when the compiler is version 6.0 of Microsoft Visual C++.

23.3.31 MSVC70
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using Microsoft Visual C++ 7.0.

Set to ‘true’ when the compiler is version 7.0 of Microsoft Visual C++.

23.3.32 MSVC71
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using Microsoft Visual C++ 7.1.

Set to ‘true’ when the compiler is version 7.1 of Microsoft Visual C++.

23.3.33 MSVC80
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v80’ toolset (‘cl’
version 14) or another compiler that simulates it.

23.3.34 MSVC90
--------------

Discouraged.  Use the MSVC_VERSION variable instead.

‘True’ when using the Microsoft Visual Studio ‘v90’ toolset (‘cl’
version 15) or another compiler that simulates it.

23.3.35 MSVC_IDE
----------------

‘True’ when using the Microsoft Visual C++ IDE.

Set to ‘true’ when the target platform is the Microsoft Visual C++ IDE,
as opposed to the command line compiler.

23.3.36 MSVC_TOOLSET_VERSION
----------------------------

New in version 3.12.

The toolset version of Microsoft Visual C/C++ being used if any.  If
MSVC-like is being used, this variable is set based on the version of
the compiler as given by the MSVC_VERSION variable.

Known toolset version numbers are:

     80        = VS 2005 (8.0)
     90        = VS 2008 (9.0)
     100       = VS 2010 (10.0)
     110       = VS 2012 (11.0)
     120       = VS 2013 (12.0)
     140       = VS 2015 (14.0)
     141       = VS 2017 (15.0)
     142       = VS 2019 (16.0)

Compiler versions newer than those known to CMake will be reported as
the latest known toolset version.

See also the MSVC_VERSION variable.

23.3.37 MSVC_VERSION
--------------------

The version of Microsoft Visual C/C++ being used if any.  If a compiler
simulating Visual C++ is being used, this variable is set to the toolset
version simulated as given by the ‘_MSC_VER’ preprocessor definition.

Known version numbers are:

     1200      = VS  6.0
     1300      = VS  7.0
     1310      = VS  7.1
     1400      = VS  8.0 (v80 toolset)
     1500      = VS  9.0 (v90 toolset)
     1600      = VS 10.0 (v100 toolset)
     1700      = VS 11.0 (v110 toolset)
     1800      = VS 12.0 (v120 toolset)
     1900      = VS 14.0 (v140 toolset)
     1910-1919 = VS 15.0 (v141 toolset)
     1920-1929 = VS 16.0 (v142 toolset)

See also the CMAKE_<LANG>_COMPILER_VERSION and
MSVC_TOOLSET_VERSION variable.

23.3.38 MSYS
------------

New in version 3.14.

‘True’ when using the MSYS Makefiles generator.

23.3.39 UNIX
------------

Set to ‘True’ when the target system is UNIX or UNIX-like (e.g.  see
APPLE and CYGWIN).  The CMAKE_SYSTEM_NAME
variable should be queried if a more specific understanding of the
target system is required.

23.3.40 WIN32
-------------

Set to ‘True’ when the target system is Windows, including Win64.

23.3.41 WINCE
-------------

New in version 3.1.

True when the CMAKE_SYSTEM_NAME variable is set to
‘WindowsCE’.

23.3.42 WINDOWS_PHONE
---------------------

New in version 3.1.

True when the CMAKE_SYSTEM_NAME variable is set to
‘WindowsPhone’.

23.3.43 WINDOWS_STORE
---------------------

New in version 3.1.

True when the CMAKE_SYSTEM_NAME variable is set to
‘WindowsStore’.

23.3.44 XCODE
-------------

New in version 3.7.

‘True’ when using Xcode generator.

23.3.45 XCODE_VERSION
---------------------

Version of Xcode ( see Xcode generator only).

Under the Xcode generator, this is the version of Xcode as
specified in ‘Xcode.app/Contents/version.plist’ (such as ‘3.1.2’).

23.4 Variables that Control the Build
=====================================

23.4.1 CMAKE_AIX_EXPORT_ALL_SYMBOLS
-----------------------------------

New in version 3.17.

Default value for AIX_EXPORT_ALL_SYMBOLS target property.
This variable is used to initialize the property on each target as it is
created.

23.4.2 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
-------------------------------------------

New in version 3.4.

Default value for the ANDROID_ANT_ADDITIONAL_OPTIONS target
property.  See that target property for additional information.

23.4.3 CMAKE_ANDROID_API
------------------------

New in version 3.1.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this variable may be set to specify the default
value for the ANDROID_API target property.  See that target
property for additional information.

Otherwise, when Cross Compiling for Android, this variable
provides the Android API version number targeted.  This will be the same
value as the CMAKE_SYSTEM_VERSION variable for ‘Android’
platforms.

23.4.4 CMAKE_ANDROID_API_MIN
----------------------------

New in version 3.2.

Default value for the ANDROID_API_MIN target property.  See
that target property for additional information.

23.4.5 CMAKE_ANDROID_ARCH
-------------------------

New in version 3.4.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this variable may be set to specify the default
value for the ANDROID_ARCH target property.  See that target
property for additional information.

Otherwise, when Cross Compiling for Android, this variable
provides the name of the Android architecture corresponding to the value
of the CMAKE_ANDROID_ARCH_ABI variable.  The architecture
name may be one of:

   * ‘arm’

   * ‘arm64’

   * ‘mips’

   * ‘mips64’

   * ‘x86’

   * ‘x86_64’

23.4.6 CMAKE_ANDROID_ARCH_ABI
-----------------------------

New in version 3.7.

When Cross Compiling for Android, this variable specifies
the target architecture and ABI to be used.  Valid values are:

   * ‘arm64-v8a’

   * ‘armeabi-v7a’

   * ‘armeabi-v6’

   * ‘armeabi’

   * ‘mips’

   * ‘mips64’

   * ‘x86’

   * ‘x86_64’

See also the CMAKE_ANDROID_ARM_MODE and
CMAKE_ANDROID_ARM_NEON variables.

23.4.7 CMAKE_ANDROID_ARM_MODE
-----------------------------

New in version 3.7.

When Cross Compiling for Android and
CMAKE_ANDROID_ARCH_ABI is set to one of the ‘armeabi’
architectures, set ‘CMAKE_ANDROID_ARM_MODE’ to ‘ON’ to target 32-bit ARM
processors (‘-marm’).  Otherwise, the default is to target the 16-bit
Thumb processors (‘-mthumb’).

23.4.8 CMAKE_ANDROID_ARM_NEON
-----------------------------

New in version 3.7.

When Cross Compiling for Android and
CMAKE_ANDROID_ARCH_ABI is set to ‘armeabi-v7a’ set
‘CMAKE_ANDROID_ARM_NEON’ to ‘ON’ to target ARM NEON devices.

23.4.9 CMAKE_ANDROID_ASSETS_DIRECTORIES
---------------------------------------

New in version 3.4.

Default value for the ANDROID_ASSETS_DIRECTORIES target
property.  See that target property for additional information.

23.4.10 CMAKE_ANDROID_GUI
-------------------------

New in version 3.1.

Default value for the ANDROID_GUI target property of
executables.  See that target property for additional information.

23.4.11 CMAKE_ANDROID_JAR_DEPENDENCIES
--------------------------------------

New in version 3.4.

Default value for the ANDROID_JAR_DEPENDENCIES target
property.  See that target property for additional information.

23.4.12 CMAKE_ANDROID_JAR_DIRECTORIES
-------------------------------------

New in version 3.4.

Default value for the ANDROID_JAR_DIRECTORIES target
property.  See that target property for additional information.

23.4.13 CMAKE_ANDROID_JAVA_SOURCE_DIR
-------------------------------------

New in version 3.4.

Default value for the ANDROID_JAVA_SOURCE_DIR target
property.  See that target property for additional information.

23.4.14 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
---------------------------------------------

New in version 3.4.

Default value for the ANDROID_NATIVE_LIB_DEPENDENCIES target
property.  See that target property for additional information.

23.4.15 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
--------------------------------------------

New in version 3.4.

Default value for the ANDROID_NATIVE_LIB_DIRECTORIES target
property.  See that target property for additional information.

23.4.16 CMAKE_ANDROID_NDK
-------------------------

New in version 3.7.

When Cross Compiling for Android with the NDK, this variable
holds the absolute path to the root directory of the NDK. The directory
must contain a ‘platforms’ subdirectory holding the ‘android-<api>’
directories.

23.4.17 CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
--------------------------------------------

New in version 3.9.

When Cross Compiling for Android with the NDK, this variable
may be set to specify whether to use the deprecated per-api-level
headers instead of the unified headers.

If not specified, the default will be `false' if using a NDK version
that provides the unified headers and `true' otherwise.

23.4.18 CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
--------------------------------------------

New in version 3.7.1.

When Cross Compiling for Android with the NDK, this variable
provides the NDK’s “host tag” used to construct the path to prebuilt
toolchains that run on the host.

23.4.19 CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
-------------------------------------------

New in version 3.7.

When Cross Compiling for Android with the NDK, this variable
may be set to specify the version of the toolchain to be used as the
compiler.

On NDK r19 or above, this variable must be unset or set to ‘clang’.

On NDK r18 or below, this variable must be set to one of these forms:

   * ‘<major>.<minor>’: GCC of specified version

   * ‘clang<major>.<minor>’: Clang of specified version

   * ‘clang’: Clang of most recent available version

A toolchain of the requested version will be selected automatically to
match the ABI named in the CMAKE_ANDROID_ARCH_ABI variable.

If not specified, the default will be a value that selects the latest
available GCC toolchain.

23.4.20 CMAKE_ANDROID_PROCESS_MAX
---------------------------------

New in version 3.4.

Default value for the ANDROID_PROCESS_MAX target property.
See that target property for additional information.

23.4.21 CMAKE_ANDROID_PROGUARD
------------------------------

New in version 3.4.

Default value for the ANDROID_PROGUARD target property.  See
that target property for additional information.

23.4.22 CMAKE_ANDROID_PROGUARD_CONFIG_PATH
------------------------------------------

New in version 3.4.

Default value for the ANDROID_PROGUARD_CONFIG_PATH target
property.  See that target property for additional information.

23.4.23 CMAKE_ANDROID_SECURE_PROPS_PATH
---------------------------------------

New in version 3.4.

Default value for the ANDROID_SECURE_PROPS_PATH target
property.  See that target property for additional information.

23.4.24 CMAKE_ANDROID_SKIP_ANT_STEP
-----------------------------------

New in version 3.4.

Default value for the ANDROID_SKIP_ANT_STEP target property.
See that target property for additional information.

23.4.25 CMAKE_ANDROID_STANDALONE_TOOLCHAIN
------------------------------------------

New in version 3.7.

When Cross Compiling for Android with a Standalone Toolchain,
this variable holds the absolute path to the root directory of the
toolchain.  The specified directory must contain a ‘sysroot’
subdirectory.

23.4.26 CMAKE_ANDROID_STL_TYPE
------------------------------

New in version 3.4.

When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition,
this variable may be set to specify the default
value for the ANDROID_STL_TYPE target property.  See that
target property for additional information.

When Cross Compiling for Android with the NDK, this variable
may be set to specify the STL variant to be used.  The value may be one
of:

‘none’

     No C++ Support

‘system’

     Minimal C++ without STL

‘gabi++_static’

     GAbi++ Static

‘gabi++_shared’

     GAbi++ Shared

‘gnustl_static’

     GNU libstdc++ Static

‘gnustl_shared’

     GNU libstdc++ Shared

‘c++_static’

     LLVM libc++ Static

‘c++_shared’

     LLVM libc++ Shared

‘stlport_static’

     STLport Static

‘stlport_shared’

     STLport Shared

The default value is ‘gnustl_static’ on NDK versions that provide it and
otherwise ‘c++_static’.  Note that this default differs from the native
NDK build system because CMake may be used to build projects for Android
that are not natively implemented for it and use the C++ standard
library.

23.4.27 CMAKE_APPLE_SILICON_PROCESSOR
-------------------------------------

New in version 3.19.2.

On Apple Silicon hosts running macOS, set this variable to tell CMake
what architecture to use for CMAKE_HOST_SYSTEM_PROCESSOR.
The value must be either ‘arm64’ or ‘x86_64’.

The value of this variable should never be modified by project code.  It
is meant to be set by a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable, or as a cache entry provided by the
user, e.g.  via ‘-DCMAKE_APPLE_SILICON_PROCESSOR=...’.

See also the CMAKE_APPLE_SILICON_PROCESSOR environment
variable.

23.4.28 CMAKE_ARCHIVE_OUTPUT_DIRECTORY
--------------------------------------

Where to put all the ARCHIVE target files when built.

This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY
property on all the targets.  See that target property for
additional information.

23.4.29 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
-----------------------------------------------

New in version 3.3.

Where to put all the ARCHIVE target files when built for a
specific configuration.

This variable is used to initialize the
ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> property on all the targets.
See that target property for additional information.

23.4.30 CMAKE_AUTOGEN_ORIGIN_DEPENDS
------------------------------------

New in version 3.14.

Switch for forwarding origin target dependencies to the corresponding
‘_autogen’ targets.

This variable is used to initialize the AUTOGEN_ORIGIN_DEPENDS
property on all the targets.  See that target property for
additional information.

By default CMAKE_AUTOGEN_ORIGIN_DEPENDS is ‘ON’.

23.4.31 CMAKE_AUTOGEN_PARALLEL
------------------------------

New in version 3.11.

Number of parallel ‘moc’ or ‘uic’ processes to start when using
AUTOMOC and AUTOUIC.

This variable is used to initialize the AUTOGEN_PARALLEL.
property on all the targets.  See that target property for additional
information.

By default CMAKE_AUTOGEN_PARALLEL is unset.

23.4.32 CMAKE_AUTOGEN_VERBOSE
-----------------------------

New in version 3.13.

Sets the verbosity of AUTOMOC, AUTOUIC and
AUTORCC.  A positive integer value or a true boolean value lets the
‘AUTO*’ generators output additional processing information.

Setting CMAKE_AUTOGEN_VERBOSE has the same effect as
setting the ‘VERBOSE’ environment variable during generation (e.g.  by
calling ‘make VERBOSE=1’).  The extra verbosity is limited to the
‘AUTO*’ generators though.

By default CMAKE_AUTOGEN_VERBOSE is unset.

23.4.33 CMAKE_AUTOMOC
---------------------

Whether to handle ‘moc’ automatically for Qt targets.

This variable is used to initialize the AUTOMOC property on
all the targets.  See that target property for additional information.

23.4.34 CMAKE_AUTOMOC_COMPILER_PREDEFINES
-----------------------------------------

New in version 3.10.

This variable is used to initialize the
AUTOMOC_COMPILER_PREDEFINES property on all the targets.  See that
target property for additional information.

By default it is ON.

23.4.35 CMAKE_AUTOMOC_DEPEND_FILTERS
------------------------------------

New in version 3.9.

Filter definitions used by CMAKE_AUTOMOC to extract file
names from source code as additional dependencies for the ‘moc’ file.

This variable is used to initialize the AUTOMOC_DEPEND_FILTERS
property on all the targets.  See that target property for
additional information.

By default it is empty.

23.4.36 CMAKE_AUTOMOC_MACRO_NAMES
---------------------------------

New in version 3.10.

Semicolon-separated list list of macro names used by
CMAKE_AUTOMOC to determine if a C++ file needs to be processed by
‘moc’.

This variable is used to initialize the AUTOMOC_MACRO_NAMES.
property on all the targets.  See that target property for additional
information.

The default value is ‘Q_OBJECT;Q_GADGET;Q_NAMESPACE’.

23.4.36.1 Example
.................

Let CMake know that source files that contain ‘CUSTOM_MACRO’ must be
‘moc’ processed as well:

     set(CMAKE_AUTOMOC ON)
     list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")

23.4.37 CMAKE_AUTOMOC_MOC_OPTIONS
---------------------------------

Additional options for ‘moc’ when using CMAKE_AUTOMOC.

This variable is used to initialize the AUTOMOC_MOC_OPTIONS.
property on all the targets.  See that target property for additional
information.

23.4.38 CMAKE_AUTOMOC_PATH_PREFIX
---------------------------------

New in version 3.16.

Whether to generate the ‘-p’ path prefix option for ‘moc’ on
AUTOMOC enabled Qt targets.

This variable is used to initialize the AUTOMOC_PATH_PREFIX.
property on all the targets.  See that target property for additional
information.

The default value is ‘OFF’.

23.4.39 CMAKE_AUTORCC
---------------------

Whether to handle ‘rcc’ automatically for Qt targets.

This variable is used to initialize the AUTORCC property on
all the targets.  See that target property for additional information.

23.4.40 CMAKE_AUTORCC_OPTIONS
-----------------------------

Additional options for ‘rcc’ when using CMAKE_AUTORCC.

This variable is used to initialize the AUTORCC_OPTIONS.
property on all the targets.  See that target property for additional
information.

23.4.40.1 EXAMPLE
.................

     # ...
     set(CMAKE_AUTORCC_OPTIONS "--compress;9")
     # ...

23.4.41 CMAKE_AUTOUIC
---------------------

Whether to handle ‘uic’ automatically for Qt targets.

This variable is used to initialize the AUTOUIC property on
all the targets.  See that target property for additional information.

23.4.42 CMAKE_AUTOUIC_OPTIONS
-----------------------------

Additional options for ‘uic’ when using CMAKE_AUTOUIC.

This variable is used to initialize the AUTOUIC_OPTIONS.
property on all the targets.  See that target property for additional
information.

23.4.42.1 EXAMPLE
.................

     # ...
     set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection")
     # ...

23.4.43 CMAKE_AUTOUIC_SEARCH_PATHS
----------------------------------

New in version 3.9.

Search path list used by CMAKE_AUTOUIC to find included
‘.ui’ files.

This variable is used to initialize the AUTOUIC_SEARCH_PATHS.
property on all the targets.  See that target property for additional
information.

By default it is empty.

23.4.44 CMAKE_BUILD_RPATH
-------------------------

New in version 3.8.

Semicolon-separated list specifying runtime path (‘RPATH’)
entries to add to binaries linked in the build tree (for platforms that
support it).  The entries will `not' be used for binaries in the install
tree.  See also the CMAKE_INSTALL_RPATH variable.

This is used to initialize the BUILD_RPATH target property
for all targets.

23.4.45 CMAKE_BUILD_RPATH_USE_ORIGIN
------------------------------------

New in version 3.14.

Whether to use relative paths for the build ‘RPATH’.

This is used to initialize the BUILD_RPATH_USE_ORIGIN target
property for all targets, see that property for more details.

23.4.46 CMAKE_BUILD_WITH_INSTALL_NAME_DIR
-----------------------------------------

New in version 3.9.

Whether to use INSTALL_NAME_DIR on targets in the build
tree.

This variable is used to initialize the
BUILD_WITH_INSTALL_NAME_DIR property on all targets.

23.4.47 CMAKE_BUILD_WITH_INSTALL_RPATH
--------------------------------------

Use the install path for the ‘RPATH’.

Normally CMake uses the build tree for the ‘RPATH’ when building
executables etc on systems that use ‘RPATH’.  When the software is
installed the executables etc are relinked by CMake to have the install
‘RPATH’.  If this variable is set to true then the software is always
built with the install path for the ‘RPATH’ and does not need to be
relinked when installed.

23.4.48 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
------------------------------------------

New in version 3.1.

Output directory for MS debug symbol ‘.pdb’ files generated by the
compiler while building source files.

This variable is used to initialize the
COMPILE_PDB_OUTPUT_DIRECTORY property on all the targets.

23.4.49 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
---------------------------------------------------

New in version 3.1.

Per-configuration output directory for MS debug symbol ‘.pdb’ files
generated by the compiler while building source files.

This is a per-configuration version of
CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.  This variable is used to
initialize the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>.
property on all the targets.

23.4.50 CMAKE_<CONFIG>_POSTFIX
------------------------------

Default filename postfix for libraries under configuration ‘<CONFIG>’.

When a non-executable target is created its <CONFIG>_POSTFIX.
target property is initialized with the value of this variable if it is
set.

23.4.51 CMAKE_CROSS_CONFIGS
---------------------------

New in version 3.17.

Specifies a semicolon-separated list of configurations
available from all ‘build-<Config>.ninja’ files in the Ninja Multi-Config
generator.  This variable activates cross-config
mode.  Targets from each config specified in this variable can be built
from any ‘build-<Config>.ninja’ file.  Custom commands will use the
configuration native to ‘build-<Config>.ninja’.  If it is set to ‘all’,
all configurations from CMAKE_CONFIGURATION_TYPES are
cross-configs.  If it is not specified, or empty, each
‘build-<Config>.ninja’ file will only contain build rules for its own
configuration.

The value of this variable must be a subset of
CMAKE_CONFIGURATION_TYPES.

23.4.52 CMAKE_CTEST_ARGUMENTS
-----------------------------

New in version 3.17.

Set this to a semicolon-separated list of command-line
arguments to pass to ctest(1) when running tests through the
‘test’ (or ‘RUN_TESTS’) target of the generated build system.

23.4.53 CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
-----------------------------------------

New in version 3.16.

Default value for CUDA_RESOLVE_DEVICE_SYMBOLS target
property.  This variable is used to initialize the property on each
target as it is created.

23.4.54 CMAKE_CUDA_RUNTIME_LIBRARY
----------------------------------

New in version 3.17.

Select the CUDA runtime library for use when compiling and linking CUDA.
This variable is used to initialize the CUDA_RUNTIME_LIBRARY.
property on all targets as they are created.

The allowed case insensitive values are:

‘None’

     Link with ‘-cudart=none’ or equivalent flag(s) to use no CUDA
     runtime library.

‘Shared’

     Link with ‘-cudart=shared’ or equivalent flag(s) to use a
     dynamically-linked CUDA runtime library.

‘Static’

     Link with ‘-cudart=static’ or equivalent flag(s) to use a
     statically-linked CUDA runtime library.

Contents of ‘CMAKE_CUDA_RUNTIME_LIBRARY’ may use generator expressions.

If this variable is not set then the CUDA_RUNTIME_LIBRARY.
target property will not be set automatically.  If that property is not
set then CMake uses an appropriate default value based on the compiler
to select the CUDA runtime library.

     Note: This property has effect only when the ‘CUDA’ language is
     enabled.  To control the CUDA runtime linking when only using the
     CUDA SDK with the ‘C’ or ‘C++’ language we recommend using the
     FindCUDAToolkit module.

23.4.55 CMAKE_CUDA_SEPARABLE_COMPILATION
----------------------------------------

New in version 3.11.

Default value for CUDA_SEPARABLE_COMPILATION target
property.  This variable is used to initialize the property on each
target as it is created.

23.4.56 CMAKE_DEBUG_POSTFIX
---------------------------

See variable CMAKE_<CONFIG>_POSTFIX.

This variable is a special case of the more-general
CMAKE_<CONFIG>_POSTFIX variable for the ‘DEBUG’ configuration.

23.4.57 CMAKE_DEFAULT_BUILD_TYPE
--------------------------------

New in version 3.17.

Specifies the configuration to use by default in a ‘build.ninja’ file in
the Ninja Multi-Config generator.  If this variable is
specified, ‘build.ninja’ uses build rules from ‘build-<Config>.ninja’ by
default.  All custom commands are executed with this configuration.  If
the variable is not specified, the first item from
CMAKE_CONFIGURATION_TYPES is used instead.

The value of this variable must be one of the items from
CMAKE_CONFIGURATION_TYPES.

23.4.58 CMAKE_DEFAULT_CONFIGS
-----------------------------

New in version 3.17.

Specifies a semicolon-separated list of configurations to
build for a target in ‘build.ninja’ if no ‘:<Config>’ suffix is
specified in the Ninja Multi-Config generator.  If it is set
to ‘all’, all configurations from CMAKE_CROSS_CONFIGS are
used.  If it is not specified, it defaults to
CMAKE_DEFAULT_BUILD_TYPE.

For example, if you set CMAKE_DEFAULT_BUILD_TYPE to
‘Release’, but set CMAKE_DEFAULT_CONFIGS to ‘Debug’ or
‘all’, all ‘<target>’ aliases in ‘build.ninja’ will resolve to
‘<target>:Debug’ or ‘<target>:all’, but custom commands will still use
the ‘Release’ configuration.

The value of this variable must be a subset of
CMAKE_CROSS_CONFIGS or be the same as
CMAKE_DEFAULT_BUILD_TYPE.  It must not be specified if
CMAKE_DEFAULT_BUILD_TYPE or CMAKE_CROSS_CONFIGS is not
used.

23.4.59 CMAKE_DISABLE_PRECOMPILE_HEADERS
----------------------------------------

New in version 3.16.

Default value for DISABLE_PRECOMPILE_HEADERS of targets.

By default ‘CMAKE_DISABLE_PRECOMPILE_HEADERS’ is ‘OFF’.

23.4.60 CMAKE_ENABLE_EXPORTS
----------------------------

New in version 3.4.

Specify whether executables export symbols for loadable modules.

This variable is used to initialize the ENABLE_EXPORTS.
target property for executable targets when they are created by calls to
the add_executable() command.  See the property documentation
for details.

23.4.61 CMAKE_EXE_LINKER_FLAGS
------------------------------

Linker flags to be used to create executables.

These flags will be used by the linker when creating an executable.

23.4.62 CMAKE_EXE_LINKER_FLAGS_<CONFIG>
---------------------------------------

Flags to be used when linking an executable.

Same as ‘CMAKE_C_FLAGS_*’ but used by the linker when creating
executables.

23.4.63 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT
--------------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_EXE_LINKER_FLAGS_<CONFIG>
cache entry the first time a build tree is configured.  This
variable is meant to be set by a toolchain file.  CMake may
prepend or append content to the value based on the environment and
target platform.

See also CMAKE_EXE_LINKER_FLAGS_INIT.

23.4.64 CMAKE_EXE_LINKER_FLAGS_INIT
-----------------------------------

New in version 3.7.

Value used to initialize the CMAKE_EXE_LINKER_FLAGS cache
entry the first time a build tree is configured.  This variable is meant
to be set by a toolchain file.  CMake may prepend or append
content to the value based on the environment and target platform.

See also the configuration-specific variable
CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT.

23.4.65 CMAKE_FOLDER
--------------------

New in version 3.12.

Set the folder name.  Use to organize targets in an IDE.

This variable is used to initialize the FOLDER property on
all the targets.  See that target property for additional information.

23.4.66 CMAKE_FRAMEWORK
-----------------------

New in version 3.15.

Default value for FRAMEWORK of targets.

This variable is used to initialize the FRAMEWORK property on
all the targets.  See that target property for additional information.

23.4.67 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
-----------------------------------------------------

New in version 3.18.

Default framework filename postfix under configuration ‘<CONFIG>’ when
using a multi-config generator.

When a framework target is created its
FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property is
initialized with the value of this variable if it is set.

23.4.68 CMAKE_Fortran_FORMAT
----------------------------

Set to ‘FIXED’ or ‘FREE’ to indicate the Fortran source layout.

This variable is used to initialize the Fortran_FORMAT.
property on all the targets.  See that target property for additional
information.

23.4.69 CMAKE_Fortran_MODULE_DIRECTORY
--------------------------------------

Fortran module output directory.

This variable is used to initialize the Fortran_MODULE_DIRECTORY
property on all the targets.  See that target property for
additional information.

23.4.70 CMAKE_Fortran_PREPROCESS
--------------------------------

New in version 3.18.

Default value for Fortran_PREPROCESS of targets.

This variable is used to initialize the Fortran_PREPROCESS.
property on all the targets.  See that target property for additional
information.

23.4.71 CMAKE_GHS_NO_SOURCE_GROUP_FILE
--------------------------------------

New in version 3.14.

‘ON’ / ‘OFF’ boolean to control if the project file for a target should
be one single file or multiple files.  Refer to
GHS_NO_SOURCE_GROUP_FILE for further details.

23.4.72 CMAKE_GLOBAL_AUTOGEN_TARGET
-----------------------------------

New in version 3.14.

Switch to enable generation of a global ‘autogen’ target.

When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a custom target
‘autogen’ is generated.  This target depends on all AUTOMOC.
and AUTOUIC generated ‘<ORIGIN>_autogen’ targets in the
project.  By building the global ‘autogen’ target, all AUTOMOC
and AUTOUIC files in the project will be generated.

The name of the global ‘autogen’ target can be changed by setting
CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.

By default CMAKE_GLOBAL_AUTOGEN_TARGET is unset.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

23.4.72.1 Note
..............

‘<ORIGIN>_autogen’ targets by default inherit their origin target’s
dependencies.  This might result in unintended dependency target builds
when only ‘<ORIGIN>_autogen’ targets are built.  A solution is to
disable AUTOGEN_ORIGIN_DEPENDS on the respective origin
targets.

23.4.73 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME
----------------------------------------

New in version 3.14.

Change the name of the global ‘autogen’ target.

When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a global custom
target named ‘autogen’ is created.
CMAKE_GLOBAL_AUTOGEN_TARGET_NAME allows to set a different name
for that target.

By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

23.4.74 CMAKE_GLOBAL_AUTORCC_TARGET
-----------------------------------

New in version 3.14.

Switch to enable generation of a global ‘autorcc’ target.

When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a custom target
‘autorcc’ is generated.  This target depends on all AUTORCC.
generated ‘<ORIGIN>_arcc_<QRC>’ targets in the project.  By building the
global ‘autorcc’ target, all AUTORCC files in the project
will be generated.

The name of the global ‘autorcc’ target can be changed by setting
CMAKE_GLOBAL_AUTORCC_TARGET_NAME.

By default CMAKE_GLOBAL_AUTORCC_TARGET is unset.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

23.4.75 CMAKE_GLOBAL_AUTORCC_TARGET_NAME
----------------------------------------

New in version 3.14.

Change the name of the global ‘autorcc’ target.

When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a global custom
target named ‘autorcc’ is created.
CMAKE_GLOBAL_AUTORCC_TARGET_NAME allows to set a different name
for that target.

By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.

See the cmake-qt(7) manual for more information on using
CMake with Qt.

23.4.76 CMAKE_GNUtoMS
---------------------

Convert GNU import libraries (‘.dll.a’) to MS format (‘.lib’).

This variable is used to initialize the GNUtoMS property on
targets when they are created.  See that target property for additional
information.

23.4.77 CMAKE_INCLUDE_CURRENT_DIR
---------------------------------

Automatically add the current source and build directories to the
include path.

If this variable is enabled, CMake automatically adds
CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR.
to the include path for each directory.  These additional include
directories do not propagate down to subdirectories.  This is useful
mainly for out-of-source builds, where files generated into the build
tree are included by files located in the source tree.

By default ‘CMAKE_INCLUDE_CURRENT_DIR’ is ‘OFF’.

23.4.78 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
----------------------------------------------

Automatically add the current source and build directories to the
INTERFACE_INCLUDE_DIRECTORIES target property.

If this variable is enabled, CMake automatically adds for each shared
library target, static library target, module target and executable
target, see CMAKE_CURRENT_SOURCE_DIR and
CMAKE_CURRENT_BINARY_DIR to the
INTERFACE_INCLUDE_DIRECTORIES target property.  By default
‘CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE’ is ‘OFF’.

23.4.79 CMAKE_INSTALL_NAME_DIR
------------------------------

macOS directory name for installed targets.

‘CMAKE_INSTALL_NAME_DIR’ is used to initialize the
INSTALL_NAME_DIR property on all targets.  See that target
property for more information.

23.4.80 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH
----------------------------------------------

New in version 3.16.

Sets the default for whether toolchain-defined rpaths should be removed
during installation.

‘CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH’ is a boolean that provides the
default value for the INSTALL_REMOVE_ENVIRONMENT_RPATH.
property of all subsequently created targets.

23.4.81 CMAKE_INSTALL_RPATH
---------------------------

The rpath to use for installed targets.

A semicolon-separated list specifying the rpath to use in installed
targets (for platforms that support it).  This is used to initialize the
target property INSTALL_RPATH for all targets.

23.4.82 CMAKE_INSTALL_RPATH_USE_LINK_PATH
-----------------------------------------

Add paths to linker search and installed rpath.

‘CMAKE_INSTALL_RPATH_USE_LINK_PATH’ is a boolean that if set to ‘True’
will append to the runtime search path (rpath) of installed binaries any
directories outside the project that are in the linker search path or
contain linked library files.  The directories are appended after the
value of the INSTALL_RPATH target property.

This variable is used to initialize the target property
INSTALL_RPATH_USE_LINK_PATH for all targets.

23.4.83 CMAKE_INTERPROCEDURAL_OPTIMIZATION
------------------------------------------

New in version 3.9.

Default value for INTERPROCEDURAL_OPTIMIZATION of targets.

This variable is used to initialize the
INTERPROCEDURAL_OPTIMIZATION property on all the targets.  See
that target property for additional information.

23.4.84 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
---------------------------------------------------

New in version 3.9.

Default value for INTERPROCEDURAL_OPTIMIZATION_<CONFIG> of
targets.

This variable is used to initialize the
INTERPROCEDURAL_OPTIMIZATION_<CONFIG> property on all the targets.
See that target property for additional information.

23.4.85 CMAKE_IOS_INSTALL_COMBINED
----------------------------------

New in version 3.5.

Default value for IOS_INSTALL_COMBINED of targets.

This variable is used to initialize the IOS_INSTALL_COMBINED.
property on all the targets.  See that target property for additional
information.

23.4.86 CMAKE_<LANG>_CLANG_TIDY
-------------------------------

New in version 3.6.

Default value for <LANG>_CLANG_TIDY target property when
‘<LANG>’ is ‘C’ or ‘CXX’.

This variable is used to initialize the property on each target as it is
created.  For example:

     set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*)
     add_executable(foo foo.cxx)

23.4.87 CMAKE_<LANG>_COMPILER_LAUNCHER
--------------------------------------

New in version 3.4.

Default value for <LANG>_COMPILER_LAUNCHER target property.
This variable is used to initialize the property on each target as it is
created.  This is done only when ‘<LANG>’ is ‘C’, ‘CXX’, ‘Fortran’,
‘ISPC’, ‘OBJC’, ‘OBJCXX’, or ‘CUDA’.

This variable is initialized to the
CMAKE_<LANG>_COMPILER_LAUNCHER environment variable if it is set.

23.4.88 CMAKE_<LANG>_CPPCHECK
-----------------------------

New in version 3.10.

Default value for <LANG>_CPPCHECK target property.  This
variable is used to initialize the property on each target as it is
created.  This is done only when ‘<LANG>’ is ‘C’ or ‘CXX’.

23.4.89 CMAKE_<LANG>_CPPLINT
----------------------------

New in version 3.8.

Default value for <LANG>_CPPLINT target property.  This
variable is used to initialize the property on each target as it is
created.  This is done only when ‘<LANG>’ is ‘C’ or ‘CXX’.

23.4.90 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE
-----------------------------------------

New in version 3.3.

Default value for <LANG>_INCLUDE_WHAT_YOU_USE target
property.  This variable is used to initialize the property on each
target as it is created.  This is done only when ‘<LANG>’ is ‘C’ or
‘CXX’.

23.4.91 CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG
-------------------------------------------

New in version 3.16.

Language-specific flag to be used to link a library specified by a path
to its file.

The flag will be used before a library file path is given to the linker.
This is needed only on very few platforms.

23.4.92 CMAKE_<LANG>_LINK_LIBRARY_FLAG
--------------------------------------

New in version 3.16.

Flag to be used to link a library into a shared library or executable.

This flag will be used to specify a library to link to a shared library
or an executable for the specific language.  On most compilers this is
‘-l’.

23.4.93 CMAKE_<LANG>_VISIBILITY_PRESET
--------------------------------------

Default value for the <LANG>_VISIBILITY_PRESET target
property when a target is created.

23.4.94 CMAKE_LIBRARY_OUTPUT_DIRECTORY
--------------------------------------

Where to put all the LIBRARY target files when built.

This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY
property on all the targets.  See that target property for
additional information.

23.4.95 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
-----------------------------------------------

New in version 3.3.

Where to put all the LIBRARY target files when built for a
specific configuration.

This variable is used to initialize the
LIBRARY_OUTPUT_DIRECTORY_<CONFIG> property on all the targets.
See that target property for additional information.

23.4.96 CMAKE_LIBRARY_PATH_FLAG
-------------------------------

The flag to be used to add a library search path to a compiler.

The flag will be used to specify a library directory to the compiler.
On most compilers this is ‘-L’.

23.4.97 CMAKE_LINK_DEF_FILE_FLAG
--------------------------------

Linker flag to be used to specify a ‘.def’ file for dll creation.

The flag will be used to add a ‘.def’ file when creating a dll on
Windows; this is only defined on Windows.

23.4.98 CMAKE_LINK_DEPENDS_NO_SHARED
------------------------------------

Whether to skip link dependencies on shared library files.

This variable initializes the LINK_DEPENDS_NO_SHARED.
property on targets when they are created.  See that target property for
additional information.

23.4.99 CMAKE_LINK_INTERFACE_LIBRARIES
--------------------------------------

Default value for LINK_INTERFACE_LIBRARIES of targets.

This variable is used to initialize the LINK_INTERFACE_LIBRARIES
property on all the targets.  See that target property for
additional information.

23.4.100 CMAKE_LINK_LIBRARY_FILE_FLAG
-------------------------------------

Flag to be used to link a library specified by a path to its file.

The flag will be used before a library file path is given to the linker.
This is needed only on very few platforms.

23.4.101 CMAKE_LINK_LIBRARY_FLAG
--------------------------------

Flag to be used to link a library into an executable.

The flag will be used to specify a library to link to an executable.  On
most compilers this is ‘-l’.

23.4.102 CMAKE_LINK_WHAT_YOU_USE
--------------------------------

New in version 3.7.

Default value for LINK_WHAT_YOU_USE target property.  This
variable is used to initialize the property on each target as it is
created.

23.4.103 CMAKE_MACOSX_BUNDLE
----------------------------

Default value for MACOSX_BUNDLE of targets.

This variable is used to initialize the MACOSX_BUNDLE.
property on all the targets.  See that target property for additional
information.

This variable is set to ‘ON’ by default if CMAKE_SYSTEM_NAME.
equals to iOS, tvOS or watchOS.

23.4.104 CMAKE_MACOSX_RPATH
---------------------------

Whether to use rpaths on macOS and iOS.

This variable is used to initialize the MACOSX_RPATH.
property on all targets.

23.4.105 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>
-------------------------------------------

Default value for MAP_IMPORTED_CONFIG_<CONFIG> of targets.

This variable is used to initialize the
MAP_IMPORTED_CONFIG_<CONFIG> property on all the targets.  See
that target property for additional information.

23.4.106 CMAKE_MODULE_LINKER_FLAGS
----------------------------------

Linker flags to be used to create modules.

These flags will be used by the linker when creating a module.

23.4.107 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
-------------------------------------------

Flags to be used when linking a module.

Same as ‘CMAKE_C_FLAGS_*’ but used by the linker when creating modules.

23.4.108 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT
------------------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
cache entry the first time a build tree is configured.  This
variable is meant to be set by a toolchain file.  CMake may
prepend or append content to the value based on the environment and
target platform.

See also CMAKE_MODULE_LINKER_FLAGS_INIT.

23.4.109 CMAKE_MODULE_LINKER_FLAGS_INIT
---------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_MODULE_LINKER_FLAGS.
cache entry the first time a build tree is configured.  This variable is
meant to be set by a toolchain file.  CMake may prepend or
append content to the value based on the environment and target
platform.

See also the configuration-specific variable
CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT.

23.4.110 CMAKE_MSVCIDE_RUN_PATH
-------------------------------

New in version 3.10.

Extra PATH locations that should be used when executing
add_custom_command() or add_custom_target() when using
the Visual Studio 9 2008. (or above) generator.  This allows
for running commands and using dll’s that the IDE environment is not
aware of.

If not set explicitly the value is initialized by the
‘CMAKE_MSVCIDE_RUN_PATH’ environment variable, if set, and otherwise
left empty.

23.4.111 CMAKE_MSVC_RUNTIME_LIBRARY
-----------------------------------

New in version 3.15.

Select the MSVC runtime library for use by compilers targeting the MSVC
ABI. This variable is used to initialize the MSVC_RUNTIME_LIBRARY
property on all targets as they are created.  It is also propagated
by calls to the try_compile() command into the test project.

The allowed values are:

‘MultiThreaded’

     Compile with ‘-MT’ or equivalent flag(s) to use a multi-threaded
     statically-linked runtime library.

‘MultiThreadedDLL’

     Compile with ‘-MD’ or equivalent flag(s) to use a multi-threaded
     dynamically-linked runtime library.

‘MultiThreadedDebug’

     Compile with ‘-MTd’ or equivalent flag(s) to use a multi-threaded
     statically-linked runtime library.

‘MultiThreadedDebugDLL’

     Compile with ‘-MDd’ or equivalent flag(s) to use a multi-threaded
     dynamically-linked runtime library.

The value is ignored on non-MSVC compilers but an unsupported value will
be rejected as an error when using a compiler targeting the MSVC ABI.

The value may also be the empty string (‘""’) in which case no runtime
library selection flag will be added explicitly by CMake.  Note that
with Visual Studio Generators the native build system may
choose to add its own default runtime library selection flag.

Use generator expressions to support per-configuration
specification.  For example, the code:

     set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")

selects for all following targets a multi-threaded statically-linked
runtime library with or without debug information depending on the
configuration.

If this variable is not set then the MSVC_RUNTIME_LIBRARY.
target property will not be set automatically.  If that property is not
set then CMake uses the default value
‘MultiThreaded$<$<CONFIG:Debug>:Debug>DLL’ to select a MSVC runtime
library.

     Note: This variable has effect only when policy CMP0091.
     is set to ‘NEW’ prior to the first project() or
     enable_language() command that enables a language using a
     compiler targeting the MSVC ABI.

23.4.112 CMAKE_NINJA_OUTPUT_PATH_PREFIX
---------------------------------------

New in version 3.6.

Set output files path prefix for the Ninja generator.

Every output files listed in the generated ‘build.ninja’ will be
prefixed by the contents of this variable (a trailing slash is appended
if missing).  This is useful when the generated ninja file is meant to
be embedded as a ‘subninja’ file into a `super' ninja project.  For
example, a ninja build file generated with a command like:

     cd top-build-dir/sub &&
     cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source

can be embedded in ‘top-build-dir/build.ninja’ with a directive like
this:

     subninja sub/build.ninja

The ‘auto-regeneration’ rule in ‘top-build-dir/build.ninja’ must have an
order-only dependency on ‘sub/build.ninja’.

     Note: When ‘CMAKE_NINJA_OUTPUT_PATH_PREFIX’ is set, the project
     generated by CMake cannot be used as a standalone project.  No
     default targets are specified.

23.4.113 CMAKE_NO_BUILTIN_CHRPATH
---------------------------------

Do not use the builtin ELF editor to fix RPATHs on installation.

When an ELF binary needs to have a different RPATH after installation
than it does in the build tree, CMake uses a builtin editor to change
the RPATH in the installed copy.  If this variable is set to true then
CMake will relink the binary before installation instead of using its
builtin editor.

23.4.114 CMAKE_NO_SYSTEM_FROM_IMPORTED
--------------------------------------

Default value for NO_SYSTEM_FROM_IMPORTED of targets.

This variable is used to initialize the NO_SYSTEM_FROM_IMPORTED
property on all the targets.  See that target property for
additional information.

23.4.115 CMAKE_OPTIMIZE_DEPENDENCIES
------------------------------------

New in version 3.19.

Initializes the OPTIMIZE_DEPENDENCIES target property.

23.4.116 CMAKE_OSX_ARCHITECTURES
--------------------------------

Target specific architectures for macOS and iOS.

This variable is used to initialize the OSX_ARCHITECTURES.
property on each target as it is created.  See that target property for
additional information.

The value of this variable should be set prior to the first
project() or enable_language() command invocation
because it may influence configuration of the toolchain and flags.  It
is intended to be set locally by the user creating a build tree.  This
variable should be set as a ‘CACHE’ entry (or else CMake may remove it
while initializing a cache entry of the same name).

Despite the ‘OSX’ part in the variable name(s) they apply also to other
SDKs than macOS like iOS, tvOS, or watchOS.

This variable is ignored on platforms other than Apple.

23.4.117 CMAKE_OSX_DEPLOYMENT_TARGET
------------------------------------

Specify the minimum version of the target platform (e.g.  macOS or iOS)
on which the target binaries are to be deployed.  CMake uses this
variable value for the ‘-mmacosx-version-min’ flag or their respective
target platform equivalents.  For older Xcode versions that shipped
multiple macOS SDKs this variable also helps to choose the SDK in case
CMAKE_OSX_SYSROOT is unset.

If not set explicitly the value is initialized by the
‘MACOSX_DEPLOYMENT_TARGET’ environment variable, if set, and otherwise
computed based on the host platform.

The value of this variable should be set prior to the first
project() or enable_language() command invocation
because it may influence configuration of the toolchain and flags.  It
is intended to be set locally by the user creating a build tree.  This
variable should be set as a ‘CACHE’ entry (or else CMake may remove it
while initializing a cache entry of the same name).

Despite the ‘OSX’ part in the variable name(s) they apply also to other
SDKs than macOS like iOS, tvOS, or watchOS.

This variable is ignored on platforms other than Apple.

23.4.118 CMAKE_OSX_SYSROOT
--------------------------

Specify the location or name of the macOS platform SDK to be used.
CMake uses this value to compute the value of the ‘-isysroot’ flag or
equivalent and to help the ‘find_*’ commands locate files in the SDK.

If not set explicitly the value is initialized by the ‘SDKROOT’
environment variable, if set, and otherwise computed based on the
CMAKE_OSX_DEPLOYMENT_TARGET or the host platform.

The value of this variable should be set prior to the first
project() or enable_language() command invocation
because it may influence configuration of the toolchain and flags.  It
is intended to be set locally by the user creating a build tree.  This
variable should be set as a ‘CACHE’ entry (or else CMake may remove it
while initializing a cache entry of the same name).

Despite the ‘OSX’ part in the variable name(s) they apply also to other
SDKs than macOS like iOS, tvOS, or watchOS.

This variable is ignored on platforms other than Apple.

23.4.119 CMAKE_PCH_WARN_INVALID
-------------------------------

New in version 3.18.

This variable is used to initialize the PCH_WARN_INVALID.
property of targets when they are created.

23.4.120 CMAKE_PCH_INSTANTIATE_TEMPLATES
----------------------------------------

New in version 3.19.

This variable is used to initialize the PCH_INSTANTIATE_TEMPLATES
property of targets when they are created.

23.4.121 CMAKE_PDB_OUTPUT_DIRECTORY
-----------------------------------

Output directory for MS debug symbol ‘.pdb’ files generated by the
linker for executable and shared library targets.

This variable is used to initialize the PDB_OUTPUT_DIRECTORY.
property on all the targets.  See that target property for additional
information.

23.4.122 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>
--------------------------------------------

Per-configuration output directory for MS debug symbol ‘.pdb’ files
generated by the linker for executable and shared library targets.

This is a per-configuration version of CMAKE_PDB_OUTPUT_DIRECTORY.
This variable is used to initialize the
PDB_OUTPUT_DIRECTORY_<CONFIG> property on all the targets.  See
that target property for additional information.

23.4.123 CMAKE_POSITION_INDEPENDENT_CODE
----------------------------------------

Default value for POSITION_INDEPENDENT_CODE of targets.

This variable is used to initialize the POSITION_INDEPENDENT_CODE
property on all the targets.  See that target property for
additional information.  If set, it’s value is also used by the
try_compile() command.

23.4.124 CMAKE_RUNTIME_OUTPUT_DIRECTORY
---------------------------------------

Where to put all the RUNTIME target files when built.

This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY
property on all the targets.  See that target property for
additional information.

23.4.125 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
------------------------------------------------

New in version 3.3.

Where to put all the RUNTIME target files when built for a
specific configuration.

This variable is used to initialize the
RUNTIME_OUTPUT_DIRECTORY_<CONFIG> property on all the targets.
See that target property for additional information.

23.4.126 CMAKE_SHARED_LINKER_FLAGS
----------------------------------

Linker flags to be used to create shared libraries.

These flags will be used by the linker when creating a shared library.

23.4.127 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
-------------------------------------------

Flags to be used when linking a shared library.

Same as ‘CMAKE_C_FLAGS_*’ but used by the linker when creating shared
libraries.

23.4.128 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT
------------------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
cache entry the first time a build tree is configured.  This
variable is meant to be set by a toolchain file.  CMake may
prepend or append content to the value based on the environment and
target platform.

See also CMAKE_SHARED_LINKER_FLAGS_INIT.

23.4.129 CMAKE_SHARED_LINKER_FLAGS_INIT
---------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_SHARED_LINKER_FLAGS.
cache entry the first time a build tree is configured.  This variable is
meant to be set by a toolchain file.  CMake may prepend or
append content to the value based on the environment and target
platform.

See also the configuration-specific variable
CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT.

23.4.130 CMAKE_SKIP_BUILD_RPATH
-------------------------------

Do not include RPATHs in the build tree.

Normally CMake uses the build tree for the RPATH when building
executables etc on systems that use RPATH. When the software is
installed the executables etc are relinked by CMake to have the install
RPATH. If this variable is set to true then the software is always built
with no RPATH.

23.4.131 CMAKE_SKIP_INSTALL_RPATH
---------------------------------

Do not include RPATHs in the install tree.

Normally CMake uses the build tree for the RPATH when building
executables etc on systems that use RPATH. When the software is
installed the executables etc are relinked by CMake to have the install
RPATH. If this variable is set to true then the software is always
installed without RPATH, even if RPATH is enabled when building.  This
can be useful for example to allow running tests from the build
directory with RPATH enabled before the installation step.  To omit
RPATH in both the build and install steps, use CMAKE_SKIP_RPATH
instead.

23.4.132 CMAKE_STATIC_LINKER_FLAGS
----------------------------------

Flags to be used to create static libraries.  These flags will be passed
to the archiver when creating a static library.

See also CMAKE_STATIC_LINKER_FLAGS_<CONFIG>.

     Note: Static libraries do not actually link.  They are essentially
     archives of object files.  The use of the name “linker” in the name
     of this variable is kept for compatibility.

23.4.133 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
-------------------------------------------

Flags to be used to create static libraries.  These flags will be passed
to the archiver when creating a static library in the ‘<CONFIG>’
configuration.

See also CMAKE_STATIC_LINKER_FLAGS.

     Note: Static libraries do not actually link.  They are essentially
     archives of object files.  The use of the name “linker” in the name
     of this variable is kept for compatibility.

23.4.134 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT
------------------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
cache entry the first time a build tree is configured.  This
variable is meant to be set by a toolchain file.  CMake may
prepend or append content to the value based on the environment and
target platform.

See also CMAKE_STATIC_LINKER_FLAGS_INIT.

23.4.135 CMAKE_STATIC_LINKER_FLAGS_INIT
---------------------------------------

New in version 3.7.

Value used to initialize the CMAKE_STATIC_LINKER_FLAGS.
cache entry the first time a build tree is configured.  This variable is
meant to be set by a toolchain file.  CMake may prepend or
append content to the value based on the environment and target
platform.

See also the configuration-specific variable
CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT.

23.4.136 CMAKE_TRY_COMPILE_CONFIGURATION
----------------------------------------

Build configuration used for try_compile() and
try_run() projects.

Projects built by try_compile() and try_run() are
built synchronously during the CMake configuration step.  Therefore a
specific build configuration must be chosen even if the generated build
system supports multiple configurations.

23.4.137 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
---------------------------------------------

New in version 3.6.

List of variables that the try_compile() command source file
signature must propagate into the test project in order to target the
same platform as the host project.

This variable should not be set by project code.  It is meant to be set
by CMake’s platform information modules for the current toolchain, or by
a toolchain file when used with CMAKE_TOOLCHAIN_FILE.

Variables meaningful to CMake, such as CMAKE_<LANG>_FLAGS,
are propagated automatically.  The
‘CMAKE_TRY_COMPILE_PLATFORM_VARIABLES’ variable may be set to pass
custom variables meaningful to a toolchain file.  For example, a
toolchain file may contain:

     set(CMAKE_SYSTEM_NAME ...)
     set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE)
     # ... use MY_CUSTOM_VARIABLE ...

If a user passes ‘-DMY_CUSTOM_VARIABLE=SomeValue’ to CMake then this
setting will be made visible to the toolchain file both for the main
project and for test projects generated by the try_compile().
command source file signature.

23.4.138 CMAKE_TRY_COMPILE_TARGET_TYPE
--------------------------------------

New in version 3.6.

Type of target generated for try_compile() calls using the
source file signature.  Valid values are:

‘EXECUTABLE’

     Use add_executable() to name the source file in the
     generated project.  This is the default if no value is given.

‘STATIC_LIBRARY’

     Use add_library() with the ‘STATIC’ option to name the
     source file in the generated project.  This avoids running the
     linker and is intended for use with cross-compiling toolchains that
     cannot link without custom flags or linker scripts.

23.4.139 CMAKE_UNITY_BUILD
--------------------------

New in version 3.16.

This variable is used to initialize the UNITY_BUILD.
property of targets when they are created.  Setting it to true enables
batch compilation of multiple sources within each target.  This feature
is known as a `Unity' or `Jumbo' build.

Projects should not set this variable, it is intended as a developer
control to be set on the cmake(1) command line or other
equivalent methods.  The developer must have the ability to enable or
disable unity builds according to the capabilities of their own machine
and compiler.

By default, this variable is not set, which will result in unity builds
being disabled.

     Note: This option currently does not work well in combination with
     the CMAKE_EXPORT_COMPILE_COMMANDS variable.

23.4.140 CMAKE_UNITY_BUILD_BATCH_SIZE
-------------------------------------

New in version 3.16.

This variable is used to initialize the UNITY_BUILD_BATCH_SIZE
property of targets when they are created.  It specifies the
default upper limit on the number of source files that may be combined
in any one unity source file when unity builds are enabled for a target.

23.4.141 CMAKE_USE_RELATIVE_PATHS
---------------------------------

This variable has no effect.  The partially implemented effect it had in
previous releases was removed in CMake 3.4.

23.4.142 CMAKE_VISIBILITY_INLINES_HIDDEN
----------------------------------------

Default value for the VISIBILITY_INLINES_HIDDEN target
property when a target is created.

23.4.143 CMAKE_VS_GLOBALS
-------------------------

New in version 3.13.

List of ‘Key=Value’ records to be set per target as target properties
VS_GLOBAL_<variable> with ‘variable=Key’ and value ‘Value’.

For example:

     set(CMAKE_VS_GLOBALS
       "DefaultLanguage=en-US"
       "MinimumVisualStudioVersion=14.0"
       )

will set properties ‘VS_GLOBAL_DefaultLanguage’ to ‘en-US’ and
‘VS_GLOBAL_MinimumVisualStudioVersion’ to ‘14.0’ for all targets (except
for ‘INTERFACE’ libraries).

This variable is meant to be set by a toolchain file.

23.4.144 CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
--------------------------------------------------

New in version 3.3.

Include ‘INSTALL’ target to default build.

In Visual Studio solution, by default the ‘INSTALL’ target will not be
part of the default build.  Setting this variable will enable the
‘INSTALL’ target to be part of the default build.

23.4.145 CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
--------------------------------------------------

New in version 3.8.

Include ‘PACKAGE’ target to default build.

In Visual Studio solution, by default the ‘PACKAGE’ target will not be
part of the default build.  Setting this variable will enable the
‘PACKAGE’ target to be part of the default build.

23.4.146 CMAKE_VS_JUST_MY_CODE_DEBUGGING
----------------------------------------

New in version 3.15.

Enable Just My Code with Visual Studio debugger.

This variable is used to initialize the VS_JUST_MY_CODE_DEBUGGING
property on all targets when they are created.  See that target
property for additional information.

23.4.147 CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
-----------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Exclude
Directories.

23.4.148 CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
--------------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Executable
Directories.

23.4.149 CMAKE_VS_SDK_INCLUDE_DIRECTORIES
-----------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Include
Directories.

23.4.150 CMAKE_VS_SDK_LIBRARY_DIRECTORIES
-----------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Library
Directories.

23.4.151 CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
-----------------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Library WinRT
Directories.

23.4.152 CMAKE_VS_SDK_REFERENCE_DIRECTORIES
-------------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Reference
Directories.

23.4.153 CMAKE_VS_SDK_SOURCE_DIRECTORIES
----------------------------------------

New in version 3.12.

This variable allows to override Visual Studio default Source
Directories.

23.4.154 CMAKE_VS_WINRT_BY_DEFAULT
----------------------------------

New in version 3.13.

Inform Visual Studio Generators for VS 2010 and above that
the target platform enables WinRT compilation by default and it needs to
be explicitly disabled if ‘/ZW’ or VS_WINRT_COMPONENT is
omitted (as opposed to enabling it when either of those options is
present)

This makes cmake configuration consistent in terms of WinRT among
platforms - if you did not enable the WinRT compilation explicitly, it
will be disabled (by either not enabling it or explicitly disabling it)

Note: WinRT compilation is always explicitly disabled for C language
source files, even if it is expliclty enabled for a project

This variable is meant to be set by a toolchain file for
such platforms.

23.4.155 CMAKE_WIN32_EXECUTABLE
-------------------------------

Default value for WIN32_EXECUTABLE of targets.

This variable is used to initialize the WIN32_EXECUTABLE.
property on all the targets.  See that target property for additional
information.

23.4.156 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
-----------------------------------------

New in version 3.4.

Default value for WINDOWS_EXPORT_ALL_SYMBOLS target
property.  This variable is used to initialize the property on each
target as it is created.

23.4.157 CMAKE_XCODE_ATTRIBUTE_<an-attribute>
---------------------------------------------

New in version 3.1.

Set Xcode target attributes directly.

Tell the Xcode generator to set ‘<an-attribute>’ to a given
value in the generated Xcode project.  Ignored on other generators.

See the XCODE_ATTRIBUTE_<an-attribute> target property to
set attributes on a specific target.

Contents of ‘CMAKE_XCODE_ATTRIBUTE_<an-attribute>’ may use “generator
expressions” with the syntax ‘$<...>’.  See the
cmake-generator-expressions(7) manual for available expressions.
See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

23.4.158 EXECUTABLE_OUTPUT_PATH
-------------------------------

Old executable location variable.

The target property RUNTIME_OUTPUT_DIRECTORY supercedes this
variable for a target if it is set.  Executable targets are otherwise
placed in this directory.

23.4.159 LIBRARY_OUTPUT_PATH
----------------------------

Old library location variable.

The target properties ARCHIVE_OUTPUT_DIRECTORY,
LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY.
supersede this variable for a target if they are set.  Library targets
are otherwise placed in this directory.

23.5 Variables for Languages
============================

23.5.1 CMAKE_COMPILER_IS_GNUCC
------------------------------

New in version 3.7.

True if the ‘C’ compiler is GNU. Use CMAKE_C_COMPILER_ID.
instead.

23.5.2 CMAKE_COMPILER_IS_GNUCXX
-------------------------------

New in version 3.7.

True if the C++ (‘CXX’) compiler is GNU. Use
CMAKE_CXX_COMPILER_ID instead.

23.5.3 CMAKE_COMPILER_IS_GNUG77
-------------------------------

New in version 3.7.

True if the ‘Fortran’ compiler is GNU. Use
CMAKE_Fortran_COMPILER_ID instead.

23.5.4 CMAKE_CUDA_ARCHITECTURES
-------------------------------

New in version 3.18.

Default value for CUDA_ARCHITECTURES property of targets.

This is initialized as follows depending on
CMAKE_CUDA_COMPILER_ID.:

   - For ‘Clang’: the oldest architecture that works.

   - For ‘NVIDIA’: the default architecture chosen by the compiler.  See
     policy CMP0104.

Users are encouraged to override this, as the default varies across
compilers and compiler versions.

This variable is used to initialize the CUDA_ARCHITECTURES.
property on all targets.  See the target property for additional
information.

23.5.5 CMAKE_CUDA_COMPILE_FEATURES
----------------------------------

New in version 3.17.

List of features known to the CUDA compiler

These features are known to be available for use with the CUDA compiler.
This list is a subset of the features listed in the
CMAKE_CUDA_KNOWN_FEATURES global property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.6 CMAKE_CUDA_EXTENSIONS
----------------------------

New in version 3.8.

Default value for CUDA_EXTENSIONS property of targets.

This variable is used to initialize the CUDA_EXTENSIONS.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.7 CMAKE_CUDA_HOST_COMPILER
-------------------------------

New in version 3.10.

When CMAKE_CUDA_COMPILER_ID is ‘NVIDIA’,
‘CMAKE_CUDA_HOST_COMPILER’ selects the compiler executable to use when
compiling host code for ‘CUDA’ language files.  This maps to the ‘nvcc
-ccbin’ option.

The ‘CMAKE_CUDA_HOST_COMPILER’ variable may be set explicitly before
CUDA is first enabled by a project() or
enable_language() command.  This can be done via
‘-DCMAKE_CUDA_HOST_COMPILER=...’ on the command line or in a
toolchain file.  Or, one may set the CUDAHOSTCXX.
environment variable to provide a default value.

Once the CUDA language is enabled, the ‘CMAKE_CUDA_HOST_COMPILER’
variable is read-only and changes to it are undefined behavior.

     Note: Since ‘CMAKE_CUDA_HOST_COMPILER’ is meaningful only when the
     CMAKE_CUDA_COMPILER_ID is ‘NVIDIA’, it does not make
     sense to set ‘CMAKE_CUDA_HOST_COMPILER’ without also setting
     ‘CMAKE_CUDA_COMPILER’ to NVCC.

23.5.8 CMAKE_CUDA_STANDARD
--------------------------

New in version 3.8.

Default value for CUDA_STANDARD property of targets.

This variable is used to initialize the CUDA_STANDARD.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.9 CMAKE_CUDA_STANDARD_REQUIRED
-----------------------------------

New in version 3.8.

Default value for CUDA_STANDARD_REQUIRED property of
targets.

This variable is used to initialize the CUDA_STANDARD_REQUIRED
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.10 CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES
----------------------------------------------

New in version 3.8.

When the ‘CUDA’ language has been enabled, this provides a
semicolon-separated list of include directories provided by the
CUDA Toolkit.  The value may be useful for C++ source files to include
CUDA headers.

23.5.11 CMAKE_CXX_COMPILE_FEATURES
----------------------------------

New in version 3.1.

List of features known to the C++ compiler

These features are known to be available for use with the C++ compiler.
This list is a subset of the features listed in the
CMAKE_CXX_KNOWN_FEATURES global property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.12 CMAKE_CXX_EXTENSIONS
----------------------------

New in version 3.1.

Default value for CXX_EXTENSIONS property of targets.

This variable is used to initialize the CXX_EXTENSIONS.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.13 CMAKE_CXX_STANDARD
--------------------------

New in version 3.1.

Default value for CXX_STANDARD property of targets.

This variable is used to initialize the CXX_STANDARD.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.14 CMAKE_CXX_STANDARD_REQUIRED
-----------------------------------

New in version 3.1.

Default value for CXX_STANDARD_REQUIRED property of targets.

This variable is used to initialize the CXX_STANDARD_REQUIRED
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.15 CMAKE_C_COMPILE_FEATURES
--------------------------------

New in version 3.1.

List of features known to the C compiler

These features are known to be available for use with the C compiler.
This list is a subset of the features listed in the
CMAKE_C_KNOWN_FEATURES global property.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.16 CMAKE_C_EXTENSIONS
--------------------------

New in version 3.1.

Default value for C_EXTENSIONS property of targets.

This variable is used to initialize the C_EXTENSIONS.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.17 CMAKE_C_STANDARD
------------------------

New in version 3.1.

Default value for C_STANDARD property of targets.

This variable is used to initialize the C_STANDARD property
on all targets.  See that target property for additional information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.18 CMAKE_C_STANDARD_REQUIRED
---------------------------------

New in version 3.1.

Default value for C_STANDARD_REQUIRED property of targets.

This variable is used to initialize the C_STANDARD_REQUIRED.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.19 CMAKE_Fortran_MODDIR_DEFAULT
------------------------------------

Fortran default module output directory.

Most Fortran compilers write ‘.mod’ files to the current working
directory.  For those that do not, this is set to ‘.’ and used when the
Fortran_MODULE_DIRECTORY target property is not set.

23.5.20 CMAKE_Fortran_MODDIR_FLAG
---------------------------------

Fortran flag for module output directory.

This stores the flag needed to pass the value of the
Fortran_MODULE_DIRECTORY target property to the compiler.

23.5.21 CMAKE_Fortran_MODOUT_FLAG
---------------------------------

Fortran flag to enable module output.

Most Fortran compilers write ‘.mod’ files out by default.  For others,
this stores the flag needed to enable module output.

23.5.22 CMAKE_ISPC_HEADER_DIRECTORY
-----------------------------------

New in version 3.19.

ISPC generated header output directory.

This variable is used to initialize the ISPC_HEADER_DIRECTORY
property on all the targets.  See the target property for
additional information.

23.5.23 CMAKE_ISPC_HEADER_SUFFIX
--------------------------------

New in version 3.19.2.

Output suffix to be used for ISPC generated headers.

This variable is used to initialize the ISPC_HEADER_SUFFIX.
property on all the targets.  See the target property for additional
information.

23.5.24 CMAKE_ISPC_INSTRUCTION_SETS
-----------------------------------

New in version 3.19.

Default value for ISPC_INSTRUCTION_SETS property of targets.

This variable is used to initialize the ISPC_INSTRUCTION_SETS
property on all targets.  See the target property for additional
information.

23.5.25 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE
----------------------------------------------

New in version 3.7.1.

When Cross Compiling for Android this variable contains the
toolchain binutils machine name (e.g.  ‘gcc -dumpmachine’).  The
binutils typically have a ‘<machine>-’ prefix on their name.

See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.

23.5.26 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
---------------------------------------------

New in version 3.7.

When Cross Compiling for Android this variable contains the
absolute path prefixing the toolchain GNU compiler and its binutils.

See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX and
CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.

For example, the path to the linker is:

     ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX}

23.5.27 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
---------------------------------------------

New in version 3.7.

When Cross Compiling for Android this variable contains the
host platform suffix of the toolchain GNU compiler and its binutils.

See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.

23.5.28 CMAKE_<LANG>_ARCHIVE_APPEND
-----------------------------------

Rule variable to append to a static archive.

This is a rule variable that tells CMake how to append to a static
archive.  It is used in place of
CMAKE_<LANG>_CREATE_STATIC_LIBRARY on some platforms in order to
support large object counts.  See also
CMAKE_<LANG>_ARCHIVE_CREATE and
CMAKE_<LANG>_ARCHIVE_FINISH.

23.5.29 CMAKE_<LANG>_ARCHIVE_CREATE
-----------------------------------

Rule variable to create a new static archive.

This is a rule variable that tells CMake how to create a static archive.
It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY.
on some platforms in order to support large object counts.  See also
CMAKE_<LANG>_ARCHIVE_APPEND and
CMAKE_<LANG>_ARCHIVE_FINISH.

23.5.30 CMAKE_<LANG>_ARCHIVE_FINISH
-----------------------------------

Rule variable to finish an existing static archive.

This is a rule variable that tells CMake how to finish a static archive.
It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY.
on some platforms in order to support large object counts.  See also
CMAKE_<LANG>_ARCHIVE_CREATE and
CMAKE_<LANG>_ARCHIVE_APPEND.

23.5.31 CMAKE_<LANG>_COMPILER
-----------------------------

The full path to the compiler for ‘LANG’.

This is the command that will be used as the ‘<LANG>’ compiler.  Once
set, you can not change this variable.

23.5.31.1 Usage
...............

This variable can be set by the user during the first time a build tree
is configured.

If a non-full path value is supplied then CMake will resolve the full
path of the compiler.

The variable could be set in a user supplied toolchain file or via ‘-D’
on the command line.

     Note: Options that are required to make the compiler work correctly
     can be included as items in a list; they can not be changed.

     #set within user supplied toolchain file
     set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2)

or

     $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2'

23.5.32 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN
------------------------------------------------

The external toolchain for cross-compiling, if supported.

Some compiler toolchains do not ship their own auxiliary utilities such
as archivers and linkers.  The compiler driver may support a
command-line argument to specify the location of such tools.
‘CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN’ may be set to a path to the
external toolchain and will be passed to the compiler driver if
supported.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

23.5.33 CMAKE_<LANG>_COMPILER_ID
--------------------------------

Compiler identification string.

A short string unique to the compiler vendor.  Possible values include:

     Absoft = Absoft Fortran (absoft.com)
     ADSP = Analog VisualDSP++ (analog.com)
     AppleClang = Apple Clang (apple.com)
     ARMCC = ARM Compiler (arm.com)
     ARMClang = ARM Compiler based on Clang (arm.com)
     Bruce = Bruce C Compiler
     CCur = Concurrent Fortran (ccur.com)
     Clang = LLVM Clang (clang.llvm.org)
     Cray = Cray Compiler (cray.com)
     Embarcadero, Borland = Embarcadero (embarcadero.com)
     Flang = Flang LLVM Fortran Compiler
     G95 = G95 Fortran (g95.org)
     GNU = GNU Compiler Collection (gcc.gnu.org)
     GHS = Green Hills Software (www.ghs.com)
     HP = Hewlett-Packard Compiler (hp.com)
     IAR = IAR Systems (iar.com)
     Intel = Intel Compiler (intel.com)
     MSVC = Microsoft Visual Studio (microsoft.com)
     NVIDIA = NVIDIA CUDA Compiler (nvidia.com)
     OpenWatcom = Open Watcom (openwatcom.org)
     PGI = The Portland Group (pgroup.com)
     PathScale = PathScale (pathscale.com)
     SDCC = Small Device C Compiler (sdcc.sourceforge.net)
     SunPro = Oracle Solaris Studio (oracle.com)
     TI = Texas Instruments (ti.com)
     TinyCC = Tiny C Compiler (tinycc.org)
     XL, VisualAge, zOS = IBM XL (ibm.com)
     XLClang = IBM Clang-based XL (ibm.com)

This variable is not guaranteed to be defined for all compilers or
languages.

23.5.34 CMAKE_<LANG>_COMPILER_LOADED
------------------------------------

Defined to true if the language is enabled.

When language ‘<LANG>’ is enabled by project() or
enable_language() this variable is defined to ‘1’.

23.5.35 CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND
------------------------------------------------

New in version 3.10.

Command that outputs the compiler pre definitions.

See AUTOMOC which uses
CMAKE_CXX_COMPILER_PREDEFINES_COMMAND to generate the
AUTOMOC_COMPILER_PREDEFINES.

23.5.36 CMAKE_<LANG>_COMPILER_TARGET
------------------------------------

The target for cross-compiling, if supported.

Some compiler drivers are inherently cross-compilers, such as clang and
QNX qcc.  These compiler drivers support a command-line argument to
specify the target to cross-compile for.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

23.5.37 CMAKE_<LANG>_COMPILER_VERSION
-------------------------------------

Compiler version string.

Compiler version in major[.minor[.patch[.tweak]]] format.  This variable
is not guaranteed to be defined for all compilers or languages.

For example ‘CMAKE_C_COMPILER_VERSION’ and ‘CMAKE_CXX_COMPILER_VERSION’
might indicate the respective C and C++ compiler version.

23.5.38 CMAKE_<LANG>_COMPILE_OBJECT
-----------------------------------

Rule variable to compile a single object file.

This is a rule variable that tells CMake how to compile a single object
file for the language ‘<LANG>’.

23.5.39 CMAKE_<LANG>_CREATE_SHARED_LIBRARY
------------------------------------------

Rule variable to create a shared library.

This is a rule variable that tells CMake how to create a shared library
for the language ‘<LANG>’.  This rule variable is a ‘;’ delimited list
of commands to run to perform the linking step.

23.5.40 CMAKE_<LANG>_CREATE_SHARED_MODULE
-----------------------------------------

Rule variable to create a shared module.

This is a rule variable that tells CMake how to create a shared library
for the language ‘<LANG>’.  This rule variable is a ‘;’ delimited list
of commands to run.

23.5.41 CMAKE_<LANG>_CREATE_STATIC_LIBRARY
------------------------------------------

Rule variable to create a static library.

This is a rule variable that tells CMake how to create a static library
for the language ‘<LANG>’.

23.5.42 CMAKE_<LANG>_FLAGS
--------------------------

Flags for all build types.

‘<LANG>’ flags used regardless of the value of CMAKE_BUILD_TYPE.

This is initialized for each language from environment variables:

   * ‘CMAKE_C_FLAGS’: Initialized by the CFLAGS environment
     variable.

   * ‘CMAKE_CXX_FLAGS’: Initialized by the CXXFLAGS.
     environment variable.

   * ‘CMAKE_CUDA_FLAGS’: Initialized by the CUDAFLAGS.
     environment variable.

   * ‘CMAKE_Fortran_FLAGS’: Initialized by the FFLAGS.
     environment variable.

23.5.43 CMAKE_<LANG>_FLAGS_<CONFIG>
-----------------------------------

New in version 3.11.

Flags for language ‘<LANG>’ when building for the ‘<CONFIG>’
configuration.

23.5.44 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
----------------------------------------

New in version 3.11.

Value used to initialize the CMAKE_<LANG>_FLAGS_<CONFIG>.
cache entry the first time a build tree is configured for language
‘<LANG>’.  This variable is meant to be set by a toolchain file.
CMake may prepend or append content to the value based on the
environment and target platform.

See also CMAKE_<LANG>_FLAGS_INIT.

23.5.45 CMAKE_<LANG>_FLAGS_DEBUG
--------------------------------

This variable is the ‘Debug’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG> variable.

23.5.46 CMAKE_<LANG>_FLAGS_DEBUG_INIT
-------------------------------------

New in version 3.7.

This variable is the ‘Debug’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.

23.5.47 CMAKE_<LANG>_FLAGS_INIT
-------------------------------

New in version 3.7.

Value used to initialize the CMAKE_<LANG>_FLAGS cache entry
the first time a build tree is configured for language ‘<LANG>’.  This
variable is meant to be set by a toolchain file.  CMake may
prepend or append content to the value based on the environment and
target platform.  For example, the contents of a ‘xxxFLAGS’ environment
variable will be prepended, where ‘xxx’ will be language-specific but
not necessarily the same as ‘<LANG>’ (e.g.  see CXXFLAGS for
‘CXX’, see FFLAGS for ‘Fortran’, and so on).

See also the configuration-specific
CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.

23.5.48 CMAKE_<LANG>_FLAGS_MINSIZEREL
-------------------------------------

This variable is the ‘MinSizeRel’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG> variable.

23.5.49 CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
------------------------------------------

New in version 3.7.

This variable is the ‘MinSizeRel’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.

23.5.50 CMAKE_<LANG>_FLAGS_RELEASE
----------------------------------

This variable is the ‘Release’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG> variable.

23.5.51 CMAKE_<LANG>_FLAGS_RELEASE_INIT
---------------------------------------

New in version 3.7.

This variable is the ‘Release’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.

23.5.52 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
-----------------------------------------

This variable is the ‘RelWithDebInfo’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG> variable.

23.5.53 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT
----------------------------------------------

New in version 3.7.

This variable is the ‘RelWithDebInfo’ variant of the
CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.

23.5.54 CMAKE_<LANG>_IGNORE_EXTENSIONS
--------------------------------------

File extensions that should be ignored by the build.

This is a list of file extensions that may be part of a project for a
given language but are not compiled.

23.5.55 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
-------------------------------------------------

Directories implicitly searched by the compiler for header files.

CMake does not explicitly specify these directories on compiler command
lines for language ‘<LANG>’.  This prevents system include directories
from being treated as user include directories on some compilers, which
is important for ‘C’, ‘CXX’, and ‘CUDA’ to avoid overriding standard
library headers.

This value is not used for ‘Fortran’ because it has no standard library
headers and some compilers do not search their implicit include
directories for module ‘.mod’ files.

23.5.56 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
----------------------------------------------

Implicit linker search path detected for language ‘<LANG>’.

Compilers typically pass directories containing language runtime
libraries and default library search paths when they invoke a linker.
These paths are implicit linker search directories for the compiler’s
language.  CMake automatically detects these directories for each
language and reports the results in this variable.

Some toolchains read implicit directories from an environment variable
such as ‘LIBRARY_PATH’.  If using such an environment variable, keep its
value consistent when operating in a given build tree because CMake
saves the value detected when first creating a build tree.

If policy CMP0060 is not set to ‘NEW’, then when a library
in one of these directories is given by full path to
target_link_libraries(). CMake will generate the ‘-l<name>’ form on
link lines for historical purposes.

23.5.57 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
--------------------------------------------------------

Implicit linker framework search path detected for language ‘<LANG>’.

These paths are implicit linker framework search directories for the
compiler’s language.  CMake automatically detects these directories for
each language and reports the results in this variable.

23.5.58 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
--------------------------------------------

Implicit link libraries and flags detected for language ‘<LANG>’.

Compilers typically pass language runtime library names and other flags
when they invoke a linker.  These flags are implicit link options for
the compiler’s language.  CMake automatically detects these libraries
and flags for each language and reports the results in this variable.

23.5.59 CMAKE_<LANG>_LIBRARY_ARCHITECTURE
-----------------------------------------

Target architecture library directory name detected for ‘<LANG>’.

If the ‘<LANG>’ compiler passes to the linker an architecture-specific
system library search directory such as ‘<prefix>/lib/<arch>’ this
variable contains the ‘<arch>’ name if/as detected by CMake.

23.5.60 CMAKE_<LANG>_LINK_EXECUTABLE
------------------------------------

Rule variable to link an executable.

Rule variable to link an executable for the given language.

23.5.61 CMAKE_<LANG>_LINKER_PREFERENCE
--------------------------------------

Preference value for linker language selection.

The “linker language” for executable, shared library, and module targets
is the language whose compiler will invoke the linker.  The
LINKER_LANGUAGE target property sets the language explicitly.
Otherwise, the linker language is that whose linker preference value is
highest among languages compiled and linked into the target.  See also
the CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES variable.

23.5.62 CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
-------------------------------------------------

True if CMAKE_<LANG>_LINKER_PREFERENCE propagates across
targets.

This is used when CMake selects a linker language for a target.
Languages compiled directly into the target are always considered.  A
language compiled into static libraries linked by the target is
considered if this variable is true.

23.5.63 CMAKE_<LANG>_LINKER_WRAPPER_FLAG
----------------------------------------

New in version 3.13.

Defines the syntax of compiler driver option to pass options to the
linker tool.  It will be used to translate the ‘LINKER:’ prefix in the
link options (see add_link_options() and
target_link_options()).

This variable holds a semicolon-separated list of tokens.  If
a space (i.e.  ” “) is specified as last token, flag and ‘LINKER:’
arguments will be specified as separate arguments to the compiler
driver.  The CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variable
can be specified to manage concatenation of arguments.

For example, for ‘Clang’ we have:

     set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")

Specifying ‘"LINKER:-z,defs"’ will be transformed in ‘-Xlinker -z
-Xlinker defs’.

For ‘GNU GCC’:

     set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
     set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")

Specifying ‘"LINKER:-z,defs"’ will be transformed in ‘-Wl,-z,defs’.

And for ‘SunPro’:

     set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
     set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")

Specifying ‘"LINKER:-z,defs"’ will be transformed in ‘-Qoption ld
-z,defs’.

23.5.64 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
--------------------------------------------

New in version 3.13.

This variable is used with CMAKE_<LANG>_LINKER_WRAPPER_FLAG.
variable to format ‘LINKER:’ prefix in the link options (see
add_link_options() and target_link_options()).

When specified, arguments of the ‘LINKER:’ prefix will be concatenated
using this value as separator.

23.5.65 CMAKE_<LANG>_OUTPUT_EXTENSION
-------------------------------------

Extension for the output of a compile for a single file.

This is the extension for an object file for the given ‘<LANG>’.  For
example ‘.obj’ for C on Windows.

23.5.66 CMAKE_<LANG>_SIMULATE_ID
--------------------------------

Identification string of “simulated” compiler.

Some compilers simulate other compilers to serve as drop-in
replacements.  When CMake detects such a compiler it sets this variable
to what would have been the CMAKE_<LANG>_COMPILER_ID for the
simulated compiler.

23.5.67 CMAKE_<LANG>_SIMULATE_VERSION
-------------------------------------

Version string of “simulated” compiler.

Some compilers simulate other compilers to serve as drop-in
replacements.  When CMake detects such a compiler it sets this variable
to what would have been the CMAKE_<LANG>_COMPILER_VERSION.
for the simulated compiler.

23.5.68 CMAKE_<LANG>_SIZEOF_DATA_PTR
------------------------------------

Size of pointer-to-data types for language ‘<LANG>’.

This holds the size (in bytes) of pointer-to-data types in the target
platform ABI. It is defined for languages ‘C’ and ‘CXX’ (C++).

23.5.69 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
-------------------------------------------

Extensions of source files for the given language.

This is the list of extensions for a given language’s source files.

23.5.70 CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES
-------------------------------------------------

New in version 3.6.

Include directories to be used for every source file compiled with the
‘<LANG>’ compiler.  This is meant for specification of system include
directories needed by the language for the current platform.  The
directories always appear at the end of the include path passed to the
compiler.

This variable should not be set by project code.  It is meant to be set
by CMake’s platform information modules for the current toolchain, or by
a toolchain file when used with CMAKE_TOOLCHAIN_FILE.

See also CMAKE_<LANG>_STANDARD_LIBRARIES.

23.5.71 CMAKE_<LANG>_STANDARD_LIBRARIES
---------------------------------------

New in version 3.6.

Libraries linked into every executable and shared library linked for
language ‘<LANG>’.  This is meant for specification of system libraries
needed by the language for the current platform.

This variable should not be set by project code.  It is meant to be set
by CMake’s platform information modules for the current toolchain, or by
a toolchain file when used with CMAKE_TOOLCHAIN_FILE.

See also CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES.

23.5.72 CMAKE_OBJC_EXTENSIONS
-----------------------------

New in version 3.16.

Default value for OBJC_EXTENSIONS property of targets.

This variable is used to initialize the OBJC_EXTENSIONS.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.73 CMAKE_OBJC_STANDARD
---------------------------

New in version 3.16.

Default value for OBJC_STANDARD property of targets.

This variable is used to initialize the OBJC_STANDARD.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.74 CMAKE_OBJC_STANDARD_REQUIRED
------------------------------------

New in version 3.16.

Default value for OBJC_STANDARD_REQUIRED property of
targets.

This variable is used to initialize the OBJC_STANDARD_REQUIRED
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.75 CMAKE_OBJCXX_EXTENSIONS
-------------------------------

New in version 3.16.

Default value for OBJCXX_EXTENSIONS property of targets.

This variable is used to initialize the OBJCXX_EXTENSIONS.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.76 CMAKE_OBJCXX_STANDARD
-----------------------------

New in version 3.16.

Default value for OBJCXX_STANDARD property of targets.

This variable is used to initialize the OBJCXX_STANDARD.
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.77 CMAKE_OBJCXX_STANDARD_REQUIRED
--------------------------------------

New in version 3.16.

Default value for OBJCXX_STANDARD_REQUIRED property of
targets.

This variable is used to initialize the OBJCXX_STANDARD_REQUIRED
property on all targets.  See that target property for additional
information.

See the cmake-compile-features(7) manual for information on
compile features and a list of supported compilers.

23.5.78 CMAKE_Swift_LANGUAGE_VERSION
------------------------------------

New in version 3.7.

Set to the Swift language version number.  If not set, the oldest legacy
version known to be available in the host Xcode version is assumed:

   * Swift ‘4.0’ for Xcode 10.2 and above.

   * Swift ‘3.0’ for Xcode 8.3 and above.

   * Swift ‘2.3’ for Xcode 8.2 and below.

23.5.79 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
---------------------------------------------

Specify a CMake file that overrides platform information for ‘<LANG>’.

This is a language-specific version of
CMAKE_USER_MAKE_RULES_OVERRIDE loaded only when enabling language
‘<LANG>’.

23.6 Variables for CTest
========================

23.6.1 CTEST_BINARY_DIRECTORY
-----------------------------

New in version 3.1.

Specify the CTest ‘BuildDirectory’ setting in a ctest(1).
dashboard client script.

23.6.2 CTEST_BUILD_COMMAND
--------------------------

New in version 3.1.

Specify the CTest ‘MakeCommand’ setting in a ctest(1).
dashboard client script.

23.6.3 CTEST_BUILD_NAME
-----------------------

New in version 3.1.

Specify the CTest ‘BuildName’ setting in a ctest(1) dashboard
client script.

23.6.4 CTEST_BZR_COMMAND
------------------------

New in version 3.1.

Specify the CTest ‘BZRCommand’ setting in a ctest(1).
dashboard client script.

23.6.5 CTEST_BZR_UPDATE_OPTIONS
-------------------------------

New in version 3.1.

Specify the CTest ‘BZRUpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.6 CTEST_CHANGE_ID
----------------------

New in version 3.4.

Specify the CTest ‘ChangeId’ setting in a ctest(1) dashboard
client script.

This setting allows CTest to pass arbitrary information about this build
up to CDash.  One use of this feature is to allow CDash to post comments
on your pull request if anything goes wrong with your build.

23.6.7 CTEST_CHECKOUT_COMMAND
-----------------------------

New in version 3.1.

Tell the ctest_start() command how to checkout or initialize
the source directory in a ctest(1) dashboard client script.

23.6.8 CTEST_CONFIGURATION_TYPE
-------------------------------

New in version 3.1.

Specify the CTest ‘DefaultCTestConfigurationType’ setting in a
ctest(1) dashboard client script.

If the configuration type is set via ‘-C <cfg>’ from the command line
then this variable is populated accordingly.

23.6.9 CTEST_CONFIGURE_COMMAND
------------------------------

New in version 3.1.

Specify the CTest ‘ConfigureCommand’ setting in a ctest(1).
dashboard client script.

23.6.10 CTEST_COVERAGE_COMMAND
------------------------------

New in version 3.1.

Specify the CTest ‘CoverageCommand’ setting in a ctest(1).
dashboard client script.

23.6.10.1 Cobertura
...................

Using Cobertura(1) as the coverage generation within your multi-module
Java project can generate a series of XML files.

The Cobertura Coverage parser expects to read the coverage data from a
single XML file which contains the coverage data for all modules.
Cobertura has a program with the ability to merge given ‘cobertura.ser’
files and then another program to generate a combined XML file from the
previous merged file.  For command line testing, this can be done by
hand prior to CTest looking for the coverage files.  For script builds,
set the ‘CTEST_COVERAGE_COMMAND’ variable to point to a file which will
perform these same steps, such as a ‘.sh’ or ‘.bat’ file.

     set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh)

where the ‘run-coverage-and-consolidate.sh’ script is perhaps created by
the configure_file() command and might contain the following
code:

     #!/usr/bin/env bash
     CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")"
     SourceDirs="$(find "/path/to/source" -name "java" -type d)"
     cobertura-merge --datafile coberturamerge.ser $CoberturaFiles
     cobertura-report --datafile coberturamerge.ser --destination . \
                      --format xml $SourceDirs

The script uses ‘find’ to capture the paths to all of the
‘cobertura.ser’ files found below the project’s source directory.  It
keeps the list of files and supplies it as an argument to the
‘cobertura-merge’ program.  The ‘--datafile’ argument signifies where
the result of the merge will be kept.

The combined ‘coberturamerge.ser’ file is then used to generate the XML
report using the ‘cobertura-report’ program.  The call to the
cobertura-report program requires some named arguments.

‘--datafila’

     path to the merged ‘.ser’ file

‘--destination’

     path to put the output files(s)

‘--format’

     file format to write output in: xml or html

The rest of the supplied arguments consist of the full paths to the
‘/src/main/java’ directories of each module within the source tree.
These directories are needed and should not be forgotten.

   ---------- Footnotes ----------

   (1) http://cobertura.github.io/cobertura/

23.6.11 CTEST_COVERAGE_EXTRA_FLAGS
----------------------------------

New in version 3.1.

Specify the CTest ‘CoverageExtraFlags’ setting in a ctest(1).
dashboard client script.

23.6.12 CTEST_CURL_OPTIONS
--------------------------

New in version 3.1.

Specify the CTest ‘CurlOptions’ setting in a ctest(1).
dashboard client script.

23.6.13 CTEST_CUSTOM_COVERAGE_EXCLUDE
-------------------------------------

A list of regular expressions which will be used to exclude files by
their path from coverage output by the ctest_coverage().
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.14 CTEST_CUSTOM_ERROR_EXCEPTION
------------------------------------

A list of regular expressions which will be used to exclude when
detecting error messages in build outputs by the ctest_test().
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.15 CTEST_CUSTOM_ERROR_MATCH
--------------------------------

A list of regular expressions which will be used to detect error
messages in build outputs by the ctest_test() command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.16 CTEST_CUSTOM_ERROR_POST_CONTEXT
---------------------------------------

The number of lines to include as context which follow an error message
by the ctest_test() command.  The default is 10.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.17 CTEST_CUSTOM_ERROR_PRE_CONTEXT
--------------------------------------

The number of lines to include as context which precede an error message
by the ctest_test() command.  The default is 10.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.18 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
----------------------------------------------------

When saving a failing test’s output, this is the maximum size, in bytes,
that will be collected by the ctest_test() command.  Defaults
to 307200 (300 KiB).

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.19 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
---------------------------------------------

The maximum number of errors in a single build step which will be
detected.  After this, the ctest_test() command will truncate
the output.  Defaults to 50.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.20 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
-----------------------------------------------

The maximum number of warnings in a single build step which will be
detected.  After this, the ctest_test() command will truncate
the output.  Defaults to 50.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.21 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
----------------------------------------------------

When saving a passing test’s output, this is the maximum size, in bytes,
that will be collected by the ctest_test() command.  Defaults
to 1024 (1 KiB).

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.22 CTEST_CUSTOM_MEMCHECK_IGNORE
------------------------------------

A list of regular expressions to use to exclude tests during the
ctest_memcheck() command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.23 CTEST_CUSTOM_POST_MEMCHECK
----------------------------------

A list of commands to run at the end of the ctest_memcheck().
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.24 CTEST_CUSTOM_POST_TEST
------------------------------

A list of commands to run at the end of the ctest_test().
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.25 CTEST_CUSTOM_PRE_MEMCHECK
---------------------------------

A list of commands to run at the start of the ctest_memcheck()
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.26 CTEST_CUSTOM_PRE_TEST
-----------------------------

A list of commands to run at the start of the ctest_test().
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.27 CTEST_CUSTOM_TESTS_IGNORE
---------------------------------

A list of regular expressions to use to exclude tests during the
ctest_test() command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.28 CTEST_CUSTOM_WARNING_EXCEPTION
--------------------------------------

A list of regular expressions which will be used to exclude when
detecting warning messages in build outputs by the ctest_build()
command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.29 CTEST_CUSTOM_WARNING_MATCH
----------------------------------

A list of regular expressions which will be used to detect warning
messages in build outputs by the ctest_build() command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.30 CTEST_CVS_CHECKOUT
--------------------------

New in version 3.1.

Deprecated.  Use CTEST_CHECKOUT_COMMAND instead.

23.6.31 CTEST_CVS_COMMAND
-------------------------

New in version 3.1.

Specify the CTest ‘CVSCommand’ setting in a ctest(1).
dashboard client script.

23.6.32 CTEST_CVS_UPDATE_OPTIONS
--------------------------------

New in version 3.1.

Specify the CTest ‘CVSUpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.33 CTEST_DROP_LOCATION
---------------------------

New in version 3.1.

Specify the CTest ‘DropLocation’ setting in a ctest(1).
dashboard client script.

23.6.34 CTEST_DROP_METHOD
-------------------------

New in version 3.1.

Specify the CTest ‘DropMethod’ setting in a ctest(1).
dashboard client script.

23.6.35 CTEST_DROP_SITE
-----------------------

New in version 3.1.

Specify the CTest ‘DropSite’ setting in a ctest(1) dashboard
client script.

23.6.36 CTEST_DROP_SITE_CDASH
-----------------------------

New in version 3.1.

Specify the CTest ‘IsCDash’ setting in a ctest(1) dashboard
client script.

23.6.37 CTEST_DROP_SITE_PASSWORD
--------------------------------

New in version 3.1.

Specify the CTest ‘DropSitePassword’ setting in a ctest(1).
dashboard client script.

23.6.38 CTEST_DROP_SITE_USER
----------------------------

New in version 3.1.

Specify the CTest ‘DropSiteUser’ setting in a ctest(1).
dashboard client script.

23.6.39 CTEST_EXTRA_COVERAGE_GLOB
---------------------------------

New in version 3.4.

A list of regular expressions which will be used to find files which
should be covered by the ctest_coverage() command.

It is initialized by ctest(1), but may be edited in a
‘CTestCustom’ file.  See ctest_read_custom_files().
documentation.

23.6.40 CTEST_GIT_COMMAND
-------------------------

New in version 3.1.

Specify the CTest ‘GITCommand’ setting in a ctest(1).
dashboard client script.

23.6.41 CTEST_GIT_INIT_SUBMODULES
---------------------------------

New in version 3.6.

Specify the CTest ‘GITInitSubmodules’ setting in a ctest(1).
dashboard client script.

23.6.42 CTEST_GIT_UPDATE_CUSTOM
-------------------------------

New in version 3.1.

Specify the CTest ‘GITUpdateCustom’ setting in a ctest(1).
dashboard client script.

23.6.43 CTEST_GIT_UPDATE_OPTIONS
--------------------------------

New in version 3.1.

Specify the CTest ‘GITUpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.44 CTEST_HG_COMMAND
------------------------

New in version 3.1.

Specify the CTest ‘HGCommand’ setting in a ctest(1) dashboard
client script.

23.6.45 CTEST_HG_UPDATE_OPTIONS
-------------------------------

New in version 3.1.

Specify the CTest ‘HGUpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.46 CTEST_LABELS_FOR_SUBPROJECTS
------------------------------------

New in version 3.10.

Specify the CTest ‘LabelsForSubprojects’ setting in a ctest(1)
dashboard client script.

23.6.47 CTEST_MEMORYCHECK_COMMAND
---------------------------------

New in version 3.1.

Specify the CTest ‘MemoryCheckCommand’ setting in a ctest(1).
dashboard client script.

23.6.48 CTEST_MEMORYCHECK_COMMAND_OPTIONS
-----------------------------------------

New in version 3.1.

Specify the CTest ‘MemoryCheckCommandOptions’ setting in a
ctest(1) dashboard client script.

23.6.49 CTEST_MEMORYCHECK_SANITIZER_OPTIONS
-------------------------------------------

New in version 3.1.

Specify the CTest ‘MemoryCheckSanitizerOptions’ setting in a
ctest(1) dashboard client script.

23.6.50 CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
-------------------------------------------

New in version 3.1.

Specify the CTest ‘MemoryCheckSuppressionFile’ setting in a
ctest(1) dashboard client script.

23.6.51 CTEST_MEMORYCHECK_TYPE
------------------------------

New in version 3.1.

Specify the CTest ‘MemoryCheckType’ setting in a ctest(1).
dashboard client script.  Valid values are ‘Valgrind’, ‘Purify’,
‘BoundsChecker’, ‘DrMemory’, ‘CudaSanitizer’, ‘ThreadSanitizer’,
‘AddressSanitizer’, ‘LeakSanitizer’, ‘MemorySanitizer’ and
‘UndefinedBehaviorSanitizer’.

23.6.52 CTEST_NIGHTLY_START_TIME
--------------------------------

New in version 3.1.

Specify the CTest ‘NightlyStartTime’ setting in a ctest(1).
dashboard client script.

Note that this variable must always be set for a nightly build in a
dashboard script.  It is needed so that nightly builds can be properly
grouped together in CDash.

23.6.53 CTEST_P4_CLIENT
-----------------------

New in version 3.1.

Specify the CTest ‘P4Client’ setting in a ctest(1) dashboard
client script.

23.6.54 CTEST_P4_COMMAND
------------------------

New in version 3.1.

Specify the CTest ‘P4Command’ setting in a ctest(1) dashboard
client script.

23.6.55 CTEST_P4_OPTIONS
------------------------

New in version 3.1.

Specify the CTest ‘P4Options’ setting in a ctest(1) dashboard
client script.

23.6.56 CTEST_P4_UPDATE_OPTIONS
-------------------------------

New in version 3.1.

Specify the CTest ‘P4UpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.57 CTEST_RESOURCE_SPEC_FILE
--------------------------------

New in version 3.18.

Specify the CTest ‘ResourceSpecFile’ setting in a ctest(1).
dashboard client script.

This can also be used to specify the resource spec file from a CMake
build.  If no ‘RESOURCE_SPEC_FILE’ is passed to ctest_test(),
and ‘CTEST_RESOURCE_SPEC_FILE’ is not specified in the dashboard script,
the value of this variable from the build is used.

23.6.58 CTEST_RUN_CURRENT_SCRIPT
--------------------------------

New in version 3.11.

Setting this to 0 prevents ctest(1) from being run again when
it reaches the end of a script run by calling ‘ctest -S’.

23.6.59 CTEST_SCP_COMMAND
-------------------------

New in version 3.1.

Legacy option.  Not used.

23.6.60 CTEST_SITE
------------------

New in version 3.1.

Specify the CTest ‘Site’ setting in a ctest(1) dashboard
client script.

23.6.61 CTEST_SUBMIT_URL
------------------------

New in version 3.14.

Specify the CTest ‘SubmitURL’ setting in a ctest(1) dashboard
client script.

23.6.62 CTEST_SOURCE_DIRECTORY
------------------------------

New in version 3.1.

Specify the CTest ‘SourceDirectory’ setting in a ctest(1).
dashboard client script.

23.6.63 CTEST_SVN_COMMAND
-------------------------

New in version 3.1.

Specify the CTest ‘SVNCommand’ setting in a ctest(1).
dashboard client script.

23.6.64 CTEST_SVN_OPTIONS
-------------------------

New in version 3.1.

Specify the CTest ‘SVNOptions’ setting in a ctest(1).
dashboard client script.

23.6.65 CTEST_SVN_UPDATE_OPTIONS
--------------------------------

New in version 3.1.

Specify the CTest ‘SVNUpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.66 CTEST_TEST_LOAD
-----------------------

New in version 3.4.

Specify the ‘TestLoad’ setting in the CTest Test Step of a
ctest(1) dashboard client script.  This sets the default
value for the ‘TEST_LOAD’ option of the ctest_test() command.

23.6.67 CTEST_TEST_TIMEOUT
--------------------------

New in version 3.1.

Specify the CTest ‘TimeOut’ setting in a ctest(1) dashboard
client script.

23.6.68 CTEST_TRIGGER_SITE
--------------------------

New in version 3.1.

Legacy option.  Not used.

23.6.69 CTEST_UPDATE_COMMAND
----------------------------

New in version 3.1.

Specify the CTest ‘UpdateCommand’ setting in a ctest(1).
dashboard client script.

23.6.70 CTEST_UPDATE_OPTIONS
----------------------------

New in version 3.1.

Specify the CTest ‘UpdateOptions’ setting in a ctest(1).
dashboard client script.

23.6.71 CTEST_UPDATE_VERSION_ONLY
---------------------------------

New in version 3.1.

Specify the CTest UpdateVersionOnly setting in a
ctest(1) dashboard client script.

23.6.72 CTEST_UPDATE_VERSION_OVERRIDE
-------------------------------------

New in version 3.15.

Specify the CTest UpdateVersionOverride setting in a
ctest(1) dashboard client script.

23.6.73 CTEST_USE_LAUNCHERS
---------------------------

New in version 3.1.

Specify the CTest ‘UseLaunchers’ setting in a ctest(1).
dashboard client script.

23.7 Variables for CPack
========================

23.7.1 CPACK_ABSOLUTE_DESTINATION_FILES
---------------------------------------

List of files which have been installed using an ‘ABSOLUTE DESTINATION’
path.

This variable is a Read-Only variable which is set internally by CPack
during installation and before packaging using
CMAKE_ABSOLUTE_DESTINATION_FILES defined in ‘cmake_install.cmake’
scripts.  The value can be used within CPack project configuration file
and/or ‘CPack<GEN>.cmake’ file of ‘<GEN>’ generator.

23.7.2 CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
-------------------------------------------------

Boolean toggle to include/exclude top level directory (component case).

Similar usage as CPACK_INCLUDE_TOPLEVEL_DIRECTORY but for
the component case.  See CPACK_INCLUDE_TOPLEVEL_DIRECTORY.
documentation for the detail.

23.7.3 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
--------------------------------------------------

Ask CPack to error out as soon as a file with absolute ‘INSTALL
DESTINATION’ is encountered.

The fatal error is emitted before the installation of the offending file
takes place.  Some CPack generators, like ‘NSIS’, enforce this
internally.  This variable triggers the definition of
CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs.

23.7.4 CPACK_INCLUDE_TOPLEVEL_DIRECTORY
---------------------------------------

Boolean toggle to include/exclude top level directory.

When preparing a package CPack installs the item under the so-called top
level directory.  The purpose of is to include (set to ‘1’ or ‘ON’ or
‘TRUE’) the top level directory in the package or not (set to ‘0’ or
‘OFF’ or ‘FALSE’).

Each CPack generator has a built-in default value for this variable.
E.g.  Archive generators (ZIP, TGZ, …) includes the top level whereas
RPM or DEB don’t.  The user may override the default value by setting
this variable.

There is a similar variable
CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY which may be used to
override the behavior for the component packaging case which may have
different default value for historical (now backward compatibility)
reason.

23.7.5 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
--------------------------------------------------

New in version 3.11.

Default permissions for implicitly created directories during packaging.

This variable serves the same purpose during packaging as the
CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable serves during
installation (e.g.  ‘make install’).

If ‘include(CPack)’ is used then by default this variable is set to the
content of CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.

23.7.6 CPACK_PACKAGING_INSTALL_PREFIX
-------------------------------------

The prefix used in the built package.

Each CPack generator has a default value (like ‘/usr’).  This default
value may be overwritten from the ‘CMakeLists.txt’ or the
cpack(1) command line by setting an alternative value.  Example:

     set(CPACK_PACKAGING_INSTALL_PREFIX "/opt")

This is not the same purpose as CMAKE_INSTALL_PREFIX which is
used when installing from the build tree without building a package.

23.7.7 CPACK_SET_DESTDIR
------------------------

Boolean toggle to make CPack use ‘DESTDIR’ mechanism when packaging.

‘DESTDIR’ means DESTination DIRectory.  It is commonly used by makefile
users in order to install software at non-default location.  It is a
basic relocation mechanism that should not be used on Windows (see
CMAKE_INSTALL_PREFIX documentation).  It is usually invoked like
this:

     make DESTDIR=/home/john install

which will install the concerned software using the installation prefix,
e.g.  ‘/usr/local’ prepended with the ‘DESTDIR’ value which finally
gives ‘/home/john/usr/local’.  When preparing a package, CPack first
installs the items to be packaged in a local (to the build tree)
directory by using the same ‘DESTDIR’ mechanism.  Nevertheless, if
‘CPACK_SET_DESTDIR’ is set then CPack will set ‘DESTDIR’ before doing
the local install.  The most noticeable difference is that without
‘CPACK_SET_DESTDIR’, CPack uses CPACK_PACKAGING_INSTALL_PREFIX
as a prefix whereas with ‘CPACK_SET_DESTDIR’ set, CPack will use
CMAKE_INSTALL_PREFIX as a prefix.

Manually setting ‘CPACK_SET_DESTDIR’ may help (or simply be necessary)
if some install rules uses absolute ‘DESTINATION’ (see CMake
install() command).  However, starting with CPack/CMake 2.8.3 RPM
and DEB installers tries to handle ‘DESTDIR’ automatically so that it is
seldom necessary for the user to set it.

23.7.8 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
-------------------------------------------------

Ask CPack to warn each time a file with absolute ‘INSTALL DESTINATION’
is encountered.

This variable triggers the definition of
CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs
‘cmake_install.cmake’ scripts.

23.8 Variable Expansion Operators
=================================

23.8.1 CACHE
------------

New in version 3.13.

Operator to read cache variables.

Use the syntax ‘$CACHE{VAR}’ to read cache entry ‘VAR’.  See the
cmake-language(7) variables documentation for more complete
documentation of the interaction of normal variables and cache entries.

When evaluating Variable References of the form ‘${VAR}’,
CMake first searches for a normal variable with that name, and if not
found CMake will search for a cache entry with that name.  The
‘$CACHE{VAR}’ syntax can be used to do direct cache lookup and ignore
any existing normal variable.

See the set() and unset() commands to see how to
write or remove cache variables.

23.8.2 ENV
----------

Operator to read environment variables.

Use the syntax ‘$ENV{VAR}’ to read environment variable ‘VAR’.

To test whether an environment variable is defined, use the signature
‘if(DEFINED ENV{<name>})’ of the if() command.

See the set() and unset() commands to see how to
write or remove environment variables.

23.9 Internal Variables
=======================

CMake has many internal variables.  Most of them are undocumented.  Some
of them, however, were at some point described as normal variables, and
therefore may be encountered in legacy code.  They are subject to
change, and not recommended for use in project code.

23.9.1 CMAKE_HOME_DIRECTORY
---------------------------

Path to top of source tree.  Same as CMAKE_SOURCE_DIR.

This is an internal cache entry used to locate the source directory when
loading a ‘CMakeCache.txt’ from a build tree.  It should not be used in
project code.  The variable CMAKE_SOURCE_DIR has the same
value and should be preferred.

23.9.2 CMAKE_INTERNAL_PLATFORM_ABI
----------------------------------

An internal variable subject to change.

This is used in determining the compiler ABI and is subject to change.

23.9.3 CMAKE_<LANG>_COMPILER_ABI
--------------------------------

An internal variable subject to change.

This is used in determining the compiler ABI and is subject to change.

23.9.4 CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID
--------------------------------------------

New in version 3.10.

An internal variable subject to change.

This is used to identify the variant of a compiler based on its target
architecture.  For some compilers this is needed to determine the
correct usage.

23.9.5 CMAKE_<LANG>_COMPILER_VERSION_INTERNAL
---------------------------------------------

New in version 3.10.

An internal variable subject to change.

This is used to identify the variant of a compiler based on an internal
version number.  For some compilers this is needed to determine the
correct usage.

23.9.6 CMAKE_<LANG>_PLATFORM_ID
-------------------------------

An internal variable subject to change.

This is used in determining the platform and is subject to change.

23.9.7 CMAKE_NOT_USING_CONFIG_FLAGS
-----------------------------------

Skip ‘_BUILD_TYPE’ flags if true.

This is an internal flag used by the generators in CMake to tell CMake
to skip the ‘_BUILD_TYPE’ flags.

23.9.8 CMAKE_VS_INTEL_Fortran_PROJECT_VERSION
---------------------------------------------

When generating for Visual Studio 9 2008 or greater with the
Intel Fortran plugin installed, this specifies the ‘.vfproj’ project
file format version.  This is intended for internal use by CMake and
should not be used by project code.

24 cpack-generators(7)
**********************

24.1 Generators
===============

24.1.1 CPack Archive Generator
------------------------------

CPack generator for packaging files into an archive, which can have any
of the following formats:

        - 7Z - 7zip - (.7z)

        - TBZ2 (.tar.bz2)

        - TGZ (.tar.gz)

        - TXZ (.tar.xz)

        - TZ (.tar.Z)

        - TZST (.tar.zst)

        - ZIP (.zip)

When this generator is called from ‘CPackSourceConfig.cmake’ (or through
the ‘package_source’ target), then the generated archive will contain
all files in the project directory, except those specified in
CPACK_SOURCE_IGNORE_FILES.  The following is one example of
packaging all source files of a project:

     set(CPACK_SOURCE_GENERATOR "TGZ")
     set(CPACK_SOURCE_IGNORE_FILES
       \\.git/
       build/
       ".*~$"
     )
     set(CPACK_VERBATIM_VARIABLES YES)
     include(CPack)

When this generator is called from ‘CPackConfig.cmake’ (or through the
‘package’ target), then the generated archive will contain all files
that have been installed via CMake’s install() command (and
the deprecated commands install_files(),
install_programs(), and install_targets()).

24.1.1.1 Variables specific to CPack Archive generator
......................................................

 -- Variable: CPACK_ARCHIVE_FILE_NAME
 -- Variable: CPACK_ARCHIVE_<component>_FILE_NAME

     Package file name without extension.  The extension is determined
     from the archive format (see list above) and automatically appended
     to the file name.  The default is
     ‘<CPACK_PACKAGE_FILE_NAME>[-<component>]’, with spaces replaced by
     ‘-‘.

 -- Variable: CPACK_ARCHIVE_COMPONENT_INSTALL

     Enable component packaging.  If enabled (ON), then the archive
     generator creates multiple packages.  The default is OFF, which
     means that a single package containing files of all components is
     generated.

24.1.1.2 Variables used by CPack Archive generator
..................................................

These variables are used by the Archive generator, but are also
available to CPack generators which are essentially archives at their
core.  These include:

        - CPack Cygwin Generator.

        - CPack FreeBSD Generator.

 -- Variable: CPACK_ARCHIVE_THREADS

     The number of threads to use when performing the compression.  If
     set to ‘0’, the number of available cores on the machine will be
     used instead.  The default is ‘1’ which limits compression to a
     single thread.  Note that not all compression modes support
     threading in all environments.  Currently, only the XZ compression
     may support it.

     Note: Official CMake binaries available on ‘cmake.org’ ship with a
     ‘liblzma’ that does not support parallel compression.

24.1.2 CPack Bundle Generator
-----------------------------

CPack Bundle generator (macOS) specific options

24.1.2.1 Variables specific to CPack Bundle generator
.....................................................

Installers built on macOS using the Bundle generator use the
aforementioned DragNDrop (‘CPACK_DMG_xxx’) variables, plus the following
Bundle-specific parameters (‘CPACK_BUNDLE_xxx’).

 -- Variable: CPACK_BUNDLE_NAME

     The name of the generated bundle.  This appears in the macOS Finder
     as the bundle name.  Required.

 -- Variable: CPACK_BUNDLE_PLIST

     Path to an macOS Property List (‘.plist’) file that will be used
     for the generated bundle.  This assumes that the caller has
     generated or specified their own ‘Info.plist’ file.  Required.

 -- Variable: CPACK_BUNDLE_ICON

     Path to an macOS icon file that will be used as the icon for the
     generated bundle.  This is the icon that appears in the macOS
     Finder for the bundle, and in the macOS dock when the bundle is
     opened.  Required.

 -- Variable: CPACK_BUNDLE_STARTUP_COMMAND

     Path to a startup script.  This is a path to an executable or
     script that will be run whenever an end-user double-clicks the
     generated bundle in the macOS Finder.  Optional.

 -- Variable: CPACK_BUNDLE_APPLE_CERT_APP

     The name of your Apple supplied code signing certificate for the
     application.  The name usually takes the form ‘Developer ID
     Application: [Name]’ or ‘3rd Party Mac Developer Application:
     [Name]’.  If this variable is not set the application will not be
     signed.

 -- Variable: CPACK_BUNDLE_APPLE_ENTITLEMENTS

     The name of the Property List (‘.plist’) file that contains your
     Apple entitlements for sandboxing your application.  This file is
     required for submission to the macOS App Store.

 -- Variable: CPACK_BUNDLE_APPLE_CODESIGN_FILES

     A list of additional files that you wish to be signed.  You do not
     need to list the main application folder, or the main executable.
     You should list any frameworks and plugins that are included in
     your app bundle.

 -- Variable: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER

     Additional parameter that will passed to ‘codesign’.  Default
     value: ‘--deep -f’

 -- Variable: CPACK_COMMAND_CODESIGN

     Path to the ‘codesign(1)’ command used to sign applications with an
     Apple cert.  This variable can be used to override the
     automatically detected command (or specify its location if the
     auto-detection fails to find it).

24.1.3 CPack Cygwin Generator
-----------------------------

Cygwin CPack generator (Cygwin).

24.1.3.1 Variables affecting the CPack Cygwin generator
.......................................................

        - CPACK_ARCHIVE_THREADS.

24.1.3.2 Variables specific to CPack Cygwin generator
.....................................................

The following variable is specific to installers build on and/or for
Cygwin:

 -- Variable: CPACK_CYGWIN_PATCH_NUMBER

     The Cygwin patch number.  FIXME: This documentation is incomplete.

 -- Variable: CPACK_CYGWIN_PATCH_FILE

     The Cygwin patch file.  FIXME: This documentation is incomplete.

 -- Variable: CPACK_CYGWIN_BUILD_SCRIPT

     The Cygwin build script.  FIXME: This documentation is incomplete.

24.1.4 CPack DEB Generator
--------------------------

The built in (binary) CPack DEB generator (Unix only)

24.1.4.1 Variables specific to CPack Debian (DEB) generator
...........................................................

The CPack DEB generator may be used to create DEB package using
CPack.  The CPack DEB generator is a CPack generator thus
it uses the ‘CPACK_XXX’ variables used by CPack.

The CPack DEB generator should work on any Linux host but it will
produce better deb package when Debian specific tools ‘dpkg-xxx’ are
usable on the build system.

The CPack DEB generator has specific features which are controlled by
the specifics ‘CPACK_DEBIAN_XXX’ variables.

‘CPACK_DEBIAN_<COMPONENT>_XXXX’ variables may be used in order to have
`component' specific values.  Note however that ‘<COMPONENT>’ refers to
the `grouping name' written in upper case.  It may be either a component
name or a component GROUP name.

Here are some CPack DEB generator wiki resources that are here for
historic reasons and are no longer maintained but may still prove
useful:

        -
          ‘https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration’

        -
          ‘https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#deb-unix-only’

List of CPack DEB generator specific variables:

 -- Variable: CPACK_DEB_COMPONENT_INSTALL

     Enable component packaging for CPackDEB

        * Mandatory : NO

        * Default : OFF

     If enabled (ON) multiple packages are generated.  By default a
     single package containing files of all components is generated.

 -- Variable: CPACK_DEBIAN_PACKAGE_NAME
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME

     Set Package control field (variable is automatically transformed to
     lower case).

        * Mandatory : YES

        * Default :

             - CPACK_PACKAGE_NAME for non-component based
               installations

             - CPACK_DEBIAN_PACKAGE_NAME suffixed with
               -<COMPONENT> for component-based installations.

     See
     ‘https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source’

 -- Variable: CPACK_DEBIAN_FILE_NAME
 -- Variable: CPACK_DEBIAN_<COMPONENT>_FILE_NAME

     Package file name.

        * Mandatory : YES

        * Default : ‘<CPACK_PACKAGE_FILE_NAME>[-<component>].deb’

     This may be set to ‘DEB-DEFAULT’ to allow the CPack DEB generator
     to generate package file name by itself in deb format:

          <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb

     Alternatively provided package file name must end with either
     ‘.deb’ or ‘.ipk’ suffix.

          Note: Preferred setting of this variable is ‘DEB-DEFAULT’ but
          for backward compatibility with the CPack DEB generator in
          CMake prior to version 3.6 this feature is disabled by
          default.

          Note: By using non default filenames duplicate names may
          occur.  Duplicate files get overwritten and it is up to the
          packager to set the variables in a manner that will prevent
          such errors.

 -- Variable: CPACK_DEBIAN_PACKAGE_EPOCH

     The Debian package epoch

        * Mandatory : No

        * Default : -

     Optional number that should be incremented when changing versioning
     schemas or fixing mistakes in the version numbers of older
     packages.

 -- Variable: CPACK_DEBIAN_PACKAGE_VERSION

     The Debian package version

        * Mandatory : YES

        * Default : CPACK_PACKAGE_VERSION.

     This variable may contain only alphanumerics (A-Za-z0-9) and the
     characters .  + - ~ (full stop, plus, hyphen, tilde) and should
     start with a digit.  If CPACK_DEBIAN_PACKAGE_RELEASE.
     is not set then hyphens are not allowed.

          Note: For backward compatibility with CMake 3.9 and lower a
          failed test of this variable’s content is not a hard error
          when both CPACK_DEBIAN_PACKAGE_RELEASE and
          CPACK_DEBIAN_PACKAGE_EPOCH variables are not set.  An
          author warning is reported instead.

 -- Variable: CPACK_DEBIAN_PACKAGE_RELEASE

     The Debian package release - Debian revision number.

        * Mandatory : No

        * Default : -

     This is the numbering of the DEB package itself, i.e.  the version
     of the packaging and not the version of the content (see
     CPACK_DEBIAN_PACKAGE_VERSION).  One may change the default
     value if the previous packaging was buggy and/or you want to put
     here a fancy Linux distro specific numbering.

 -- Variable: CPACK_DEBIAN_PACKAGE_ARCHITECTURE
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE

     The Debian package architecture

        * Mandatory : YES

        * Default : Output of ‘dpkg --print-architecture’ (or ‘i386’ if
          ‘dpkg’ is not found)

 -- Variable: CPACK_DEBIAN_PACKAGE_DEPENDS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS

     Sets the Debian dependencies of this package.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_DEPENDS for
               component-based installations.

          Note: If CPACK_DEBIAN_PACKAGE_SHLIBDEPS or more
          specifically CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
          is set for this component, the discovered dependencies
          will be appended to
          CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS instead of
          CPACK_DEBIAN_PACKAGE_DEPENDS.  If
          CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS is an empty
          string, only the automatically discovered dependencies will be
          set for this component.

     Example:

          set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")

 -- Variable: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS

     Sets inter component dependencies if listed with
     CPACK_COMPONENT_<compName>_DEPENDS variables.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_DEBIAN_PACKAGE_MAINTAINER

     The Debian package maintainer

        * Mandatory : YES

        * Default : ‘CPACK_PACKAGE_CONTACT’

 -- Variable: CPACK_DEBIAN_PACKAGE_DESCRIPTION
 -- Variable: CPACK_DEBIAN_<COMPONENT>_DESCRIPTION

     The Debian package description

        * Mandatory : YES

        * Default :

             - CPACK_DEBIAN_<COMPONENT>_DESCRIPTION.
               (component based installers only) if set, or
               CPACK_DEBIAN_PACKAGE_DESCRIPTION if set, or

             - CPACK_COMPONENT_<compName>_DESCRIPTION.
               (component based installers only) if set, or
               CPACK_PACKAGE_DESCRIPTION if set, or

             - content of the file specified in
               CPACK_PACKAGE_DESCRIPTION_FILE if set

     If after that description is not set, see
     CPACK_PACKAGE_DESCRIPTION_SUMMARY going to be used if set.
     Otherwise, see CPACK_PACKAGE_DESCRIPTION_SUMMARY will be
     added as the first line of description as defined in Debian Policy
     Manual(1).

 -- Variable: CPACK_DEBIAN_PACKAGE_SECTION
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION

     Set Section control field e.g.  admin, devel, doc, …

        * Mandatory : YES

        * Default : “devel”

     See
     ‘https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections’

 -- Variable: CPACK_DEBIAN_ARCHIVE_TYPE

     The archive format used for creating the Debian package.

        * Mandatory : YES

        * Default : “gnutar”

     Possible value is:

        - gnutar

          Note: This variable previously defaulted to the ‘paxr’ value,
          but ‘dpkg’ has never supported that tar format.  For backwards
          compatibility the ‘paxr’ value will be mapped to ‘gnutar’ and
          a deprecation message will be emitted.

 -- Variable: CPACK_DEBIAN_COMPRESSION_TYPE

     The compression used for creating the Debian package.

        * Mandatory : YES

        * Default : “gzip”

     Possible values are:

        - lzma

        - xz

        - bzip2

        - gzip

 -- Variable: CPACK_DEBIAN_PACKAGE_PRIORITY
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY

     Set Priority control field e.g.  required, important, standard,
     optional, extra

        * Mandatory : YES

        * Default : “optional”

     See
     ‘https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities’

 -- Variable: CPACK_DEBIAN_PACKAGE_HOMEPAGE

     The URL of the web site for this package, preferably (when
     applicable) the site from which the original source can be obtained
     and any additional upstream documentation or information may be
     found.

        * Mandatory : NO

        * Default : CMAKE_PROJECT_HOMEPAGE_URL.

          Note: The content of this field is a simple URL without any
          surrounding characters such as <>.

 -- Variable: CPACK_DEBIAN_PACKAGE_SHLIBDEPS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS

     May be set to ON in order to use ‘dpkg-shlibdeps’ to generate
     better package dependency list.

        * Mandatory : NO

        * Default :

             - CPACK_DEBIAN_PACKAGE_SHLIBDEPS if set or

             - OFF

          Note: You may need set CMAKE_INSTALL_RPATH to an
          appropriate value if you use this feature, because if you
          don’t ‘dpkg-shlibdeps’ may fail to find your own shared libs.
          See
          ‘https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling’

 -- Variable: CPACK_DEBIAN_PACKAGE_DEBUG

     May be set when invoking cpack in order to trace debug information
     during the CPack DEB generator run.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_DEBIAN_PACKAGE_PREDEPENDS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS

     Sets the ‘Pre-Depends’ field of the Debian package.  Like
     Depends, except that it also forces ‘dpkg’ to complete
     installation of the packages named before even starting the
     installation of the package which declares the pre-dependency.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_PREDEPENDS for
               component-based installations.

     See
     ‘http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_ENHANCES
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES

     Sets the ‘Enhances’ field of the Debian package.  Similar to
     Suggests but works in the opposite direction: declares that
     a package can enhance the functionality of another package.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_ENHANCES for
               component-based installations.

     See
     ‘http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_BREAKS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS

     Sets the ‘Breaks’ field of the Debian package.  When a binary
     package (P) declares that it breaks other packages (B), ‘dpkg’ will
     not allow the package (P) which declares ‘Breaks’ be `unpacked'
     unless the packages that will be broken (B) are deconfigured first.
     As long as the package (P) is configured, the previously
     deconfigured packages (B) cannot be reconfigured again.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_BREAKS for
               component-based installations.

     See
     ‘https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks’

 -- Variable: CPACK_DEBIAN_PACKAGE_CONFLICTS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS

     Sets the ‘Conflicts’ field of the Debian package.  When one binary
     package declares a conflict with another using a ‘Conflicts’ field,
     ‘dpkg’ will not allow them to be unpacked on the system at the same
     time.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_CONFLICTS for
               component-based installations.

     See
     ‘https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts’

          Note: This is a stronger restriction than Breaks,
          which prevents the broken package from being configured while
          the breaking package is in the “Unpacked” state but allows
          both packages to be unpacked at the same time.

 -- Variable: CPACK_DEBIAN_PACKAGE_PROVIDES
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES

     Sets the ‘Provides’ field of the Debian package.  A virtual package
     is one which appears in the ‘Provides’ control field of another
     package.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_PROVIDES for
               component-based installations.

     See
     ‘https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual’

 -- Variable: CPACK_DEBIAN_PACKAGE_REPLACES
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES

     Sets the ‘Replaces’ field of the Debian package.  Packages can
     declare in their control file that they should overwrite files in
     certain other packages, or completely replace other packages.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_REPLACES for
               component-based installations.

     See
     ‘http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_RECOMMENDS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS

     Sets the ‘Recommends’ field of the Debian package.  Allows packages
     to declare a strong, but not absolute, dependency on other
     packages.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_RECOMMENDS for
               component-based installations.

     See
     ‘http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_SUGGESTS
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS

     Sets the ‘Suggests’ field of the Debian package.  Allows packages
     to declare a suggested package install grouping.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_SUGGESTS for
               component-based installations.

     See
     ‘http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS

        * Mandatory : NO

        * Default : OFF

     Allows to generate shlibs control file automatically.
     Compatibility is defined by
     CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY variable value.

          Note: Libraries are only considered if they have both library
          name and version set.  This can be done by setting SOVERSION
          property with set_target_properties() command.

 -- Variable: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY

     Compatibility policy for auto-generated shlibs control file.

        * Mandatory : NO

        * Default : “=”

     Defines compatibility policy for auto-generated shlibs control
     file.  Possible values: “=”, “>=”

     See
     ‘https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps’

 -- Variable: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA

     This variable allow advanced user to add custom script to the
     control.tar.gz.  Typical usage is for conffiles, postinst, postrm,
     prerm.

        * Mandatory : NO

        * Default : -

     Usage:

          set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
              "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")

          Note: The original permissions of the files will be used in
          the final package unless the variable
          CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION is set.
          In particular, the scripts should have the proper executable
          flag prior to the generation of the package.

 -- Variable: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION

     This variable indicates if the Debian policy on control files
     should be strictly followed.

        * Mandatory : NO

        * Default : FALSE

     Usage:

          set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)

          Note: This overrides the permissions on the original files,
          following the rules set by Debian policy
          ‘https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners’

 -- Variable: CPACK_DEBIAN_PACKAGE_SOURCE
 -- Variable: CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE

     Sets the ‘Source’ field of the binary Debian package.  When the
     binary package name is not the same as the source package name (in
     particular when several components/binaries are generated from one
     source) the source from which the binary has been generated should
     be indicated with the field ‘Source’.

        * Mandatory : NO

        * Default :

             - An empty string for non-component based installations

             - CPACK_DEBIAN_PACKAGE_SOURCE for
               component-based installations.

     See
     ‘https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source’

          Note: This value is not interpreted.  It is possible to pass
          an optional revision number of the referenced source package
          as well.

   ---------- Footnotes ----------

   (1)
https://www.debian.org/doc/debian-policy/ch-controlfields.html#description

24.1.4.2 Packaging of debug information
.......................................

Dbgsym packages contain debug symbols for debugging packaged binaries.

Dbgsym packaging has its own set of variables:

 -- Variable: CPACK_DEBIAN_DEBUGINFO_PACKAGE
 -- Variable: CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE

     Enable generation of dbgsym .ddeb package(s).

        * Mandatory : NO

        * Default : OFF

     Note: Binaries must contain debug symbols before packaging so use
     either ‘Debug’ or ‘RelWithDebInfo’ for CMAKE_BUILD_TYPE.
     variable value.

24.1.4.3 Building Debian packages on Windows
............................................

To communicate UNIX file permissions from the install stage to the CPack
DEB generator the “cmake_mode_t” NTFS alternate data stream (ADT) is
used.

When a filesystem without ADT support is used only owner read/write
permissions can be preserved.

24.1.4.4 Reproducible packages
..............................

The environment variable ‘SOURCE_DATE_EPOCH’ may be set to a UNIX
timestamp, defined as the number of seconds, excluding leap seconds,
since 01 Jan 1970 00:00:00 UTC. If set, the CPack DEB generator will use
its value for timestamps in the package.

24.1.5 CPack DragNDrop Generator
--------------------------------

The DragNDrop CPack generator (macOS) creates a DMG image.

24.1.5.1 Variables specific to CPack DragNDrop generator
........................................................

The following variables are specific to the DragNDrop installers built
on macOS:

 -- Variable: CPACK_DMG_VOLUME_NAME

     The volume name of the generated disk image.  Defaults to
     CPACK_PACKAGE_FILE_NAME.

 -- Variable: CPACK_DMG_FORMAT

     The disk image format.  Common values are ‘UDRO’ (UDIF read-only),
     ‘UDZO’ (UDIF zlib-compressed) or ‘UDBZ’ (UDIF bzip2-compressed).
     Refer to ‘hdiutil(1)’ for more information on other available
     formats.  Defaults to ‘UDZO’.

 -- Variable: CPACK_DMG_DS_STORE

     Path to a custom ‘.DS_Store’ file.  This ‘.DS_Store’ file can be
     used to specify the Finder window position/geometry and layout
     (such as hidden toolbars, placement of the icons etc.).  This file
     has to be generated by the Finder (either manually or through
     AppleScript) using a normal folder from which the ‘.DS_Store’ file
     can then be extracted.

 -- Variable: CPACK_DMG_DS_STORE_SETUP_SCRIPT

     Path to a custom AppleScript file.  This AppleScript is used to
     generate a ‘.DS_Store’ file which specifies the Finder window
     position/geometry and layout (such as hidden toolbars, placement of
     the icons etc.).  By specifying a custom AppleScript there is no
     need to use ‘CPACK_DMG_DS_STORE’, as the ‘.DS_Store’ that is
     generated by the AppleScript will be packaged.

 -- Variable: CPACK_DMG_BACKGROUND_IMAGE

     Path to an image file to be used as the background.  This file will
     be copied to ‘.background’/‘background.<ext>’, where ‘<ext>’ is the
     original image file extension.  The background image is installed
     into the image before ‘CPACK_DMG_DS_STORE_SETUP_SCRIPT’ is executed
     or ‘CPACK_DMG_DS_STORE’ is installed.  By default no background
     image is set.

 -- Variable: CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK

     Default behaviour is to include a symlink to ‘/Applications’ in the
     DMG. Set this option to ‘ON’ to avoid adding the symlink.

 -- Variable: CPACK_DMG_SLA_DIR

     Directory where license and menu files for different languages are
     stored.  Setting this causes CPack to look for a
     ‘<language>.menu.txt’ and ‘<language>.license.txt’ or
     ‘<language>.license.rtf’ file for every language defined in
     ‘CPACK_DMG_SLA_LANGUAGES’.  If both this variable and
     ‘CPACK_RESOURCE_FILE_LICENSE’ are set, CPack will only look for the
     menu files and use the same license file for all languages.  If
     both ‘<language>.license.txt’ and ‘<language>.license.rtf’ exist,
     the ‘.txt’ file will be used.

 -- Variable: CPACK_DMG_SLA_LANGUAGES

     Languages for which a license agreement is provided when mounting
     the generated DMG. A menu file consists of 9 lines of text.  The
     first line is is the name of the language itself, uppercase, in
     English (e.g.  German).  The other lines are translations of the
     following strings:

        - Agree

        - Disagree

        - Print

        - Save…

        - You agree to the terms of the License Agreement when you click
          the “Agree” button.

        - Software License Agreement

        - This text cannot be saved.  The disk may be full or locked, or
          the file may be locked.

        - Unable to print.  Make sure you have selected a printer.

     For every language in this list, CPack will try to find files
     ‘<language>.menu.txt’ and ‘<language>.license.txt’ in the directory
     specified by the CPACK_DMG_SLA_DIR variable.

 -- Variable: CPACK_DMG_<component>_FILE_NAME

     File name when packaging ‘<component>’ as its own DMG
     (‘CPACK_COMPONENTS_GROUPING’ set to IGNORE).

        - Default: ‘CPACK_PACKAGE_FILE_NAME-<component>’

 -- Variable: CPACK_COMMAND_HDIUTIL

     Path to the ‘hdiutil(1)’ command used to operate on disk image
     files on macOS. This variable can be used to override the
     automatically detected command (or specify its location if the
     auto-detection fails to find it).

 -- Variable: CPACK_COMMAND_SETFILE

     Path to the ‘SetFile(1)’ command used to set extended attributes on
     files and directories on macOS. This variable can be used to
     override the automatically detected command (or specify its
     location if the auto-detection fails to find it).

 -- Variable: CPACK_COMMAND_REZ

     Path to the ‘Rez(1)’ command used to compile resources on macOS.
     This variable can be used to override the automatically detected
     command (or specify its location if the auto-detection fails to
     find it).

24.1.6 CPack External Generator
-------------------------------

CPack provides many generators to create packages for a variety of
platforms and packaging systems.  The intention is for CMake/CPack to be
a complete end-to-end solution for building and packaging a software
project.  However, it may not always be possible to use CPack for the
entire packaging process, due to either technical limitations or
policies that require the use of certain tools.  For this reason, CPack
provides the “External” generator, which allows external packaging
software to take advantage of some of the functionality provided by
CPack, such as component installation and the dependency graph.

24.1.6.1 Integration with External Packaging Tools
..................................................

The CPack External generator generates a ‘.json’ file containing the
CPack internal metadata, which gives external software information on
how to package the software.  External packaging software may itself
invoke CPack, consume the generated metadata, install and package files
as required.

Alternatively CPack can invoke an external packaging software through an
optional custom CMake script in CPACK_EXTERNAL_PACKAGE_SCRIPT
instead.

Staging of installation files may also optionally be taken care of by
the generator when enabled through the
CPACK_EXTERNAL_ENABLE_STAGING variable.

24.1.6.2 JSON Format
....................

The JSON metadata file contains a list of CPack components and component
groups, the various options passed to cpack_add_component().
and cpack_add_component_group(), the dependencies between the
components and component groups, and various other options passed to
CPack.

The JSON’s root object will always provide two fields:
‘formatVersionMajor’ and ‘formatVersionMinor’, which are always integers
that describe the output format of the generator.  Backwards-compatible
changes to the output format (for example, adding a new field that
didn’t exist before) cause the minor version to be incremented, and
backwards-incompatible changes (for example, deleting a field or
changing its meaning) cause the major version to be incremented and the
minor version reset to 0.  The format version is always of the format
‘major.minor’.  In other words, it always has exactly two parts,
separated by a period.

You can request one or more specific versions of the output format as
described below with CPACK_EXTERNAL_REQUESTED_VERSIONS.  The
output format will have a major version that exactly matches the
requested major version, and a minor version that is greater than or
equal to the requested minor version.  If no version is requested with
CPACK_EXTERNAL_REQUESTED_VERSIONS, the latest known major
version is used by default.  Currently, the only supported format is
1.0, which is described below.

24.1.6.3 Version 1.0
....................

In addition to the standard format fields, format version 1.0 provides
the following fields in the root:

‘components’

     The ‘components’ field is an object with component names as the
     keys and objects describing the components as the values.  The
     component objects have the following fields:

     ‘name’

          The name of the component.  This is always the same as the key
          in the ‘components’ object.

     ‘displayName’

          The value of the ‘DISPLAY_NAME’ field passed to
          cpack_add_component().

     ‘description’

          The value of the ‘DESCRIPTION’ field passed to
          cpack_add_component().

     ‘isHidden’

          True if ‘HIDDEN’ was passed to cpack_add_component(),
          false if it was not.

     ‘isRequired’

          True if ‘REQUIRED’ was passed to cpack_add_component(),
          false if it was not.

     ‘isDisabledByDefault’

          True if ‘DISABLED’ was passed to cpack_add_component(),
          false if it was not.

     ‘group’

          Only present if ‘GROUP’ was passed to
          cpack_add_component().  If so, this field is a string
          value containing the component’s group.

     ‘dependencies’

          An array of components the component depends on.  This
          contains the values in the ‘DEPENDS’ argument passed to
          cpack_add_component().  If no ‘DEPENDS’ argument was
          passed, this is an empty list.

     ‘installationTypes’

          An array of installation types the component is part of.  This
          contains the values in the ‘INSTALL_TYPES’ argument passed to
          cpack_add_component().  If no ‘INSTALL_TYPES’
          argument was passed, this is an empty list.

     ‘isDownloaded’

          True if ‘DOWNLOADED’ was passed to
          cpack_add_component(), false if it was not.

     ‘archiveFile’

          The name of the archive file passed with the ‘ARCHIVE_FILE’
          argument to cpack_add_component().  If no
          ‘ARCHIVE_FILE’ argument was passed, this is an empty string.

‘componentGroups’

     The ‘componentGroups’ field is an object with component group names
     as the keys and objects describing the component groups as the
     values.  The component group objects have the following fields:

     ‘name’

          The name of the component group.  This is always the same as
          the key in the ‘componentGroups’ object.

     ‘displayName’

          The value of the ‘DISPLAY_NAME’ field passed to
          cpack_add_component_group().

     ‘description’

          The value of the ‘DESCRIPTION’ field passed to
          cpack_add_component_group().

     ‘parentGroup’

          Only present if ‘PARENT_GROUP’ was passed to
          cpack_add_component_group().  If so, this field is a
          string value containing the component group’s parent group.

     ‘isExpandedByDefault’

          True if ‘EXPANDED’ was passed to
          cpack_add_component_group(), false if it was not.

     ‘isBold’

          True if ‘BOLD_TITLE’ was passed to
          cpack_add_component_group(), false if it was not.

     ‘components’

          An array of names of components that are direct members of the
          group (components that have this group as their ‘GROUP’).
          Components of subgroups are not included.

     ‘subgroups’

          An array of names of component groups that are subgroups of
          the group (groups that have this group as their
          ‘PARENT_GROUP’).

‘installationTypes’

     The ‘installationTypes’ field is an object with installation type
     names as the keys and objects describing the installation types as
     the values.  The installation type objects have the following
     fields:

     ‘name’

          The name of the installation type.  This is always the same as
          the key in the ‘installationTypes’ object.

     ‘displayName’

          The value of the ‘DISPLAY_NAME’ field passed to
          cpack_add_install_type().

     ‘index’

          The integer index of the installation type in the list.

‘projects’

     The ‘projects’ field is an array of objects describing CMake
     projects which comprise the CPack project.  The values in this
     field are derived from CPACK_INSTALL_CMAKE_PROJECTS.  In
     most cases, this will be only a single project.  The project
     objects have the following fields:

     ‘projectName’

          The project name passed to CPACK_INSTALL_CMAKE_PROJECTS.

     ‘component’

          The name of the component or component set which comprises the
          project.

     ‘directory’

          The build directory of the CMake project.  This is the
          directory which contains the ‘cmake_install.cmake’ script.

     ‘subDirectory’

          The subdirectory to install the project into inside the CPack
          package.

‘packageName’

     The package name given in CPACK_PACKAGE_NAME.  Only
     present if this option is set.

‘packageVersion’

     The package version given in CPACK_PACKAGE_VERSION.  Only
     present if this option is set.

‘packageDescriptionFile’

     The package description file given in
     CPACK_PACKAGE_DESCRIPTION_FILE.  Only present if this option
     is set.

‘packageDescriptionSummary’

     The package description summary given in
     CPACK_PACKAGE_DESCRIPTION_SUMMARY.  Only present if this
     option is set.

‘buildConfig’

     The build configuration given to CPack with the ‘-C’ option.  Only
     present if this option is set.

‘defaultDirectoryPermissions’

     The default directory permissions given in
     CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.  Only present if
     this option is set.

‘setDestdir’

     True if CPACK_SET_DESTDIR is true, false if it is not.

‘packagingInstallPrefix’

     The install prefix given in CPACK_PACKAGING_INSTALL_PREFIX.
     Only present if CPACK_SET_DESTDIR is true.

‘stripFiles’

     True if CPACK_STRIP_FILES is true, false if it is not.

‘warnOnAbsoluteInstallDestination’

     True if CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION is
     true, false if it is not.

‘errorOnAbsoluteInstallDestination’

     True if CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION is
     true, false if it is not.

24.1.6.4 Variables specific to CPack External generator
.......................................................

 -- Variable: CPACK_EXTERNAL_REQUESTED_VERSIONS

     This variable is used to request a specific version of the CPack
     External generator.  It is a list of ‘major.minor’ values,
     separated by semicolons.

     If this variable is set to a non-empty value, the CPack External
     generator will iterate through each item in the list to search for
     a version that it knows how to generate.  Requested versions should
     be listed in order of descending preference by the client software,
     as the first matching version in the list will be generated.

     The generator knows how to generate the version if it has a
     versioned generator whose major version exactly matches the
     requested major version, and whose minor version is greater than or
     equal to the requested minor version.  For example, if
     ‘CPACK_EXTERNAL_REQUESTED_VERSIONS’ contains 1.0, and the CPack
     External generator knows how to generate 1.1, it will generate 1.1.
     If the generator doesn’t know how to generate a version in the
     list, it skips the version and looks at the next one.  If it
     doesn’t know how to generate any of the requested versions, an
     error is thrown.

     If this variable is not set, or is empty, the CPack External
     generator will generate the highest major and minor version that it
     knows how to generate.

     If an invalid version is encountered in
     ‘CPACK_EXTERNAL_REQUESTED_VERSIONS’ (one that doesn’t match
     ‘major.minor’, where ‘major’ and ‘minor’ are integers), it is
     ignored.

 -- Variable: CPACK_EXTERNAL_ENABLE_STAGING

     This variable can be set to true to enable optional installation
     into a temporary staging area which can then be picked up and
     packaged by an external packaging tool.  The top level directory
     used by CPack for the current packaging task is contained in
     ‘CPACK_TOPLEVEL_DIRECTORY’.  It is automatically cleaned up on each
     run before packaging is initiated and can be used for custom
     temporary files required by the external packaging tool.  It also
     contains the staging area ‘CPACK_TEMPORARY_DIRECTORY’ into which
     CPack performs the installation when staging is enabled.

 -- Variable: CPACK_EXTERNAL_PACKAGE_SCRIPT

     This variable can optionally specify the full path to a CMake
     script file to be run as part of the CPack invocation.  It is
     invoked after (optional) staging took place and may run an external
     packaging tool.  The script has access to the variables defined by
     the CPack config file.

 -- Variable: CPACK_EXTERNAL_BUILT_PACKAGES

     The ‘CPACK_EXTERNAL_PACKAGE_SCRIPT’ script may set this list
     variable to the full paths of generated package files.  CPack will
     copy these files from the staging directory back to the top build
     directory and possibly produce checksum files if the
     CPACK_PACKAGE_CHECKSUM is set.

24.1.7 CPack FreeBSD Generator
------------------------------

The built in (binary) CPack FreeBSD (pkg) generator (Unix only)

24.1.7.1 Variables affecting the CPack FreeBSD (pkg) generator
..............................................................

        - CPACK_ARCHIVE_THREADS.

24.1.7.2 Variables specific to CPack FreeBSD (pkg) generator
............................................................

The CPack FreeBSD generator may be used to create pkg(8) packages –
these may be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on
Linux or OSX, depending on the installed package-management tools –
using CPack.

The CPack FreeBSD generator is a CPack generator and uses the
‘CPACK_XXX’ variables used by CPack.  It tries to re-use
packaging information that may already be specified for Debian packages
for the CPack DEB Generator.  It also tries to re-use RPM
packaging information when Debian does not specify.

The CPack FreeBSD generator should work on any host with libpkg
installed.  The packages it produces are specific to the host
architecture and ABI.

The CPack FreeBSD generator sets package-metadata through
‘CPACK_FREEBSD_XXX’ variables.  The CPack FreeBSD generator, unlike the
CPack Deb generator, does not specially support componentized packages;
a single package is created from all the software artifacts created
through CMake.

All of the variables can be set specifically for FreeBSD packaging in
the CPackConfig file or in CMakeLists.txt, but most of them have
defaults that use general settings (e.g.  CMAKE_PROJECT_NAME) or
Debian-specific variables when those make sense (e.g.  the homepage of
an upstream project is usually unchanged by the flavor of packaging).
When there is no Debian information to fall back on, but the RPM
packaging has it, fall back to the RPM information (e.g.  package
license).

 -- Variable: CPACK_FREEBSD_PACKAGE_NAME

     Sets the package name (in the package manifest, but also affects
     the output filename).

        * Mandatory: YES

        * Default:

             - CPACK_PACKAGE_NAME. (this is always set by
               CPack itself, based on CMAKE_PROJECT_NAME).

 -- Variable: CPACK_FREEBSD_PACKAGE_COMMENT

     Sets the package comment.  This is the short description displayed
     by pkg(8) in standard “pkg info” output.

        * Mandatory: YES

        * Default:

             - CPACK_PACKAGE_DESCRIPTION_SUMMARY. (this is
               always set by CPack itself, if nothing else sets it
               explicitly).

             - PROJECT_DESCRIPTION. (this can be set with the
               DESCRIPTION parameter for project()).

 -- Variable: CPACK_FREEBSD_PACKAGE_DESCRIPTION

     Sets the package description.  This is the long description of the
     package, given by “pkg info” with a specific package as argument.

        * Mandatory: YES

        * Default:

             - CPACK_DEBIAN_PACKAGE_DESCRIPTION. (this may
               be set already for Debian packaging, so we may as well
               re-use it).

 -- Variable: CPACK_FREEBSD_PACKAGE_WWW

     The URL of the web site for this package, preferably (when
     applicable) the site from which the original source can be obtained
     and any additional upstream documentation or information may be
     found.

        * Mandatory: YES

        * Default:

             - CMAKE_PROJECT_HOMEPAGE_URL, or if that is not
               set, see CPACK_DEBIAN_PACKAGE_HOMEPAGE. (this may
               be set already for Debian packaging, so we may as well
               re-use it).

 -- Variable: CPACK_FREEBSD_PACKAGE_LICENSE

     The license, or licenses, which apply to this software package.
     This must be one or more license-identifiers that pkg recognizes as
     acceptable license identifiers (e.g.  “GPLv2”).

        * Mandatory: YES

        * Default:

             - CPACK_RPM_PACKAGE_LICENSE.

 -- Variable: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC

     This variable is only of importance if there is more than one
     license.  The default is “single”, which is only applicable to a
     single license.  Other acceptable values are determined by pkg –
     those are “dual” or “multi” – meaning choice (OR) or simultaneous
     (AND) application of the licenses.

        * Mandatory: NO

        * Default: single

 -- Variable: CPACK_FREEBSD_PACKAGE_MAINTAINER

     The FreeBSD maintainer (e.g.  <kde@freebsd.org>) of this package.

        * Mandatory: YES

        * Default: none

 -- Variable: CPACK_FREEBSD_PACKAGE_ORIGIN

     The origin (ports label) of this package; for packages built by
     CPack outside of the ports system this is of less importance.  The
     default puts the package somewhere under misc/, as a stopgap.

        * Mandatory: YES

        * Default: misc/<package name>

 -- Variable: CPACK_FREEBSD_PACKAGE_CATEGORIES

     The ports categories where this package lives (if it were to be
     built from ports).  If none is set a single category is determined
     based on the package origin.

        * Mandatory: YES

        * Default: derived from ORIGIN

 -- Variable: CPACK_FREEBSD_PACKAGE_DEPS

     A list of package origins that should be added as package
     dependencies.  These are in the form <category>/<packagename>, e.g.
     x11/libkonq.  No version information needs to be provided (this is
     not included in the manifest).

        * Mandatory: NO

        * Default: empty

24.1.8 CPack IFW Generator
--------------------------

Configure and run the Qt Installer Framework to generate a Qt installer.

24.1.8.1 Overview
.................

This cpack generator generates configuration and meta
information for the Qt Installer Framework(1) (QtIFW), and runs QtIFW
tools to generate a Qt installer.

QtIFW provides tools and utilities to create installers for the
platforms supported by Qt(2): Linux, Microsoft Windows, and macOS.

To make use of this generator, QtIFW needs to be installed.  The
CPackIFW module looks for the location of the QtIFW command-line
utilities, and defines several commands to control the behavior of this
generator.

   ---------- Footnotes ----------

   (1) http://doc.qt.io/qtinstallerframework/index.html

   (2) https://www.qt.io

24.1.8.2 Variables
..................

You can use the following variables to change behavior of CPack ‘IFW’
generator.

24.1.8.3 Debug
..............

 -- Variable: CPACK_IFW_VERBOSE

     Set to ‘ON’ to enable addition debug output.  By default is ‘OFF’.

24.1.8.4 Package
................

 -- Variable: CPACK_IFW_PACKAGE_TITLE

     Name of the installer as displayed on the title bar.  By default
     used CPACK_PACKAGE_DESCRIPTION_SUMMARY.

 -- Variable: CPACK_IFW_PACKAGE_PUBLISHER

     Publisher of the software (as shown in the Windows Control Panel).
     By default used CPACK_PACKAGE_VENDOR.

 -- Variable: CPACK_IFW_PRODUCT_URL

     URL to a page that contains product information on your web site.

 -- Variable: CPACK_IFW_PACKAGE_ICON

     Filename for a custom installer icon.  The actual file is ‘.icns’
     (macOS), ‘.ico’ (Windows).  No functionality on Unix.

 -- Variable: CPACK_IFW_PACKAGE_WINDOW_ICON

     Filename for a custom window icon in PNG format for the Installer
     application.

 -- Variable: CPACK_IFW_PACKAGE_LOGO

     Filename for a logo is used as QWizard::LogoPixmap.

 -- Variable: CPACK_IFW_PACKAGE_WATERMARK

     Filename for a watermark is used as QWizard::WatermarkPixmap.

 -- Variable: CPACK_IFW_PACKAGE_BANNER

     Filename for a banner is used as QWizard::BannerPixmap.

 -- Variable: CPACK_IFW_PACKAGE_BACKGROUND

     Filename for an image used as QWizard::BackgroundPixmap (only used
     by MacStyle).

 -- Variable: CPACK_IFW_PACKAGE_WIZARD_STYLE

     Wizard style to be used (“Modern”, “Mac”, “Aero” or “Classic”).

 -- Variable: CPACK_IFW_PACKAGE_STYLE_SHEET

     Filename for a stylesheet.

 -- Variable: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH

     Default width of the wizard in pixels.  Setting a banner image will
     override this.

 -- Variable: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT

     Default height of the wizard in pixels.  Setting a watermark image
     will override this.

 -- Variable: CPACK_IFW_PACKAGE_TITLE_COLOR

     Color of the titles and subtitles (takes an HTML color code, such
     as “#88FF33”).

 -- Variable: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY

     Name of the default program group for the product in the Windows
     Start menu.

     By default used CPACK_IFW_PACKAGE_NAME.

 -- Variable: CPACK_IFW_TARGET_DIRECTORY

     Default target directory for installation.  By default used
     “@ApplicationsDir@/ see CPACK_PACKAGE_INSTALL_DIRECTORY.”
     (variables embedded in ‘@’ are expanded by the QtIFW scripting
     engine(1)).

     You can use predefined variables.

 -- Variable: CPACK_IFW_ADMIN_TARGET_DIRECTORY

     Default target directory for installation with administrator
     rights.

     You can use predefined variables.

 -- Variable: CPACK_IFW_PACKAGE_GROUP

     The group, which will be used to configure the root package

 -- Variable: CPACK_IFW_PACKAGE_NAME

     The root package name, which will be used if configuration group is
     not specified

 -- Variable: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME

     Filename of the generated maintenance tool.  The platform-specific
     executable file extension is appended.

     By default used QtIFW defaults (‘maintenancetool’).

 -- Variable: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR

     Set to ‘OFF’ if the target directory should not be deleted when
     uninstalling.

     Is ‘ON’ by default

 -- Variable: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE

     Filename for the configuration of the generated maintenance tool.

     By default used QtIFW defaults (‘maintenancetool.ini’).

 -- Variable: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS

     Set to ‘ON’ if the installation path can contain non-ASCII
     characters.

     Is ‘ON’ for QtIFW less 2.0 tools.

 -- Variable: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH

     Set to ‘OFF’ if the installation path cannot contain space
     characters.

     Is ‘ON’ for QtIFW less 2.0 tools.

 -- Variable: CPACK_IFW_PACKAGE_CONTROL_SCRIPT

     Filename for a custom installer control script.

 -- Variable: CPACK_IFW_PACKAGE_RESOURCES

     List of additional resources (‘.qrc’ files) to include in the
     installer binary.

     You can use cpack_ifw_add_package_resources() command
     to resolve relative paths.

 -- Variable: CPACK_IFW_PACKAGE_FILE_EXTENSION

     The target binary extension.

     On Linux, the name of the target binary is automatically extended
     with ‘.run’, if you do not specify the extension.

     On Windows, the target is created as an application with the
     extension ‘.exe’, which is automatically added, if not supplied.

     On Mac, the target is created as an DMG disk image with the
     extension ‘.dmg’, which is automatically added, if not supplied.

 -- Variable: CPACK_IFW_REPOSITORIES_ALL

     The list of remote repositories.

     The default value of this variable is computed by CPack and
     contains all repositories added with command
     cpack_ifw_add_repository() or updated with command
     cpack_ifw_update_repository().

 -- Variable: CPACK_IFW_DOWNLOAD_ALL

     If this is ‘ON’ all components will be downloaded.  By default is
     ‘OFF’ or used value from ‘CPACK_DOWNLOAD_ALL’ if set

   ---------- Footnotes ----------

   (1) https://doc.qt.io/qtinstallerframework/scripting.html

24.1.8.5 Components
...................

 -- Variable: CPACK_IFW_RESOLVE_DUPLICATE_NAMES

     Resolve duplicate names when installing components with groups.

 -- Variable: CPACK_IFW_PACKAGES_DIRECTORIES

     Additional prepared packages dirs that will be used to resolve
     dependent components.

 -- Variable: CPACK_IFW_REPOSITORIES_DIRECTORIES

     Additional prepared repository dirs that will be used to resolve
     and repack dependent components.  This feature available only since
     QtIFW 3.1.

24.1.8.6 QtIFW Tools
....................

 -- Variable: CPACK_IFW_FRAMEWORK_VERSION

     The version of used QtIFW tools.

The following variables provide the locations of the QtIFW command-line
tools as discovered by the module CPackIFW.  These variables
are cached, and may be configured if needed.

 -- Variable: CPACK_IFW_ARCHIVEGEN_EXECUTABLE

     The path to ‘archivegen’.

 -- Variable: CPACK_IFW_BINARYCREATOR_EXECUTABLE

     The path to ‘binarycreator’.

 -- Variable: CPACK_IFW_REPOGEN_EXECUTABLE

     The path to ‘repogen’.

 -- Variable: CPACK_IFW_INSTALLERBASE_EXECUTABLE

     The path to ‘installerbase’.

 -- Variable: CPACK_IFW_DEVTOOL_EXECUTABLE

     The path to ‘devtool’.

24.1.8.7 Hints for Finding QtIFW
................................

Generally, the CPack ‘IFW’ generator automatically finds QtIFW tools,
but if you don’t use a default path for installation of the QtIFW tools,
the path may be specified in either a CMake or an environment variable:

 -- Variable: CPACK_IFW_ROOT

     An CMake variable which specifies the location of the QtIFW tool
     suite.

     The variable will be cached in the ‘CPackConfig.cmake’ file and
     used at CPack runtime.

 -- Variable: QTIFWDIR

     An environment variable which specifies the location of the QtIFW
     tool suite.

     Note: The specified path should not contain “bin” at the end (for
     example: “D:\DevTools\QtIFW2.0.5”).

The CPACK_IFW_ROOT variable has a higher priority and
overrides the value of the QTIFWDIR variable.

24.1.8.8 Other Settings
.......................

24.1.8.9 Online installer
.........................

By default, this generator generates an `offline installer'.  This means
that that all packaged files are fully contained in the installer
executable.

In contrast, an `online installer' will download some or all components
from a remote server.

The ‘DOWNLOADED’ option in the cpack_add_component() command
specifies that a component is to be downloaded.  Alternatively, the
‘ALL’ option in the cpack_configure_downloads() command
specifies that ‘all’ components are to be be downloaded.

The cpack_ifw_add_repository() command and the
CPACK_IFW_DOWNLOAD_ALL variable allow for more specific
configuration.

When there are online components, CPack will write them to archive
files.  The help page of the CPackComponent module,
especially the section on the cpack_configure_downloads().
function, explains how to make these files accessible from a download
URL.

24.1.8.10 Internationalization
..............................

Some variables and command arguments support internationalization via
CMake script.  This is an optional feature.

Installers created by QtIFW tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of the your components and
groups that will be distributed.

Localization of the description of your components and groups is useful
for users of your installers.

A localized variable or argument can contain a single default value, and
a set of pairs the name of the locale and the localized value.

For example:

     set(LOCALIZABLE_VARIABLE "Default value"
       en "English value"
       en_US "American value"
       en_GB "Great Britain value"
       )

24.1.8.11 See Also
..................

Qt Installer Framework Manual:

   * Index page: ‘http://doc.qt.io/qtinstallerframework/index.html’

   * Component Scripting:
     ‘http://doc.qt.io/qtinstallerframework/scripting.html’

   * Predefined Variables:
     ‘http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables’

   * Promoting Updates:
     ‘http://doc.qt.io/qtinstallerframework/ifw-updates.html’

Download Qt Installer Framework for your platform from Qt site:

     ‘http://download.qt.io/official_releases/qt-installer-framework’

24.1.9 CPack NSIS Generator
---------------------------

CPack Nullsoft Scriptable Install System (NSIS) generator specific
options.

The NSIS generator requires NSIS 3.0 or newer.

24.1.9.1 Variables specific to CPack NSIS generator
...................................................

The following variables are specific to the graphical installers built
on Windows Nullsoft Scriptable Install System.

 -- Variable: CPACK_NSIS_INSTALL_ROOT

     The default installation directory presented to the end user by the
     NSIS installer is under this root dir.  The full directory
     presented to the end user is:
     ‘${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}’

 -- Variable: CPACK_NSIS_MUI_ICON

     An icon filename.  The name of a ‘*.ico’ file used as the main icon
     for the generated install program.

 -- Variable: CPACK_NSIS_MUI_UNIICON

     An icon filename.  The name of a ‘*.ico’ file used as the main icon
     for the generated uninstall program.

 -- Variable: CPACK_NSIS_INSTALLER_MUI_ICON_CODE

     undocumented.

 -- Variable: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP

     The filename of a bitmap to use as the NSIS
     ‘MUI_WELCOMEFINISHPAGE_BITMAP’.

 -- Variable: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP

     The filename of a bitmap to use as the NSIS
     ‘MUI_UNWELCOMEFINISHPAGE_BITMAP’.

 -- Variable: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS

     Extra NSIS commands that will be added to the beginning of the
     install Section, before your install tree is available on the
     target system.

 -- Variable: CPACK_NSIS_EXTRA_INSTALL_COMMANDS

     Extra NSIS commands that will be added to the end of the install
     Section, after your install tree is available on the target system.

 -- Variable: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS

     Extra NSIS commands that will be added to the uninstall Section,
     before your install tree is removed from the target system.

 -- Variable: CPACK_NSIS_COMPRESSOR

     The arguments that will be passed to the NSIS ‘SetCompressor’
     command.

 -- Variable: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL

     Ask about uninstalling previous versions first.  If this is set to
     ‘ON’, then an installer will look for previous installed versions
     and if one is found, ask the user whether to uninstall it before
     proceeding with the install.

 -- Variable: CPACK_NSIS_MODIFY_PATH

     Modify ‘PATH’ toggle.  If this is set to ‘ON’, then an extra page
     will appear in the installer that will allow the user to choose
     whether the program directory should be added to the system ‘PATH’
     variable.

 -- Variable: CPACK_NSIS_DISPLAY_NAME

     The display name string that appears in the Windows ‘Apps &
     features’ in ‘Control Panel’

 -- Variable: CPACK_NSIS_PACKAGE_NAME

     The title displayed at the top of the installer.

 -- Variable: CPACK_NSIS_INSTALLED_ICON_NAME

     A path to the executable that contains the installer icon.

 -- Variable: CPACK_NSIS_HELP_LINK

     URL to a web site providing assistance in installing your
     application.

 -- Variable: CPACK_NSIS_URL_INFO_ABOUT

     URL to a web site providing more information about your
     application.

 -- Variable: CPACK_NSIS_CONTACT

     Contact information for questions and comments about the
     installation process.

 -- Variable: CPACK_NSIS_<compName>_INSTALL_DIRECTORY

     Custom install directory for the specified component ‘<compName>’
     instead of ‘$INSTDIR’.

 -- Variable: CPACK_NSIS_CREATE_ICONS_EXTRA

     Additional NSIS commands for creating ‘Start Menu’ shortcuts.

 -- Variable: CPACK_NSIS_DELETE_ICONS_EXTRA

     Additional NSIS commands to uninstall ‘Start Menu’ shortcuts.

 -- Variable: CPACK_NSIS_EXECUTABLES_DIRECTORY

     Creating NSIS ‘Start Menu’ links assumes that they are in ‘bin’
     unless this variable is set.  For example, you would set this to
     ‘exec’ if your executables are in an exec directory.

 -- Variable: CPACK_NSIS_MUI_FINISHPAGE_RUN

     Specify an executable to add an option to run on the finish page of
     the NSIS installer.

 -- Variable: CPACK_NSIS_MENU_LINKS

     Specify links in ‘[application]’ menu.  This should contain a list
     of pair ‘link’ ‘link name’.  The link may be a URL or a path
     relative to installation prefix.  Like:

          set(CPACK_NSIS_MENU_LINKS
              "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
              "CMake Help" "https://cmake.org" "CMake Web Site")

 -- Variable: CPACK_NSIS_UNINSTALL_NAME

     Specify the name of the program to uninstall the version.  Default
     is ‘Uninstall’.

 -- Variable: CPACK_NSIS_WELCOME_TITLE

     The title to display on the top of the page for the welcome page.

 -- Variable: CPACK_NSIS_WELCOME_TITLE_3LINES

     Display the title in the welcome page on 3 lines instead of 2.

 -- Variable: CPACK_NSIS_FINISH_TITLE

     The title to display on the top of the page for the finish page.

 -- Variable: CPACK_NSIS_FINISH_TITLE_3LINES

     Display the title in the finish page on 3 lines instead of 2.

 -- Variable: CPACK_NSIS_MUI_HEADERIMAGE

     The image to display on the header of installers pages.

 -- Variable: CPACK_NSIS_MANIFEST_DPI_AWARE

     If set, declares that the installer is DPI-aware.

24.1.10 CPack NuGet Generator
-----------------------------

When build a NuGet package there is no direct way to control an output
filename due a lack of the corresponding CLI option of NuGet, so there
is no ‘CPACK_NUGET_PACKAGE_FILENAME’ variable.  To form the output
filename NuGet uses the package name and the version according to its
built-in rules.

Also, be aware that including a top level directory
(‘CPACK_INCLUDE_TOPLEVEL_DIRECTORY’) is ignored by this generator.

24.1.10.1 Variables specific to CPack NuGet generator
.....................................................

The CPack NuGet generator may be used to create NuGet packages using
CPack.  The CPack NuGet generator is a CPack.
generator thus it uses the ‘CPACK_XXX’ variables used by CPack.

The CPack NuGet generator has specific features which are controlled by
the specifics ‘CPACK_NUGET_XXX’ variables.  In the “one per group” mode
(see CPACK_COMPONENTS_GROUPING), ‘<compName>’ placeholder in
the variables below would contain a group name (uppercased and turned
into a “C” identifier).

List of CPack NuGet generator specific variables:

 -- Variable: CPACK_NUGET_COMPONENT_INSTALL

     Enable component packaging for CPack NuGet generator

        * Mandatory : NO

        * Default : OFF

 -- Variable: CPACK_NUGET_PACKAGE_NAME
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_NAME

     The NUGET package name.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_NAME.

 -- Variable: CPACK_NUGET_PACKAGE_VERSION
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_VERSION

     The NuGet package version.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_VERSION.

 -- Variable: CPACK_NUGET_PACKAGE_DESCRIPTION
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION

     A long description of the package for UI display.

        * Mandatory : YES

        *
          Default :

                  - CPACK_COMPONENT_<compName>_DESCRIPTION

                  - ‘CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION’,

                  - CPACK_PACKAGE_DESCRIPTION.

 -- Variable: CPACK_NUGET_PACKAGE_AUTHORS
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_AUTHORS

     A comma-separated list of packages authors, matching the profile
     names on nuget.org(1).  These are displayed in the NuGet Gallery on
     nuget.org(2) and are used to cross-reference packages by the same
     authors.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_VENDOR.

 -- Variable: CPACK_NUGET_PACKAGE_TITLE
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_TITLE

     A human-friendly title of the package, typically used in UI
     displays as on nuget.org(3) and the Package Manager in Visual
     Studio.  If not specified, the package ID is used.

        * Mandatory : NO

        *
          Default :

                  - CPACK_COMPONENT_<compName>_DISPLAY_NAME

                  - ‘CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME’

 -- Variable: CPACK_NUGET_PACKAGE_OWNERS
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_OWNERS

     A comma-separated list of the package creators using profile names
     on nuget.org(4).  This is often the same list as in authors, and is
     ignored when uploading the package to nuget.org(5).

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_HOMEPAGE_URL
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL

     A URL for the package’s home page, often shown in UI displays as
     well as nuget.org(6).

        * Mandatory : NO

        * Default : CPACK_PACKAGE_HOMEPAGE_URL.

 -- Variable: CPACK_NUGET_PACKAGE_LICENSEURL
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_LICENSEURL

     A URL for the package’s license, often shown in UI displays as well
     as nuget.org(7).

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_ICONURL
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_ICONURL

     A URL for a 64x64 image with transparency background to use as the
     icon for the package in UI display.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY

     A short description of the package for UI display.  If omitted, a
     truncated version of description is used.

        * Mandatory : NO

        * Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY.

 -- Variable: CPACK_NUGET_PACKAGE_RELEASE_NOTES
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES

     A description of the changes made in this release of the package,
     often used in UI like the Updates tab of the Visual Studio Package
     Manager in place of the package description.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_COPYRIGHT
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT

     Copyright details for the package.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_TAGS
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_TAGS

     A space-delimited list of tags and keywords that describe the
     package and aid discoverability of packages through search and
     filtering.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_DEPENDENCIES
 -- Variable: CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES

     A list of package dependencies.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION
 -- Variable:
          CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION

     A version specification(8) for the particular dependency, where
     ‘<dependency>’ is an item of the dependency list (see above)
     transformed with ‘MAKE_C_IDENTIFIER’ function of string()
     command.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_NUGET_PACKAGE_DEBUG

     Enable debug messages while executing CPack NuGet generator.

        * Mandatory : NO

        * Default : OFF

   ---------- Footnotes ----------

   (1) http://nuget.org

   (2) http://nuget.org

   (3) http://nuget.org

   (4) http://nuget.org

   (5) http://nuget.org

   (6) http://nuget.org

   (7) http://nuget.org

   (8)
https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards

24.1.11 CPack PackageMaker Generator
------------------------------------

PackageMaker CPack generator (macOS).

Deprecated since version 3.17: Xcode no longer distributes the
PackageMaker tools.  This CPack generator will be removed in a future
version of CPack.

24.1.11.1 Variables specific to CPack PackageMaker generator
............................................................

The following variable is specific to installers built on Mac macOS
using PackageMaker:

 -- Variable: CPACK_OSX_PACKAGE_VERSION

     The version of macOS that the resulting PackageMaker archive should
     be compatible with.  Different versions of macOS support different
     features.  For example, CPack can only build component-based
     installers for macOS 10.4 or newer, and can only build installers
     that download components on-the-fly for macOS 10.5 or newer.  If
     left blank, this value will be set to the minimum version of macOS
     that supports the requested features.  Set this variable to some
     value (e.g., 10.4) only if you want to guarantee that your
     installer will work on that version of macOS, and don’t mind
     missing extra features available in the installer shipping with
     later versions of macOS.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND

     Adds a background to Distribution XML if specified.  The value
     contains the path to image in ‘Resources’ directory.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT

     Adds an ‘alignment’ attribute to the background in Distribution
     XML. Refer to Apple documentation for valid values.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_SCALING

     Adds a ‘scaling’ attribute to the background in Distribution XML.
     Refer to Apple documentation for valid values.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE

     Adds a ‘mime-type’ attribute to the background in Distribution XML.
     The option contains MIME type of an image.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_UTI

     Adds an ‘uti’ attribute to the background in Distribution XML. The
     option contains UTI type of an image.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA

     Adds a background for the Dark Aqua theme to Distribution XML if
     specified.  The value contains the path to image in ‘Resources’
     directory.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT

     Does the same as CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
     option, but for the dark theme.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING

     Does the same as CPACK_PACKAGEMAKER_BACKGROUND_SCALING.
     option, but for the dark theme.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE

     Does the same as CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
     option, but for the dark theme.

 -- Variable: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI

     Does the same as CPACK_PACKAGEMAKER_BACKGROUND_UTI.
     option, but for the dark theme.

24.1.12 CPack productbuild Generator
------------------------------------

productbuild CPack generator (macOS).

24.1.12.1 Variables specific to CPack productbuild generator
............................................................

The following variable is specific to installers built on Mac macOS
using ProductBuild:

 -- Variable: CPACK_COMMAND_PRODUCTBUILD

     Path to the ‘productbuild(1)’ command used to generate a product
     archive for the macOS Installer or Mac App Store.  This variable
     can be used to override the automatically detected command (or
     specify its location if the auto-detection fails to find it).

 -- Variable: CPACK_PRODUCTBUILD_IDENTITY_NAME

     Adds a digital signature to the resulting package.

 -- Variable: CPACK_PRODUCTBUILD_KEYCHAIN_PATH

     Specify a specific keychain to search for the signing identity.

 -- Variable: CPACK_COMMAND_PKGBUILD

     Path to the ‘pkgbuild(1)’ command used to generate an macOS
     component package on macOS. This variable can be used to override
     the automatically detected command (or specify its location if the
     auto-detection fails to find it).

 -- Variable: CPACK_PKGBUILD_IDENTITY_NAME

     Adds a digital signature to the resulting package.

 -- Variable: CPACK_PKGBUILD_KEYCHAIN_PATH

     Specify a specific keychain to search for the signing identity.

 -- Variable: CPACK_PREFLIGHT_<COMP>_SCRIPT

     Full path to a file that will be used as the ‘preinstall’ script
     for the named ‘<COMP>’ component’s package, where ‘<COMP>’ is the
     uppercased component name.  No ‘preinstall’ script is added if this
     variable is not defined for a given component.

 -- Variable: CPACK_POSTFLIGHT_<COMP>_SCRIPT

     Full path to a file that will be used as the ‘postinstall’ script
     for the named ‘<COMP>’ component’s package, where ‘<COMP>’ is the
     uppercased component name.  No ‘postinstall’ script is added if
     this variable is not defined for a given component.

 -- Variable: CPACK_PRODUCTBUILD_RESOURCES_DIR

     If specified the productbuild generator copies files from this
     directory (including subdirectories) to the ‘Resources’ directory.
     This is done before the CPACK_RESOURCE_FILE_WELCOME,
     CPACK_RESOURCE_FILE_README, and
     CPACK_RESOURCE_FILE_LICENSE files are copied.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND

     Adds a background to Distribution XML if specified.  The value
     contains the path to image in ‘Resources’ directory.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT

     Adds an ‘alignment’ attribute to the background in Distribution
     XML. Refer to Apple documentation for valid values.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_SCALING

     Adds a ‘scaling’ attribute to the background in Distribution XML.
     Refer to Apple documentation for valid values.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE

     Adds a ‘mime-type’ attribute to the background in Distribution XML.
     The option contains MIME type of an image.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_UTI

     Adds an ‘uti’ attribute to the background in Distribution XML. The
     option contains UTI type of an image.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA

     Adds a background for the Dark Aqua theme to Distribution XML if
     specified.  The value contains the path to image in ‘Resources’
     directory.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT

     Does the same as CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT
     option, but for the dark theme.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING

     Does the same as CPACK_PRODUCTBUILD_BACKGROUND_SCALING.
     option, but for the dark theme.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE

     Does the same as CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE
     option, but for the dark theme.

 -- Variable: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI

     Does the same as CPACK_PRODUCTBUILD_BACKGROUND_UTI.
     option, but for the dark theme.

24.1.13 CPack RPM Generator
---------------------------

The built in (binary) CPack RPM generator (Unix only)

24.1.13.1 Variables specific to CPack RPM generator
...................................................

The CPack RPM generator may be used to create RPM packages using
CPack.  The CPack RPM generator is a CPack generator thus
it uses the ‘CPACK_XXX’ variables used by CPack.

The CPack RPM generator has specific features which are controlled by
the specifics ‘CPACK_RPM_XXX’ variables.

‘CPACK_RPM_<COMPONENT>_XXXX’ variables may be used in order to have
`component' specific values.  Note however that ‘<COMPONENT>’ refers to
the `grouping name' written in upper case.  It may be either a component
name or a component GROUP name.  Usually those variables correspond to
RPM spec file entities.  One may find information about spec files here
‘http://www.rpm.org/wiki/Docs’

     Note: ‘<COMPONENT>’ part of variables is preferred to be in upper
     case (e.g.  if component is named ‘foo’ then use
     ‘CPACK_RPM_FOO_XXXX’ variable name format) as is with other
     ‘CPACK_<COMPONENT>_XXXX’ variables.  For the purposes of back
     compatibility (CMake/CPack version 3.5 and lower) support for same
     cased component (e.g.  ‘fOo’ would be used as ‘CPACK_RPM_fOo_XXXX’)
     is still supported for variables defined in older versions of
     CMake/CPack but is not guaranteed for variables that will be added
     in the future.  For the sake of back compatibility same cased
     component variables also override upper cased versions where both
     are present.

Here are some CPack RPM generator wiki resources that are here for
historic reasons and are no longer maintained but may still prove
useful:

        -
          ‘https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration’

        -
          ‘https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#rpm-unix-only’

List of CPack RPM generator specific variables:

 -- Variable: CPACK_RPM_COMPONENT_INSTALL

     Enable component packaging for CPack RPM generator

        * Mandatory : NO

        * Default : OFF

     If enabled (‘ON’) multiple packages are generated.  By default a
     single package containing files of all components is generated.

 -- Variable: CPACK_RPM_PACKAGE_SUMMARY
 -- Variable: CPACK_RPM_<component>_PACKAGE_SUMMARY

     The RPM package summary.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY.

 -- Variable: CPACK_RPM_PACKAGE_NAME
 -- Variable: CPACK_RPM_<component>_PACKAGE_NAME

     The RPM package name.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_NAME.

 -- Variable: CPACK_RPM_FILE_NAME
 -- Variable: CPACK_RPM_<component>_FILE_NAME

     Package file name.

        * Mandatory : YES

        *
          Default : ‘<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm’ with spaces

               replaced by ‘-‘

     This may be set to ‘RPM-DEFAULT’ to allow ‘rpmbuild’ tool to
     generate package file name by itself.  Alternatively provided
     package file name must end with ‘.rpm’ suffix.

          Note: By using user provided spec file, rpm macro extensions
          such as for generating ‘debuginfo’ packages or by simply using
          multiple components more than one rpm file may be generated,
          either from a single spec file or from multiple spec files
          (each component execution produces its own spec file).  In
          such cases duplicate file names may occur as a result of this
          variable setting or spec file content structure.  Duplicate
          files get overwritten and it is up to the packager to set the
          variables in a manner that will prevent such errors.

 -- Variable: CPACK_RPM_MAIN_COMPONENT

     Main component that is packaged without component suffix.

        * Mandatory : NO

        * Default : -

     This variable can be set to any component or group name so that
     component or group rpm package is generated without component
     suffix in filename and package name.

 -- Variable: CPACK_RPM_PACKAGE_EPOCH

     The RPM package epoch

        * Mandatory : No

        * Default : -

     Optional number that should be incremented when changing versioning
     schemas or fixing mistakes in the version numbers of older
     packages.

 -- Variable: CPACK_RPM_PACKAGE_VERSION

     The RPM package version.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_VERSION.

 -- Variable: CPACK_RPM_PACKAGE_ARCHITECTURE
 -- Variable: CPACK_RPM_<component>_PACKAGE_ARCHITECTURE

     The RPM package architecture.

        * Mandatory : YES

        * Default : Native architecture output by ‘uname -m’

     This may be set to ‘noarch’ if you know you are building a ‘noarch’
     package.

 -- Variable: CPACK_RPM_PACKAGE_RELEASE

     The RPM package release.

        * Mandatory : YES

        * Default : 1

     This is the numbering of the RPM package itself, i.e.  the version
     of the packaging and not the version of the content (see
     CPACK_RPM_PACKAGE_VERSION).  One may change the default
     value if the previous packaging was buggy and/or you want to put
     here a fancy Linux distro specific numbering.

     Note: This is the string that goes into the RPM ‘Release:’ field.
     Some distros (e.g.  Fedora, CentOS) require ‘1%{?dist}’ format and
     not just a number.  ‘%{?dist}’ part can be added by setting
     CPACK_RPM_PACKAGE_RELEASE_DIST.

 -- Variable: CPACK_RPM_PACKAGE_RELEASE_DIST

     The dist tag that is added RPM ‘Release:’ field.

        * Mandatory : NO

        * Default : OFF

     This is the reported ‘%{dist}’ tag from the current distribution or
     empty ‘%{dist}’ if RPM macro is not set.  If this variable is set
     then RPM ‘Release:’ field value is set to
     ‘${CPACK_RPM_PACKAGE_RELEASE}%{?dist}’.

 -- Variable: CPACK_RPM_PACKAGE_LICENSE

     The RPM package license policy.

        * Mandatory : YES

        * Default : “unknown”

 -- Variable: CPACK_RPM_PACKAGE_GROUP
 -- Variable: CPACK_RPM_<component>_PACKAGE_GROUP

     The RPM package group.

        * Mandatory : YES

        * Default : “unknown”

 -- Variable: CPACK_RPM_PACKAGE_VENDOR

     The RPM package vendor.

        * Mandatory : YES

        * Default : CPACK_PACKAGE_VENDOR if set or “unknown”

 -- Variable: CPACK_RPM_PACKAGE_URL
 -- Variable: CPACK_RPM_<component>_PACKAGE_URL

     The projects URL.

        * Mandatory : NO

        * Default : CMAKE_PROJECT_HOMEPAGE_URL.

 -- Variable: CPACK_RPM_PACKAGE_DESCRIPTION
 -- Variable: CPACK_RPM_<component>_PACKAGE_DESCRIPTION

     RPM package description.

        * Mandatory : YES

        * Default : CPACK_COMPONENT_<compName>_DESCRIPTION.
          (component based installers only) if set, see
          CPACK_PACKAGE_DESCRIPTION_FILE if set or “no package
          description available”

 -- Variable: CPACK_RPM_COMPRESSION_TYPE

     RPM compression type.

        * Mandatory : NO

        * Default : -

     May be used to override RPM compression type to be used to build
     the RPM. For example some Linux distribution now default to ‘lzma’
     or ‘xz’ compression whereas older cannot use such RPM. Using this
     one can enforce compression type to be used.

     Possible values are:

        - lzma

        - xz

        - bzip2

        - gzip

 -- Variable: CPACK_RPM_PACKAGE_AUTOREQ
 -- Variable: CPACK_RPM_<component>_PACKAGE_AUTOREQ

     RPM spec autoreq field.

        * Mandatory : NO

        * Default : -

     May be used to enable (‘1’, ‘yes’) or disable (‘0’, ‘no’) automatic
     shared libraries dependency detection.  Dependencies are added to
     requires list.

          Note: By default automatic dependency detection is enabled by
          rpm generator.

 -- Variable: CPACK_RPM_PACKAGE_AUTOPROV
 -- Variable: CPACK_RPM_<component>_PACKAGE_AUTOPROV

     RPM spec autoprov field.

        * Mandatory : NO

        * Default : -

     May be used to enable (‘1’, ‘yes’) or disable (‘0’, ‘no’) automatic
     listing of shared libraries that are provided by the package.
     Shared libraries are added to provides list.

          Note: By default automatic provides detection is enabled by
          rpm generator.

 -- Variable: CPACK_RPM_PACKAGE_AUTOREQPROV
 -- Variable: CPACK_RPM_<component>_PACKAGE_AUTOREQPROV

     RPM spec autoreqprov field.

        * Mandatory : NO

        * Default : -

     Variable enables/disables autoreq and autoprov at the same time.
     See CPACK_RPM_PACKAGE_AUTOREQ and
     CPACK_RPM_PACKAGE_AUTOPROV for more details.

          Note: By default automatic detection feature is enabled by
          rpm.

 -- Variable: CPACK_RPM_PACKAGE_REQUIRES
 -- Variable: CPACK_RPM_<component>_PACKAGE_REQUIRES

     RPM spec requires field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM dependencies (requires).  Note that you must
     enclose the complete requires string between quotes, for example:

          set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")

     The required package list of an RPM file could be printed with:

          rpm -qp --requires file.rpm

 -- Variable: CPACK_RPM_PACKAGE_CONFLICTS
 -- Variable: CPACK_RPM_<component>_PACKAGE_CONFLICTS

     RPM spec conflicts field.

        * Mandatory : NO

        * Default : -

     May be used to set negative RPM dependencies (conflicts).  Note
     that you must enclose the complete requires string between quotes,
     for example:

          set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2")

     The conflicting package list of an RPM file could be printed with:

          rpm -qp --conflicts file.rpm

 -- Variable: CPACK_RPM_PACKAGE_REQUIRES_PRE
 -- Variable: CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE

     RPM spec requires(pre) field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM preinstall dependencies (requires(pre)).
     Note that you must enclose the complete requires string between
     quotes, for example:

          set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts")

 -- Variable: CPACK_RPM_PACKAGE_REQUIRES_POST
 -- Variable: CPACK_RPM_<component>_PACKAGE_REQUIRES_POST

     RPM spec requires(post) field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM postinstall dependencies (requires(post)).
     Note that you must enclose the complete requires string between
     quotes, for example:

          set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts")

 -- Variable: CPACK_RPM_PACKAGE_REQUIRES_POSTUN
 -- Variable: CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN

     RPM spec requires(postun) field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM postuninstall dependencies
     (requires(postun)).  Note that you must enclose the complete
     requires string between quotes, for example:

          set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts")

 -- Variable: CPACK_RPM_PACKAGE_REQUIRES_PREUN
 -- Variable: CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN

     RPM spec requires(preun) field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM preuninstall dependencies (requires(preun)).
     Note that you must enclose the complete requires string between
     quotes, for example:

          set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts")

 -- Variable: CPACK_RPM_PACKAGE_SUGGESTS
 -- Variable: CPACK_RPM_<component>_PACKAGE_SUGGESTS

     RPM spec suggest field.

        * Mandatory : NO

        * Default : -

     May be used to set weak RPM dependencies (suggests).  Note that you
     must enclose the complete requires string between quotes.

 -- Variable: CPACK_RPM_PACKAGE_PROVIDES
 -- Variable: CPACK_RPM_<component>_PACKAGE_PROVIDES

     RPM spec provides field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM dependencies (provides).  The provided
     package list of an RPM file could be printed with:

          rpm -qp --provides file.rpm

 -- Variable: CPACK_RPM_PACKAGE_OBSOLETES
 -- Variable: CPACK_RPM_<component>_PACKAGE_OBSOLETES

     RPM spec obsoletes field.

        * Mandatory : NO

        * Default : -

     May be used to set RPM packages that are obsoleted by this one.

 -- Variable: CPACK_RPM_PACKAGE_RELOCATABLE

     build a relocatable RPM.

        * Mandatory : NO

        * Default : CPACK_PACKAGE_RELOCATABLE

     If this variable is set to TRUE or ON, the CPack RPM generator will
     try to build a relocatable RPM package.  A relocatable RPM may be
     installed using:

          rpm --prefix or --relocate

     in order to install it at an alternate place see rpm(8).  Note that
     currently this may fail if CPACK_SET_DESTDIR is set to
     ‘ON’.  If CPACK_SET_DESTDIR is set then you will get a
     warning message but if there is file installed with absolute path
     you’ll get unexpected behavior.

 -- Variable: CPACK_RPM_SPEC_INSTALL_POST

     Deprecated - use CPACK_RPM_SPEC_MORE_DEFINE instead.

        * Mandatory : NO

        * Default : -

        * Deprecated: YES

     May be used to override the ‘__spec_install_post’ section within
     the generated spec file.  This affects the install step during
     package creation, not during package installation.  For adding
     operations to be performed during package installation, use
     CPACK_RPM_POST_INSTALL_SCRIPT_FILE instead.

 -- Variable: CPACK_RPM_SPEC_MORE_DEFINE

     RPM extended spec definitions lines.

        * Mandatory : NO

        * Default : -

     May be used to add any ‘%define’ lines to the generated spec file.
     An example of its use is to prevent stripping of executables (but
     note that this may also disable other default post install
     processing):

          set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true")

 -- Variable: CPACK_RPM_PACKAGE_DEBUG

     Toggle CPack RPM generator debug output.

        * Mandatory : NO

        * Default : -

     May be set when invoking cpack in order to trace debug information
     during CPack RPM run.  For example you may launch CPack like this:

          cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM

 -- Variable: CPACK_RPM_USER_BINARY_SPECFILE
 -- Variable: CPACK_RPM_<componentName>_USER_BINARY_SPECFILE

     A user provided spec file.

        * Mandatory : NO

        * Default : -

     May be set by the user in order to specify a USER binary spec file
     to be used by the CPack RPM generator instead of generating the
     file.  The specified file will be processed by configure_file(
     @ONLY).

 -- Variable: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE

     Spec file template.

        * Mandatory : NO

        * Default : -

     If set CPack will generate a template for USER specified binary
     spec file and stop with an error.  For example launch CPack like
     this:

          cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM

     The user may then use this file in order to hand-craft is own
     binary spec file which may be used with
     CPACK_RPM_USER_BINARY_SPECFILE.

 -- Variable: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
 -- Variable: CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
 -- Variable: CPACK_RPM_PRE_TRANS_SCRIPT_FILE

     Path to file containing pre install/uninstall/transaction script.

        * Mandatory : NO

        * Default : -

     May be used to embed a pre installation/uninstallation/transaction
     script in the spec file.  The referred script file (or both) will
     be read and directly put after the ‘%pre’ or ‘%preun’ section If
     CPACK_RPM_COMPONENT_INSTALL is set to ON the
     install/uninstall/transaction script for each component can be
     overridden with ‘CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE’,
     ‘CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE’, and
     ‘CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE’ One may verify which
     scriptlet has been included with:

          rpm -qp --scripts  package.rpm

 -- Variable: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
 -- Variable: CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
 -- Variable: CPACK_RPM_POST_TRANS_SCRIPT_FILE

     Path to file containing post install/uninstall/transaction script.

        * Mandatory : NO

        * Default : -

     May be used to embed a post installation/uninstallation/transaction
     script in the spec file.  The referred script file (or both) will
     be read and directly put after the ‘%post’ or ‘%postun’ section.
     If CPACK_RPM_COMPONENT_INSTALL is set to ON the
     install/uninstall/transaction script for each component can be
     overridden with ‘CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE’,
     ‘CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE’, and
     ‘CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE’ One may verify which
     scriptlet has been included with:

          rpm -qp --scripts  package.rpm

 -- Variable: CPACK_RPM_USER_FILELIST
 -- Variable: CPACK_RPM_<COMPONENT>_USER_FILELIST

        * Mandatory : NO

        * Default : -

     May be used to explicitly specify ‘%(<directive>)’ file line in the
     spec file.  Like ‘%config(noreplace)’ or any other directive that
     be found in the ‘%files’ section.  You can have multiple directives
     per line, as in ‘%attr(600,root,root) %config(noreplace)’.  Since
     the CPack RPM generator is generating the list of files (and
     directories) the user specified files of the
     ‘CPACK_RPM_<COMPONENT>_USER_FILELIST’ list will be removed from the
     generated list.  If referring to directories do not add a trailing
     slash.

 -- Variable: CPACK_RPM_CHANGELOG_FILE

     RPM changelog file.

        * Mandatory : NO

        * Default : -

     May be used to embed a changelog in the spec file.  The referred
     file will be read and directly put after the ‘%changelog’ section.

 -- Variable: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST

     list of path to be excluded.

        * Mandatory : NO

        *
          Default : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib

               /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal
               /usr/share/doc

     May be used to exclude path (directories or files) from the
     auto-generated list of paths discovered by CPack RPM. The default
     value contains a reasonable set of values if the variable is not
     defined by the user.  If the variable is defined by the user then
     the CPack RPM generator will NOT any of the default path.  If you
     want to add some path to the default list then you can use
     CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.

 -- Variable: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION

     additional list of path to be excluded.

        * Mandatory : NO

        * Default : -

     May be used to add more exclude path (directories or files) from
     the initial default list of excluded paths.  See
     CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.

 -- Variable: CPACK_RPM_RELOCATION_PATHS

     Packages relocation paths list.

        * Mandatory : NO

        * Default : -

     May be used to specify more than one relocation path per
     relocatable RPM. Variable contains a list of relocation paths that
     if relative are prefixed by the value of
     CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX or by the value of
     CPACK_PACKAGING_INSTALL_PREFIX if the component
     version is not provided.  Variable is not component based as its
     content can be used to set a different path prefix for e.g.  binary
     dir and documentation dir at the same time.  Only prefixes that are
     required by a certain component are added to that component -
     component must contain at least one file/directory/symbolic link
     with CPACK_RPM_RELOCATION_PATHS prefix for a certain
     relocation path to be added.  Package will not contain any
     relocation paths if there are no files/directories/symbolic links
     on any of the provided prefix locations.  Packages that either do
     not contain any relocation paths or contain
     files/directories/symbolic links that are outside relocation paths
     print out an ‘AUTHOR_WARNING’ that RPM will be partially
     relocatable.

 -- Variable: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX

     Per component relocation path install prefix.

        * Mandatory : NO

        * Default : CPACK_PACKAGING_INSTALL_PREFIX

     May be used to set per component
     CPACK_PACKAGING_INSTALL_PREFIX for relocatable RPM packages.

 -- Variable: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION
 -- Variable: CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION

     Removal of default install prefix from relocation paths list.

        * Mandatory : NO

        *
          Default : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX

               are treated as one of relocation paths

     May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and
     CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX from relocatable RPM prefix
     paths.

 -- Variable: CPACK_RPM_ADDITIONAL_MAN_DIRS

        * Mandatory : NO

        * Default : -

     May be used to set additional man dirs that could potentially be
     compressed by brp-compress RPM macro.  Variable content must be a
     list of regular expressions that point to directories containing
     man files or to man files directly.  Note that in order to compress
     man pages a path must also be present in brp-compress RPM script
     and that brp-compress script must be added to RPM configuration by
     the operating system.

     Regular expressions that are added by default were taken from
     brp-compress RPM macro:

        - /usr/man/man.*

        - /usr/man/.*/man.*

        - /usr/info.*

        - /usr/share/man/man.*

        - /usr/share/man/.*/man.*

        - /usr/share/info.*

        - /usr/kerberos/man.*

        - /usr/X11R6/man/man.*

        - /usr/lib/perl5/man/man.*

        - /usr/share/doc/.*/man/man.*

        - /usr/lib/.*/man/man.*

 -- Variable: CPACK_RPM_DEFAULT_USER
 -- Variable: CPACK_RPM_<compName>_DEFAULT_USER

     default user ownership of RPM content

        * Mandatory : NO

        * Default : root

     Value should be user name and not UID. Note that <compName> must be
     in upper-case.

 -- Variable: CPACK_RPM_DEFAULT_GROUP
 -- Variable: CPACK_RPM_<compName>_DEFAULT_GROUP

     default group ownership of RPM content

        * Mandatory : NO

        * Default : root

     Value should be group name and not GID. Note that <compName> must
     be in upper-case.

 -- Variable: CPACK_RPM_DEFAULT_FILE_PERMISSIONS
 -- Variable: CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS

     default permissions used for packaged files

        * Mandatory : NO

        * Default : - (system default)

     Accepted values are lists with ‘PERMISSIONS’.  Valid permissions
     are:

        - OWNER_READ

        - OWNER_WRITE

        - OWNER_EXECUTE

        - GROUP_READ

        - GROUP_WRITE

        - GROUP_EXECUTE

        - WORLD_READ

        - WORLD_WRITE

        - WORLD_EXECUTE

     Note that <compName> must be in upper-case.

 -- Variable: CPACK_RPM_DEFAULT_DIR_PERMISSIONS
 -- Variable: CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS

     default permissions used for packaged directories

        * Mandatory : NO

        * Default : - (system default)

     Accepted values are lists with PERMISSIONS. Valid permissions are
     the same as for CPACK_RPM_DEFAULT_FILE_PERMISSIONS.
     Note that <compName> must be in upper-case.

 -- Variable: CPACK_RPM_INSTALL_WITH_EXEC

     force execute permissions on programs and shared libraries

        * Mandatory : NO

        * Default : - (system default)

     Force set owner, group and world execute permissions on programs
     and shared libraries.  This can be used for creating valid rpm
     packages on systems such as Debian where shared libraries do not
     have execute permissions set.

     Note: Programs and shared libraries without execute permissions are
     ignored during separation of debug symbols from the binary for
     debuginfo packages.

24.1.13.2 Packaging of Symbolic Links
.....................................

The CPack RPM generator supports packaging of symbolic links:

     execute_process(COMMAND ${CMAKE_COMMAND}
       -E create_symlink <relative_path_location> <symlink_name>)
     install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name>
       DESTINATION <symlink_location> COMPONENT libraries)

Symbolic links will be optimized (paths will be shortened if possible)
before being added to the package or if multiple relocation paths are
detected, a post install symlink relocation script will be generated.

Symbolic links may point to locations that are not packaged by the same
package (either a different component or even not packaged at all) but
those locations will be treated as if they were a part of the package
while determining if symlink should be either created or present in a
post install script - depending on relocation paths.

Symbolic links that point to locations outside packaging path produce a
warning and are treated as non relocatable permanent symbolic links.

Currently there are a few limitations though:

   * For component based packaging component interdependency is not
     checked when processing symbolic links.  Symbolic links pointing to
     content of a different component are treated the same way as if
     pointing to location that will not be packaged.

   * Symbolic links pointing to a location through one or more
     intermediate symbolic links will not be handled differently - if
     the intermediate symbolic link(s) is also on a relocatable path,
     relocating it during package installation may cause initial
     symbolic link to point to an invalid location.

24.1.13.3 Packaging of debug information
........................................

Debuginfo packages contain debug symbols and sources for debugging
packaged binaries.

Debuginfo RPM packaging has its own set of variables:

 -- Variable: CPACK_RPM_DEBUGINFO_PACKAGE
 -- Variable: CPACK_RPM_<component>_DEBUGINFO_PACKAGE

     Enable generation of debuginfo RPM package(s).

        * Mandatory : NO

        * Default : OFF

     Note: Binaries must contain debug symbols before packaging so use
     either ‘Debug’ or ‘RelWithDebInfo’ for CMAKE_BUILD_TYPE.
     variable value.

     Note: Packages generated from packages without binary files, with
     binary files but without execute permissions or without debug
     symbols will cause packaging termination.

 -- Variable: CPACK_BUILD_SOURCE_DIRS

     Provides locations of root directories of source files from which
     binaries were built.

        * Mandatory : YES if CPACK_RPM_DEBUGINFO_PACKAGE is
          set

        * Default : -

     Note: For CMake project CPACK_BUILD_SOURCE_DIRS is set
     by default to point to CMAKE_SOURCE_DIR and
     CMAKE_BINARY_DIR paths.

     Note: Sources with path prefixes that do not fall under any
     location provided with CPACK_BUILD_SOURCE_DIRS will
     not be present in debuginfo package.

 -- Variable: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX
 -- Variable: CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX

     Prefix of location where sources will be placed during package
     installation.

        * Mandatory : YES if CPACK_RPM_DEBUGINFO_PACKAGE is
          set

        *
          Default : “/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>” and

               for component packaging
               “/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>”

     Note: Each source path prefix is additionally suffixed by
     ‘src_<index>’ where index is index of the path used from
     CPACK_BUILD_SOURCE_DIRS variable.  This produces
     ‘<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>’ replacement
     path.  Limitation is that replaced path part must be shorter or of
     equal length than the length of its replacement.  If that is not
     the case either CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX.
     variable has to be set to a shorter path or source directories must
     be placed on a longer path.

 -- Variable: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS

     Directories containing sources that should be excluded from
     debuginfo packages.

        * Mandatory : NO

        * Default : “/usr /usr/src /usr/src/debug”

     Listed paths are owned by other RPM packages and should therefore
     not be deleted on debuginfo package uninstallation.

 -- Variable: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION

     Paths that should be appended to
     CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS for exclusion.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE

     Create a single debuginfo package even if components packaging is
     set.

        * Mandatory : NO

        * Default : OFF

     When this variable is enabled it produces a single debuginfo
     package even if component packaging is enabled.

     When using this feature in combination with components packaging
     and there is more than one component this variable requires
     CPACK_RPM_MAIN_COMPONENT to be set.

     Note: If none of the CPACK_RPM_<component>_DEBUGINFO_PACKAGE
     variables is set then CPACK_RPM_DEBUGINFO_PACKAGE
     is automatically set to ‘ON’ when
     CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE is set.

 -- Variable: CPACK_RPM_DEBUGINFO_FILE_NAME
 -- Variable: CPACK_RPM_<component>_DEBUGINFO_FILE_NAME

     Debuginfo package file name.

        * Mandatory : NO

        * Default : rpmbuild tool generated package file name

     Alternatively provided debuginfo package file name must end with
     ‘.rpm’ suffix and should differ from file names of other generated
     packages.

     Variable may contain ‘@cpack_component@’ placeholder which will be
     replaced by component name if component packaging is enabled
     otherwise it deletes the placeholder.

     Setting the variable to ‘RPM-DEFAULT’ may be used to explicitly set
     filename generation to default.

     Note: CPACK_RPM_FILE_NAME also supports rpmbuild tool
     generated package file name - disabled by default but can be
     enabled by setting the variable to ‘RPM-DEFAULT’.

24.1.13.4 Packaging of sources (SRPM)
.....................................

SRPM packaging is enabled by setting CPACK_RPM_PACKAGE_SOURCES
variable while usually using CPACK_INSTALLED_DIRECTORIES
variable to provide directory containing CMakeLists.txt and source
files.

For CMake projects SRPM package would be produced by executing:

     cpack -G RPM --config ./CPackSourceConfig.cmake

     Note: Produced SRPM package is expected to be built with
     cmake(1) executable and packaged with cpack(1).
     executable so CMakeLists.txt has to be located in root source
     directory and must be able to generate binary rpm packages by
     executing ‘cpack -G’ command.  The two executables as well as
     rpmbuild must also be present when generating binary rpm packages
     from the produced SRPM package.

Once the SRPM package is generated it can be used to generate binary
packages by creating a directory structure for rpm generation and
executing rpmbuild tool:

     mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
     rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name>

Generated packages will be located in build_dir/RPMS directory or its
sub directories.

     Note: SRPM package internally uses CPack/RPM generator to generate
     binary packages so CMakeScripts.txt can decide during the SRPM to
     binary rpm generation step what content the package(s) should have
     as well as how they should be packaged (monolithic or components).
     CMake can decide this for e.g.  by reading environment variables
     set by the package manager before starting the process of
     generating binary rpm packages.  This way a single SRPM package can
     be used to produce different binary rpm packages on different
     platforms depending on the platform’s packaging rules.

Source RPM packaging has its own set of variables:

 -- Variable: CPACK_RPM_PACKAGE_SOURCES

     Should the content be packaged as a source rpm (default is binary
     rpm).

        * Mandatory : NO

        * Default : OFF

     Note: For cmake projects CPACK_RPM_PACKAGE_SOURCES.
     variable is set to ‘OFF’ in CPackConfig.cmake and ‘ON’ in
     CPackSourceConfig.cmake generated files.

 -- Variable: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS

     Additional command-line parameters provided to cmake(1).
     executable.

        * Mandatory : NO

        * Default : -

 -- Variable: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX

     Packaging install prefix that would be provided in
     CPACK_PACKAGING_INSTALL_PREFIX variable for producing binary
     RPM packages.

        * Mandatory : YES

        * Default : “/”

 -- Variable: CPACK_RPM_BUILDREQUIRES

     List of source rpm build dependencies.

        * Mandatory : NO

        * Default : -

     May be used to set source RPM build dependencies (BuildRequires).
     Note that you must enclose the complete build requirements string
     between quotes, for example:

          set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8")

24.1.14 CPack WIX Generator
---------------------------

CPack WIX generator specific options

24.1.14.1 Variables specific to CPack WIX generator
...................................................

The following variables are specific to the installers built on Windows
using WiX.

 -- Variable: CPACK_WIX_UPGRADE_GUID

     Upgrade GUID (‘Product/@UpgradeCode’)

     Will be automatically generated unless explicitly provided.

     It should be explicitly set to a constant generated globally unique
     identifier (GUID) to allow your installers to replace existing
     installations that use the same GUID.

     You may for example explicitly set this variable in your
     CMakeLists.txt to the value that has been generated per default.
     You should not use GUIDs that you did not generate yourself or
     which may belong to other projects.

     A GUID shall have the following fixed length syntax:

          XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

     (each X represents an uppercase hexadecimal digit)

 -- Variable: CPACK_WIX_PRODUCT_GUID

     Product GUID (‘Product/@Id’)

     Will be automatically generated unless explicitly provided.

     If explicitly provided this will set the Product Id of your
     installer.

     The installer will abort if it detects a pre-existing installation
     that uses the same GUID.

     The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.

 -- Variable: CPACK_WIX_LICENSE_RTF

     RTF License File

     If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used
     as-is.

     If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is
     implicitly converted to RTF by the WIX Generator.  The expected
     encoding of the .txt file is UTF-8.

     With CPACK_WIX_LICENSE_RTF you can override the license file used
     by the WIX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an
     unsupported format or the .txt -> .rtf conversion does not work as
     expected.

 -- Variable: CPACK_WIX_PRODUCT_ICON

     The Icon shown next to the program name in Add/Remove programs.

     If set, this icon is used in place of the default icon.

 -- Variable: CPACK_WIX_UI_REF

     This variable allows you to override the Id of the ‘<UIRef>’
     element in the WiX template.

     The default is ‘WixUI_InstallDir’ in case no CPack components have
     been defined and ‘WixUI_FeatureTree’ otherwise.

 -- Variable: CPACK_WIX_UI_BANNER

     The bitmap will appear at the top of all installer pages other than
     the welcome and completion dialogs.

     If set, this image will replace the default banner image.

     This image must be 493 by 58 pixels.

 -- Variable: CPACK_WIX_UI_DIALOG

     Background bitmap used on the welcome and completion dialogs.

     If this variable is set, the installer will replace the default
     dialog image.

     This image must be 493 by 312 pixels.

 -- Variable: CPACK_WIX_PROGRAM_MENU_FOLDER

     Start menu folder name for launcher.

     If this variable is not set, it will be initialized with
     CPACK_PACKAGE_NAME

     If this variable is set to ‘.’, then application shortcuts will be
     created directly in the start menu and the uninstaller shortcut
     will be omitted.

 -- Variable: CPACK_WIX_CULTURES

     Language(s) of the installer

     Languages are compiled into the WixUI extension library.  To use
     them, simply provide the name of the culture.  If you specify more
     than one culture identifier in a comma or semicolon delimited list,
     the first one that is found will be used.  You can find a list of
     supported languages at:
     ‘http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm’

 -- Variable: CPACK_WIX_TEMPLATE

     Template file for WiX generation

     If this variable is set, the specified template will be used to
     generate the WiX wxs file.  This should be used if further
     customization of the output is required.

     If this variable is not set, the default MSI template included with
     CMake will be used.

 -- Variable: CPACK_WIX_PATCH_FILE

     Optional list of XML files with fragments to be inserted into
     generated WiX sources

     This optional variable can be used to specify an XML file that the
     WIX generator will use to inject fragments into its generated
     source files.

     Patch files understood by the CPack WIX generator roughly follow
     this RELAX NG compact schema:

          start = CPackWiXPatch

          CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }

          CPackWiXFragment = element CPackWiXFragment
          {
              attribute Id { string },
              fragmentContent*
          }

          fragmentContent = element * - CPackWiXFragment
          {
              (attribute * { text } | text | fragmentContent)*
          }

     Currently fragments can be injected into most Component, File,
     Directory and Feature elements.

     The following additional special Ids can be used:

        * ‘#PRODUCT’ for the ‘<Product>’ element.

        * ‘#PRODUCTFEATURE’ for the root ‘<Feature>’ element.

     The following example illustrates how this works.

     Given that the WIX generator creates the following XML element:

          <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>

     The following XML patch file may be used to inject an Environment
     element into it:

          <CPackWiXPatch>
            <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
              <Environment Id="MyEnvironment" Action="set"
                Name="MyVariableName" Value="MyVariableValue"/>
            </CPackWiXFragment>
          </CPackWiXPatch>

 -- Variable: CPACK_WIX_EXTRA_SOURCES

     Extra WiX source files

     This variable provides an optional list of extra WiX source files
     (.wxs) that should be compiled and linked.  The full path to source
     files is required.

 -- Variable: CPACK_WIX_EXTRA_OBJECTS

     Extra WiX object files or libraries

     This variable provides an optional list of extra WiX object
     (.wixobj) and/or WiX library (.wixlib) files.  The full path to
     objects and libraries is required.

 -- Variable: CPACK_WIX_EXTENSIONS

     This variable provides a list of additional extensions for the WiX
     tools light and candle.

 -- Variable: CPACK_WIX_<TOOL>_EXTENSIONS

     This is the tool specific version of CPACK_WIX_EXTENSIONS. ‘<TOOL>’
     can be either LIGHT or CANDLE.

 -- Variable: CPACK_WIX_<TOOL>_EXTRA_FLAGS

     This list variable allows you to pass additional flags to the WiX
     tool ‘<TOOL>’.

     Use it at your own risk.  Future versions of CPack may generate
     flags which may be in conflict with your own flags.

     ‘<TOOL>’ can be either LIGHT or CANDLE.

 -- Variable: CPACK_WIX_CMAKE_PACKAGE_REGISTRY

     If this variable is set the generated installer will create an
     entry in the windows registry key
     ‘HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>’
     The value for ‘<PackageName>’ is provided by this variable.

     Assuming you also install a CMake configuration file this will
     allow other CMake projects to find your package with the
     find_package() command.

 -- Variable: CPACK_WIX_PROPERTY_<PROPERTY>

     This variable can be used to provide a value for the Windows
     Installer property ‘<PROPERTY>’

     The following list contains some example properties that can be
     used to customize information under “Programs and Features” (also
     known as “Add or Remove Programs”)

        * ARPCOMMENTS - Comments

        * ARPHELPLINK - Help and support information URL

        * ARPURLINFOABOUT - General information URL

        * ARPURLUPDATEINFO - Update information URL

        * ARPHELPTELEPHONE - Help and support telephone number

        * ARPSIZE - Size (in kilobytes) of the application

 -- Variable: CPACK_WIX_ROOT_FEATURE_TITLE

     Sets the name of the root install feature in the WIX installer.
     Same as CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.

 -- Variable: CPACK_WIX_ROOT_FEATURE_DESCRIPTION

     Sets the description of the root install feature in the WIX
     installer.  Same as CPACK_COMPONENT_<compName>_DESCRIPTION for
     components.

 -- Variable: CPACK_WIX_SKIP_PROGRAM_FOLDER

     If this variable is set to true, the default install location of
     the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY
     directly.  The install location will not be located relatively
     below ProgramFiles or ProgramFiles64.

               Note: Installers created with this feature do not take
               differences between the system on which the installer is
               created and the system on which the installer might be
               used into account.

               It is therefore possible that the installer e.g.  might
               try to install onto a drive that is unavailable or
               unintended or a path that does not follow the
               localization or convention of the system on which the
               installation is performed.

 -- Variable: CPACK_WIX_ROOT_FOLDER_ID

     This variable allows specification of a custom root folder ID. The
     generator specific ‘<64>’ token can be used for folder IDs that
     come in 32-bit and 64-bit variants.  In 32-bit builds the token
     will expand empty while in 64-bit builds it will expand to ‘64’.

     When unset generated installers will default installing to
     ‘ProgramFiles<64>Folder’.

 -- Variable: CPACK_WIX_ROOT

     This variable can optionally be set to the root directory of a
     custom WiX Toolset installation.

     When unspecified CPack will try to locate a WiX Toolset
     installation via the ‘WIX’ environment variable instead.

 -- Variable: CPACK_WIX_CUSTOM_XMLNS

     This variable provides a list of custom namespace declarations that
     are necessary for using WiX extensions.  Each declaration should be
     in the form name=url, where name is the plain namespace without the
     usual xmlns: prefix and url is an unquoted namespace url.  A list
     of commonly known WiX schemata can be found here:
     ‘https://wixtoolset.org/documentation/manual/v3/xsd/’

Guides
******

25 CMake Tutorial
*****************

25.1 Introduction
=================

The CMake tutorial provides a step-by-step guide that covers common
build system issues that CMake helps address.  Seeing how various topics
all work together in an example project can be very helpful.  The
tutorial documentation and source code for examples can be found in the
‘Help/guide/tutorial’ directory of the CMake source code tree.  Each
step has its own subdirectory containing code that may be used as a
starting point.  The tutorial examples are progressive so that each step
provides the complete solution for the previous step.

25.2 A Basic Starting Point (Step 1)
====================================

The most basic project is an executable built from source code files.
For simple projects, a three line ‘CMakeLists.txt’ file is all that is
required.  This will be the starting point for our tutorial.  Create a
‘CMakeLists.txt’ file in the ‘Step1’ directory that looks like:

     cmake_minimum_required(VERSION 3.10)

     # set the project name
     project(Tutorial)

     # add the executable
     add_executable(Tutorial tutorial.cxx)

Note that this example uses lower case commands in the ‘CMakeLists.txt’
file.  Upper, lower, and mixed case commands are supported by CMake.
The source code for ‘tutorial.cxx’ is provided in the ‘Step1’ directory
and can be used to compute the square root of a number.

25.2.1 Adding a Version Number and Configured Header File
---------------------------------------------------------

The first feature we will add is to provide our executable and project
with a version number.  While we could do this exclusively in the source
code, using ‘CMakeLists.txt’ provides more flexibility.

First, modify the ‘CMakeLists.txt’ file to use the project().
command to set the project name and version number.

     cmake_minimum_required(VERSION 3.10)

     # set the project name and version
     project(Tutorial VERSION 1.0)

Then, configure a header file to pass the version number to the source
code:

     configure_file(TutorialConfig.h.in TutorialConfig.h)

Since the configured file will be written into the binary tree, we must
add that directory to the list of paths to search for include files.
Add the following lines to the end of the ‘CMakeLists.txt’ file:

     target_include_directories(Tutorial PUBLIC
                                "${PROJECT_BINARY_DIR}"
                                )

Using your favorite editor, create ‘TutorialConfig.h.in’ in the source
directory with the following contents:

     // the configured options and settings for Tutorial
     #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
     #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

When CMake configures this header file the values for
‘@Tutorial_VERSION_MAJOR@’ and ‘@Tutorial_VERSION_MINOR@’ will be
replaced.

Next modify ‘tutorial.cxx’ to include the configured header file,
‘TutorialConfig.h’.

Finally, let’s print out the executable name and version number by
updating ‘tutorial.cxx’ as follows:

       if (argc < 2) {
         // report version
         std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
                   << Tutorial_VERSION_MINOR << std::endl;
         std::cout << "Usage: " << argv[0] << " number" << std::endl;
         return 1;
       }

25.2.2 Specify the C++ Standard
-------------------------------

Next let’s add some C++11 features to our project by replacing ‘atof’
with ‘std::stod’ in ‘tutorial.cxx’.  At the same time, remove ‘#include
<cstdlib>’.

       const double inputValue = std::stod(argv[1]);

We will need to explicitly state in the CMake code that it should use
the correct flags.  The easiest way to enable support for a specific C++
standard in CMake is by using the CMAKE_CXX_STANDARD.
variable.  For this tutorial, set the CMAKE_CXX_STANDARD.
variable in the ‘CMakeLists.txt’ file to 11 and
CMAKE_CXX_STANDARD_REQUIRED to True.  Make sure to add the
‘CMAKE_CXX_STANDARD’ declarations above the call to ‘add_executable’.

     cmake_minimum_required(VERSION 3.10)

     # set the project name and version
     project(Tutorial VERSION 1.0)

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

25.2.3 Build and Test
---------------------

Run the cmake executable or the cmake-gui to
configure the project and then build it with your chosen build tool.

For example, from the command line we could navigate to the
‘Help/guide/tutorial’ directory of the CMake source code tree and create
a build directory:

     mkdir Step1_build

Next, navigate to the build directory and run CMake to configure the
project and generate a native build system:

     cd Step1_build
     cmake ../Step1

Then call that build system to actually compile/link the project:

     cmake --build .

Finally, try to use the newly built ‘Tutorial’ with these commands:

     Tutorial 4294967296
     Tutorial 10
     Tutorial

25.3 Adding a Library (Step 2)
==============================

Now we will add a library to our project.  This library will contain our
own implementation for computing the square root of a number.  The
executable can then use this library instead of the standard square root
function provided by the compiler.

For this tutorial we will put the library into a subdirectory called
‘MathFunctions’.  This directory already contains a header file,
‘MathFunctions.h’, and a source file ‘mysqrt.cxx’.  The source file has
one function called ‘mysqrt’ that provides similar functionality to the
compiler’s ‘sqrt’ function.

Add the following one line ‘CMakeLists.txt’ file to the ‘MathFunctions’
directory:

     add_library(MathFunctions mysqrt.cxx)

To make use of the new library we will add an add_subdirectory()
call in the top-level ‘CMakeLists.txt’ file so that the library
will get built.  We add the new library to the executable, and add
‘MathFunctions’ as an include directory so that the ‘mqsqrt.h’ header
file can be found.  The last few lines of the top-level ‘CMakeLists.txt’
file should now look like:

     # add the MathFunctions library
     add_subdirectory(MathFunctions)

     # add the executable
     add_executable(Tutorial tutorial.cxx)

     target_link_libraries(Tutorial PUBLIC MathFunctions)

     # add the binary tree to the search path for include files
     # so that we will find TutorialConfig.h
     target_include_directories(Tutorial PUBLIC
                               "${PROJECT_BINARY_DIR}"
                               "${PROJECT_SOURCE_DIR}/MathFunctions"
                               )

Now let us make the MathFunctions library optional.  While for the
tutorial there really isn’t any need to do so, for larger projects this
is a common occurrence.  The first step is to add an option to the
top-level ‘CMakeLists.txt’ file.

     option(USE_MYMATH "Use tutorial provided math implementation" ON)

     # configure a header file to pass some of the CMake settings
     # to the source code
     configure_file(TutorialConfig.h.in TutorialConfig.h)

This option will be displayed in the cmake-gui and
ccmake with a default value of ON that can be changed by the user.
This setting will be stored in the cache so that the user does not need
to set the value each time they run CMake on a build directory.

The next change is to make building and linking the MathFunctions
library conditional.  To do this we change the end of the top-level
‘CMakeLists.txt’ file to look like the following:

     if(USE_MYMATH)
       add_subdirectory(MathFunctions)
       list(APPEND EXTRA_LIBS MathFunctions)
       list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions")
     endif()

     # add the executable
     add_executable(Tutorial tutorial.cxx)

     target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS})

     # add the binary tree to the search path for include files
     # so that we will find TutorialConfig.h
     target_include_directories(Tutorial PUBLIC
                                "${PROJECT_BINARY_DIR}"
                                ${EXTRA_INCLUDES}
                                )

Note the use of the variable ‘EXTRA_LIBS’ to collect up any optional
libraries to later be linked into the executable.  The variable
‘EXTRA_INCLUDES’ is used similarly for optional header files.  This is a
classic approach when dealing with many optional components, we will
cover the modern approach in the next step.

The corresponding changes to the source code are fairly straightforward.
First, in ‘tutorial.cxx’, include the ‘MathFunctions.h’ header if we
need it:

     #ifdef USE_MYMATH
     #  include "MathFunctions.h"
     #endif

Then, in the same file, make ‘USE_MYMATH’ control which square root
function is used:

     #ifdef USE_MYMATH
       const double outputValue = mysqrt(inputValue);
     #else
       const double outputValue = sqrt(inputValue);
     #endif

Since the source code now requires ‘USE_MYMATH’ we can add it to
‘TutorialConfig.h.in’ with the following line:

     #cmakedefine USE_MYMATH

`Exercise': Why is it important that we configure ‘TutorialConfig.h.in’
after the option for ‘USE_MYMATH’?  What would happen if we inverted the
two?

Run the cmake executable or the cmake-gui to
configure the project and then build it with your chosen build tool.
Then run the built Tutorial executable.

Now let’s update the value of ‘USE_MYMATH’.  The easiest way is to use
the cmake-gui or ccmake if you’re in the terminal.
Or, alternatively, if you want to change the option from the
command-line, try:

     cmake ../Step2 -DUSE_MYMATH=OFF

Rebuild and run the tutorial again.

Which function gives better results, sqrt or mysqrt?

25.4 Adding Usage Requirements for Library (Step 3)
===================================================

Usage requirements allow for far better control over a library or
executable’s link and include line while also giving more control over
the transitive property of targets inside CMake.  The primary commands
that leverage usage requirements are:

        - target_compile_definitions().

        - target_compile_options().

        - target_include_directories().

        - target_link_libraries().

Let’s refactor our code from Adding a Library (Step 2) to
use the modern CMake approach of usage requirements.  We first state
that anybody linking to MathFunctions needs to include the current
source directory, while MathFunctions itself doesn’t.  So this can
become an ‘INTERFACE’ usage requirement.

Remember ‘INTERFACE’ means things that consumers require but the
producer doesn’t.  Add the following lines to the end of
‘MathFunctions/CMakeLists.txt’:

     target_include_directories(MathFunctions
               INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
               )

Now that we’ve specified usage requirements for MathFunctions we can
safely remove our uses of the ‘EXTRA_INCLUDES’ variable from the
top-level ‘CMakeLists.txt’, here:

     if(USE_MYMATH)
       add_subdirectory(MathFunctions)
       list(APPEND EXTRA_LIBS MathFunctions)
     endif()

And here:

     target_include_directories(Tutorial PUBLIC
                                "${PROJECT_BINARY_DIR}"
                                )

Once this is done, run the cmake executable or the
cmake-gui to configure the project and then build it with your
chosen build tool or by using ‘cmake --build .’ from the build
directory.

25.5 Installing and Testing (Step 4)
====================================

Now we can start adding install rules and testing support to our
project.

25.5.1 Install Rules
--------------------

The install rules are fairly simple: for MathFunctions we want to
install the library and header file and for the application we want to
install the executable and configured header.

So to the end of ‘MathFunctions/CMakeLists.txt’ we add:

     install(TARGETS MathFunctions DESTINATION lib)
     install(FILES MathFunctions.h DESTINATION include)

And to the end of the top-level ‘CMakeLists.txt’ we add:

     install(TARGETS Tutorial DESTINATION bin)
     install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
       DESTINATION include
       )

That is all that is needed to create a basic local install of the
tutorial.

Now run the cmake executable or the cmake-gui to
configure the project and then build it with your chosen build tool.

Then run the install step by using the ‘install’ option of the
cmake command (introduced in 3.15, older versions of CMake must use
‘make install’) from the command line.  For multi-configuration tools,
don’t forget to use the ‘--config’ argument to specify the
configuration.  If using an IDE, simply build the ‘INSTALL’ target.
This step will install the appropriate header files, libraries, and
executables.  For example:

     cmake --install .

The CMake variable CMAKE_INSTALL_PREFIX is used to determine
the root of where the files will be installed.  If using the ‘cmake
--install’ command, the installation prefix can be overridden via the
‘--prefix’ argument.  For example:

     cmake --install . --prefix "/home/myuser/installdir"

Navigate to the install directory and verify that the installed Tutorial
runs.

25.5.2 Testing Support
----------------------

Next let’s test our application.  At the end of the top-level
‘CMakeLists.txt’ file we can enable testing and then add a number of
basic tests to verify that the application is working correctly.

     enable_testing()

     # does the application run
     add_test(NAME Runs COMMAND Tutorial 25)

     # does the usage message work?
     add_test(NAME Usage COMMAND Tutorial)
     set_tests_properties(Usage
       PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
       )

     # define a function to simplify adding tests
     function(do_test target arg result)
       add_test(NAME Comp${arg} COMMAND ${target} ${arg})
       set_tests_properties(Comp${arg}
         PROPERTIES PASS_REGULAR_EXPRESSION ${result}
         )
     endfunction(do_test)

     # do a bunch of result based tests
     do_test(Tutorial 4 "4 is 2")
     do_test(Tutorial 9 "9 is 3")
     do_test(Tutorial 5 "5 is 2.236")
     do_test(Tutorial 7 "7 is 2.645")
     do_test(Tutorial 25 "25 is 5")
     do_test(Tutorial -25 "-25 is [-nan|nan|0]")
     do_test(Tutorial 0.0001 "0.0001 is 0.01")

The first test simply verifies that the application runs, does not
segfault or otherwise crash, and has a zero return value.  This is the
basic form of a CTest test.

The next test makes use of the PASS_REGULAR_EXPRESSION test
property to verify that the output of the test contains certain strings.
In this case, verifying that the usage message is printed when an
incorrect number of arguments are provided.

Lastly, we have a function called ‘do_test’ that runs the application
and verifies that the computed square root is correct for given input.
For each invocation of ‘do_test’, another test is added to the project
with a name, input, and expected results based on the passed arguments.

Rebuild the application and then cd to the binary directory and run the
ctest executable: ‘ctest -N’ and ‘ctest -VV’.  For
multi-config generators (e.g.  Visual Studio), the configuration type
must be specified.  To run tests in Debug mode, for example, use ‘ctest
-C Debug -VV’ from the build directory (not the Debug subdirectory!).
Alternatively, build the ‘RUN_TESTS’ target from the IDE.

25.6 Adding System Introspection (Step 5)
=========================================

Let us consider adding some code to our project that depends on features
the target platform may not have.  For this example, we will add some
code that depends on whether or not the target platform has the ‘log’
and ‘exp’ functions.  Of course almost every platform has these
functions but for this tutorial assume that they are not common.

If the platform has ‘log’ and ‘exp’ then we will use them to compute the
square root in the ‘mysqrt’ function.  We first test for the
availability of these functions using the CheckSymbolExists.
module in the top-level ‘CMakeLists.txt’.  On some platforms, we will
need to link to the m library.  If ‘log’ and ‘exp’ are not initially
found, require the m library and try again.

We’re going to use the new defines in ‘TutorialConfig.h.in’, so be sure
to set them before that file is configured.

     include(CheckSymbolExists)
     check_symbol_exists(log "math.h" HAVE_LOG)
     check_symbol_exists(exp "math.h" HAVE_EXP)
     if(NOT (HAVE_LOG AND HAVE_EXP))
       unset(HAVE_LOG CACHE)
       unset(HAVE_EXP CACHE)
       set(CMAKE_REQUIRED_LIBRARIES "m")
       check_symbol_exists(log "math.h" HAVE_LOG)
       check_symbol_exists(exp "math.h" HAVE_EXP)
       if(HAVE_LOG AND HAVE_EXP)
         target_link_libraries(MathFunctions PRIVATE m)
       endif()
     endif()

Now let’s add these defines to ‘TutorialConfig.h.in’ so that we can use
them from ‘mysqrt.cxx’:

     // does the platform provide exp and log functions?
     #cmakedefine HAVE_LOG
     #cmakedefine HAVE_EXP

If ‘log’ and ‘exp’ are available on the system, then we will use them to
compute the square root in the ‘mysqrt’ function.  Add the following
code to the ‘mysqrt’ function in ‘MathFunctions/mysqrt.cxx’ (don’t
forget the ‘#endif’ before returning the result!):

     #if defined(HAVE_LOG) && defined(HAVE_EXP)
       double result = exp(log(x) * 0.5);
       std::cout << "Computing sqrt of " << x << " to be " << result
                 << " using log and exp" << std::endl;
     #else
       double result = x;

We will also need to modify ‘mysqrt.cxx’ to include ‘cmath’.

     #include <cmath>

Run the cmake executable or the cmake-gui to
configure the project and then build it with your chosen build tool and
run the Tutorial executable.

You will notice that we’re not using ‘log’ and ‘exp’, even if we think
they should be available.  We should realize quickly that we have
forgotten to include ‘TutorialConfig.h’ in ‘mysqrt.cxx’.

We will also need to update ‘MathFunctions/CMakeLists.txt’ so
‘mysqrt.cxx’ knows where this file is located:

     target_include_directories(MathFunctions
               INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
               PRIVATE ${CMAKE_BINARY_DIR}
               )

After making this update, go ahead and build the project again and run
the built Tutorial executable.  If ‘log’ and ‘exp’ are still not being
used, open the generated ‘TutorialConfig.h’ file from the build
directory.  Maybe they aren’t available on the current system?

Which function gives better results now, sqrt or mysqrt?

25.6.1 Specify Compile Definition
---------------------------------

Is there a better place for us to save the ‘HAVE_LOG’ and ‘HAVE_EXP’
values other than in ‘TutorialConfig.h’?  Let’s try to use
target_compile_definitions().

First, remove the defines from ‘TutorialConfig.h.in’.  We no longer need
to include ‘TutorialConfig.h’ from ‘mysqrt.cxx’ or the extra include in
‘MathFunctions/CMakeLists.txt’.

Next, we can move the check for ‘HAVE_LOG’ and ‘HAVE_EXP’ to
‘MathFunctions/CMakeLists.txt’ and then specify those values as
‘PRIVATE’ compile definitions.

     include(CheckSymbolExists)
     check_symbol_exists(log "math.h" HAVE_LOG)
     check_symbol_exists(exp "math.h" HAVE_EXP)
     if(NOT (HAVE_LOG AND HAVE_EXP))
       unset(HAVE_LOG CACHE)
       unset(HAVE_EXP CACHE)
       set(CMAKE_REQUIRED_LIBRARIES "m")
       check_symbol_exists(log "math.h" HAVE_LOG)
       check_symbol_exists(exp "math.h" HAVE_EXP)
       if(HAVE_LOG AND HAVE_EXP)
         target_link_libraries(MathFunctions PRIVATE m)
       endif()
     endif()

     # add compile definitions
     if(HAVE_LOG AND HAVE_EXP)
       target_compile_definitions(MathFunctions
                                  PRIVATE "HAVE_LOG" "HAVE_EXP")
     endif()

After making these updates, go ahead and build the project again.  Run
the built Tutorial executable and verify that the results are same as
earlier in this step.

25.7 Adding a Custom Command and Generated File (Step 6)
========================================================

Suppose, for the purpose of this tutorial, we decide that we never want
to use the platform ‘log’ and ‘exp’ functions and instead would like to
generate a table of precomputed values to use in the ‘mysqrt’ function.
In this section, we will create the table as part of the build process,
and then compile that table into our application.

First, let’s remove the check for the ‘log’ and ‘exp’ functions in
‘MathFunctions/CMakeLists.txt’.  Then remove the check for ‘HAVE_LOG’
and ‘HAVE_EXP’ from ‘mysqrt.cxx’.  At the same time, we can remove
‘#include <cmath>’.

In the ‘MathFunctions’ subdirectory, a new source file named
‘MakeTable.cxx’ has been provided to generate the table.

After reviewing the file, we can see that the table is produced as valid
C++ code and that the output filename is passed in as an argument.

The next step is to add the appropriate commands to the
‘MathFunctions/CMakeLists.txt’ file to build the MakeTable executable
and then run it as part of the build process.  A few commands are needed
to accomplish this.

First, at the top of ‘MathFunctions/CMakeLists.txt’, the executable for
‘MakeTable’ is added as any other executable would be added.

     add_executable(MakeTable MakeTable.cxx)

Then we add a custom command that specifies how to produce ‘Table.h’ by
running MakeTable.

     add_custom_command(
       OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
       COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
       DEPENDS MakeTable
       )

Next we have to let CMake know that ‘mysqrt.cxx’ depends on the
generated file ‘Table.h’.  This is done by adding the generated
‘Table.h’ to the list of sources for the library MathFunctions.

     add_library(MathFunctions
                 mysqrt.cxx
                 ${CMAKE_CURRENT_BINARY_DIR}/Table.h
                 )

We also have to add the current binary directory to the list of include
directories so that ‘Table.h’ can be found and included by ‘mysqrt.cxx’.

     target_include_directories(MathFunctions
               INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
               PRIVATE ${CMAKE_CURRENT_BINARY_DIR}
               )

Now let’s use the generated table.  First, modify ‘mysqrt.cxx’ to
include ‘Table.h’.  Next, we can rewrite the mysqrt function to use the
table:

     double mysqrt(double x)
     {
       if (x <= 0) {
         return 0;
       }

       // use the table to help find an initial value
       double result = x;
       if (x >= 1 && x < 10) {
         std::cout << "Use the table to help find an initial value " << std::endl;
         result = sqrtTable[static_cast<int>(x)];
       }

       // do ten iterations
       for (int i = 0; i < 10; ++i) {
         if (result <= 0) {
           result = 0.1;
         }
         double delta = x - (result * result);
         result = result + 0.5 * delta / result;
         std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
       }

       return result;
     }

Run the cmake executable or the cmake-gui to
configure the project and then build it with your chosen build tool.

When this project is built it will first build the ‘MakeTable’
executable.  It will then run ‘MakeTable’ to produce ‘Table.h’.
Finally, it will compile ‘mysqrt.cxx’ which includes ‘Table.h’ to
produce the MathFunctions library.

Run the Tutorial executable and verify that it is using the table.

25.8 Building an Installer (Step 7)
===================================

Next suppose that we want to distribute our project to other people so
that they can use it.  We want to provide both binary and source
distributions on a variety of platforms.  This is a little different
from the install we did previously in Installing and Testing (Step 4).
, where we were installing the binaries that we had built from
the source code.  In this example we will be building installation
packages that support binary installations and package management
features.  To accomplish this we will use CPack to create platform
specific installers.  Specifically we need to add a few lines to the
bottom of our top-level ‘CMakeLists.txt’ file.

     include(InstallRequiredSystemLibraries)
     set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
     set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
     set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
     include(CPack)

That is all there is to it.  We start by including
InstallRequiredSystemLibraries.  This module will include any
runtime libraries that are needed by the project for the current
platform.  Next we set some CPack variables to where we have stored the
license and version information for this project.  The version
information was set earlier in this tutorial and the ‘license.txt’ has
been included in the top-level source directory for this step.

Finally we include the CPack module which will use these
variables and some other properties of the current system to setup an
installer.

The next step is to build the project in the usual manner and then run
the cpack executable.  To build a binary distribution, from
the binary directory run:

     cpack

To specify the generator, use the ‘-G’ option.  For multi-config builds,
use ‘-C’ to specify the configuration.  For example:

     cpack -G ZIP -C Debug

To create a source distribution you would type:

     cpack --config CPackSourceConfig.cmake

Alternatively, run ‘make package’ or right click the ‘Package’ target
and ‘Build Project’ from an IDE.

Run the installer found in the binary directory.  Then run the installed
executable and verify that it works.

25.9 Adding Support for a Dashboard (Step 8)
============================================

Adding support for submitting our test results to a dashboard is simple.
We already defined a number of tests for our project in Testing Support.
Now we just have to run those tests and submit them to a
dashboard.  To include support for dashboards we include the
CTest module in our top-level ‘CMakeLists.txt’.

Replace:

     # enable testing
     enable_testing()

With:

     # enable dashboard scripting
     include(CTest)

The CTest module will automatically call ‘enable_testing()’,
so we can remove it from our CMake files.

We will also need to create a ‘CTestConfig.cmake’ file in the top-level
directory where we can specify the name of the project and where to
submit the dashboard.

     set(CTEST_PROJECT_NAME "CMakeTutorial")
     set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")

     set(CTEST_DROP_METHOD "http")
     set(CTEST_DROP_SITE "my.cdash.org")
     set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
     set(CTEST_DROP_SITE_CDASH TRUE)

The ctest executable will read in this file when it runs.  To
create a simple dashboard you can run the cmake executable or
the cmake-gui to configure the project, but do not build it
yet.  Instead, change directory to the binary tree, and then run:

     ctest [-VV] -D Experimental

Remember, for multi-config generators (e.g.  Visual Studio), the
configuration type must be specified:

     ctest [-VV] -C Debug -D Experimental

Or, from an IDE, build the ‘Experimental’ target.

The ctest executable will build and test the project and
submit the results to Kitware’s public dashboard:
‘https://my.cdash.org/index.php?project=CMakeTutorial’.

25.10 Mixing Static and Shared (Step 9)
=======================================

In this section we will show how the BUILD_SHARED_LIBS.
variable can be used to control the default behavior of
add_library(), and allow control over how libraries without an
explicit type (‘STATIC’, ‘SHARED’, ‘MODULE’ or ‘OBJECT’) are built.

To accomplish this we need to add BUILD_SHARED_LIBS to the
top-level ‘CMakeLists.txt’.  We use the option() command as
it allows users to optionally select if the value should be ON or OFF.

Next we are going to refactor MathFunctions to become a real library
that encapsulates using ‘mysqrt’ or ‘sqrt’, instead of requiring the
calling code to do this logic.  This will also mean that ‘USE_MYMATH’
will not control building MathFunctions, but instead will control the
behavior of this library.

The first step is to update the starting section of the top-level
‘CMakeLists.txt’ to look like:

     cmake_minimum_required(VERSION 3.10)

     # set the project name and version
     project(Tutorial VERSION 1.0)

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

     # control where the static and shared libraries are built so that on windows
     # we don't need to tinker with the path to run the executable
     set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
     set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
     set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")

     option(BUILD_SHARED_LIBS "Build using shared libraries" ON)

     # configure a header file to pass the version number only
     configure_file(TutorialConfig.h.in TutorialConfig.h)

     # add the MathFunctions library
     add_subdirectory(MathFunctions)

     # add the executable
     add_executable(Tutorial tutorial.cxx)
     target_link_libraries(Tutorial PUBLIC MathFunctions)

Now that we have made MathFunctions always be used, we will need to
update the logic of that library.  So, in ‘MathFunctions/CMakeLists.txt’
we need to create a SqrtLibrary that will conditionally be built and
installed when ‘USE_MYMATH’ is enabled.  Now, since this is a tutorial,
we are going to explicitly require that SqrtLibrary is built statically.

The end result is that ‘MathFunctions/CMakeLists.txt’ should look like:

     # add the library that runs
     add_library(MathFunctions MathFunctions.cxx)

     # state that anybody linking to us needs to include the current source dir
     # to find MathFunctions.h, while we don't.
     target_include_directories(MathFunctions
                                INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
                                )

     # should we use our own math functions
     option(USE_MYMATH "Use tutorial provided math implementation" ON)
     if(USE_MYMATH)

       target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")

       # first we add the executable that generates the table
       add_executable(MakeTable MakeTable.cxx)

       # add the command to generate the source code
       add_custom_command(
         OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
         COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
         DEPENDS MakeTable
         )

       # library that just does sqrt
       add_library(SqrtLibrary STATIC
                   mysqrt.cxx
                   ${CMAKE_CURRENT_BINARY_DIR}/Table.h
                   )

       # state that we depend on our binary dir to find Table.h
       target_include_directories(SqrtLibrary PRIVATE
                                  ${CMAKE_CURRENT_BINARY_DIR}
                                  )

       target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
     endif()

     # define the symbol stating we are using the declspec(dllexport) when
     # building on windows
     target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")

     # install rules
     set(installable_libs MathFunctions)
     if(TARGET SqrtLibrary)
       list(APPEND installable_libs SqrtLibrary)
     endif()
     install(TARGETS ${installable_libs} DESTINATION lib)
     install(FILES MathFunctions.h DESTINATION include)

Next, update ‘MathFunctions/mysqrt.cxx’ to use the ‘mathfunctions’ and
‘detail’ namespaces:

     #include <iostream>

     #include "MathFunctions.h"

     // include the generated table
     #include "Table.h"

     namespace mathfunctions {
     namespace detail {
     // a hack square root calculation using simple operations
     double mysqrt(double x)
     {
       if (x <= 0) {
         return 0;
       }

       // use the table to help find an initial value
       double result = x;
       if (x >= 1 && x < 10) {
         std::cout << "Use the table to help find an initial value " << std::endl;
         result = sqrtTable[static_cast<int>(x)];
       }

       // do ten iterations
       for (int i = 0; i < 10; ++i) {
         if (result <= 0) {
           result = 0.1;
         }
         double delta = x - (result * result);
         result = result + 0.5 * delta / result;
         std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
       }

       return result;
     }
     }
     }

We also need to make some changes in ‘tutorial.cxx’, so that it no
longer uses ‘USE_MYMATH’:

  1. Always include ‘MathFunctions.h’

  2. Always use ‘mathfunctions::sqrt’

  3. Don’t include cmath

Finally, update ‘MathFunctions/MathFunctions.h’ to use dll export
defines:

     #if defined(_WIN32)
     #  if defined(EXPORTING_MYMATH)
     #    define DECLSPEC __declspec(dllexport)
     #  else
     #    define DECLSPEC __declspec(dllimport)
     #  endif
     #else // non windows
     #  define DECLSPEC
     #endif

     namespace mathfunctions {
     double DECLSPEC sqrt(double x);
     }

At this point, if you build everything, you may notice that linking
fails as we are combining a static library without position independent
code with a library that has position independent code.  The solution to
this is to explicitly set the POSITION_INDEPENDENT_CODE.
target property of SqrtLibrary to be True no matter the build type.

       # state that SqrtLibrary need PIC when the default is shared libraries
       set_target_properties(SqrtLibrary PROPERTIES
                             POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                             )

       target_link_libraries(MathFunctions PRIVATE SqrtLibrary)

`Exercise': We modified ‘MathFunctions.h’ to use dll export defines.
Using CMake documentation can you find a helper module to simplify this?

25.11 Adding Generator Expressions (Step 10)
============================================

Generator expressions are evaluated during build system
generation to produce information specific to each build configuration.

Generator expressions are allowed in the context of many
target properties, such as LINK_LIBRARIES,
INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and others.
They may also be used when using commands to populate those properties,
such as target_link_libraries(),
target_include_directories(), target_compile_definitions()
and others.

Generator expressions may be used to enable conditional
linking, conditional definitions used when compiling, conditional
include directories and more.  The conditions may be based on the build
configuration, target properties, platform information or any other
queryable information.

There are different types of generator expressions including
Logical, Informational, and Output expressions.

Logical expressions are used to create conditional output.  The basic
expressions are the 0 and 1 expressions.  A ‘$<0:...>’ results in the
empty string, and ‘<1:...>’ results in the content of “…”.  They can
also be nested.

A common usage of generator expressions is to conditionally
add compiler flags, such as those for language levels or warnings.  A
nice pattern is to associate this information to an ‘INTERFACE’ target
allowing this information to propagate.  Let’s start by constructing an
‘INTERFACE’ target and specifying the required C++ standard level of
‘11’ instead of using CMAKE_CXX_STANDARD.

So the following code:

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

Would be replaced with:

     add_library(tutorial_compiler_flags INTERFACE)
     target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)

Next we add the desired compiler warning flags that we want for our
project.  As warning flags vary based on the compiler we use the
‘COMPILE_LANG_AND_ID’ generator expression to control which flags to
apply given a language and a set of compiler ids as seen below:

     set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
     set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
     target_compile_options(tutorial_compiler_flags INTERFACE
       "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
       "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
     )

Looking at this we see that the warning flags are encapsulated inside a
‘BUILD_INTERFACE’ condition.  This is done so that consumers of our
installed project will not inherit our warning flags.

`Exercise': Modify ‘MathFunctions/CMakeLists.txt’ so that all targets
have a target_link_libraries() call to
‘tutorial_compiler_flags’.

25.12 Adding Export Configuration (Step 11)
===========================================

During Installing and Testing (Step 4) of the tutorial we
added the ability for CMake to install the library and headers of the
project.  During Building an Installer (Step 7) we added
the ability to package up this information so it could be distributed to
other people.

The next step is to add the necessary information so that other CMake
projects can use our project, be it from a build directory, a local
install or when packaged.

The first step is to update our install(TARGETS) commands to
not only specify a ‘DESTINATION’ but also an ‘EXPORT’.  The ‘EXPORT’
keyword generates and installs a CMake file containing code to import
all targets listed in the install command from the installation tree.
So let’s go ahead and explicitly ‘EXPORT’ the MathFunctions library by
updating the ‘install’ command in ‘MathFunctions/CMakeLists.txt’ to look
like:

     set(installable_libs MathFunctions tutorial_compiler_flags)
     if(TARGET SqrtLibrary)
       list(APPEND installable_libs SqrtLibrary)
     endif()
     install(TARGETS ${installable_libs}
             DESTINATION lib
             EXPORT MathFunctionsTargets)
     install(FILES MathFunctions.h DESTINATION include)

Now that we have MathFunctions being exported, we also need to
explicitly install the generated ‘MathFunctionsTargets.cmake’ file.
This is done by adding the following to the bottom of the top-level
‘CMakeLists.txt’:

     install(EXPORT MathFunctionsTargets
       FILE MathFunctionsTargets.cmake
       DESTINATION lib/cmake/MathFunctions
     )

At this point you should try and run CMake.  If everything is setup
properly you will see that CMake will generate an error that looks like:

     Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains
     path:

       "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions"

     which is prefixed in the source directory.

What CMake is trying to say is that during generating the export
information it will export a path that is intrinsically tied to the
current machine and will not be valid on other machines.  The solution
to this is to update the MathFunctions
target_include_directories() to understand that it needs different
‘INTERFACE’ locations when being used from within the build directory
and from an install / package.  This means converting the
target_include_directories() call for MathFunctions to look like:

     target_include_directories(MathFunctions
                                INTERFACE
                                 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
                                 $<INSTALL_INTERFACE:include>
                                )

Once this has been updated, we can re-run CMake and verify that it
doesn’t warn anymore.

At this point, we have CMake properly packaging the target information
that is required but we will still need to generate a
‘MathFunctionsConfig.cmake’ so that the CMake find_package().
command can find our project.  So let’s go ahead and add a new file to
the top-level of the project called ‘Config.cmake.in’ with the following
contents:

     @PACKAGE_INIT@

     include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )

Then, to properly configure and install that file, add the following to
the bottom of the top-level ‘CMakeLists.txt’:

     install(EXPORT MathFunctionsTargets
       FILE MathFunctionsTargets.cmake
       DESTINATION lib/cmake/MathFunctions
     )

     include(CMakePackageConfigHelpers)
     # generate the config file that is includes the exports
     configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
       INSTALL_DESTINATION "lib/cmake/example"
       NO_SET_AND_CHECK_MACRO
       NO_CHECK_REQUIRED_COMPONENTS_MACRO
       )
     # generate the version file for the config file
     write_basic_package_version_file(
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
       VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}"
       COMPATIBILITY AnyNewerVersion
     )

     # install the configuration file
     install(FILES
       ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake
       DESTINATION lib/cmake/MathFunctions
       )

At this point, we have generated a relocatable CMake Configuration for
our project that can be used after the project has been installed or
packaged.  If we want our project to also be used from a build directory
we only have to add the following to the bottom of the top level
‘CMakeLists.txt’:

     export(EXPORT MathFunctionsTargets
       FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake"
     )

With this export call we now generate a ‘Targets.cmake’, allowing the
configured ‘MathFunctionsConfig.cmake’ in the build directory to be used
by other projects, without needing it to be installed.

25.13 Packaging Debug and Release (Step 12)
===========================================

`Note:' This example is valid for single-configuration generators and
will not work for multi-configuration generators (e.g.  Visual Studio).

By default, CMake’s model is that a build directory only contains a
single configuration, be it Debug, Release, MinSizeRel, or
RelWithDebInfo.  It is possible, however, to setup CPack to bundle
multiple build directories and construct a package that contains
multiple configurations of the same project.

First, we want to ensure that the debug and release builds use different
names for the executables and libraries that will be installed.  Let’s
use ‘d’ as the postfix for the debug executable and libraries.

Set CMAKE_DEBUG_POSTFIX near the beginning of the top-level
‘CMakeLists.txt’ file:

     set(CMAKE_DEBUG_POSTFIX d)

     add_library(tutorial_compiler_flags INTERFACE)

And the DEBUG_POSTFIX property on the tutorial executable:

     add_executable(Tutorial tutorial.cxx)
     set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})

     target_link_libraries(Tutorial PUBLIC MathFunctions)

Let’s also add version numbering to the MathFunctions library.  In
‘MathFunctions/CMakeLists.txt’, set the VERSION and
SOVERSION properties:

     set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
     set_property(TARGET MathFunctions PROPERTY SOVERSION "1")

From the ‘Step12’ directory, create ‘debug’ and ‘release’
subbdirectories.  The layout will look like:

     - Step12
        - debug
        - release

Now we need to setup debug and release builds.  We can use
CMAKE_BUILD_TYPE to set the configuration type:

     cd debug
     cmake -DCMAKE_BUILD_TYPE=Debug ..
     cmake --build .
     cd ../release
     cmake -DCMAKE_BUILD_TYPE=Release ..
     cmake --build .

Now that both the debug and release builds are complete, we can use a
custom configuration file to package both builds into a single release.
In the ‘Step12’ directory, create a file called
‘MultiCPackConfig.cmake’.  In this file, first include the default
configuration file that was created by the cmake executable.

Next, use the ‘CPACK_INSTALL_CMAKE_PROJECTS’ variable to specify which
projects to install.  In this case, we want to install both debug and
release.

     include("release/CPackConfig.cmake")

     set(CPACK_INSTALL_CMAKE_PROJECTS
         "debug;Tutorial;ALL;/"
         "release;Tutorial;ALL;/"
         )

From the ‘Step12’ directory, run cpack specifying our custom
configuration file with the ‘config’ option:

     cpack --config MultiCPackConfig.cmake

26 User Interaction Guide
*************************

26.1 Introduction
=================

Where a software package supplies a CMake-based buildsystem with the
source of their software, the consumer of the software is required to
run a CMake user interaction tool in order to build it.

Well-behaved CMake-based buildsystems do not create any output in the
source directory, so typically, the user performs an out-of-source build
and performs the build there.  First, CMake must be instructed to
generate a suitable buildsystem, then the user invokes a build tool to
process that generated buildsystem.  The generated buildsystem is
specific to the machine used to generate it and is not redistributable.
Each consumer of a provided source software package is required to use
CMake to generate a buildsystem specific to their system.

Generated buildsystems should generally be treated as read-only.  The
CMake files as a primary artifact should completely specify the
buildsystem and there should be no reason to populate properties
manually in an IDE for example after generating the buildsystem.  CMake
will periodically rewrite the generated buildsystem, so modifications by
users will be overwritten.

The features and user interfaces described in this manual are available
for all CMake-based build systems by virtue of providing CMake files.

The CMake tooling may report errors to the user when processing provided
CMake files, such as reporting that the compiler is not supported, or
the compiler does not support a required compile option, or a dependency
can not be found.  These errors must be resolved by the user by choosing
a different compiler, see installing dependencies, or instructing
CMake where to find them, etc.

26.1.1 Command Line cmake tool
------------------------------

A simple but typical use of cmake(1) with a fresh copy of
software source code is to create a build directory and invoke cmake
there:

     $ cd some_software-1.4.2
     $ mkdir build
     $ cd build
     $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
     $ cmake --build .
     $ cmake --build . --target install

It is recommended to build in a separate directory to the source because
that keeps the source directory pristine, allows for building a single
source with multiple toolchains, and allows easy clearing of build
artifacts by simply deleting the build directory.

The CMake tooling may report warnings which are intended for the
provider of the software, not intended for the consumer of the software.
Such warnings end with “This warning is for project developers”.  Users
may disable such warnings by passing the ‘-Wno-dev’ flag to
cmake(1).

26.1.2 cmake-gui tool
---------------------

Users more accustomed to GUI interfaces may use the cmake-gui(1)
tool to invoke CMake and generate a buildsystem.

The source and binary directories must first be populated.  It is always
advised to use different directories for the source and the build.

[Choosing source and binary directories]

26.2 Generating a Buildsystem
=============================

There are several user interface tools which may be used to generate a
buildsystem from CMake files.  The ccmake(1) and
cmake-gui(1) tools guide the user through setting the various
necessary options.  The cmake(1) tool can be invoked to
specify options on the command line.  This manual describes options
which may be set using any of the user interface tools, though the mode
of setting an option is different for each tool.

26.2.1 Command line environment
-------------------------------

When invoking cmake(1) with a command line buildsystem such as
‘Makefiles’ or ‘Ninja’, it is necessary to use the correct build
environment to ensure that build tools are available.  CMake must be
able to find the appropriate build tool, compiler, linker and
other tools as needed.

On Linux systems, the appropriate tools are often provided in
system-wide locations and may be readily installed through the system
package manager.  Other toolchains provided by the user or installed in
non-default locations can also be used.

When cross-compiling, some platforms may require environment variables
to be set or may provide scripts to set the environment.

Visual Studio ships multiple command prompts and ‘vcvarsall.bat’ scripts
for setting up the correct environments for command line buildsystems.
While not strictly necessary to use a corresponding command line
environment when using a Visual Studio generator, doing so has no
disadvantages.

When using Xcode, there can be more than one Xcode version installed.
Which one to use can be selected in a number of different ways, but the
most common methods are:

   * Setting the default version in the preferences of the Xcode IDE.

   * Setting the default version via the ‘xcode-select’ command line
     tool.

   * Overriding the default version by setting the ‘DEVELOPER_DIR’
     environment variable when running CMake and the build tool.

For convenience, see cmake-gui(1) provides an environment variable
editor.

26.2.2 Command line ‘-G’ option
-------------------------------

CMake chooses a generator by default based on the platform.  Usually,
the default generator is sufficient to allow the user to proceed to
build the software.

The user may override the default generator with the ‘-G’ option:

     $ cmake .. -G Ninja

The output of ‘cmake --help’ includes a list of generators.
available for the user to choose from.  Note that generator names are
case sensitive.

On Unix-like systems (including Mac OS X), the Unix Makefiles.
generator is used by default.  A variant of that generator can also be
used on Windows in various environments, such as the NMake Makefiles
and MinGW Makefiles generator.  These
generators generate a ‘Makefile’ variant which can be executed with
‘make’, ‘gmake’, ‘nmake’ or similar tools.  See the individual generator
documentation for more information on targeted environments and tools.

The Ninja generator is available on all major platforms.
‘ninja’ is a build tool similar in use-cases to ‘make’, but with a focus
on performance and efficiency.

On Windows, see cmake(1) can be used to generate solutions for the
Visual Studio IDE. Visual Studio versions may be specified by the
product name of the IDE, which includes a four-digit year.  Aliases are
provided for other means by which Visual Studio versions are sometimes
referred to, such as two digits which correspond to the product version
of the VisualC++ compiler, or a combination of the two:

     $ cmake .. -G "Visual Studio 2019"
     $ cmake .. -G "Visual Studio 16"
     $ cmake .. -G "Visual Studio 16 2019"

Visual Studio generators can target different architectures.  One can
specify the target architecture using the ‘-A’ option:

     cmake .. -G "Visual Studio 2019" -A x64
     cmake .. -G "Visual Studio 16" -A ARM
     cmake .. -G "Visual Studio 16 2019" -A ARM64

On Apple, the Xcode generator may be used to generate
project files for the Xcode IDE.

Some IDEs such as KDevelop4, QtCreator and CLion have native support for
CMake-based buildsystems.  Those IDEs provide user interface for
selecting an underlying generator to use, typically a choice between a
‘Makefile’ or a ‘Ninja’ based generator.

Note that it is not possible to change the generator with ‘-G’ after the
first invocation of CMake.  To change the generator, the build directory
must be deleted and the build must be started from scratch.

When generating Visual Studio project and solutions files several other
options are available to use when initially running cmake(1).

The Visual Studio toolset can be specified with the ‘-T’ option:

     $ # Build with the clang-cl toolset
     $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T LLVM
     $ # Build targeting Windows XP
     $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp

Whereas the ‘-A’ option specifies the _target_ architecture, the ‘-T’
option can be used to specify details of the toolchain used.  For
example, ‘-Thost=x64’ can be given to select the 64-bit version of the
host tools.  The following demonstrates how to use 64-bit tools and also
build for a 64-bit target architecture:

     $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64

26.2.3 Choosing a generator in cmake-gui
----------------------------------------

The “Configure” button triggers a new dialog to select the CMake
generator to use.

[Configuring a generator]
All generators available on the command line are also available in
cmake-gui(1).

[Choosing a generator]
When choosing a Visual Studio generator, further options are available
to set an architecture to generate for.

[Choosing an architecture for Visual Studio generators]

26.3 Setting Build Variables
============================

Software projects often require variables to be set on the command line
when invoking CMake.  Some of the most commonly used CMake variables are
listed in the table below:

Variable                                       Meaning

----------------------------------------------------------------------------------------------------------------

See CMAKE_PREFIX_PATH.                  Path to search for dependent packages.

See CMAKE_MODULE_PATH.                  Path to search for additional CMake modules

See CMAKE_BUILD_TYPE.                   Build configuration, such as ‘Debug’ or ‘Release’, determining
                                               debug/optimization flags.  This is only relevant for
                                               single-configuration buildsystems such as ‘Makefile’ and
                                               ‘Ninja’.  Multi-configuration buildsystems such as those for
                                               Visual Studio and Xcode ignore this setting.

See CMAKE_INSTALL_PREFIX.                Location to install the software to with the ‘install’ build
                                               target

See CMAKE_TOOLCHAIN_FILE.               File containing cross-compiling data such as
                                               toolchains and sysroots.

See BUILD_SHARED_LIBS.                   Whether to build shared instead of static libraries for
                                               add_library() commands used without a type

See CMAKE_EXPORT_COMPILE_COMMANDS.      Generate a ‘compile_commands.json’ file for use with
                                               clang-based tools

Other project-specific variables may be available to control builds,
such as enabling or disabling components of the project.

There is no convention provided by CMake for how such variables are
named between different provided buildsystems, except that variables
with the prefix ‘CMAKE_’ usually refer to options provided by CMake
itself and should not be used in third-party options, which should use
their own prefix instead.  The cmake-gui(1) tool can display
options in groups defined by their prefix, so it makes sense for third
parties to ensure that they use a self-consistent prefix.

26.3.1 Setting variables on the command line
--------------------------------------------

CMake variables can be set on the command line either when creating the
initial build:

     $ mkdir build
     $ cd build
     $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

or later on a subsequent invocation of cmake(1).:

     $ cd build
     $ cmake . -DCMAKE_BUILD_TYPE=Debug

The ‘-U’ flag may be used to unset variables on the cmake(1).
command line:

     $ cd build
     $ cmake . -UMyPackage_DIR

A CMake buildsystem which was initially created on the command line can
be modified using the cmake-gui(1) and vice-versa.

The cmake(1) tool allows specifying a file to use to populate
the initial cache using the ‘-C’ option.  This can be useful to simplify
commands and scripts which repeatedly require the same cache entries.

26.3.2 Setting variables with cmake-gui
---------------------------------------

Variables may be set in the cmake-gui using the “Add Entry” button.
This triggers a new dialog to set the value of the variable.

[Editing a cache entry]
The main view of the cmake-gui(1) user interface can be used
to edit existing variables.

26.3.3 The CMake Cache
----------------------

When CMake is executed, it needs to find the locations of compilers,
tools and dependencies.  It also needs to be able to consistently
re-generate a buildsystem to use the same compile/link flags and paths
to dependencies.  Such parameters are also required to be configurable
by the user because they are paths and options specific to the users
system.

When it is first executed, CMake generates a ‘CMakeCache.txt’ file in
the build directory containing key-value pairs for such artifacts.  The
cache file can be viewed or edited by the user by running the
cmake-gui(1) or ccmake(1) tool.  The tools provide an
interactive interface for re-configuring the provided software and
re-generating the buildsystem, as is needed after editing cached values.
Each cache entry may have an associated short help text which is
displayed in the user interface tools.

The cache entries may also have a type to signify how it should be
presented in the user interface.  For example, a cache entry of type
‘BOOL’ can be edited by a checkbox in a user interface, a ‘STRING’ can
be edited in a text field, and a ‘FILEPATH’ while similar to a ‘STRING’
should also provide a way to locate filesystem paths using a file
dialog.  An entry of type ‘STRING’ may provide a restricted list of
allowed values which are then provided in a drop-down menu in the
cmake-gui(1) user interface (see the STRINGS cache
property).

The CMake files shipped with a software package may also define boolean
toggle options using the option() command.  The command
creates a cache entry which has a help text and a default value.  Such
cache entries are typically specific to the provided software and affect
the configuration of the build, such as whether tests and examples are
built, whether to build with exceptions enabled etc.

26.4 Presets
============

CMake understands a file, ‘CMakePresets.json’, and its user-specific
counterpart, ‘CMakeUserPresets.json’, for saving presets for
commonly-used configure settings.  These presets can set the build
directory, generator, cache variables, environment variables, and other
command-line options.  All of these options can be overridden by the
user.  The full details of the ‘CMakePresets.json’ format are listed in
the cmake-presets(7) manual.

26.4.1 Using presets on the command-line
----------------------------------------

When using the cmake(1) command line tool, a preset can be
invoked by using the ‘--preset’ option.  If ‘--preset’ is specified, the
generator and build directory are not required, but can be specified to
override them.  For example, if you have the following
‘CMakePresets.json’ file:

     {
       "version": 1,
       "configurePresets": [
         {
           "name": "ninja-release",
           "binaryDir": "${sourceDir}/build/${presetName}",
           "generator": "Ninja",
           "cacheVariables": {
             "CMAKE_BUILD_TYPE": "Release"
           }
         }
       ]
     }

and you run the following:

     cmake -S /path/to/source --preset=ninja-release

This will generate a build directory in
‘/path/to/source/build/ninja-release’ with the Ninja.
generator, and with CMAKE_BUILD_TYPE set to ‘Release’.

If you want to see the list of available presets, you can run:

     cmake -S /path/to/source --list-presets

This will list the presets available in
‘/path/to/source/CMakePresets.json’ and
‘/path/to/source/CMakeUsersPresets.json’ without generating a build
tree.

26.4.2 Using presets in cmake-gui
---------------------------------

If a project has presets available, either through ‘CMakePresets.json’
or ‘CMakeUserPresets.json’, the list of presets will appear in a
drop-down menu in cmake-gui(1) between the source directory
and the binary directory.  Choosing a preset sets the binary directory,
generator, environment variables, and cache variables, but all of these
options can be overridden after a preset is selected.

26.5 Invoking the Buildsystem
=============================

After generating the buildsystem, the software can be built by invoking
the particular build tool.  In the case of the IDE generators, this can
involve loading the generated project file into the IDE to invoke the
build.

CMake is aware of the specific build tool needed to invoke a build so in
general, to build a buildsystem or project from the command line after
generating, the following command may be invoked in the build directory:

     $ cmake --build .

The ‘--build’ flag enables a particular mode of operation for the
cmake(1) tool.  It invokes the CMAKE_MAKE_PROGRAM.
command associated with the generator, or the build tool
configured by the user.

The ‘--build’ mode also accepts the parameter ‘--target’ to specify a
particular target to build, for example a particular library, executable
or custom target, or a particular special target like ‘install’:

     $ cmake --build . --target myexe

The ‘--build’ mode also accepts a ‘--config’ parameter in the case of
multi-config generators to specify which particular configuration to
build:

     $ cmake --build . --target myexe --config Release

The ‘--config’ option has no effect if the generator generates a
buildsystem specific to a configuration which is chosen when invoking
cmake with the CMAKE_BUILD_TYPE variable.

Some buildsystems omit details of command lines invoked during the
build.  The ‘--verbose’ flag can be used to cause those command lines to
be shown:

     $ cmake --build . --target myexe --verbose

The ‘--build’ mode can also pass particular command line options to the
underlying build tool by listing them after ‘--’.  This can be useful to
specify options to the build tool, such as to continue the build after a
failed job, where CMake does not provide a high-level user interface.

For all generators, it is possible to run the underlying build tool
after invoking CMake.  For example, ‘make’ may be executed after
generating with the Unix Makefiles generator to invoke the
build, or ‘ninja’ after generating with the Ninja generator
etc.  The IDE buildsystems usually provide command line tooling for
building a project which can also be invoked.

26.5.1 Selecting a Target
-------------------------

Each executable and library described in the CMake files is a build
target, and the buildsystem may describe custom targets, either for
internal use, or for user consumption, for example to create
documentation.

CMake provides some built-in targets for all buildsystems providing
CMake files.

‘all’

     The default target used by ‘Makefile’ and ‘Ninja’ generators.
     Builds all targets in the buildsystem, except those which are
     excluded by their EXCLUDE_FROM_ALL target property or
     EXCLUDE_FROM_ALL directory property.  The name
     ‘ALL_BUILD’ is used for this purpose for the Xcode and Visual
     Studio generators.

‘help’

     Lists the targets available for build.  This target is available
     when using the Unix Makefiles or Ninja.
     generator, and the exact output is tool-specific.

‘clean’

     Delete built object files and other output files.  The ‘Makefile’
     based generators create a ‘clean’ target per directory, so that an
     individual directory can be cleaned.  The ‘Ninja’ tool provides its
     own granular ‘-t clean’ system.

‘test’

     Runs tests.  This target is only automatically available if the
     CMake files provide CTest-based tests.  See also Running Tests.

‘install’

     Installs the software.  This target is only automatically available
     if the software defines install rules with the install()
     command.  See also Software Installation.

‘package’

     Creates a binary package.  This target is only automatically
     available if the CMake files provide CPack-based packages.

‘package_source’

     Creates a source package.  This target is only automatically
     available if the CMake files provide CPack-based packages.

For ‘Makefile’ based systems, ‘/fast’ variants of binary build targets
are provided.  The ‘/fast’ variants are used to build the specified
target without regard for its dependencies.  The dependencies are not
checked and are not rebuilt if out of date.  The Ninja.
generator is sufficiently fast at dependency checking that such targets
are not provided for that generator.

‘Makefile’ based systems also provide build-targets to preprocess,
assemble and compile individual files in a particular directory.

     $ make foo.cpp.i
     $ make foo.cpp.s
     $ make foo.cpp.o

The file extension is built into the name of the target because another
file with the same name but a different extension may exist.  However,
build-targets without the file extension are also provided.

     $ make foo.i
     $ make foo.s
     $ make foo.o

In buildsystems which contain ‘foo.c’ and ‘foo.cpp’, building the
‘foo.i’ target will preprocess both files.

26.5.2 Specifying a Build Program
---------------------------------

The program invoked by the ‘--build’ mode is determined by the
CMAKE_MAKE_PROGRAM variable.  For most generators, the particular
program does not need to be configured.

Generator                 Default make program            Alternatives

------------------------------------------------------------------------------------------

XCode                     ‘xcodebuild’

Unix Makefiles            ‘make’

NMake Makefiles           ‘nmake’                         ‘jom’

NMake Makefiles JOM       ‘jom’                           ‘nmake’

MinGW Makefiles           ‘mingw32-make’

MSYS Makefiles            ‘make’

Ninja                     ‘ninja’

Visual Studio             ‘msbuild’

Watcom WMake              ‘wmake’

The ‘jom’ tool is capable of reading makefiles of the ‘NMake’ flavor and
building in parallel, while the ‘nmake’ tool always builds serially.
After generating with the NMake Makefiles generator a user
can run ‘jom’ instead of ‘nmake’.  The ‘--build’ mode would also use
‘jom’ if the CMAKE_MAKE_PROGRAM was set to ‘jom’ while using
the NMake Makefiles generator, and as a convenience, the
NMake Makefiles JOM generator is provided to find ‘jom’ in
the normal way and use it as the CMAKE_MAKE_PROGRAM.  For
completeness, ‘nmake’ is an alternative tool which can process the
output of the NMake Makefiles JOM generator, but doing so
would be a pessimisation.

26.6 Software Installation
==========================

The CMAKE_INSTALL_PREFIX variable can be set in the CMake
cache to specify where to install the provided software.  If the
provided software has install rules, specified using the
install() command, they will install artifacts into that prefix.
On Windows, the default installation location corresponds to the
‘ProgramFiles’ system directory which may be architecture specific.  On
Unix hosts, ‘/usr/local’ is the default installation location.

The CMAKE_INSTALL_PREFIX variable always refers to the
installation prefix on the target filesystem.

In cross-compiling or packaging scenarios where the sysroot is read-only
or where the sysroot should otherwise remain pristine, the
CMAKE_STAGING_PREFIX variable can be set to a location to actually
install the files.

The commands:

     $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
       -DCMAKE_SYSROOT=$HOME/root \
       -DCMAKE_STAGING_PREFIX=/tmp/package
     $ cmake --build .
     $ cmake --build . --target install

result in files being installed to paths such as
‘/tmp/package/lib/libfoo.so’ on the host machine.  The ‘/usr/local’
location on the host machine is not affected.

Some provided software may specify ‘uninstall’ rules, but CMake does not
generate such rules by default itself.

26.7 Running Tests
==================

The ctest(1) tool is shipped with the CMake distribution to
execute provided tests and report results.  The ‘test’ build-target is
provided to run all available tests, but the ctest(1) tool
allows granular control over which tests to run, how to run them, and
how to report results.  Executing ctest(1) in the build
directory is equivalent to running the ‘test’ target:

     $ ctest

A regular expression can be passed to run only tests which match the
expression.  To run only tests with ‘Qt’ in their name:

     $ ctest -R Qt

Tests can be excluded by regular expression too.  To run only tests
without ‘Qt’ in their name:

     $ ctest -E Qt

Tests can be run in parallel by passing ‘-j’ arguments to
ctest(1).:

     $ ctest -R Qt -j8

The environment variable CTEST_PARALLEL_LEVEL can
alternatively be set to avoid the need to pass ‘-j’.

By default ctest(1) does not print the output from the tests.
The command line argument ‘-V’ (or ‘--verbose’) enables verbose mode to
print the output from all tests.  The ‘--output-on-failure’ option
prints the test output for failing tests only.  The environment variable
CTEST_OUTPUT_ON_FAILURE can be set to ‘1’ as an alternative
to passing the ‘--output-on-failure’ option to ctest(1).

27 Using Dependencies Guide
***************************

27.1 Introduction
=================

For developers wishing to use CMake to consume a third party binary
package, there are multiple possibilities regarding how to optimally do
so, depending on how CMake-aware the third-party library is.

CMake files provided with a software package contain instructions for
finding each build dependency.  Some build dependencies are optional in
that the build may succeed with a different feature set if the
dependency is missing, and some dependencies are required.  CMake
searches well-known locations for each dependency, and the provided
software may supply additional hints or locations to CMake to find each
dependency.

If a required dependency is not found by cmake(1), the cache is
populated with an entry which contains a ‘NOTFOUND’ value.  This value
can be replaced by specifying it on the command line, or in the
ccmake(1) or cmake-gui(1) tool.  See the User Interaction Guide
for more about setting cache entries.

27.2 Libraries providing Config-file packages
=============================================

The most convenient way for a third-party to provide library binaries
for use with CMake is to provide Config-file Packages.  These
packages are text files shipped with the library which instruct CMake
how to use the library binaries and associated headers, helper tools and
CMake macros provided by the library.

The config files can usually be found in a directory whose name matches
the pattern ‘lib/cmake/<PackageName>’, though they may be in other
locations instead.  The ‘<PackageName>’ corresponds to use in CMake code
with the find_package() command such as
‘find_package(PackageName REQUIRED)’.

The ‘lib/cmake/<PackageName>’ directory will contain a file which is
either named ‘<PackageName>Config.cmake’ or
‘<PackageName>-config.cmake’.  This is the entry point to the package
for CMake.  A separate optional file named
‘<PackageName>ConfigVersion.cmake’ may also exist in the directory.
This file is used by CMake to determine whether the version of the third
party package satisfies uses of the find_package() command
which specify version constraints.  It is optional to specify a version
when using find_package(), even if a ‘ConfigVersion’ file is
present.

If the ‘Config.cmake’ file is found and the optionally-specified version
is satisfied, then the CMake find_package() command considers
the package to be found and the entire library package is assumed to be
complete as designed.

There may be additional files providing CMake macros or Imported Targets
for you to use.  CMake does not enforce any naming
convention for these files.  They are related to the primary ‘Config’
file by use of the CMake include() command.

Invoking CMake with the intent of using a package of third
party binaries requires that cmake find_package() commands
succeed in finding the package.  If the location of the package is in a
directory known to CMake, the find_package() call should
succeed.  The directories known to cmake are platform-specific.  For
example, packages installed on Linux with a standard system package
manager will be found in the ‘/usr’ prefix automatically.  Packages
installed in ‘Program Files’ on Windows will similarly be found
automatically.

Packages which are not found automatically are in locations not
predictable to CMake such as ‘/opt/mylib’ or ‘$HOME/dev/prefix’.  This
is a normal situation and CMake provides several ways for users to
specify where to find such libraries.

The CMAKE_PREFIX_PATH variable may be set when invoking CMake.
It is treated as a list of paths to search for
Config-file Packages.  A package installed in
‘/opt/somepackage’ will typically install config files such as
‘/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake’.  In
that case, ‘/opt/somepackage’ should be added to
CMAKE_PREFIX_PATH.

The environment variable ‘CMAKE_PREFIX_PATH’ may also be populated with
prefixes to search for packages.  Like the ‘PATH’ environment variable,
this is a list and needs to use the platform-specific environment
variable list item separator (‘:’ on Unix and ‘;’ on Windows).

The CMAKE_PREFIX_PATH variable provides convenience in cases
where multiple prefixes need to be specified, or when multiple different
package binaries are available in the same prefix.  Paths to packages
may also be specified by setting variables matching ‘<PackageName>_DIR’,
such as ‘SomePackage_DIR’.  Note that this is not a prefix but should be
a full path to a directory containing a config-style package file, such
as ‘/opt/somepackage/lib/cmake/SomePackage/’ in the above example.

27.3 Imported Targets from Packages
===================================

A third-party package which provides config-file packages may also
provide Imported Targets.  These will be specified in files
containing configuration-specific file paths relevant to the package,
such as debug and release versions of libraries.

Often the third-party package documentation will point out the names of
imported targets available after a successful ‘find_package’ for a
library.  Those imported target names can be used with the
target_link_libraries() command.

A complete example which makes a simple use of a third party library
might look like:

     cmake_minimum_required(VERSION 3.10)
     project(MyExeProject VERSION 1.0.0)

     find_package(SomePackage REQUIRED)
     add_executable(MyExe main.cpp)
     target_link_libraries(MyExe PRIVATE SomePrefix::LibName)

See cmake-buildsystem(7) for further information about
developing a CMake buildsystem.

27.3.1 Libraries not Providing Config-file Packages
---------------------------------------------------

Third-party libraries which do not provide config-file packages can
still be found with the find_package() command, if a
‘FindSomePackage.cmake’ file is available.

These module-file packages are different to config-file packages in
that:

  1. They should not be provided by the third party, except perhaps in
     the form of documentation

  2. The availability of a ‘Find<PackageName>.cmake’ file does not
     indicate the availability of the binaries themselves.

  3. CMake does not search the CMAKE_PREFIX_PATH for
     ‘Find<PackageName>.cmake’ files.  Instead CMake searches for such
     files in the CMAKE_MODULE_PATH variable.  It is common
     for users to set the CMAKE_MODULE_PATH when running
     CMake, and it is common for CMake projects to append to
     CMAKE_MODULE_PATH to allow use of local module-file packages.

  4. CMake ships ‘Find<PackageName>.cmake’ files for some third party packages
     for convenience in cases where the third party
     does not provide config-file packages directly.  These files are a
     maintenance burden for CMake, so new Find modules are generally not
     added to CMake anymore.  Third-parties should provide config file
     packages instead of relying on a Find module to be provided by
     CMake.

Module-file packages may also provide Imported Targets.  A
complete example which finds such a package might look like:

     cmake_minimum_required(VERSION 3.10)
     project(MyExeProject VERSION 1.0.0)

     find_package(PNG REQUIRED)

     # Add path to a FindSomePackage.cmake file
     list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
     find_package(SomePackage REQUIRED)

     add_executable(MyExe main.cpp)
     target_link_libraries(MyExe PRIVATE
         PNG::PNG
         SomePrefix::LibName
     )

The <PackageName>_ROOT variable is also searched as a prefix
for find_package() calls using module-file packages such as
‘FindSomePackage’.

28 Importing and Exporting Guide
********************************

28.1 Introduction
=================

In this guide, we will present the concept of IMPORTED.
targets and demonstrate how to import existing executable or library
files from disk into a CMake project.  We will then show how CMake
supports exporting targets from one CMake-based project and importing
them into another.  Finally, we will demonstrate how to package a
project with a configuration file to allow for easy integration into
other CMake projects.  This guide and the complete example source code
can be found in the ‘Help/guide/importing-exporting’ directory of the
CMake source code tree.

28.2 Importing Targets
======================

IMPORTED targets are used to convert files outside of a
CMake project into logical targets inside of the project.
IMPORTED targets are created using the ‘IMPORTED’ option of the
add_executable() and add_library() commands.  No
build files are generated for IMPORTED targets.  Once
imported, see IMPORTED targets may be referenced like any other
target within the project and provide a convenient, flexible reference
to outside executables and libraries.

By default, the IMPORTED target name has scope in the
directory in which it is created and below.  We can use the ‘GLOBAL’
option to extended visibility so that the target is accessible globally
in the build system.

Details about the IMPORTED target are specified by setting
properties whose names begin in ‘IMPORTED_’ and ‘INTERFACE_’.  For
example, see IMPORTED_LOCATION contains the full path to the
target on disk.

28.2.1 Importing Executables
----------------------------

To start, we will walk through a simple example that creates an
IMPORTED executable target and then references it from the
add_custom_command() command.

We’ll need to do some setup to get started.  We want to create an
executable that when run creates a basic ‘main.cc’ file in the current
directory.  The details of this project are not important.  Navigate to
‘Help/guide/importing-exporting/MyExe’, create a build directory, run
cmake and build and install the project.

     $ cd Help/guide/importing-exporting/MyExe
     $ mkdir build
     $ cd build
     $ cmake ..
     $ cmake --build .
     $ cmake --install . --prefix <install location>
     $ <install location>/myexe
     $ ls
     [...] main.cc [...]

Now we can import this executable into another CMake project.  The
source code for this section is available in
‘Help/guide/importing-exporting/Importing’.  In the CMakeLists file, use
the add_executable() command to create a new target called
‘myexe’.  Use the ‘IMPORTED’ option to tell CMake that this target
references an executable file located outside of the project.  No rules
will be generated to build it and the IMPORTED target
property will be set to ‘true’.

     add_executable(myexe IMPORTED)

Next, set the IMPORTED_LOCATION property of the target using
the set_property() command.  This will tell CMake the
location of the target on disk.  The location may need to be adjusted to
the ‘<install location>’ specified in the previous step.

     set_property(TARGET myexe PROPERTY
                  IMPORTED_LOCATION "../InstallMyExe/bin/myexe")

We can now reference this IMPORTED target just like any
target built within the project.  In this instance, let’s imagine that
we want to use the generated source file in our project.  Use the
IMPORTED target in the add_custom_command() command:

     add_custom_command(OUTPUT main.cc COMMAND myexe)

As ‘COMMAND’ specifies an executable target name, it will automatically
be replaced by the location of the executable given by the
IMPORTED_LOCATION property above.

Finally, use the output from add_custom_command().:

     add_executable(mynewexe main.cc)

28.2.2 Importing Libraries
--------------------------

In a similar manner, libraries from other projects may be accessed
through IMPORTED targets.

Note: The full source code for the examples in this section is not
provided and is left as an exercise for the reader.

In the CMakeLists file, add an IMPORTED library and specify
its location on disk:

     add_library(foo STATIC IMPORTED)
     set_property(TARGET foo PROPERTY
                  IMPORTED_LOCATION "/path/to/libfoo.a")

Then use the IMPORTED library inside of our project:

     add_executable(myexe src1.c src2.c)
     target_link_libraries(myexe PRIVATE foo)

On Windows, a .dll and its .lib import library may be imported together:

     add_library(bar SHARED IMPORTED)
     set_property(TARGET bar PROPERTY
                  IMPORTED_LOCATION "c:/path/to/bar.dll")
     set_property(TARGET bar PROPERTY
                  IMPORTED_IMPLIB "c:/path/to/bar.lib")
     add_executable(myexe src1.c src2.c)
     target_link_libraries(myexe PRIVATE bar)

A library with multiple configurations may be imported with a single
target:

     find_library(math_REL NAMES m)
     find_library(math_DBG NAMES md)
     add_library(math STATIC IMPORTED GLOBAL)
     set_target_properties(math PROPERTIES
       IMPORTED_LOCATION "${math_REL}"
       IMPORTED_LOCATION_DEBUG "${math_DBG}"
       IMPORTED_CONFIGURATIONS "RELEASE;DEBUG"
     )
     add_executable(myexe src1.c src2.c)
     target_link_libraries(myexe PRIVATE math)

The generated build system will link ‘myexe’ to ‘m.lib’ when built in
the release configuration, and ‘md.lib’ when built in the debug
configuration.

28.3 Exporting Targets
======================

While IMPORTED targets on their own are useful, they still
require that the project that imports them knows the locations of the
target files on disk.  The real power of IMPORTED targets is
when the project providing the target files also provides a CMake file
to help import them.  A project can be setup to produce the necessary
information so that it can easily be used by other CMake projects be it
from a build directory, a local install or when packaged.

In the remaining sections, we will walk through a set of example
projects step-by-step.  The first project will create and install a
library and corresponding CMake configuration and package files.  The
second project will use the generated package.

Let’s start by looking at the ‘MathFunctions’ project in the
‘Help/guide/importing-exporting/MathFunctions’ directory.  Here we have
a header file ‘MathFunctions.h’ that declares a ‘sqrt’ function:

     #pragma once

     namespace MathFunctions {
     double sqrt(double x);
     }

And a corresponding source file ‘MathFunctions.cxx’:

     #include "MathFunctions.h"

     #include <cmath>

     namespace MathFunctions {
     double sqrt(double x)
     {
       return std::sqrt(x);
     }
     }

Don’t worry too much about the specifics of the C++ files, they are just
meant to be a simple example that will compile and run on many build
systems.

Now we can create a ‘CMakeLists.txt’ file for the ‘MathFunctions’
project.  Start by specifying the cmake_minimum_required().
version and project() name:

     cmake_minimum_required(VERSION 3.15)
     project(MathFunctions)

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

Create a library called ‘MathFunctions’ with the add_library()
command:

     add_library(MathFunctions STATIC MathFunctions.cxx)

And then use the target_include_directories() command to
specify the include directories for the target:

     target_include_directories(MathFunctions
                                PUBLIC
                                "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>"
                                "$<INSTALL_INTERFACE:include>"
     )

We need to tell CMake that we want to use different include directories
depending on if we’re building the library or using it from an installed
location.  If we don’t do this, when CMake creates the export
information it will export a path that is specific to the current build
directory and will not be valid for other projects.  We can use
generator expressions to specify that if we’re building the library
include the current source directory.  Otherwise, when installed,
include the ‘include’ directory.  See the Creating Relocatable Packages
section for more details.

The install(TARGETS) and install(EXPORT).
commands work together to install both targets (a library in our case)
and a CMake file designed to make it easy to import the targets into
another CMake project.

First, in the install(TARGETS) command we will specify the
target, the ‘EXPORT’ name and the destinations that tell CMake where to
install the targets.

     install(TARGETS MathFunctions
             EXPORT MathFunctionsTargets
             LIBRARY DESTINATION lib
             ARCHIVE DESTINATION lib
             RUNTIME DESTINATION bin
             INCLUDES DESTINATION include
     )

Here, the ‘EXPORT’ option tells CMake to create an export called
‘MathFunctionsTargets’.  The generated IMPORTED targets have
appropriate properties set to define their usage requirements,
such as INTERFACE_INCLUDE_DIRECTORIES,
INTERFACE_COMPILE_DEFINITIONS and other relevant built-in
‘INTERFACE_’ properties.  The ‘INTERFACE’ variant of user-defined
properties listed in COMPATIBLE_INTERFACE_STRING and other
Compatible Interface Properties are also propagated to the
generated IMPORTED targets.  For example, in this case, the
IMPORTED target will have its
INTERFACE_INCLUDE_DIRECTORIES property populated with the
directory specified by the ‘INCLUDES DESTINATION’ property.  As a
relative path was given, it is treated as relative to the
CMAKE_INSTALL_PREFIX.

Note, we have `not' asked CMake to install the export yet.

We don’t want to forget to install the ‘MathFunctions.h’ header file
with the install(FILES) command.  The header file should be
installed to the ‘include’ directory, as specified by the
target_include_directories() command above.

     install(FILES MathFunctions.h DESTINATION include)

Now that the ‘MathFunctions’ library and header file are installed, we
also need to explicitly install the ‘MathFunctionsTargets’ export
details.  Use the install(EXPORT) command to export the
targets in ‘MathFunctionsTargets’, as defined by the
install(TARGETS) command.

     install(EXPORT MathFunctionsTargets
             FILE MathFunctionsTargets.cmake
             NAMESPACE MathFunctions::
             DESTINATION lib/cmake
     )

This command generates the ‘MathFunctionsTargets.cmake’ file and
arranges to install it to ‘lib/cmake’.  The file contains code suitable
for use by downstreams to import all targets listed in the install
command from the installation tree.

The ‘NAMESPACE’ option will prepend ‘MathFunctions::’ to the target
names as they are written to the export file.  This convention of
double-colons gives CMake a hint that the name is an IMPORTED
target when it is used by downstream projects.  This way, CMake can
issue a diagnostic message if the package providing it was not found.

The generated export file contains code that creates an IMPORTED
library.

     # Create imported target MathFunctions::MathFunctions
     add_library(MathFunctions::MathFunctions STATIC IMPORTED)

     set_target_properties(MathFunctions::MathFunctions PROPERTIES
       INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include"
     )

This code is very similar to the example we created by hand in the
Importing Libraries section.  Note that ‘${_IMPORT_PREFIX}’ is
computed relative to the file location.

An outside project may load this file with the include().
command and reference the ‘MathFunctions’ library from the installation
tree as if it were built in its own tree.  For example:

      include(${INSTALL_PREFIX}/lib/cmake/MathFunctionTargets.cmake)
      add_executable(myexe src1.c src2.c )
      target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions)

Line 1 loads the target CMake file.  Although we only exported a single
target, this file may import any number of targets.  Their locations are
computed relative to the file location so that the install tree may be
easily moved.  Line 3 references the imported ‘MathFunctions’ library.
The resulting build system will link to the library from its installed
location.

Executables may also be exported and imported using the same process.

Any number of target installations may be associated with the same
export name.  Export names are considered global so any directory may
contribute a target installation.  The install(EXPORT).
command only needs to be called once to install a file that references
all targets.  Below is an example of how multiple exports may be
combined into a single export file, even if they are in different
subdirectories of the project.

     # A/CMakeLists.txt
     add_executable(myexe src1.c)
     install(TARGETS myexe DESTINATION lib/myproj
             EXPORT myproj-targets)

     # B/CMakeLists.txt
     add_library(foo STATIC foo1.c)
     install(TARGETS foo DESTINATION lib EXPORTS myproj-targets)

     # Top CMakeLists.txt
     add_subdirectory (A)
     add_subdirectory (B)
     install(EXPORT myproj-targets DESTINATION lib/myproj)

28.3.1 Creating Packages
------------------------

At this point, the ‘MathFunctions’ project is exporting the target
information required to be used by other projects.  We can make this
project even easier for other projects to use by generating a
configuration file so that the CMake find_package() command
can find our project.

To start, we will need to make a few additions to the ‘CMakeLists.txt’
file.  First, include the CMakePackageConfigHelpers module
to get access to some helper functions for creating config files.

     include(CMakePackageConfigHelpers)

Then we will create a package configuration file and a package version
file.

28.3.1.1 Creating a Package Configuration File
..............................................

Use the configure_package_config_file() command provided by
the CMakePackageConfigHelpers to generate the package
configuration file.  Note that this command should be used instead of
the plain configure_file() command.  It helps to ensure that
the resulting package is relocatable by avoiding hardcoded paths in the
installed configuration file.  The path given to ‘INSTALL_DESTINATION’
must be the destination where the ‘MathFunctionsConfig.cmake’ file will
be installed.  We will examine the contents of the package configuration
file in the next section.

     configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
       INSTALL_DESTINATION lib/cmake
     )

Install the generated configuration files with the INSTALL(files)
command.  Both ‘MathFunctionsConfigVersion.cmake’ and
‘MathFunctionsConfig.cmake’ are installed to the same location,
completing the package.

     install(FILES
               "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
               "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
             DESTINATION lib/cmake
     )

Now we need to create the package configuration file itself.  In this
case, the ‘Config.cmake.in’ file is very simple but sufficient to allow
downstreams to use the IMPORTED targets.

     @PACKAGE_INIT@

     include("${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake")

     check_required_components(MathFunctions)

The first line of the file contains only the string ‘@PACKAGE_INIT@’.
This expands when the file is configured and allows the use of
relocatable paths prefixed with ‘PACKAGE_’.  It also provides the
‘set_and_check()’ and ‘check_required_components()’ macros.

The ‘check_required_components’ helper macro ensures that all requested,
non-optional components have been found by checking the
‘<Package>_<Component>_FOUND’ variables for all required components.
This macro should be called at the end of the package configuration file
even if the package does not have any components.  This way, CMake can
make sure that the downstream project hasn’t specified any non-existent
components.  If ‘check_required_components’ fails, the ‘<Package>_FOUND’
variable is set to FALSE, and the package is considered to be not found.

The ‘set_and_check()’ macro should be used in configuration files
instead of the normal ‘set()’ command for setting directories and file
locations.  If a referenced file or directory does not exist, the macro
will fail.

If any macros should be provided by the ‘MathFunctions’ package, they
should be in a separate file which is installed to the same location as
the ‘MathFunctionsConfig.cmake’ file, and included from there.

`All required dependencies of a package must also be found in the
package configuration file.'  Let’s imagine that we require the ‘Stats’
library in our project.  In the CMakeLists file, we would add:

     find_package(Stats 2.6.4 REQUIRED)
     target_link_libraries(MathFunctions PUBLIC Stats::Types)

As the ‘Stats::Types’ target is a ‘PUBLIC’ dependency of
‘MathFunctions’, downstreams must also find the ‘Stats’ package and link
to the ‘Stats::Types’ library.  The ‘Stats’ package should be found in
the configuration file to ensure this.

     include(CMakeFindDependencyMacro)
     find_dependency(Stats 2.6.4)

The ‘find_dependency’ macro from the CMakeFindDependencyMacro
module helps by propagating whether the package is ‘REQUIRED’, or
‘QUIET’, etc.  The ‘find_dependency’ macro also sets
‘MathFunctions_FOUND’ to ‘False’ if the dependency is not found, along
with a diagnostic that the ‘MathFunctions’ package cannot be used
without the ‘Stats’ package.

`Exercise:' Add a required library to the ‘MathFunctions’ project.

28.3.1.2 Creating a Package Version File
........................................

The CMakePackageConfigHelpers module provides the
write_basic_package_version_file() command for creating a simple
package version file.  This file is read by CMake when
find_package() is called to determine the compatibility with the
requested version, and to set some version-specific variables such as
‘<PackageName>_VERSION’, ‘<PackageName>_VERSION_MAJOR’,
‘<PackageName>_VERSION_MINOR’, etc.  See cmake-packages.
documentation for more details.

     set(version 3.4.1)

     set_property(TARGET MathFunctions PROPERTY VERSION ${version})
     set_property(TARGET MathFunctions PROPERTY SOVERSION 3)
     set_property(TARGET MathFunctions PROPERTY
       INTERFACE_MathFunctions_MAJOR_VERSION 3)
     set_property(TARGET MathFunctions APPEND PROPERTY
       COMPATIBLE_INTERFACE_STRING MathFunctions_MAJOR_VERSION
     )

     # generate the version file for the config file
     write_basic_package_version_file(
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
       VERSION "${version}"
       COMPATIBILITY AnyNewerVersion
     )

In our example, ‘MathFunctions_MAJOR_VERSION’ is defined as a
COMPATIBLE_INTERFACE_STRING which means that it must be compatible
among the dependencies of any depender.  By setting this custom defined
user property in this version and in the next version of
‘MathFunctions’, see cmake will issue a diagnostic if there is an
attempt to use version 3 together with version 4.  Packages can choose
to employ such a pattern if different major versions of the package are
designed to be incompatible.

28.3.2 Exporting Targets from the Build Tree
--------------------------------------------

Typically, projects are built and installed before being used by an
outside project.  However, in some cases, it is desirable to export
targets directly from a build tree.  The targets may then be used by an
outside project that references the build tree with no installation
involved.  The export() command is used to generate a file
exporting targets from a project build tree.

If we want our example project to also be used from a build directory we
only have to add the following to ‘CMakeLists.txt’:

     export(EXPORT MathFunctionsTargets
            FILE "${CMAKE_CURRENT_BINARY_DIR}/cmake/MathFunctionsTargets.cmake"
            NAMESPACE MathFunctions::
     )

Here we use the export() command to generate the export
targets for the build tree.  In this case, we’ll create a file called
‘MathFunctionsTargets.cmake’ in the ‘cmake’ subdirectory of the build
directory.  The generated file contains the required code to import the
target and may be loaded by an outside project that is aware of the
project build tree.  This file is specific to the build-tree, and `is
not relocatable'.

It is possible to create a suitable package configuration file and
package version file to define a package for the build tree which may be
used without installation.  Consumers of the build tree can simply
ensure that the CMAKE_PREFIX_PATH contains the build
directory, or set the ‘MathFunctions_DIR’ to ‘<build_dir>/MathFunctions’
in the cache.

An example application of this feature is for building an executable on
a host platform when cross-compiling.  The project containing the
executable may be built on the host platform and then the project that
is being cross-compiled for another platform may load it.

28.3.3 Building and Installing a Package
----------------------------------------

At this point, we have generated a relocatable CMake configuration for
our project that can be used after the project has been installed.
Let’s try to build the ‘MathFunctions’ project:

     mkdir MathFunctions_build
     cd MathFunctions_build
     cmake ../MathFunctions
     cmake --build .

In the build directory, notice that the file
‘MathFunctionsTargets.cmake’ has been created in the ‘cmake’
subdirectory.

Now install the project:

     $ cmake --install . --prefix "/home/myuser/installdir"

28.4 Creating Relocatable Packages
==================================

Packages created by install(EXPORT) are designed to be
relocatable, using paths relative to the location of the package itself.
They must not reference absolute paths of files on the machine where the
package is built that will not exist on the machines where the package
may be installed.

When defining the interface of a target for ‘EXPORT’, keep in mind that
the include directories should be specified as relative paths to the
CMAKE_INSTALL_PREFIX but should not explicitly include the
CMAKE_INSTALL_PREFIX.:

     target_include_directories(tgt INTERFACE
       # Wrong, not relocatable:
       $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
     )

     target_include_directories(tgt INTERFACE
       # Ok, relocatable:
       $<INSTALL_INTERFACE:include/TgtName>
     )

The ‘$<INSTALL_PREFIX>’ generator expression may be used as a
placeholder for the install prefix without resulting in a
non-relocatable package.  This is necessary if complex generator
expressions are used:

     target_include_directories(tgt INTERFACE
       # Ok, relocatable:
       $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include/TgtName>
     )

This also applies to paths referencing external dependencies.  It is not
advisable to populate any properties which may contain paths, such as
INTERFACE_INCLUDE_DIRECTORIES or
INTERFACE_LINK_LIBRARIES, with paths relevant to dependencies.  For
example, this code may not work well for a relocatable package:

     target_link_libraries(MathFunctions INTERFACE
       ${Foo_LIBRARIES} ${Bar_LIBRARIES}
       )
     target_include_directories(MathFunctions INTERFACE
       "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
       )

The referenced variables may contain the absolute paths to libraries and
include directories `as found on the machine the package was made on'.
This would create a package with hard-coded paths to dependencies not
suitable for relocation.

Ideally such dependencies should be used through their own
IMPORTED targets that have their own IMPORTED_LOCATION.
and usage requirement properties such as
INTERFACE_INCLUDE_DIRECTORIES populated appropriately.  Those
imported targets may then be used with the
target_link_libraries() command for ‘MathFunctions’:

     target_link_libraries(MathFunctions INTERFACE Foo::Foo Bar::Bar)

With this approach the package references its external dependencies only
through the names of IMPORTED targets.  When a consumer uses
the installed package, the consumer will run the appropriate
find_package() commands (via the ‘find_dependency’ macro described
above) to find the dependencies and populate the imported targets with
appropriate paths on their own machine.

28.5 Using the Package Configuration File
=========================================

Now we’re ready to create a project to use the installed ‘MathFunctions’
library.  In this section we will be using source code from
‘Help\guide\importing-exporting\Downstream’.  In this directory, there
is a source file called ‘main.cc’ that uses the ‘MathFunctions’ library
to calculate the square root of a given number and then prints the
results:

     // A simple program that outputs the square root of a number
     #include <iostream>
     #include <string>

     #include "MathFunctions.h"

     int main(int argc, char* argv[])
     {
       if (argc < 2) {
         std::cout << "Usage: " << argv[0] << " number" << std::endl;
         return 1;
       }

       // convert input to double
       const double inputValue = std::stod(argv[1]);

       // calculate square root
       const double sqrt = MathFunctions::sqrt(inputValue);
       std::cout << "The square root of " << inputValue << " is " << sqrt
                 << std::endl;

       return 0;
     }

As before, we’ll start with the cmake_minimum_required() and
project() commands in the ‘CMakeLists.txt’ file.  For this
project, we’ll also specify the C++ standard.

     cmake_minimum_required(VERSION 3.15)
     project(Downstream)

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

We can use the find_package() command:

     find_package(MathFunctions 3.4.1 EXACT)

Create an exectuable:

     add_executable(myexe main.cc)

And link to the ‘MathFunctions’ library:

     target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions)

That’s it!  Now let’s try to build the ‘Downstream’ project.

     mkdir Downstream_build
     cd Downstream_build
     cmake ../Downstream
     cmake --build .

A warning may have appeared during CMake configuration:

     CMake Warning at CMakeLists.txt:4 (find_package):
       By not providing "FindMathFunctions.cmake" in CMAKE_MODULE_PATH this
       project has asked CMake to find a package configuration file provided by
       "MathFunctions", but CMake did not find one.

       Could not find a package configuration file provided by "MathFunctions"
       with any of the following names:

         MathFunctionsConfig.cmake
         mathfunctions-config.cmake

       Add the installation prefix of "MathFunctions" to CMAKE_PREFIX_PATH or set
       "MathFunctions_DIR" to a directory containing one of the above files.  If
       "MathFunctions" provides a separate development package or SDK, be sure it
       has been installed.

Set the ‘CMAKE_PREFIX_PATH’ to where MathFunctions was installed
previously and try again.  Ensure that the newly created executable runs
as expected.

28.6 Adding Components
======================

Let’s edit the ‘MathFunctions’ project to use components.  The source
code for this section can be found in
‘Help\guide\importing-exporting\MathFunctionsComponents’.  The
CMakeLists file for this project adds two subdirectories: ‘Addition’ and
‘SquareRoot’.

     cmake_minimum_required(VERSION 3.15)
     project(MathFunctionsComponents)

     # specify the C++ standard
     set(CMAKE_CXX_STANDARD 11)
     set(CMAKE_CXX_STANDARD_REQUIRED True)

     add_subdirectory(Addition)
     add_subdirectory(SquareRoot)

Generate and install the package configuration and package version
files:

     include(CMakePackageConfigHelpers)

     # set version
     set(version 3.4.1)

     # generate the version file for the config file
     write_basic_package_version_file(
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
       VERSION "${version}"
       COMPATIBILITY AnyNewerVersion
     )

     # create config file
     configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
       "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
       INSTALL_DESTINATION lib/cmake
       NO_CHECK_REQUIRED_COMPONENTS_MACRO
     )

     # install config files
     install(FILES
               "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
               "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
             DESTINATION lib/cmake
     )

If ‘COMPONENTS’ are specified when the downstream uses
find_package(), they are listed in the
‘<PackageName>_FIND_COMPONENTS’ variable.  We can use this variable to
verify that all necessary component targets are included in
‘Config.cmake.in’.  At the same time, this function will act as a custom
‘check_required_components’ macro to ensure that the downstream only
attempts to use supported components.

     @PACKAGE_INIT@

     set(_supported_components Addition SquareRoot)

     foreach(_comp ${MathFunctions_FIND_COMPONENTS})
       if (NOT _comp IN_LIST _supported_components)
         set(MathFunctions_FOUND False)
         set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
       endif()
       include("${CMAKE_CURRENT_LIST_DIR}/MathFunctions${_comp}Targets.cmake")
     endforeach()

Here, the ‘MathFunctions_NOT_FOUND_MESSAGE’ is set to a diagnosis that
the package could not be found because an invalid component was
specified.  This message variable can be set for any case where the
‘_FOUND’ variable is set to ‘False’, and will be displayed to the user.

The ‘Addition’ and ‘SquareRoot’ directories are similar.  Let’s look at
one of the CMakeLists files:

     # create library
     add_library(SquareRoot STATIC SquareRoot.cxx)

     add_library(MathFunctions::SquareRoot ALIAS SquareRoot)

     # add include directories
     target_include_directories(SquareRoot
                                PUBLIC
                                "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>"
                                "$<INSTALL_INTERFACE:include>"
     )

     # install the target and create export-set
     install(TARGETS SquareRoot
             EXPORT SquareRootTargets
             LIBRARY DESTINATION lib
             ARCHIVE DESTINATION lib
             RUNTIME DESTINATION bin
             INCLUDES DESTINATION include
     )

     # install header file
     install(FILES SquareRoot.h DESTINATION include)

     # generate and install export file
     install(EXPORT SquareRootTargets
             FILE MathFunctionsSquareRootTargets.cmake
             NAMESPACE MathFunctions::
             DESTINATION lib/cmake
     )

Now we can build the project as described in earlier sections.  To test
using this package, we can use the project in
‘Help\guide\importing-exporting\DownstreamComponents’.  There’s two
differences from the previous ‘Downstream’ project.  First, we need to
find the package components.  Change the ‘find_package’ line from:

     find_package(MathFunctions 3.4.1 EXACT)

To:

     find_package(MathFunctions 3.4 COMPONENTS Addition SquareRoot)

and the ‘target_link_libraries’ line from:

     target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions)

To:

     target_link_libraries(myexe PRIVATE MathFunctions::Addition MathFunctions::SquareRoot)

In ‘main.cc’, replace ‘#include MathFunctions.h’ with:

     #include "Addition.h"
     #include "SquareRoot.h"

Finally, use the ‘Addition’ library:

       const double sum = MathFunctions::add(inputValue, inputValue);
       std::cout << inputValue << " + " << inputValue << " = " << sum << std::endl;

Build the ‘Downstream’ project and confirm that it can find and use the
package components.

29 IDE Integration Guide
************************

29.1 Introduction
=================

Integrated development environments (IDEs) may want to integrate with
CMake to improve the development experience for CMake users.  This
document lays out the recommended best practices for such integration.

29.2 Bundling
=============

Many IDE vendors will want to bundle a copy of CMake with their IDE.
IDEs that bundle CMake should present the user with the option of using
an external CMake installation instead of the bundled one, in case the
bundled copy becomes outdated and the user wants to use a newer version.

While IDE vendors may be tempted to bundle different versions of CMake
with their application, such practice is not recommended.  CMake has
strong guarantees of backwards compatibility, and there is no reason not
to use a newer version of CMake than what a project requires, or indeed,
the very latest version.  Therefore, it is recommended that IDE vendors
that bundle CMake with their application always include the very latest
patch version of CMake available at the time of release.

As a suggestion, IDEs may also ship a copy of the Ninja buildsystem
alongside CMake.  Ninja is highly performant and well-supported on all
platforms that support CMake.  IDEs that bundle Ninja should use Ninja
1.10 or later, which contains features needed to support Fortran builds.

29.3 Presets
============

CMake supports a file format called ‘CMakePresets.json’, and its
user-specific counterpart, ‘CMakeUserPresets.json’.  This file contains
information on the various configure presets that a user may want.  Each
preset may have a different compiler, build flags, etc.  The details of
this format are explained in the cmake(1) manual.

IDE vendors are encouraged to read and evaluate this file the same way
CMake does, and present the user with the presets listed in the file.
Users should be able to see (and possibly edit) the CMake cache
variables, environment variables, and command line options that are
defined for a given preset.  The IDE should then construct the list of
appropriate cmake(1) command line arguments based on these
settings, rather than using the ‘--preset=’ option directly.  The
‘--preset=’ option is intended only as a convenient frontend for command
line users, and should not be used by the IDE.

For example, if a preset named ‘ninja’ specifies ‘Ninja’ as the
generator and ‘${sourceDir}/build’ as the build directory, instead of
running:

     cmake -S /path/to/source --preset=ninja

the IDE should instead calculate the settings of the ‘ninja’ preset, and
then run:

     cmake -S /path/to/source -B /path/to/source/build -G Ninja

While reading, parsing, and evaluating the contents of
‘CMakePresets.json’ is straightforward, it is not trivial.  In addition
to the documentation, IDE vendors may also wish to refer to the CMake
source code and test cases for a better understanding of how to
implement the format.  ‘This file’ provides a machine-readable JSON
schema for the ‘CMakePresets.json’ format that IDE vendors may find
useful for validation and providing editing assistance.

29.4 Configuring
================

IDEs that invoke cmake(1) to run the configure step may wish
to receive information about the artifacts that the build will produce,
as well as the include directories, compile definitions, etc.  used to
build the artifacts.  Such information can be obtained by using the
File API.  The manual page for the File API contains more
information about the API and how to invoke it.  See Server mode.
is deprecated and should not be used on CMake 3.14 or later.

IDEs should avoid creating more build trees than necessary, and only
create multiple build trees if the user wishes to switch to a different
compiler, use different compile flags, etc.  In particular, IDEs should
NOT create multiple single-config build trees which all have the same
properties except for a differing CMAKE_BUILD_TYPE,
effectively creating a multi-config environment.  Instead, the
Ninja Multi-Config generator, in conjunction with the File API
to get the list of build configurations, should be used for
this purpose.

IDEs should not use the “extra generators” with Makefile or Ninja
generators, which generate IDE project files in addition to the Makefile
or Ninja files.  Instead the File API should be used to get
the list of build artifacts.

29.5 Building
=============

If a Makefile or Ninja generator is used to generate the build tree, it
is not recommended to invoke ‘make’ or ‘ninja’ directly.  Instead, it is
recommended that the IDE invoke cmake(1) with the ‘--build’
argument, which will in turn invoke the appropriate build tool.

If an IDE project generator is used, such as Xcode or one of
the Visual Studio generators, and the IDE understands the project format
used, the IDE should read the project file and build it the same way it
would otherwise.

The File API can be used to obtain a list of build
configurations from the build tree, and the IDE should present this list
to the user to select a build configuration.

29.6 Testing
============

ctest(1) supports outputting a JSON format with information
about the available tests and test configurations.  IDEs which want to
run CTest should obtain this information and use it to present the user
with a list of tests.

IDEs should not invoke the ‘test’ target of the generated buildsystem.
Instead, they should invoke ctest(1) directly.