Файловый менеджер - Редактировать - /var/www/html/manual.zip
Ðазад
PK ! ����� � cmake-gui.1.rstnu �[��� .. cmake-manual-description: CMake GUI Command-Line Reference cmake-gui(1) ************ Synopsis ======== .. parsed-literal:: 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 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. 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 :manual:`presets <cmake-presets(7)>` files, if it has them. ``--browse-manual`` Open the CMake reference manual in a browser and immediately exit. .. include:: OPTIONS_HELP.txt See Also ======== .. include:: LINKS.txt PK ! ���I I cmake-generators.7.rstnu �[��� .. cmake-manual-description: CMake Generators Reference cmake-generators(7) ******************* .. only:: html .. contents:: 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 :manual:`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 :manual:`cmake-gui(1)` offers interactive selection of a generator when creating a new build tree. CMake Generators ================ .. _`Command-Line Build Tool Generators`: 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. .. _`Makefile Generators`: Makefile Generators ^^^^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Borland Makefiles /generator/MSYS Makefiles /generator/MinGW Makefiles /generator/NMake Makefiles /generator/NMake Makefiles JOM /generator/Unix Makefiles /generator/Watcom WMake .. _`Ninja Generators`: Ninja Generators ^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Ninja /generator/Ninja Multi-Config .. _`IDE Build Tool Generators`: 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. .. _`Visual Studio Generators`: Visual Studio Generators ^^^^^^^^^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Visual Studio 6 /generator/Visual Studio 7 /generator/Visual Studio 7 .NET 2003 /generator/Visual Studio 8 2005 /generator/Visual Studio 9 2008 /generator/Visual Studio 10 2010 /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 /generator/Visual Studio 16 2019 /generator/Visual Studio 17 2022 Other Generators ^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Green Hills MULTI /generator/Xcode Extra Generators ================ Some of the `CMake Generators`_ listed in the :manual:`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. .. toctree:: :maxdepth: 1 /generator/CodeBlocks /generator/CodeLite /generator/Eclipse CDT4 /generator/Kate /generator/Sublime Text 2 PK ! ��R� R� ctest.1.rstnu �[��� .. cmake-manual-description: CTest Command-Line Reference ctest(1) ******** .. contents:: Synopsis ======== .. parsed-literal:: 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>...] Description =========== The **ctest** executable is the CMake test driver program. CMake-generated build trees created for projects that use the :command:`enable_testing` and :command:`add_test` commands have testing support. This program will run the tests and report results. .. _`CTest Options`: Options ======= ``--preset <preset>``, ``--preset=<preset>`` Use a test preset to specify test options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. ``--list-presets`` Lists the available test presets. The current working directory must contain CMake preset files. ``-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 :envvar:`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 :envvar:`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 :envvar:`CTEST_PARALLEL_LEVEL` environment variable. This option can be used with the :prop_test:`PROCESSORS` test property. See `Label and Subproject Summary`_. ``--resource-spec-file <file>`` Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, using the :ref:`resource specification file <ctest-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. ``--output-junit <file>`` Write test results in JUnit format. This option tells CTest to write test results to ``<file>`` in JUnit XML format. If ``<file>`` already exists, it will be overwritten. If using the ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. ``-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 as described under :ref:`string(REGEX) <Regex Specification>`. This option tells CTest to run only the tests whose labels match the given regular expression. When more than one ``-L`` option is given, a test will only be run if each regular expression matches at least one of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` relationship). See `Label Matching`_. ``-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. When more than one ``-LE`` option is given, a test will only be excluded if each regular expression matches at least one of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` relationship). See `Label Matching`_. ``-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. In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default is non-interactive. In non-interactive mode, the environment variable :envvar:`DASHBOARD_TEST_FROM_CTEST` is set. Prior to CMake 3.11, interactive mode on Windows allowed system debug popup windows to appear. Now, due to CTest's use of ``libuv`` to launch test processes, all system debug popup windows are always blocked. ``--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-dir <dir>`` Specify the directory in which to look for tests. ``--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 :prop_test:`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. .. include:: OPTIONS_HELP.txt .. _`Label Matching`: Label Matching ============== Tests may have labels attached to them. Tests may be included or excluded from a test run by filtering on the labels. Each individual filter is a regular expression applied to the labels attached to a test. When ``-L`` is used, in order for a test to be included in a test run, each regular expression must match at least one label. Using more than one ``-L`` option means "match **all** of these". The ``-LE`` option works just like ``-L``, but excludes tests rather than including them. A test is excluded if each regular expression matches at least one label. If a test has no labels attached to it, then ``-L`` will never include that test, and ``-LE`` will never exclude that test. As an example of tests with labels, consider five tests, with the following labels: * *test1* has labels *tuesday* and *production* * *test2* has labels *tuesday* and *test* * *test3* has labels *wednesday* and *production* * *test4* has label *wednesday* * *test5* has labels *friday* and *test* Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has both labels. Running CTest with ``-L test`` will select *test2* and *test5*, because both of them have a label that matches that regular expression. Because the matching works with regular expressions, take note that running CTest with ``-L es`` will match all five tests. To select the *tuesday* and *wednesday* tests together, use a single regular expression that matches either of them, like ``-L "tue|wed"``. .. _`Label and Subproject Summary`: 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. .. versionadded:: 3.22 Labels added dynamically during test execution are also reported in the timing summary. See :ref:`Additional Labels`. When the :prop_test:`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 :prop_test:`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``). .. _`Build and Test Mode`: 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 :manual:`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 .. _`Dashboard Client`: Dashboard Client ================ CTest can operate as a client for the `CDash`_ 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`_ server. The command-line signature used to submit to `CDash`_ 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. 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. 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. 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 :module:`CTest` module if included by the project. The module uses variables to obtain a value for each setting as documented with the settings below. .. _`CTest Script`: Dashboard Client via CTest Script --------------------------------- CTest can perform testing driven by a :manual:`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 :ref:`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. Dashboard Client Configuration ============================== The `Dashboard Client Steps`_ may be configured by named settings as documented in the following sections. .. _`CTest Start Step`: CTest Start Step ---------------- Start a new dashboard submission to be composed of results recorded by the following steps. In a `CTest Script`_, the :command:`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: :variable:`CTEST_BINARY_DIRECTORY` * :module:`CTest` module variable: :variable:`PROJECT_BINARY_DIR` ``SourceDirectory`` The full path to the project source tree. * `CTest Script`_ variable: :variable:`CTEST_SOURCE_DIRECTORY` * :module:`CTest` module variable: :variable:`PROJECT_SOURCE_DIR` .. _`CTest Update Step`: CTest Update Step ----------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_BZR_COMMAND` * :module:`CTest` module variable: none ``BZRUpdateOptions`` Command-line options to the ``BZRCommand`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_BZR_UPDATE_OPTIONS` * :module:`CTest` module variable: none ``CVSCommand`` ``cvs`` command-line tool to use if source tree is managed by CVS. * `CTest Script`_ variable: :variable:`CTEST_CVS_COMMAND` * :module:`CTest` module variable: ``CVSCOMMAND`` ``CVSUpdateOptions`` Command-line options to the ``CVSCommand`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_CVS_UPDATE_OPTIONS` * :module:`CTest` module variable: ``CVS_UPDATE_OPTIONS`` ``GITCommand`` ``git`` command-line tool to use if source tree is managed by Git. * `CTest Script`_ variable: :variable:`CTEST_GIT_COMMAND` * :module:`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: :variable:`CTEST_GIT_INIT_SUBMODULES` * :module:`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: :variable:`CTEST_GIT_UPDATE_CUSTOM` * :module:`CTest` module variable: ``CTEST_GIT_UPDATE_CUSTOM`` ``GITUpdateOptions`` Command-line options to the ``GITCommand`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_OPTIONS` * :module:`CTest` module variable: ``GIT_UPDATE_OPTIONS`` ``HGCommand`` ``hg`` command-line tool to use if source tree is managed by Mercurial. * `CTest Script`_ variable: :variable:`CTEST_HG_COMMAND` * :module:`CTest` module variable: none ``HGUpdateOptions`` Command-line options to the ``HGCommand`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_HG_UPDATE_OPTIONS` * :module:`CTest` module variable: none ``P4Client`` Value of the ``-c`` option to the ``P4Command``. * `CTest Script`_ variable: :variable:`CTEST_P4_CLIENT` * :module:`CTest` module variable: ``CTEST_P4_CLIENT`` ``P4Command`` ``p4`` command-line tool to use if source tree is managed by Perforce. * `CTest Script`_ variable: :variable:`CTEST_P4_COMMAND` * :module:`CTest` module variable: ``P4COMMAND`` ``P4Options`` Command-line options to the ``P4Command`` for all invocations. * `CTest Script`_ variable: :variable:`CTEST_P4_OPTIONS` * :module:`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 * :module:`CTest` module variable: ``CTEST_P4_UPDATE_CUSTOM`` ``P4UpdateOptions`` Command-line options to the ``P4Command`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_P4_UPDATE_OPTIONS` * :module:`CTest` module variable: ``CTEST_P4_UPDATE_OPTIONS`` ``SVNCommand`` ``svn`` command-line tool to use if source tree is managed by Subversion. * `CTest Script`_ variable: :variable:`CTEST_SVN_COMMAND` * :module:`CTest` module variable: ``SVNCOMMAND`` ``SVNOptions`` Command-line options to the ``SVNCommand`` for all invocations. * `CTest Script`_ variable: :variable:`CTEST_SVN_OPTIONS` * :module:`CTest` module variable: ``CTEST_SVN_OPTIONS`` ``SVNUpdateOptions`` Command-line options to the ``SVNCommand`` when updating the source. * `CTest Script`_ variable: :variable:`CTEST_SVN_UPDATE_OPTIONS` * :module:`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: :variable:`CTEST_UPDATE_COMMAND` * :module:`CTest` module variable: ``<VCS>COMMAND`` when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_COMMAND`` ``UpdateOptions`` Command-line options to the ``UpdateCommand``. * `CTest Script`_ variable: :variable:`CTEST_UPDATE_OPTIONS` * :module:`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 * :module:`CTest` module variable: ``UPDATE_TYPE`` if set, else ``CTEST_UPDATE_TYPE`` .. _`UpdateVersionOnly`: ``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: :variable:`CTEST_UPDATE_VERSION_ONLY` .. _`UpdateVersionOverride`: ``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: :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: :variable:`CTEST_NIGHTLY_START_TIME` * :module:`CTest` module variable: ``NIGHTLY_START_TIME`` if set, else ``CTEST_NIGHTLY_START_TIME`` .. _`CTest Configure Step`: CTest Configure Step -------------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_CONFIGURE_COMMAND` * :module:`CTest` module variable: :variable:`CMAKE_COMMAND` followed by :variable:`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: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` See `Label and Subproject Summary`_. .. _`CTest Build Step`: CTest Build Step ---------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_CONFIGURATION_TYPE` * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, initialized by the :envvar:`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: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`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: :variable:`CTEST_BUILD_COMMAND` * :module:`CTest` module variable: ``MAKECOMMAND``, initialized by the :command:`build_command` command ``UseLaunchers`` For build trees generated by CMake using one of the :ref:`Makefile Generators` or the :generator:`Ninja` generator, specify whether the ``CTEST_USE_LAUNCHERS`` feature is enabled by the :module:`CTestUseLaunchers` module (also included by the :module:`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: :variable:`CTEST_USE_LAUNCHERS` * :module:`CTest` module variable: ``CTEST_USE_LAUNCHERS`` .. _`CTest Test Step`: CTest Test Step --------------- In a `CTest Script`_, the :command:`ctest_test` command runs this step. Arguments to the command may specify some of the step settings. Configuration settings include: ``ResourceSpecFile`` Specify a :ref:`resource specification file <ctest-resource-specification-file>`. * `CTest Script`_ variable: :variable:`CTEST_RESOURCE_SPEC_FILE` * :module:`CTest` module variable: ``CTEST_RESOURCE_SPEC_FILE`` See :ref:`ctest-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: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`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: :variable:`CTEST_TEST_LOAD` * :module:`CTest` module variable: ``CTEST_TEST_LOAD`` ``TimeOut`` The default timeout for each test if not specified by the :prop_test:`TIMEOUT` test property. * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` To report extra test values to CDash, see :ref:`Additional Test Measurements`. .. _`CTest Coverage Step`: CTest Coverage Step ------------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_COVERAGE_COMMAND` * :module:`CTest` module variable: ``COVERAGE_COMMAND`` ``CoverageExtraFlags`` Specify command-line options to the ``CoverageCommand`` tool. * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_EXTRA_FLAGS` * :module:`CTest` module variable: ``COVERAGE_EXTRA_FLAGS`` These options are the first arguments passed to ``CoverageCommand``. .. _`CTest MemCheck Step`: CTest MemCheck Step ------------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_MEMORYCHECK_COMMAND` * :module:`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: :variable:`CTEST_MEMORYCHECK_COMMAND_OPTIONS` * :module:`CTest` module variable: ``MEMORYCHECK_COMMAND_OPTIONS`` ``MemoryCheckType`` Specify the type of memory checking to perform. * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_TYPE` * :module:`CTest` module variable: ``MEMORYCHECK_TYPE`` ``MemoryCheckSanitizerOptions`` Specify options to sanitizers when running with a sanitize-enabled build. * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` * :module:`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: :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` * :module:`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 * :module:`CTest` module variable: none ``PurifyCommand`` Specify a ``MemoryCheckCommand`` that is known to be command-line compatible with Purify. * `CTest Script`_ variable: none * :module:`CTest` module variable: ``PURIFYCOMMAND`` ``ValgrindCommand`` Specify a ``MemoryCheckCommand`` that is known to be command-line compatible with Valgrind. * `CTest Script`_ variable: none * :module:`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 * :module:`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 * :module:`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 * :module:`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 * :module:`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 * :module:`CTest` module variable: ``CUDA_SANITIZER_COMMAND_OPTIONS`` .. _`CTest Submit Step`: CTest Submit Step ----------------- In a `CTest Script`_, the :command:`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: :variable:`CTEST_BUILD_NAME` * :module:`CTest` module variable: ``BUILDNAME`` ``CDashVersion`` Legacy option. Not used. * `CTest Script`_ variable: none, detected from server * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` ``CTestSubmitRetryCount`` Specify a number of attempts to retry submission on network failure. * `CTest Script`_ variable: none, use the :command:`ctest_submit` ``RETRY_COUNT`` option. * :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_COUNT`` ``CTestSubmitRetryDelay`` Specify a delay before retrying submission on network failure. * `CTest Script`_ variable: none, use the :command:`ctest_submit` ``RETRY_DELAY`` option. * :module:`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: :variable:`CTEST_CURL_OPTIONS` * :module:`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: :variable:`CTEST_DROP_LOCATION` * :module:`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: :variable:`CTEST_DROP_METHOD` * :module:`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: :variable:`CTEST_DROP_SITE` * :module:`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: :variable:`CTEST_DROP_SITE_PASSWORD` * :module:`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: :variable:`CTEST_DROP_SITE_USER` * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, else ``CTEST_DROP_SITE_USER`` ``IsCDash`` Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` ``ScpCommand`` Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` * :module:`CTest` module variable: ``SCPCOMMAND`` ``Site`` Describe the dashboard client host site with a short string. (Hostname, domain, etc.) * `CTest Script`_ variable: :variable:`CTEST_SITE` * :module:`CTest` module variable: ``SITE``, initialized by the :command:`site_name` command ``SubmitURL`` The ``http`` or ``https`` URL of the dashboard server to send the submission to. * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_URL` * :module:`CTest` module variable: ``SUBMIT_URL`` if set, else ``CTEST_SUBMIT_URL`` ``TriggerSite`` Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, else ``CTEST_TRIGGER_SITE`` .. _`Show as JSON Object Model`: 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. .. _`ctest-resource-allocation`: 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 :ref:`resource specification file <ctest-resource-specification-file>`, described below, which describes the resources available on the system. * The :prop_test:`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 :ref:`environment variables <ctest-resource-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 :ref:`environment variables <ctest-resource-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 :ref:`environment variables <ctest-resource-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 :command:`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 :prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` properties to indicate a skipped test. .. _`ctest-resource-specification-file`: Resource Specification File --------------------------- The resource specification file is a JSON file which is passed to CTest, either on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the ``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. If a dashboard script is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead. If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, the value of :variable:`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: .. code-block:: json { "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. ``RESOURCE_GROUPS`` Property ---------------------------- See :prop_test:`RESOURCE_GROUPS` for a description of this property. .. _`ctest-resource-environment-variables`: 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 :prop_test:`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 :prop_test:`RESOURCE_GROUPS` property. For example: * ``CTEST_RESOURCE_GROUP_COUNT=3`` This variable will only be defined if :manual:`ctest(1)` has been given a ``--resource-spec-file``, or if :command:`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 :ref:`resource specification file <ctest-resource-specification-file>` and in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment variable. See Also ======== .. include:: LINKS.txt _`CDash`: https://cdash.org PK ! �_�e e cmake-toolchains.7.rstnu �[��� .. cmake-manual-description: CMake Toolchains Reference cmake-toolchains(7) ******************* .. only:: html .. contents:: 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. Languages ========= Languages are enabled by the :command:`project` command. Language-specific built-in variables, such as :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`, :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` etc are set by invoking the :command:`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``: .. code-block:: cmake project(C_Only C) A special value of ``NONE`` can also be used with the :command:`project` command to enable no languages: .. code-block:: cmake project(MyProject NONE) The :command:`enable_language` command can be used to enable languages after the :command:`project` command: .. code-block:: cmake 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 :prop_gbl:`ENABLED_LANGUAGES` global property contains the languages which are currently enabled. Variables and Properties ======================== Several variables relate to the language components of a toolchain which are enabled. :variable:`CMAKE_<LANG>_COMPILER` is the full path to the compiler used for ``<LANG>``. :variable:`CMAKE_<LANG>_COMPILER_ID` is the identifier used by CMake for the compiler and :variable:`CMAKE_<LANG>_COMPILER_VERSION` is the version of the compiler. The :variable:`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 :prop_sf:`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 :prop_tgt:`LINKER_LANGUAGE` target property. Toolchain Features ================== CMake provides the :command:`try_compile` command and wrapper macros such as :module:`CheckCXXSourceCompiles`, :module:`CheckCXXSymbolExists` and :module:`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, :prop_tgt:`POSITION_INDEPENDENT_CODE` allows specifying that a target should be built as position-independent code, if the compiler supports that feature. The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties add flags for hidden visibility, if supported by the compiler. .. _`Cross Compiling Toolchain`: Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter ``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. Note that using the :variable:`CMAKE_SOURCE_DIR` or :variable:`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 :command:`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 :variable:`CMAKE_CURRENT_LIST_DIR`, since it always has an unambiguous, predictable value. Cross Compiling for Linux ------------------------- A typical cross-compiling toolchain for Linux has content such as: .. code-block:: cmake 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 :variable:`CMAKE_SYSTEM_NAME` is the CMake-identifier of the target platform to build for. The :variable:`CMAKE_SYSTEM_PROCESSOR` is the CMake-identifier of the target architecture to build for. The :variable:`CMAKE_SYSROOT` is optional, and may be specified if a sysroot is available. The :variable:`CMAKE_STAGING_PREFIX` is also optional. It may be used to specify a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always the runtime installation location, even when cross-compiling. The :variable:`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 :variable:`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 :variable:`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. .. _`Cray Cross-Compile`: 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 :variable:`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 :variable:`CMAKE_SYSTEM_NAME` as mentioned above. Cross Compiling using Clang --------------------------- Some compilers such as Clang are inherently cross compilers. The :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a value to those supported compilers when compiling: .. code-block:: cmake 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 :variable:`CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN` variable can be set in a toolchain file to pass the path to the compiler driver. Cross Compiling for QNX ----------------------- As the Clang compiler the QNX QCC compile is inherently a cross compiler. And the :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a value to those supported compilers when compiling: .. code-block:: cmake 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}) 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: .. code-block:: cmake 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 :variable:`CMAKE_GENERATOR_PLATFORM` tells the generator which SDK to use. Further :variable:`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 :variable:`CMAKE_GENERATOR_TOOLSET` to the correct value. 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: .. code-block:: cmake 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 :variable:`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. Cross Compiling for Windows Phone --------------------------------- A toolchain file to configure a Visual Studio generator for Windows Phone may look like this: .. code-block:: cmake set(CMAKE_SYSTEM_NAME WindowsPhone) set(CMAKE_SYSTEM_VERSION 8.1) Cross Compiling for Windows Store --------------------------------- A toolchain file to configure a Visual Studio generator for Windows Store may look like this: .. code-block:: cmake set(CMAKE_SYSTEM_NAME WindowsStore) set(CMAKE_SYSTEM_VERSION 8.1) .. _`Cross Compiling for Android`: Cross Compiling for Android --------------------------- A toolchain file may configure cross-compiling for Android by setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android``. Further configuration is specific to the Android development environment to be used. For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition>` or the :ref:`Visual Studio tools for Android <Cross Compiling for Android with the NDK>` to be installed. See those sections for further configuration details. For :ref:`Makefile Generators` and the :generator:`Ninja` generator, CMake expects one of these environments: * :ref:`NDK <Cross Compiling for Android with the NDK>` * :ref:`Standalone Toolchain <Cross Compiling for Android with a Standalone Toolchain>` CMake uses the following steps to select one of the environments: * If the :variable:`CMAKE_ANDROID_NDK` variable is set, the NDK at the specified location will be used. * Else, if the :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` variable is set, the Standalone Toolchain at the specified location will be used. * Else, if the :variable:`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 :variable:`CMAKE_ANDROID_NDK` and the NDK will be used. * Else, if the :variable:`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 :variable:`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 :variable:`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 :variable:`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 :variable:`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 :variable:`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. .. versionadded:: 3.20 If an Android NDK is selected, its version number is reported in the :variable:`CMAKE_ANDROID_NDK_VERSION` variable. .. _`Cross Compiling for Android with the NDK`: Cross Compiling for Android with the NDK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A toolchain file may configure :ref:`Makefile Generators`, :ref:`Ninja Generators`, or :ref:`Visual Studio Generators` to target Android for cross-compiling. Configure use of an Android NDK with the following variables: :variable:`CMAKE_SYSTEM_NAME` Set to ``Android``. Must be specified to enable cross compiling for Android. :variable:`CMAKE_SYSTEM_VERSION` Set to the Android API level. If not specified, the value is determined as follows: * If the :variable:`CMAKE_ANDROID_API` variable is set, its value is used as the API level. * If the :variable:`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. :variable:`CMAKE_ANDROID_ARCH_ABI` Set to the Android ABI (architecture). If not specified, this variable will default to the first supported ABI in the list of ``armeabi``, ``armeabi-v7a`` and ``arm64-v8a``. The :variable:`CMAKE_ANDROID_ARCH` variable will be computed from ``CMAKE_ANDROID_ARCH_ABI`` automatically. Also see the :variable:`CMAKE_ANDROID_ARM_MODE` and :variable:`CMAKE_ANDROID_ARM_NEON` variables. :variable:`CMAKE_ANDROID_NDK` Set to the absolute path to the Android NDK root directory. If not specified, a default for this variable will be chosen as specified :ref:`above <Cross Compiling for Android>`. :variable:`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. :variable:`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. :variable:`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: :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` The absolute path prefix to the binutils in the NDK toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` The host platform suffix of the binutils in the NDK toolchain. For example, a toolchain file might contain: .. code-block:: cmake 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: .. code-block:: console $ 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 .. _`Cross Compiling for Android with a Standalone Toolchain`: Cross Compiling for Android with a Standalone Toolchain ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A toolchain file may configure :ref:`Makefile Generators` or the :generator:`Ninja` generator to target Android for cross-compiling using a standalone toolchain. Configure use of an Android standalone toolchain with the following variables: :variable:`CMAKE_SYSTEM_NAME` Set to ``Android``. Must be specified to enable cross compiling for Android. :variable:`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 :ref:`above <Cross Compiling for Android>`. :variable:`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. :variable:`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: :variable:`CMAKE_SYSTEM_VERSION` The Android API level detected from the standalone toolchain. :variable:`CMAKE_ANDROID_ARCH_ABI` The Android ABI detected from the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` The absolute path prefix to the ``binutils`` in the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` The host platform suffix of the ``binutils`` in the standalone toolchain. For example, a toolchain file might contain: .. code-block:: cmake set(CMAKE_SYSTEM_NAME Android) set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain) Alternatively one may specify the values without a toolchain file: .. code-block:: console $ cmake ../src \ -DCMAKE_SYSTEM_NAME=Android \ -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain .. _`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition`: Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A toolchain file to configure one of the :ref:`Visual Studio Generators` to build using NVIDIA Nsight Tegra targeting Android may look like this: .. code-block:: cmake set(CMAKE_SYSTEM_NAME Android) The :variable:`CMAKE_GENERATOR_TOOLSET` may be set to select the Nsight Tegra "Toolchain Version" value. See also target properties: * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` * :prop_tgt:`ANDROID_API_MIN` * :prop_tgt:`ANDROID_API` * :prop_tgt:`ANDROID_ARCH` * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` * :prop_tgt:`ANDROID_GUI` * :prop_tgt:`ANDROID_JAR_DEPENDENCIES` * :prop_tgt:`ANDROID_JAR_DIRECTORIES` * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` * :prop_tgt:`ANDROID_PROCESS_MAX` * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` * :prop_tgt:`ANDROID_PROGUARD` * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` .. _`Cross Compiling for iOS, tvOS, or watchOS`: Cross Compiling for iOS, tvOS, or watchOS ----------------------------------------- For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` generator is recommended. The :generator:`Unix Makefiles` or :generator:`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 :variable:`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 :variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be necessary (see :ref:`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: .. code-block:: console cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures for both device and simulator. Variable :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: .. code-block:: console $ 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: .. code-block:: cmake # CMakeLists.txt cmake_minimum_required(VERSION 3.14) project(foo) add_library(foo foo.cpp) install(TARGETS foo DESTINATION lib) Install: .. code-block:: console $ cmake --build _builds --config Release --target install Check library: .. code-block:: console $ lipo -info _install/lib/libfoo.a Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 .. code-block:: console $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS cmd LC_VERSION_MIN_IPHONEOS cmdsize 16 version 9.3 Code Signing ^^^^^^^^^^^^ Some build artifacts for the embedded Apple platforms require mandatory code signing. If the :generator:`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). .. _`Switching Between Device and Simulator`: 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 :generator:`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: .. code-block:: console $ 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 :command:`find_package`, :command:`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 :command:`find_package` only for libraries installed with :variable:`CMAKE_IOS_INSTALL_COMBINED` feature PK ! w=���= �= cmake-policies.7.rstnu �[��� .. cmake-manual-description: CMake Policies Reference cmake-policies(7) ***************** .. only:: html .. contents:: 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 :command:`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 :variable:`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 :command:`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 :command:`if(POLICY)` command may be used: .. code-block:: cmake 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 :command:`include` command or the :command:`find_package` command contain a use of :command:`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 :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. Policies Introduced by CMake 3.22 ================================= .. toctree:: :maxdepth: 1 CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128> CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127> Policies Introduced by CMake 3.21 ================================= .. toctree:: :maxdepth: 1 CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126> CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125> CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124> CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123> CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122> CMP0121: The list command detects invalid indices. </policy/CMP0121> Policies Introduced by CMake 3.20 ================================= .. toctree:: :maxdepth: 1 CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120> CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119> CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118> CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117> CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116> CMP0115: Source file extensions must be explicit. </policy/CMP0115> Policies Introduced by CMake 3.19 ================================= .. toctree:: :maxdepth: 1 CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114> CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113> CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112> CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111> CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> Policies Introduced by CMake 3.18 ================================= .. toctree:: :maxdepth: 1 CMP0108: A target cannot link to itself through an alias. </policy/CMP0108> CMP0107: An ALIAS target cannot overwrite another target. </policy/CMP0107> CMP0106: The Documentation module is removed. </policy/CMP0106> CMP0105: Device link step uses the link options. </policy/CMP0105> CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104> CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103> Policies Introduced by CMake 3.17 ================================= .. toctree:: :maxdepth: 1 CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. </policy/CMP0102> CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101> CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100> CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099> CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098> Policies Introduced by CMake 3.16 ================================= .. toctree:: :maxdepth: 1 CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097> CMP0096: project() preserves leading zeros in version components. </policy/CMP0096> CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095> Policies Introduced by CMake 3.15 ================================= .. toctree:: :maxdepth: 1 CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094> CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093> CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092> CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091> CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090> CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089> Policies Introduced by CMake 3.14 ================================= .. toctree:: :maxdepth: 1 CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088> CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087> CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086> CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085> CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084> CMP0083: Add PIE options when linking executable. </policy/CMP0083> CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082> Policies Introduced by CMake 3.13 ================================= .. toctree:: :maxdepth: 1 CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081> CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080> CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079> CMP0078: UseSWIG generates standard target names. </policy/CMP0078> CMP0077: option() honors normal variables. </policy/CMP0077> CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076> Policies Introduced by CMake 3.12 ================================= .. toctree:: :maxdepth: 1 CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075> CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074> CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073> Policies Introduced by CMake 3.11 ================================= .. toctree:: :maxdepth: 1 CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072> Policies Introduced by CMake 3.10 ================================= .. toctree:: :maxdepth: 1 CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071> CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070> Policies Introduced by CMake 3.9 ================================ .. toctree:: :maxdepth: 1 CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069> CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068> Policies Introduced by CMake 3.8 ================================ .. toctree:: :maxdepth: 1 CMP0067: Honor language standard in try_compile() source-file signature. </policy/CMP0067> Policies Introduced by CMake 3.7 ================================ .. toctree:: :maxdepth: 1 CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066> Policies Introduced by CMake 3.4 ================================ .. toctree:: :maxdepth: 1 CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property. </policy/CMP0065> CMP0064: Support new TEST if() operator. </policy/CMP0064> Policies Introduced by CMake 3.3 ================================ .. toctree:: :maxdepth: 1 CMP0063: Honor visibility properties for all target types. </policy/CMP0063> CMP0062: Disallow install() of export() result. </policy/CMP0062> CMP0061: CTest does not by default tell make to ignore errors (-i). </policy/CMP0061> CMP0060: Link libraries by full path even in implicit directories. </policy/CMP0060> CMP0059: Do not treat DEFINITIONS as a built-in directory property. </policy/CMP0059> CMP0058: Ninja requires custom command byproducts to be explicit. </policy/CMP0058> CMP0057: Support new IN_LIST if() operator. </policy/CMP0057> Policies Introduced by CMake 3.2 ================================ .. toctree:: :maxdepth: 1 CMP0056: Honor link flags in try_compile() source-file signature. </policy/CMP0056> CMP0055: Strict checking for break() command. </policy/CMP0055> Policies Introduced by CMake 3.1 ================================ .. toctree:: :maxdepth: 1 CMP0054: Only interpret if() arguments as variables or keywords when unquoted. </policy/CMP0054> CMP0053: Simplify variable reference and escape sequence evaluation. </policy/CMP0053> CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. </policy/CMP0052> CMP0051: List TARGET_OBJECTS in SOURCES target property. </policy/CMP0051> Policies Introduced by CMake 3.0 ================================ .. toctree:: :maxdepth: 1 CMP0050: Disallow add_custom_command SOURCE signatures. </policy/CMP0050> CMP0049: Do not expand variables in target source entries. </policy/CMP0049> CMP0048: project() command manages VERSION variables. </policy/CMP0048> CMP0047: Use QCC compiler id for the qcc drivers on QNX. </policy/CMP0047> CMP0046: Error on non-existent dependency in add_dependencies. </policy/CMP0046> CMP0045: Error on non-existent target in get_target_property. </policy/CMP0045> CMP0044: Case sensitive Lang_COMPILER_ID generator expressions. </policy/CMP0044> CMP0043: Ignore COMPILE_DEFINITIONS_Config properties. </policy/CMP0043> CMP0042: MACOSX_RPATH is enabled by default. </policy/CMP0042> CMP0041: Error on relative include with generator expression. </policy/CMP0041> CMP0040: The target in the TARGET signature of add_custom_command() must exist. </policy/CMP0040> CMP0039: Utility targets may not have link dependencies. </policy/CMP0039> CMP0038: Targets may not link directly to themselves. </policy/CMP0038> CMP0037: Target names should not be reserved and should match a validity pattern. </policy/CMP0037> CMP0036: The build_name command should not be called. </policy/CMP0036> CMP0035: The variable_requires command should not be called. </policy/CMP0035> CMP0034: The utility_source command should not be called. </policy/CMP0034> CMP0033: The export_library_dependencies command should not be called. </policy/CMP0033> CMP0032: The output_required_files command should not be called. </policy/CMP0032> CMP0031: The load_command command should not be called. </policy/CMP0031> CMP0030: The use_mangled_mesa command should not be called. </policy/CMP0030> CMP0029: The subdir_depends command should not be called. </policy/CMP0029> CMP0028: Double colon in target name means ALIAS or IMPORTED target. </policy/CMP0028> CMP0027: Conditionally linked imported targets with missing include directories. </policy/CMP0027> CMP0026: Disallow use of the LOCATION target property. </policy/CMP0026> CMP0025: Compiler id for Apple Clang is now AppleClang. </policy/CMP0025> CMP0024: Disallow include export result. </policy/CMP0024> Policies Introduced by CMake 2.8 ================================ .. toctree:: :maxdepth: 1 CMP0023: Plain and keyword target_link_libraries signatures cannot be mixed. </policy/CMP0023> CMP0022: INTERFACE_LINK_LIBRARIES defines the link interface. </policy/CMP0022> CMP0021: Fatal error on relative paths in INCLUDE_DIRECTORIES target property. </policy/CMP0021> CMP0020: Automatically link Qt executables to qtmain target on Windows. </policy/CMP0020> CMP0019: Do not re-expand variables in include and link information. </policy/CMP0019> CMP0018: Ignore CMAKE_SHARED_LIBRARY_Lang_FLAGS variable. </policy/CMP0018> CMP0017: Prefer files from the CMake module directory when including from there. </policy/CMP0017> CMP0016: target_link_libraries() reports error if its only argument is not a target. </policy/CMP0016> CMP0015: link_directories() treats paths relative to the source dir. </policy/CMP0015> CMP0014: Input directories must have CMakeLists.txt. </policy/CMP0014> CMP0013: Duplicate binary directories are not allowed. </policy/CMP0013> CMP0012: if() recognizes numbers and boolean constants. </policy/CMP0012> Policies Introduced by CMake 2.6 ================================ .. toctree:: :maxdepth: 1 CMP0011: Included scripts do automatic cmake_policy PUSH and POP. </policy/CMP0011> CMP0010: Bad variable reference syntax is an error. </policy/CMP0010> CMP0009: FILE GLOB_RECURSE calls should not follow symlinks by default. </policy/CMP0009> CMP0008: Libraries linked by full-path must have a valid library file name. </policy/CMP0008> CMP0007: list command no longer ignores empty elements. </policy/CMP0007> CMP0006: Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. </policy/CMP0006> CMP0005: Preprocessor definition values are now escaped automatically. </policy/CMP0005> CMP0004: Libraries linked may not have leading or trailing whitespace. </policy/CMP0004> CMP0003: Libraries linked via full path no longer produce linker search paths. </policy/CMP0003> CMP0002: Logical target names must be globally unique. </policy/CMP0002> CMP0001: CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. </policy/CMP0001> CMP0000: A minimum required CMake version must be specified. </policy/CMP0000> PK ! ir��w� w� cmake-presets.7.rstnu �[��� .. cmake-manual-description: CMakePresets.json cmake-presets(7) **************** .. only:: html .. contents:: 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``. Format ====== The files are a JSON document with an object as the root: .. literalinclude:: presets/example.json :language: json The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. The supported versions are ``1``, ``2``, and ``3``. ``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. This is allowed in preset files specifying version ``1`` or above. ``buildPresets`` An optional array of `Build Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. ``testPresets`` An optional array of `Test Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. Configure Preset ^^^^^^^^^^^^^^^^ Each entry of the ``configurePresets`` array is a JSON object that may contain the following fields: ``name`` A required string representing the machine-friendly name of the preset. This identifier is used in the :ref:`cmake --preset <CMake Options>` option. There must not be two configure presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a configure preset may have the same name as a build or test preset. ``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 :manual:`CMake GUI <cmake-gui(1)>`, 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. ``condition`` An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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``). In version ``3`` or above, this field may be omitted to fall back to regular generator discovery procedure. 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. ``toolchainFile`` An optional string representing the path to the toolchain file. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the build directory, and if not found, relative to the source directory. This field takes precedence over any :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files specifying version ``3`` or above. ``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``). In version ``3`` or above, this field may be omitted. ``installDir`` An optional string representing the path to the installation directory. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. This is allowed in preset files specifying version ``3`` or above. ``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. Build Preset ^^^^^^^^^^^^ Each entry of the ``buildPresets`` array is a JSON object that may contain the following fields: ``name`` A required string representing the machine-friendly name of the preset. This identifier is used in the :ref:`cmake --build --preset <Build Tool Mode>` option. There must not be two build presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a build preset may have the same name as a configure or test preset. ``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 and does not have to have a valid ``configurePreset``, 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. ``condition`` An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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. ``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. .. note:: For a CMake project using ExternalProject with a configuration preset having environment variables needed in the ExternalProject, use a build preset that inherits that configuration preset or the ExternalProject will not have the environment variables set in the configuration preset. Example: suppose the host defaults to one compiler (say Clang) and the user wishes to use another compiler (say GCC). Set configuration preset environment variables ``CC`` and ``CXX`` and use a build preset that inherits that configuration preset. Otherwise the ExternalProject may use a different (system default) compiler than the top-level CMake project. ``configurePreset`` An optional string specifying the name of a configure preset to associate with this build preset. If ``configurePreset`` is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build directory is inferred from the configure preset, so the build will take place in the same ``binaryDir`` that the configuration did. ``inheritConfigureEnvironment`` An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset. ``jobs`` An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on the command line. ``targets`` An optional string or array of strings. Equivalent to passing ``--target`` or ``-t`` on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets. This field supports macro expansion. ``configuration`` An optional string. Equivalent to passing ``--config`` on the command line. ``cleanFirst`` An optional bool. If true, equivalent to passing ``--clean-first`` on the command line. ``verbose`` An optional bool. If true, equivalent to passing ``--verbose`` on the command line. ``nativeToolOptions`` An optional array of strings. Equivalent to passing options after ``--`` on the command line. The array values support macro expansion. Test Preset ^^^^^^^^^^^ Each entry of the ``testPresets`` array is a JSON object that may contain the following fields: ``name`` A required string representing the machine-friendly name of the preset. This identifier is used in the :ref:`ctest --preset <CTest Options>` option. There must not be two test presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a test preset may have the same name as a configure or build preset. ``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 and does not have to have a valid ``configurePreset``, 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. ``condition`` An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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. ``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. ``configurePreset`` An optional string specifying the name of a configure preset to associate with this test preset. If ``configurePreset`` is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build directory is inferred from the configure preset, so tests will run in the same ``binaryDir`` that the configuration did and build did. ``inheritConfigureEnvironment`` An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset. ``configuration`` An optional string. Equivalent to passing ``--build-config`` on the command line. ``overwriteConfigurationFile`` An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing ``--overwrite`` for each value in the array. The array values support macro expansion. ``output`` An optional object specifying output options. The object may contain the following fields. ``shortProgress`` An optional bool. If true, equivalent to passing ``--progress`` on the command line. ``verbosity`` An optional string specifying verbosity level. Must be one of the following: ``default`` Equivalent to passing no verbosity flags on the command line. ``verbose`` Equivalent to passing ``--verbose`` on the command line. ``extra`` Equivalent to passing ``--extra-verbose`` on the command line. ``debug`` An optional bool. If true, equivalent to passing ``--debug`` on the command line. ``outputOnFailure`` An optional bool. If true, equivalent to passing ``--output-on-failure`` on the command line. ``quiet`` An optional bool. If true, equivalent to passing ``--quiet`` on the command line. ``outputLogFile`` An optional string specifying a path to a log file. Equivalent to passing ``--output-log`` on the command line. This field supports macro expansion. ``labelSummary`` An optional bool. If false, equivalent to passing ``--no-label-summary`` on the command line. ``subprojectSummary`` An optional bool. If false, equivalent to passing ``--no-subproject-summary`` on the command line. ``maxPassedTestOutputSize`` An optional integer specifying the maximum output for passed tests in bytes. Equivalent to passing ``--test-output-size-passed`` on the command line. ``maxFailedTestOutputSize`` An optional integer specifying the maximum output for failed tests in bytes. Equivalent to passing ``--test-output-size-failed`` on the command line. ``maxTestNameWidth`` An optional integer specifying the maximum width of a test name to output. Equivalent to passing ``--max-width`` on the command line. ``filter`` An optional object specifying how to filter the tests to run. The object may contain the following fields. ``include`` An optional object specifying which tests to include. The object may contain the following fields. ``name`` An optional string specifying a regex for test names. Equivalent to passing ``--tests-regex`` on the command line. This field supports macro expansion. CMake regex syntax is described under :ref:`string(REGEX) <Regex Specification>`. ``label`` An optional string specifying a regex for test labels. Equivalent to passing ``--label-regex`` on the command line. This field supports macro expansion. ``useUnion`` An optional bool. Equivalent to passing ``--union`` on the command line. ``index`` An optional object specifying tests to include by test index. The object may contain the following fields. Can also be an optional string specifying a file with the command line syntax for ``--tests-information``. If specified as a string, this field supports macro expansion. ``start`` An optional integer specifying a test index to start testing at. ``end`` An optional integer specifying a test index to stop testing at. ``stride`` An optional integer specifying the increment. ``specificTests`` An optional array of integers specifying specific test indices to run. ``exclude`` An optional object specifying which tests to exclude. The object may contain the following fields. ``name`` An optional string specifying a regex for test names. Equivalent to passing ``--exclude-regex`` on the command line. This field supports macro expansion. ``label`` An optional string specifying a regex for test labels. Equivalent to passing ``--label-exclude`` on the command line. This field supports macro expansion. ``fixtures`` An optional object specifying which fixtures to exclude from adding tests. The object may contain the following fields. ``any`` An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to ``--fixture-exclude-any`` on the command line. This field supports macro expansion. ``setup`` An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to ``--fixture-exclude-setup`` on the command line. This field supports macro expansion. ``cleanup`` An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to ``--fixture-exclude-cleanup`` on the command line. This field supports macro expansion. ``execution`` An optional object specifying options for test execution. The object may contain the following fields. ``stopOnFailure`` An optional bool. If true, equivalent to passing ``--stop-on-failure`` on the command line. ``enableFailover`` An optional bool. If true, equivalent to passing ``-F`` on the command line. ``jobs`` An optional integer. Equivalent to passing ``--parallel`` on the command line. ``resourceSpecFile`` An optional string. Equivalent to passing ``--resource-spec-file`` on the command line. This field supports macro expansion. ``testLoad`` An optional integer. Equivalent to passing ``--test-load`` on the command line. ``showOnly`` An optional string. Equivalent to passing ``--show-only`` on the command line. The string must be one of the following values: ``human`` ``json-v1`` ``repeat`` An optional object specifying how to repeat tests. Equivalent to passing ``--repeat`` on the command line. The object must have the following fields. ``mode`` A required string. Must be one of the following values: ``until-fail`` ``until-pass`` ``after-timeout`` ``count`` A required integer. ``interactiveDebugging`` An optional bool. If true, equivalent to passing ``--interactive-debug-mode 1`` on the command line. If false, equivalent to passing ``--interactive-debug-mode 0`` on the command line. ``scheduleRandom`` An optional bool. If true, equivalent to passing ``--schedule-random`` on the command line. ``timeout`` An optional integer. Equivalent to passing ``--timeout`` on the command line. ``noTestsAction`` An optional string specifying the behavior if no tests are found. Must be one of the following values: ``default`` Equivalent to not passing any value on the command line. ``error`` Equivalent to passing ``--no-tests=error`` on the command line. ``ignore`` Equivalent to passing ``--no-tests=ignore`` on the command line. Condition ^^^^^^^^^ The ``condition`` field of a preset, allowed in preset files specifying version ``3`` or above, is used to determine whether or not the preset is enabled. For example, this can be used to disable a preset on platforms other than Windows. ``condition`` may be either a boolean, ``null``, or an object. If it is a boolean, the boolean indicates whether the preset is enabled or disabled. If it is ``null``, the preset is enabled, but the ``null`` condition is not inherited by any presets that may inherit from the preset. Sub-conditions (for example in a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an object, it has the following fields: ``type`` A required string with one of the following values: ``"const"`` Indicates that the condition is constant. This is equivalent to using a boolean in place of the object. The condition object will have the following additional fields: ``value`` A required boolean which provides a constant value for the condition's evaluation. ``"equals"`` ``"notEquals"`` Indicates that the condition compares two strings to see if they are equal (or not equal). The condition object will have the following additional fields: ``lhs`` First string to compare. This field supports macro expansion. ``rhs`` Second string to compare. This field supports macro expansion. ``"inList"`` ``"notInList"`` Indicates that the condition searches for a string in a list of strings. The condition object will have the following additional fields: ``string`` A required string to search for. This field supports macro expansion. ``list`` A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation. ``"matches"`` ``"notMatches"`` Indicates that the condition searches for a regular expression in a string. The condition object will have the following additional fields: ``string`` A required string to search. This field supports macro expansion. ``regex`` A required regular expression to search for. This field supports macro expansion. ``"anyOf"`` ``"allOf"`` Indicates that the condition is an aggregation of zero or more nested conditions. The condition object will have the following additional fields: ``conditions`` A required array of condition objects. These conditions use short-circuit evaluation. ``"not"`` Indicates that the condition is an inversion of another condition. The condition object will have the following additional fields: ``condition`` A required condition object. Macro Expansion ^^^^^^^^^^^^^^^ 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. For build and test presets, this will evaluate to the generator specified by ``configurePreset``. ``${hostSystemName}`` The name of the host operating system. Contains the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files specifying version ``3`` or above. ``${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}``. Schema ====== :download:`This file </manual/presets/schema.json>` provides a machine-readable JSON schema for the ``CMakePresets.json`` format. PK ! ��(�� � cmake-server.7.rstnu �[��� .. cmake-manual-description: CMake Server cmake-server(7) *************** The :manual:`cmake(1)` server mode has been removed since CMake 3.20. Clients should use the :manual:`cmake-file-api(7)` instead. PK ! L�y y ccmake.1.rstnu �[��� .. cmake-manual-description: CMake Curses Dialog Command-Line Reference ccmake(1) ********* Synopsis ======== .. parsed-literal:: ccmake [<options>] {<path-to-source> | <path-to-existing-build>} 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. Options ======= .. include:: OPTIONS_BUILD.txt .. include:: OPTIONS_HELP.txt See Also ======== .. include:: LINKS.txt PK ! -'8n2 2 OPTIONS_HELP.txtnu �[��� .. |file| replace:: The help is printed to a named <f>ile if given. ``--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. |file| ``--help-full [<f>]`` Print all help manuals and exit. All manuals are printed in a human-readable text format. |file| ``--help-manual <man> [<f>]`` Print one help manual and exit. The specified manual is printed in a human-readable text format. |file| ``--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. |file| ``--help-command <cmd> [<f>]`` Print help for one command and exit. The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is printed in a human-readable text format. |file| ``--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. |file| ``--help-commands [<f>]`` Print cmake-commands manual and exit. The :manual:`cmake-commands(7)` manual is printed in a human-readable text format. |file| ``--help-module <mod> [<f>]`` Print help for one module and exit. The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed in a human-readable text format. |file| ``--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. |file| ``--help-modules [<f>]`` Print cmake-modules manual and exit. The :manual:`cmake-modules(7)` manual is printed in a human-readable text format. |file| ``--help-policy <cmp> [<f>]`` Print help for one policy and exit. The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is printed in a human-readable text format. |file| ``--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. |file| ``--help-policies [<f>]`` Print cmake-policies manual and exit. The :manual:`cmake-policies(7)` manual is printed in a human-readable text format. |file| ``--help-property <prop> [<f>]`` Print help for one property and exit. The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are printed in a human-readable text format. |file| ``--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. |file| ``--help-properties [<f>]`` Print cmake-properties manual and exit. The :manual:`cmake-properties(7)` manual is printed in a human-readable text format. |file| ``--help-variable <var> [<f>]`` Print help for one variable and exit. The :manual:`cmake-variables(7)` manual entry for ``<var>`` is printed in a human-readable text format. |file| ``--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. |file| ``--help-variables [<f>]`` Print cmake-variables manual and exit. The :manual:`cmake-variables(7)` manual is printed in a human-readable text format. |file| PK ! ��FN�( �( cmake-qt.7.rstnu �[��� .. cmake-manual-description: CMake Qt Features Reference cmake-qt(7) *********** .. only:: html .. contents:: Introduction ============ CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found by the :module:`FindQt4` find-module shipped with CMake, whereas the Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See :manual:`cmake-packages(7)` for more information about CMake packages, and see `the Qt cmake manual <http://qt-project.org/doc/qt-5/cmake-manual.html>`_ for your Qt version. Qt 4 and Qt 5 may be used together in the same :manual:`CMake buildsystem <cmake-buildsystem(7)>`: .. code-block:: cmake 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. 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 :manual:`cmake(1)` if the appropriate conditions are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. .. _`Qt AUTOMOC`: AUTOMOC ^^^^^^^ The :prop_tgt:`AUTOMOC` target property controls whether :manual:`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 :prop_tgt:`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 :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. Not included ``moc_<basename>.cpp`` files will be generated in custom folders to avoid name collisions and included in a separate file which is compiled into the target, named either ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` or ``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being invoked for, and for the appropriate build configuration. The :prop_tgt:`AUTOMOC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set options to pass to ``moc``. The :variable:`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 :prop_tgt:`AUTOMOC_MACRO_NAMES`. Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. .. _`Qt AUTOUIC`: AUTOUIC ^^^^^^^ The :prop_tgt:`AUTOUIC` target property controls whether :manual:`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 :prop_tgt:`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 :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. The :prop_tgt:`AUTOUIC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOUIC` variable. The :prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options to pass to ``uic``. The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be populated to pre-set the options for all following targets. The :prop_sf:`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 :prop_tgt:`AUTOUIC_OPTIONS` target property. A target may populate the :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS` target property with options that should be used when invoking ``uic``. This must be consistent with the :prop_tgt:`AUTOUIC_OPTIONS` target property content of the depender target. The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be used to track the origin target of such :prop_tgt:`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``: .. code-block:: cmake 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 :prop_tgt:`AUTOUIC`, as a result of linking with the :prop_tgt:`IMPORTED` target: .. code-block:: cmake 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 :prop_tgt:`AUTOUIC` processing by enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. .. _`Qt AUTORCC`: AUTORCC ^^^^^^^ The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` creates rules to execute ``rcc`` at the appropriate time on source files which have the suffix ``.qrc``. .. code-block:: cmake add_executable(myexe main.cpp resource_file.qrc) The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTORCC` variable. The :prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options to pass to ``rcc``. The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be populated to pre-set the options for all following targets. The :prop_sf:`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 :prop_tgt:`AUTORCC_OPTIONS` target property. Source files can be excluded from :prop_tgt:`AUTORCC` processing by enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. The ``<ORIGIN>_autogen`` target =============================== The ``moc`` and ``uic`` tools are executed as part of a synthesized ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. Visual Studio Generators ======================== When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` (for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). This isn't always possible though and an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used, when either - the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file - :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled qtmain.lib on Windows ===================== The Qt 4 and 5 :prop_tgt:`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 :prop_tgt:`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. .. code-block:: cmake 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) PK ! U��� � cpack.1.rstnu �[��� .. cmake-manual-description: CPack Command-Line Reference cpack(1) ******** Synopsis ======== .. parsed-literal:: cpack [<options>] 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 :manual:`cmake <cmake(1)>` command. All supported generators are specified in the :manual:`cpack-generators <cpack-generators(7)>` 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 :variable:`CPACK_GENERATOR` variable or through the command-line option ``-G``. The **cpack** program is steered by a configuration file written in the :manual:`CMake language <cmake-language(7)>`. 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 :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` module is included by the project's ``CMakeLists.txt`` file. Options ======= ``-G <generators>`` ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` 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 :variable:`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 :ref:`semicolon-separated list <CMake Language Lists>`. 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 :variable:`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 :variable:`CPACK_PACKAGE_VERSION` variable used for packaging. It will override a value set in the ``CPackConfig.cmake`` file or one automatically computed from :variable:`CPACK_PACKAGE_VERSION_MAJOR`, :variable:`CPACK_PACKAGE_VERSION_MINOR` and :variable:`CPACK_PACKAGE_VERSION_PATCH`. ``-B <packageDirectory>`` Override/define :variable:`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 :variable:`CPACK_PACKAGE_VENDOR`. .. include:: OPTIONS_HELP.txt See Also ======== .. include:: LINKS.txt PK ! Sh�? ID_RESERVE.txtnu �[��� .. 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 :manual:`CMake Command <cmake-commands(7)>`. PK ! Q�\W� � LINKS.txtnu �[��� 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. PK ! Q �P P cmake-env-variables.7.rstnu �[��� .. cmake-manual-description: CMake Environment Variables Reference cmake-env-variables(7) ********************** .. only:: html .. contents:: This page lists environment variables that have special meaning to CMake. For general information on environment variables, see the :ref:`Environment Variables <CMake Language Environment Variables>` section in the cmake-language manual. Environment Variables that Change Behavior ========================================== .. toctree:: :maxdepth: 1 /envvar/CMAKE_PREFIX_PATH Environment Variables that Control the Build ============================================ .. toctree:: :maxdepth: 1 /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_TYPE /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES /envvar/CMAKE_TOOLCHAIN_FILE /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET /envvar/PackageName_ROOT /envvar/VERBOSE Environment Variables for Languages =================================== .. toctree:: :maxdepth: 1 /envvar/ASM_DIALECT /envvar/ASM_DIALECTFLAGS /envvar/CC /envvar/CFLAGS /envvar/CSFLAGS /envvar/CUDAARCHS /envvar/CUDACXX /envvar/CUDAFLAGS /envvar/CUDAHOSTCXX /envvar/CXX /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS /envvar/HIPCXX /envvar/HIPFLAGS /envvar/ISPC /envvar/ISPCFLAGS /envvar/OBJC /envvar/OBJCXX /envvar/RC /envvar/RCFLAGS /envvar/SWIFTC Environment Variables for CTest =============================== .. toctree:: :maxdepth: 1 /envvar/CMAKE_CONFIG_TYPE /envvar/CTEST_INTERACTIVE_DEBUG_MODE /envvar/CTEST_OUTPUT_ON_FAILURE /envvar/CTEST_PARALLEL_LEVEL /envvar/CTEST_PROGRESS_OUTPUT /envvar/CTEST_USE_LAUNCHERS_DEFAULT /envvar/DASHBOARD_TEST_FROM_CTEST Environment Variables for the CMake curses interface ==================================================== .. toctree:: :maxdepth: 1 /envvar/CCMAKE_COLORS PK ! �c��q �q cmake.1.rstnu �[��� .. cmake-manual-description: CMake Command-Line Reference cmake(1) ******** Synopsis ======== .. parsed-literal:: `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> `Build a Project`_ cmake --build <dir> [<options>] [-- <build-tool-options>] `Install a Project`_ cmake --install <dir> [<options>] `Open a Project`_ cmake --open <dir> `Run a Script`_ cmake [{-D <var>=<value>}...] -P <cmake-script-file> `Run a Command-Line Tool`_ cmake -E <command> [<options>] `Run the Find-Package Tool`_ cmake --find-package [<options>] `View Help`_ cmake --help[-<topic>] 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, `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 :manual:`CMake language <cmake-language(7)>` to support their builds. For graphical user interfaces that may be used in place of **cmake**, see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. For command-line interfaces to the CMake testing and packaging facilities, see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. For more information on CMake at large, `see also`_ the links at the end of this manual. 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 :manual:`CMake language <cmake-language(7)>`. 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 :manual:`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 :manual:`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 :manual:`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 :ref:`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 :ref:`IDE Build Tool Generators`, no particular environment is needed. .. _`Generate a Project Buildsystem`: 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: .. code-block:: console $ 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: .. code-block:: console $ 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: .. code-block:: console $ 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 :generator:`Unix Makefiles` generator one may run ``make`` directly: .. code-block:: console $ make $ make install Alternatively, one may use **cmake** to `Build a Project`_ by automatically choosing and invoking the appropriate native build tool. .. _`CMake Options`: Options ------- .. include:: OPTIONS_BUILD.txt ``-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 :prop_cache:`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 :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for :module:`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 :command:`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 :variable:`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 :command:`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 :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` is ignored. ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. Do not delete the files and directories created for :command:`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 :command:`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 :variable:`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: .. code-block:: json { "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 :command:`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: .. code-block:: json { "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 :variable:`CMAKE_SOURCE_DIR` and :variable:`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>``, ``--preset=<preset>`` Reads a :manual:`preset <cmake-presets(7)>` from ``<path-to-source>/CMakePresets.json`` and ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the generator and the build directory, and a list of variables and other arguments to pass to CMake. The current working directory must contain CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`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. ``--list-presets, --list-presets=<[configure | build | test | all]>`` Lists the available presets. If no option is specified only configure presets will be listed. The current working directory must contain CMake preset files. .. _`Build Tool Mode`: Build a Project =============== CMake provides a command-line signature to build an already-generated project binary tree: .. code-block:: shell cmake --build <dir> [<options>] [-- <build-tool-options>] cmake --build --preset <preset> [<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 (unless a preset is specified) and must be first. ``--preset <preset>``, ``--preset=<preset>`` Use a build preset to specify build options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. ``--list-presets`` Lists the available build presets. The current working directory must contain CMake preset files. ``--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 :envvar:`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 :envvar:`VERBOSE` environment variable or :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. ``--`` Pass remaining options to the native tool. Run ``cmake --build`` with no options for quick help. Install a Project ================= CMake provides a command-line signature to install an already-generated project binary tree: .. code-block:: shell 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, :variable:`CMAKE_INSTALL_PREFIX`. ``--strip`` Strip before installing. ``-v, --verbose`` Enable verbose output. This option can be omitted if :envvar:`VERBOSE` environment variable is set. Run ``cmake --install`` with no options for quick help. Open a Project ============== .. code-block:: shell cmake --open <dir> Open the generated project in the associated application. This is only supported by some generators. .. _`Script Processing Mode`: Run a Script ============ .. code-block:: shell 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 :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the script (including the ``--`` itself). Run a Command-Line Tool ======================= CMake provides builtin command-line tools through the signature .. code-block:: shell 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. ``supportedPlatforms`` .. versionadded:: 3.21 Optional member that may be present when the generator supports platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` (``-A ...``). The value is a list of platforms known to be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. ``fileApi`` Optional member that is present when the :manual:`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 :ref:`file-api 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. Always false since CMake 3.20. ``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:: 3.17 Remove the file(s). The planned behavior 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:: 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 :manual:`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. 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. Run the Find-Package Tool ========================= CMake provides a pkg-config like helper for Makefile-based projects: .. code-block:: shell cmake --find-package [<options>] It searches a package using :command:`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. View Help ========= To print selected pages from the CMake documentation, use .. code-block:: shell cmake --help[-<topic>] with one of the following options: .. include:: OPTIONS_HELP.txt To view the presets available for a project, use .. code-block:: shell cmake <source-dir> --list-presets See Also ======== .. include:: LINKS.txt PK ! ���D� � OPTIONS_BUILD.txtnu �[��� ``-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 :command:`set` commands that use the ``CACHE`` option, not a cache-format file. References to :variable:`CMAKE_SOURCE_DIR` and :variable:`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 :command:`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 :manual:`cmake-generators(7)` manual. If not specified, CMake checks the :envvar:`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 :variable:`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 :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. ``--toolchain <path-to-file>`` Specify the cross compiling toolchain file, equivalent to setting :variable:`CMAKE_TOOLCHAIN_FILE` variable. ``--install-prefix <directory>`` Specify the installation directory, used by the :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. ``-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. PK ! ��W#� #� ! cmake-generator-expressions.7.rstnu �[��� .. cmake-manual-description: CMake Generator Expressions cmake-generator-expressions(7) ****************************** .. only:: html .. contents:: 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 :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. They may also be used when using commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`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. .. _`Boolean Generator Expressions`: Boolean Generator Expressions ============================= Boolean expressions evaluate to either ``0`` or ``1``. They are typically used to construct the condition in a :ref:`conditional generator expression<Conditional Generator Expressions>`. Available boolean expressions are: Logical Operators ----------------- .. genex:: $<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``. .. genex:: $<AND:conditions> where ``conditions`` is a comma-separated list of boolean expressions. Evaluates to ``1`` if all conditions are ``1``. Otherwise evaluates to ``0``. .. genex:: $<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``. .. genex:: $<NOT:condition> ``0`` if ``condition`` is ``1``, else ``1``. String Comparisons ------------------ .. genex:: $<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 :ref:`string transforming generator expression <String Transforming Generator Expressions>`, .. code-block:: cmake $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... .. genex:: $<EQUAL:value1,value2> ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. .. genex:: $<IN_LIST:string,list> .. versionadded:: 3.12 ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. .. genex:: $<VERSION_LESS:v1,v2> ``1`` if ``v1`` is a version less than ``v2``, else ``0``. .. genex:: $<VERSION_GREATER:v1,v2> ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. .. genex:: $<VERSION_EQUAL:v1,v2> ``1`` if ``v1`` is the same version as ``v2``, else ``0``. .. genex:: $<VERSION_LESS_EQUAL:v1,v2> .. versionadded:: 3.7 ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. .. genex:: $<VERSION_GREATER_EQUAL:v1,v2> .. versionadded:: 3.7 ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries ---------------- .. genex:: $<TARGET_EXISTS:target> .. versionadded:: 3.12 ``1`` if ``target`` exists, else ``0``. .. genex:: $<CONFIG:cfgs> ``1`` if config is any one of the entries in comma-separated list ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. .. genex:: $<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 :variable:`CMAKE_SYSTEM_NAME` variable. .. genex:: $<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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<CUDA_COMPILER_ID:compiler_ids> .. versionadded:: 3.15 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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJC_COMPILER_ID:compiler_ids> .. versionadded:: 3.16 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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> .. versionadded:: 3.16 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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<HIP_COMPILER_ID:compiler_ids> where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the HIP compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<ISPC_COMPILER_ID:compiler_ids> .. versionadded:: 3.19 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 :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<C_COMPILER_VERSION:version> ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<CXX_COMPILER_VERSION:version> ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<CUDA_COMPILER_VERSION:version> .. versionadded:: 3.15 ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJC_COMPILER_VERSION:version> .. versionadded:: 3.16 ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION:version> .. versionadded:: 3.16 ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<Fortran_COMPILER_VERSION:version> ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<HIP_COMPILER_VERSION:version> ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<ISPC_COMPILER_VERSION:version> .. versionadded:: 3.19 ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<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. .. genex:: $<COMPILE_FEATURES:features> .. versionadded:: 3.1 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 :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. .. _`Boolean COMPILE_LANGUAGE Generator Expression`: .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> .. versionadded:: 3.15 ``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: .. code-block:: cmake 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: .. code-block:: cmake 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> ) .. genex:: $<COMPILE_LANGUAGE:languages> .. versionadded:: 3.3 ``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: .. code-block:: cmake 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 :ref:`Visual Studio Generators` and :generator:`Xcode` there is no way to represent target-wide compile definitions or include directories separately for ``C`` and ``CXX`` languages. Also, with :ref:`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: .. code-block:: cmake 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) .. _`Boolean LINK_LANGUAGE Generator Expression`: .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> .. versionadded:: 3.18 ``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: .. code-block:: cmake 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 :ref:`the note related to <Constraints LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this generator expression. .. genex:: $<LINK_LANGUAGE:languages> .. versionadded:: 3.18 ``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: .. code-block:: cmake 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. .. _`Constraints LINK_LANGUAGE Generator Expression`: .. 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: .. code-block:: cmake 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. .. genex:: $<DEVICE_LINK:list> .. versionadded:: 3.18 Returns the list if it is the device link step, an empty list otherwise. The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`. This expression can only be used to specify link options. .. genex:: $<HOST_LINK:list> .. versionadded:: 3.18 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. String-Valued Generator Expressions =================================== These expressions expand to some string. For example, .. code-block:: cmake 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: .. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. And here two nested string-valued expressions: .. code-block:: cmake -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> generates a string of the entries in the :prop_tgt:`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: .. code-block:: cmake set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> The following string-valued generator expressions are available: Escaped Characters ------------------ String literals to escape the special meaning a character would otherwise have: .. genex:: $<ANGLE-R> A literal ``>``. Used for example to compare strings that contain a ``>``. .. genex:: $<COMMA> A literal ``,``. Used for example to compare strings which contain a ``,``. .. genex:: $<SEMICOLON> A literal ``;``. Used to prevent list expansion on an argument with ``;``. .. _`Conditional Generator Expressions`: Conditional Expressions ----------------------- Conditional generator expressions depend on a boolean condition that must be ``0`` or ``1``. .. genex:: $<condition:true_string> Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to the empty string. .. genex:: $<IF:condition,true_string,false_string> .. versionadded:: 3.8 Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. Typically, the ``condition`` is a :ref:`boolean generator expression <Boolean Generator Expressions>`. For instance, .. code-block:: cmake $<$<CONFIG:Debug>:DEBUG_MODE> expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and otherwise expands to the empty string. .. _`String Transforming Generator Expressions`: String Transformations ---------------------- .. genex:: $<JOIN:list,string> Joins the list with the content of ``string``. .. genex:: $<REMOVE_DUPLICATES:list> .. versionadded:: 3.15 Removes duplicated items in the given ``list``. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> .. versionadded:: 3.15 Includes or removes items from ``list`` that match the regular expression ``regex``. .. genex:: $<LOWER_CASE:string> Content of ``string`` converted to lower case. .. genex:: $<UPPER_CASE:string> Content of ``string`` converted to upper case. .. genex:: $<GENEX_EVAL:expr> .. versionadded:: 3.12 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. .. genex:: $<TARGET_GENEX_EVAL:tgt,expr> .. versionadded:: 3.12 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: .. code-block:: cmake 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>``: .. code-block:: cmake add_custom_target(printFooKeys COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> ) Variable Queries ---------------- .. genex:: $<CONFIG> Configuration name. .. genex:: $<CONFIGURATION> Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. .. genex:: $<PLATFORM_ID> The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. .. genex:: $<C_COMPILER_ID> The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<CXX_COMPILER_ID> The CMake's compiler id of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<CUDA_COMPILER_ID> The CMake's compiler id of the CUDA compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJC_COMPILER_ID> .. versionadded:: 3.16 The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJCXX_COMPILER_ID> .. versionadded:: 3.16 The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<Fortran_COMPILER_ID> The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<HIP_COMPILER_ID> The CMake's compiler id of the HIP compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<ISPC_COMPILER_ID> .. versionadded:: 3.19 The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<C_COMPILER_VERSION> The version of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<CXX_COMPILER_VERSION> The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<CUDA_COMPILER_VERSION> The version of the CUDA compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJC_COMPILER_VERSION> .. versionadded:: 3.16 The version of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION> .. versionadded:: 3.16 The version of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<Fortran_COMPILER_VERSION> The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<HIP_COMPILER_VERSION> The version of the HIP compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<ISPC_COMPILER_VERSION> .. versionadded:: 3.19 The version of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<COMPILE_LANGUAGE> .. versionadded:: 3.3 The compile language of source files when evaluating compile options. See :ref:`the related boolean expression <Boolean COMPILE_LANGUAGE Generator Expression>` ``$<COMPILE_LANGUAGE:language>`` for notes about the portability of this generator expression. .. genex:: $<LINK_LANGUAGE> .. versionadded:: 3.18 The link language of target when evaluating link options. See :ref:`the related boolean expression <Boolean LINK_LANGUAGE Generator 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. .. _`Target-Dependent Queries`: Target-Dependent Queries ------------------------ These queries refer to a target ``tgt``. This can be any runtime artifact, namely: * an executable target created by :command:`add_executable` * a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) created by :command:`add_library` * a static library target created by :command:`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``. .. genex:: $<TARGET_NAME_IF_EXISTS:tgt> .. versionadded:: 3.12 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. .. genex:: $<TARGET_FILE:tgt> Full path to the ``tgt`` binary file. .. genex:: $<TARGET_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 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 :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` target properties and their configuration specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`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. .. genex:: $<TARGET_FILE_PREFIX:tgt> .. versionadded:: 3.15 Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. .. genex:: $<TARGET_FILE_SUFFIX:tgt> .. versionadded:: 3.15 Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<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. .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 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 :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`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. .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> .. versionadded:: 3.15 Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target properties. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt> .. versionadded:: 3.15 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 :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target properties. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<TARGET_SONAME_FILE:tgt> File with soname (``.so.3``) where ``tgt`` is the name of a target. .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<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 :policy:`CMP0112`). .. genex:: $<TARGET_PDB_FILE:tgt> .. versionadded:: 3.1 Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 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 :prop_tgt:`PDB_NAME` target property and its configuration specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`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. .. genex:: $<TARGET_PDB_FILE_NAME:tgt> .. versionadded:: 3.1 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 :policy:`CMP0112`). .. genex:: $<TARGET_PDB_FILE_DIR:tgt> .. versionadded:: 3.1 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 :policy:`CMP0112`). .. genex:: $<TARGET_BUNDLE_DIR:tgt> .. versionadded:: 3.9 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 :policy:`CMP0112`). .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> .. versionadded:: 3.9 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 :policy:`CMP0112`). .. genex:: $<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. .. genex:: $<TARGET_PROPERTY:prop> Value of the property ``prop`` on the target for which the expression is being evaluated. Note that for generator expressions in :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. .. genex:: $<TARGET_RUNTIME_DLLS:tgt> .. versionadded:: 3.21 List of DLLs that the target depends on at runtime. This is determined by the locations of all the ``SHARED`` and ``MODULE`` targets in the target's transitive dependencies. Using this generator expression on targets other than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. On non-DLL platforms, it evaluates to an empty string. This generator expression can be used to copy all of the DLLs that a target depends on into its output directory in a ``POST_BUILD`` custom command. For example: .. code-block:: cmake find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) add_executable(exe main.c) target_link_libraries(exe PRIVATE foo::foo foo::bar) add_custom_command(TARGET exe POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> COMMAND_EXPAND_LISTS ) .. note:: :ref:`Imported Targets` are supported only if they know the location of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the :ref:`add_library imported libraries <add_library imported libraries>` section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. .. genex:: $<INSTALL_PREFIX> Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in the :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. Output-Related Expressions -------------------------- .. genex:: $<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. .. genex:: $<LINK_ONLY:...> .. versionadded:: 3.1 Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, perhaps via the :command:`target_link_libraries` command, to specify private link dependencies without other usage requirements. .. genex:: $<INSTALL_INTERFACE:...> Content of ``...`` when the property is exported using :command:`install(EXPORT)`, and empty otherwise. .. genex:: $<BUILD_INTERFACE:...> Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. .. genex:: $<MAKE_C_IDENTIFIER:...> Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. .. genex:: $<TARGET_OBJECTS:objLib> .. versionadded:: 3.1 List of objects resulting from build of ``objLib``. .. genex:: $<SHELL_PATH:...> .. versionadded:: 3.4 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. .. versionadded:: 3.14 The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` 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. .. genex:: $<OUTPUT_CONFIG:...> .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target` as the outer-most generator expression in an argument. With the :generator:`Ninja Multi-Config` generator, generator expressions in ``...`` are evaluated using the custom command's "output config". With other generators, the content of ``...`` is evaluated normally. .. genex:: $<COMMAND_CONFIG:...> .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target` as the outer-most generator expression in an argument. With the :generator:`Ninja Multi-Config` generator, generator expressions in ``...`` are evaluated using the custom command's "command config". With other generators, the content of ``...`` is evaluated normally. 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 :command:`message()` command. One possible way to generate debug messages is to add a custom target, .. code-block:: cmake 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: .. code-block:: cmake file(GENERATE OUTPUT filename CONTENT "$<...>") PK ! j��#8� 8� cmake-file-api.7.rstnu �[��� .. cmake-manual-description: CMake File-Based API cmake-file-api(7) ***************** .. only:: html .. contents:: 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, `API v1`_. 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`_, `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. 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. 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. 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: .. code-block:: json { "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. 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: .. code-block:: json { "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 :variable:`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 :variable:`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. 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. 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. .. _`file-api object kinds`: 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: .. code-block:: json { "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. 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 :manual:`cmake-server(7)` mode. "codemodel" version 2 ^^^^^^^^^^^^^^^^^^^^^ ``codemodel`` object version 2 is a JSON object: .. code-block:: json { "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" }, "jsonFile": "<file>" }, { "source": "sub", "build": "sub", "parentIndex": 0, "projectIndex": 0, "targetIndexes": [ 1 ], "minimumCMakeVersion": { "string": "3.14" }, "jsonFile": "<file>" } ], "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 :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators there is an entry for each configuration listed in the :variable:`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 :command:`add_subdirectory` or :command:`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 :command:`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 :command:`install` rules, i.e. whether a ``make install`` or equivalent rule is available. ``jsonFile`` A JSON string specifying a path relative to the codemodel file to another JSON file containing a `"codemodel" version 2 "directory" object`_. This field was added in codemodel version 2.3. ``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 :command:`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 :command:`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 :command:`add_executable`, :command:`add_library`, and :command:`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`_. "codemodel" version 2 "directory" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A codemodel "directory" object is referenced by a `"codemodel" version 2`_ object's ``directories`` array. Each "directory" object is a JSON object with members: ``paths`` 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. ``installers`` A JSON array of entries corresponding to :command:`install` rules. Each entry is a JSON object containing members: ``component`` A string specifying the component selected by the corresponding :command:`install` command invocation. ``destination`` Optional member that is present for specific ``type`` values below. The value is a string specifying the install destination path. The path may be absolute or relative to the install prefix. ``paths`` Optional member that is present for specific ``type`` values below. The value is a JSON array of entries corresponding to the paths (files or directories) to be installed. Each entry is one of: * A string specifying the path from which a file or directory is to be installed. The portion of the path not preceded by a ``/`` also specifies the path (name) to which the file or directory is to be installed under the destination. * A JSON object with members: ``from`` A string specifying the path from which a file or directory is to be installed. ``to`` A string specifying the path to which the file or directory is to be installed under the destination. In both cases the paths are represented with forward slashes. If the "from" path is inside the top-level directory documented by the corresponding ``type`` value, then the path is specified relative to that directory. Otherwise the path is absolute. ``type`` A string specifying the type of installation rule. The value is one of the following, with some variants providing additional members: ``file`` An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. The ``destination`` and ``paths`` members are populated, with paths under the top-level *source* directory expressed relative to it. The ``isOptional`` member may exist. This type has no additional members. ``directory`` An :command:`install(DIRECTORY)` call. The ``destination`` and ``paths`` members are populated, with paths under the top-level *source* directory expressed relative to it. The ``isOptional`` member may exist. This type has no additional members. ``target`` An :command:`install(TARGETS)` call. The ``destination`` and ``paths`` members are populated, with paths under the top-level *build* directory expressed relative to it. The ``isOptional`` member may exist. This type has additional members ``targetId``, ``targetIndex``, ``targetIsImportLibrary``, and ``targetInstallNamelink``. ``export`` An :command:`install(EXPORT)` call. The ``destination`` and ``paths`` members are populated, with paths under the top-level *build* directory expressed relative to it. The ``paths`` entries refer to files generated automatically by CMake for installation, and their actual values are considered private implementation details. This type has additional members ``exportName`` and ``exportTargets``. ``script`` An :command:`install(SCRIPT)` call. This type has additional member ``scriptFile``. ``code`` An :command:`install(CODE)` call. This type has no additional members. ``importedRuntimeArtifacts`` An :command:`install(IMPORTED_RUNTIME_ARTIFACTS)` call. The ``destination`` member is populated. The ``isOptional`` member may exist. This type has no additional members. ``runtimeDependencySet`` An :command:`install(RUNTIME_DEPENDENCY_SET)` call or an :command:`install(TARGETS)` call with ``RUNTIME_DEPENDENCIES``. The ``destination`` member is populated. This type has additional members ``runtimeDependencySetName`` and ``runtimeDependencySetType``. ``isExcludeFromAll`` Optional member that is present with boolean value ``true`` when :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. ``isForAllComponents`` Optional member that is present with boolean value ``true`` when :command:`install(SCRIPT|CODE)` is called with the ``ALL_COMPONENTS`` option. ``isOptional`` Optional member that is present with boolean value ``true`` when :command:`install` is called with the ``OPTIONAL`` option. This is allowed when ``type`` is ``file``, ``directory``, or ``target``. ``targetId`` Optional member that is present when ``type`` is ``target``. The value is a string uniquely identifying the target to be installed. This matches the ``id`` member of the target in the main "codemodel" object's ``targets`` array. ``targetIndex`` Optional member that is present when ``type`` is ``target``. The value is an unsigned integer 0-based index into the main "codemodel" object's ``targets`` array for the target to be installed. ``targetIsImportLibrary`` Optional member that is present when ``type`` is ``target`` and the installer is for a Windows DLL import library file or for an AIX linker import file. If present, it has boolean value ``true``. ``targetInstallNamelink`` Optional member that is present when ``type`` is ``target`` and the installer corresponds to a target that may use symbolic links to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties. The value is a string indicating how the installer is supposed to handle the symlinks: ``skip`` means the installer should skip the symlinks and install only the real file, and ``only`` means the installer should install only the symlinks and not the real file. In all cases the ``paths`` member lists what it actually installs. ``exportName`` Optional member that is present when ``type`` is ``export``. The value is a string specifying the name of the export. ``exportTargets`` Optional member that is present when ``type`` is ``export``. The value is a JSON array of entries corresponding to the targets included in the export. Each entry is a JSON object with members: ``id`` A string uniquely identifying the target. This matches the ``id`` member of the target in the main "codemodel" object's ``targets`` array. ``index`` An unsigned integer 0-based index into the main "codemodel" object's ``targets`` array for the target. ``runtimeDependencySetName`` Optional member that is present when ``type`` is ``runtimeDependencySet`` and the installer was created by an :command:`install(RUNTIME_DEPENDENCY_SET)` call. The value is a string specifying the name of the runtime dependency set that was installed. ``runtimeDependencySetType`` Optional member that is present when ``type`` is ``runtimeDependencySet``. The value is a string with one of the following values: ``library`` Indicates that this installer installs dependencies that are not macOS frameworks. ``framework`` Indicates that this installer installs dependencies that are macOS frameworks. ``scriptFile`` Optional member that is present when ``type`` is ``script``. The value is a string specifying the path to the script 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. ``backtrace`` Optional member that is present when a CMake language backtrace to the :command:`install` or other command invocation that added this installer is available. The value is an unsigned integer 0-based index into the ``backtraceGraph`` member's ``nodes`` array. ``backtraceGraph`` A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced from ``backtrace`` members elsewhere in this "directory" object. "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 :prop_tgt:`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 :command:`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 :variable:`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 :command:`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 :variable:`CMAKE_SYSROOT_LINK` or :variable:`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 :command:`add_dependencies`, :command:`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 :command:`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 :prop_sf:`GENERATED`. ``backtrace`` Optional member that is present when a CMake language backtrace to the :command:`target_sources`, :command:`add_executable`, :command:`add_library`, :command:`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 :command:`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 :prop_tgt:`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 :command:`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 :command:`target_precompile_headers` or other command invocations set :prop_tgt:`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 :command:`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 :command:`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 :variable:`CMAKE_SYSROOT_COMPILE` or :variable:`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 `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced from ``backtrace`` members elsewhere in this "target" object. "codemodel" version 2 "backtrace graph" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, or `"codemodel" version 2 "target" object`_ is a JSON object describing a graph of backtraces. Its nodes are referenced from ``backtrace`` members elsewhere in the containing object. The backtrace graph object 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. Object Kind "cache" ------------------- The ``cache`` object kind lists cache entries. These are the :ref:`CMake Language 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 :manual:`cmake-server(7)` mode. "cache" version 2 ^^^^^^^^^^^^^^^^^ ``cache`` object version 2 is a JSON object: .. code-block:: json { "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 :manual:`cmake-gui(1)` to choose a widget for editing. ``properties`` A JSON array of entries specifying associated :ref:`cache entry properties <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. 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. "cmakeFiles" version 1 ^^^^^^^^^^^^^^^^^^^^^^ ``cmakeFiles`` object version 1 is a JSON object: .. code-block:: json { "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. Object Kind "toolchains" ------------------------ The ``toolchains`` object kind lists properties of the toolchains used during the build. These include the language, compiler path, ID, and version. There is only one ``toolchains`` object major version, version 1. "toolchains" version 1 ^^^^^^^^^^^^^^^^^^^^^^ ``toolchains`` object version 1 is a JSON object: .. code-block:: json { "kind": "toolchains", "version": { "major": 1, "minor": 0 }, "toolchains": [ { "language": "C", "compiler": { "path": "/usr/bin/cc", "id": "GNU", "version": "9.3.0", "implicit": { "includeDirectories": [ "/usr/lib/gcc/x86_64-linux-gnu/9/include", "/usr/local/include", "/usr/include/x86_64-linux-gnu", "/usr/include" ], "linkDirectories": [ "/usr/lib/gcc/x86_64-linux-gnu/9", "/usr/lib/x86_64-linux-gnu", "/usr/lib", "/lib/x86_64-linux-gnu", "/lib" ], "linkFrameworkDirectories": [], "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ] } }, "sourceFileExtensions": [ "c", "m" ] }, { "language": "CXX", "compiler": { "path": "/usr/bin/c++", "id": "GNU", "version": "9.3.0", "implicit": { "includeDirectories": [ "/usr/include/c++/9", "/usr/include/x86_64-linux-gnu/c++/9", "/usr/include/c++/9/backward", "/usr/lib/gcc/x86_64-linux-gnu/9/include", "/usr/local/include", "/usr/include/x86_64-linux-gnu", "/usr/include" ], "linkDirectories": [ "/usr/lib/gcc/x86_64-linux-gnu/9", "/usr/lib/x86_64-linux-gnu", "/usr/lib", "/lib/x86_64-linux-gnu", "/lib" ], "linkFrameworkDirectories": [], "linkLibraries": [ "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc" ] } }, "sourceFileExtensions": [ "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP" ] } ] } The members specific to ``toolchains`` objects are: ``toolchains`` A JSON array whose entries are each a JSON object specifying a toolchain associated with a particular language. The members of each entry are: ``language`` A JSON string specifying the toolchain language, like C or CXX. Language names are the same as language names that can be passed to the :command:`project` command. Because CMake only supports a single toolchain per language, this field can be used as a key. ``compiler`` A JSON object containing members: ``path`` Optional member that is present when the :variable:`CMAKE_<LANG>_COMPILER` variable is defined for the current language. Its value is a JSON string holding the path to the compiler. ``id`` Optional member that is present when the :variable:`CMAKE_<LANG>_COMPILER_ID` variable is defined for the current language. Its value is a JSON string holding the ID (GNU, MSVC, etc.) of the compiler. ``version`` Optional member that is present when the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable is defined for the current language. Its value is a JSON string holding the version of the compiler. ``target`` Optional member that is present when the :variable:`CMAKE_<LANG>_COMPILER_TARGET` variable is defined for the current language. Its value is a JSON string holding the cross-compiling target of the compiler. ``implicit`` A JSON object containing members: ``includeDirectories`` Optional member that is present when the :variable:`CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES` variable is defined for the current language. Its value is a JSON array of JSON strings where each string holds a path to an implicit include directory for the compiler. ``linkDirectories`` Optional member that is present when the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable is defined for the current language. Its value is a JSON array of JSON strings where each string holds a path to an implicit link directory for the compiler. ``linkFrameworkDirectories`` Optional member that is present when the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES` variable is defined for the current language. Its value is a JSON array of JSON strings where each string holds a path to an implicit link framework directory for the compiler. ``linkLibraries`` Optional member that is present when the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable is defined for the current language. Its value is a JSON array of JSON strings where each string holds a path to an implicit link library for the compiler. ``sourceFileExtensions`` Optional member that is present when the :variable:`CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS` variable is defined for the current language. Its value is a JSON array of JSON strings where each each string holds a file extension (without the leading dot) for the language. PK ! �Ч]> > cmake-commands.7.rstnu �[��� .. cmake-manual-description: CMake Language Command Reference cmake-commands(7) ***************** .. only:: html .. contents:: Scripting Commands ================== These commands are always available. .. toctree:: :maxdepth: 1 /command/break /command/cmake_host_system_information /command/cmake_language /command/cmake_minimum_required /command/cmake_parse_arguments /command/cmake_path /command/cmake_policy /command/configure_file /command/continue /command/else /command/elseif /command/endforeach /command/endfunction /command/endif /command/endmacro /command/endwhile /command/execute_process /command/file /command/find_file /command/find_library /command/find_package /command/find_path /command/find_program /command/foreach /command/function /command/get_cmake_property /command/get_directory_property /command/get_filename_component /command/get_property /command/if /command/include /command/include_guard /command/list /command/macro /command/mark_as_advanced /command/math /command/message /command/option /command/return /command/separate_arguments /command/set /command/set_directory_properties /command/set_property /command/site_name /command/string /command/unset /command/variable_watch /command/while Project Commands ================ These commands are available only in CMake projects. .. toctree:: :maxdepth: 1 /command/add_compile_definitions /command/add_compile_options /command/add_custom_command /command/add_custom_target /command/add_definitions /command/add_dependencies /command/add_executable /command/add_library /command/add_link_options /command/add_subdirectory /command/add_test /command/aux_source_directory /command/build_command /command/create_test_sourcelist /command/define_property /command/enable_language /command/enable_testing /command/export /command/fltk_wrap_ui /command/get_source_file_property /command/get_target_property /command/get_test_property /command/include_directories /command/include_external_msproject /command/include_regular_expression /command/install /command/link_directories /command/link_libraries /command/load_cache /command/project /command/remove_definitions /command/set_source_files_properties /command/set_target_properties /command/set_tests_properties /command/source_group /command/target_compile_definitions /command/target_compile_features /command/target_compile_options /command/target_include_directories /command/target_link_directories /command/target_link_libraries /command/target_link_options /command/target_precompile_headers /command/target_sources /command/try_compile /command/try_run .. _`CTest Commands`: CTest Commands ============== These commands are available only in CTest scripts. .. toctree:: :maxdepth: 1 /command/ctest_build /command/ctest_configure /command/ctest_coverage /command/ctest_empty_binary_directory /command/ctest_memcheck /command/ctest_read_custom_files /command/ctest_run_script /command/ctest_sleep /command/ctest_start /command/ctest_submit /command/ctest_test /command/ctest_update /command/ctest_upload 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. .. toctree:: :maxdepth: 1 /command/build_name /command/exec_program /command/export_library_dependencies /command/install_files /command/install_programs /command/install_targets /command/load_command /command/make_directory /command/output_required_files /command/qt_wrap_cpp /command/qt_wrap_ui /command/remove /command/subdir_depends /command/subdirs /command/use_mangled_mesa /command/utility_source /command/variable_requires /command/write_file PK ! ��9��L �L cmake-language.7.rstnu �[��� .. cmake-manual-description: CMake Language Reference cmake-language(7) ***************** .. only:: html .. contents:: 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``). 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 :command:`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. Scripts ------- An individual ``<script>.cmake`` source file may be processed in *script mode* by using the :manual:`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. Modules ------- CMake Language code in either `Directories`_ or `Scripts`_ may use the :command:`include` command to load a ``<module>.cmake`` source file in the scope of the including context. See the :manual:`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 :variable:`CMAKE_MODULE_PATH` variable. Syntax ====== .. _`CMake Language Encoding`: 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`_ in source files. .. _`Byte-Order Mark`: http://en.wikipedia.org/wiki/Byte_order_mark Source Files ------------ A CMake Language source file consists of zero or more `Command Invocations`_ separated by newlines and optionally spaces and `Comments`_: .. raw:: latex \begin{small} .. productionlist:: 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'> .. raw:: latex \end{small} Note that any source file line not inside `Command Arguments`_ or a `Bracket Comment`_ can end in a `Line Comment`_. .. _`Command Invocations`: Command Invocations ------------------- A *command invocation* is a name followed by paren-enclosed arguments separated by whitespace: .. raw:: latex \begin{small} .. productionlist:: 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` .. raw:: latex \end{small} For example: .. code-block:: cmake 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 :command:`if` command to enclose conditions. For example: .. code-block:: cmake 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. Command Arguments ----------------- There are three types of arguments within `Command Invocations`_: .. raw:: latex \begin{small} .. productionlist:: argument: `bracket_argument` | `quoted_argument` | `unquoted_argument` .. raw:: latex \end{small} .. _`Bracket Argument`: Bracket Argument ^^^^^^^^^^^^^^^^ A *bracket argument*, inspired by `Lua`_ long bracket syntax, encloses content between opening and closing "brackets" of the same length: .. raw:: latex \begin{small} .. productionlist:: 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: ']' '='* ']' .. raw:: latex \end{small} 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. .. No code-block syntax highlighting in the following example (long string literal not supported by our cmake.py) 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`_. .. _`Lua`: http://www.lua.org/ .. _`Quoted Argument`: Quoted Argument ^^^^^^^^^^^^^^^ A *quoted argument* encloses content between opening and closing double-quote characters: .. raw:: latex \begin{small} .. productionlist:: quoted_argument: '"' `quoted_element`* '"' quoted_element: <any character except '\' or '"'> | : `escape_sequence` | : `quoted_continuation` quoted_continuation: '\' `newline` .. raw:: latex \end{small} 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. .. No code-block syntax highlighting in the following example (escape \" not supported by our cmake.py) For example: .. code-block:: cmake 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. ") .. No code-block syntax highlighting in the following example (for conformity with the two above examples) 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: .. code-block:: cmake 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. .. _`Unquoted Argument`: 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: .. raw:: latex \begin{small} .. productionlist:: unquoted_argument: `unquoted_element`+ | `unquoted_legacy` unquoted_element: <any character except whitespace or one of '()#"\'> | : `escape_sequence` unquoted_legacy: <see note in text> .. raw:: latex \end{small} 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: .. code-block:: cmake 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. .. _`Escape Sequences`: Escape Sequences ---------------- An *escape sequence* is a ``\`` followed by one character: .. raw:: latex \begin{small} .. productionlist:: escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon` escape_identity: '\' <match '[^A-Za-z0-9;]'> escape_encoded: '\t' | '\r' | '\n' escape_semicolon: '\;' .. raw:: latex \end{small} 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 :policy:`CMP0053` documentation for historical considerations.) .. _`Variable References`: 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 :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 :variable:`CACHE` for more information. The :command:`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>}``. Comments -------- A comment starts with a ``#`` character that is not inside a `Bracket Argument`_, `Quoted Argument`_, or escaped with ``\`` as part of an `Unquoted Argument`_. There are two types of comments: a `Bracket Comment`_ and a `Line Comment`_. .. _`Bracket Comment`: Bracket Comment ^^^^^^^^^^^^^^^ A ``#`` immediately followed by a :token:`bracket_open` forms a *bracket comment* consisting of the entire bracket enclosure: .. raw:: latex \begin{small} .. productionlist:: bracket_comment: '#' `bracket_argument` .. raw:: latex \end{small} 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`_. .. _`Line Comment`: Line Comment ^^^^^^^^^^^^ A ``#`` not immediately followed by a :token:`bracket_open` forms a *line comment* that runs until the end of the line: .. raw:: latex \begin{small} .. productionlist:: line_comment: '#' <any text not starting in a `bracket_open` : and not containing a `newline`> .. raw:: latex \end{small} For example: .. code-block:: cmake # This is a line comment. message("First Argument\n" # This is a line comment :) "Second Argument") # This is a line comment. Control Structures ================== Conditional Blocks ------------------ The :command:`if`/:command:`elseif`/:command:`else`/:command:`endif` commands delimit code blocks to be executed conditionally. Loops ----- The :command:`foreach`/:command:`endforeach` and :command:`while`/:command:`endwhile` commands delimit code blocks to be executed in a loop. Inside such blocks the :command:`break` command may be used to terminate the loop early whereas the :command:`continue` command may be used to start with the next iteration immediately. Command Definitions ------------------- The :command:`macro`/:command:`endmacro`, and :command:`function`/:command:`endfunction` commands delimit code blocks to be recorded for later invocation as commands. .. _`CMake Language Variables`: 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 :command:`set` and :command:`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 :command:`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 :command:`set` and :command:`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 :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. .. include:: ID_RESERVE.txt .. _`CMake Language Environment Variables`: 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 :command:`set` and :command:`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 :manual:`cmake-env-variables(7)` manual documents environment variables that have special meaning to CMake. .. _`CMake Language Lists`: 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 :command:`set` command stores multiple values into the destination variable as a list: .. code-block:: cmake 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: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" PK ! M1�� � presets/example.jsonnu �[��� { "version": 3, "cmakeMinimumRequired": { "major": 3, "minor": 21, "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" }, { "name": "windows-only", "inherits": "default", "displayName": "Windows-only configuration", "description": "This build is only available on Windows", "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Windows" } } ], "buildPresets": [ { "name": "default", "configurePreset": "default" } ], "testPresets": [ { "name": "default", "configurePreset": "default", "output": {"outputOnFailure": true}, "execution": {"noTestsAction": "error", "stopOnFailure": true} } ], "vendor": { "example.com/ExampleIDE/1.0": { "autoFormat": false } } } PK ! � ��� �� presets/schema.jsonnu �[��� { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "description": "The presets specify the generator and the build directory, and optionally a list of variables and other arguments to pass to CMake.", "oneOf": [ { "properties": { "version": { "const": 1, "description": "A required integer representing the version of the JSON schema." }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} }, "additionalProperties": false }, { "properties": { "version": { "const": 2, "description": "A required integer representing the version of the JSON schema." }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, "testPresets": { "$ref": "#/definitions/testPresetsV2"} }, "additionalProperties": false }, { "properties": { "version": { "const": 3, "description": "A required integer representing the version of the JSON schema." }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV3"}, "testPresets": { "$ref": "#/definitions/testPresetsV3"} }, "additionalProperties": false } ], "required": [ "version" ], "definitions": { "cmakeMinimumRequired": { "type": "object", "description": "An optional object representing the minimum version of CMake needed to build this project.", "properties": { "major": { "type": "integer", "description": "An optional integer representing the major version." }, "minor": { "type": "integer", "description": "An optional integer representing the minor version." }, "patch": { "type": "integer", "description": "An optional integer representing the patch version." } }, "additionalProperties": false }, "vendor": { "type": "object", "description": "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.", "properties": {} }, "configurePresetsItemsV3": { "type": "array", "description": "A configure preset object.", "items": { "type": "object", "description": "A configure preset object.", "properties": { "binaryDir": { "type": "string", "description": "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, the path is calculated using regular methods." }, "generator": { "type": "string", "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. 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." }, "toolchainFile": { "type": "string", "description": "An optional string representing the path to the toolchain file. This field supports macro expansion. If a relative path is specified, it is calculated relative to the build directory, and if not found, relative to the source directory." }, "installDir": { "type": "string", "description": "An optional string representing the path to the installation directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory." }, "condition": { "$ref": "#/definitions/topCondition" } } } }, "configurePresetsItemsV1": { "type": "array", "description": "An optional array of configure preset objects.", "items": { "type": "object", "description": "A configure preset object.", "properties": { "name": { "type": "string", "description": "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.", "minLength": 1 }, "hidden": { "type": "boolean", "description": "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": { "anyOf": [ { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", "minLength": 1 }, { "type": "array", "description": "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 must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", "minLength": 1 } } ] }, "vendor": { "type": "object", "description": "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.", "properties": {} }, "displayName": { "type": "string", "description": "An optional string with a human-friendly name of the preset." }, "description": { "type": "string", "description": "An optional string with a human-friendly description of the preset." }, "generator": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "description": "An optional string representing the platform for generators that support it." }, { "type": "object", "description": "An optional object representing the platform for generators that support it.", "properties": { "value": { "type": "string", "description": "An optional string representing the value." }, "strategy": { "type": "string", "description": "An optional string telling CMake how to handle the 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.", "enum": [ "set", "external" ] } }, "additionalProperties": false } ] }, "toolset": { "anyOf": [ { "type": "string", "description": "An optional string representing the toolset for generators that support it." }, { "type": "object", "description": "An optional object representing the toolset for generators that support it.", "properties": { "value": { "type": "string", "description": "An optional string representing the value." }, "strategy": { "type": "string", "description": "An optional string telling CMake how to handle the 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.", "enum": [ "set", "external" ] } }, "additionalProperties": false } ] }, "binaryDir": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "object", "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). 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.", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "null", "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, { "type": "boolean", "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." }, { "type": "string", "description": "A string representing the value of the variable (which supports macro expansion)." }, { "type": "object", "description": "An object representing the type and value of the variable.", "properties": { "type": { "type": "string", "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL." }, "value": { "anyOf": [ { "type": "boolean", "description": "A required boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." }, { "type": "string", "description": "A required string representing the value of the variable. This field supports macro expansion." } ] } }, "required": [ "value" ], "additionalProperties": false } ] }, "propertyNames": { "pattern": "^.+$" } }, "environment": { "type": "object", "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). 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.", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "null", "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, { "type": "string", "description": "A string representing the value of the variable." } ] }, "propertyNames": { "pattern": "^.+$" } }, "warnings": { "type": "object", "description": "An optional object specifying warnings.", "properties": { "dev": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "An optional boolean. Setting this to true is equivalent to passing --warn-uninitialized on the command line." }, "unusedCli": { "type": "boolean", "description": "An optional boolean. Setting this to false is equivalent to passing --no-warn-unused-cli on the command line." }, "systemVars": { "type": "boolean", "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." } }, "additionalProperties": false }, "errors": { "type": "object", "description": "An optional object specifying errors.", "properties": { "dev": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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." } }, "additionalProperties": false }, "debug": { "type": "object", "description": "An optional object specifying debug options.", "properties": { "output": { "type": "boolean", "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." }, "tryCompile": { "type": "boolean", "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." }, "find": { "type": "boolean", "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." } }, "additionalProperties": false } } } }, "configurePresetsV3": { "type": "array", "description": "An optional array of configure preset objects.", "allOf": [ { "$ref": "#/definitions/configurePresetsItemsV1" }, { "$ref": "#/definitions/configurePresetsItemsV3" } ], "items": { "properties": { "name": {}, "hidden": {}, "inherits": {}, "vendor": {}, "displayName": {}, "description": {}, "generator": {}, "architecture": {}, "toolset": {}, "toolchainFile": {}, "binaryDir": {}, "installDir": {}, "cmakeExecutable": {}, "cacheVariables": {}, "environment": {}, "warnings": {}, "errors": {}, "debug": {}, "condition": {} }, "required": [ "name" ], "additionalProperties": false } }, "configurePresetsV1": { "type": "array", "description": "An optional array of configure preset objects.", "allOf": [ { "$ref": "#/definitions/configurePresetsItemsV1" } ], "items": { "properties": { "name": {}, "hidden": {}, "inherits": {}, "vendor": {}, "displayName": {}, "description": {}, "generator": {}, "architecture": {}, "toolset": {}, "binaryDir": {}, "cmakeExecutable": {}, "cacheVariables": {}, "environment": {}, "warnings": {}, "errors": {}, "debug": {} }, "required": [ "name" ], "additionalProperties": false } }, "buildPresetsItemsV3": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { "type": "object", "properties": { "condition": { "$ref": "#/definitions/topCondition" } } } }, "buildPresetsItemsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "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 (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", "description": "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 configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ { "type": "string", "description": "An optional string representing the name of the build preset to inherit from.", "minLength": 1 }, { "type": "array", "description": "An optional array of strings representing the names of build 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 must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", "minLength": 1 } } ] }, "configurePreset": { "type": "string", "description": "An optional string specifying the name of a configure preset to associate with this build preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", "minLength": 1 }, "vendor": { "type": "object", "description": "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.", "properties": {} }, "displayName": { "type": "string", "description": "An optional string with a human-friendly name of the preset." }, "description": { "type": "string", "description": "An optional string with a human-friendly description of the preset." }, "inheritConfigureEnvironment": { "type": "boolean", "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset." }, "environment": { "type": "object", "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). 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.", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "null", "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, { "type": "string", "description": "A string representing the value of the variable." } ] }, "propertyNames": { "pattern": "^.+$" } }, "jobs": { "type": "integer", "description": "An optional integer. Equivalent to passing --parallel or -j on the command line." }, "targets": { "anyOf": [ { "type": "string", "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." }, { "type": "array", "description": "An optional array of strings. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets.", "items": { "type": "string", "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." } } ] }, "configuration": { "type": "string", "description": "An optional string. Equivalent to passing --config on the command line." }, "cleanFirst": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --clean-first on the command line." }, "verbose": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --verbose on the command line." }, "nativeToolOptions": { "type": "array", "description": "An optional array of strings. Equivalent to passing options after -- on the command line.", "items": { "type": "string", "description": "An optional string representing an option to pass after -- on the command line." } } }, "required": [ "name" ] } }, "buildPresetsV3": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "allOf": [ { "$ref": "#/definitions/buildPresetsItemsV3" }, { "$ref": "#/definitions/buildPresetsItemsV2" } ], "items": { "type": "object", "properties": { "name": {}, "hidden": {}, "inherits": {}, "configurePreset": {}, "vendor": {}, "displayName": {}, "description": {}, "inheritConfigureEnvironment": {}, "environment": {}, "jobs": {}, "targets": {}, "configuration": {}, "cleanFirst": {}, "verbose": {}, "nativeToolOptions": {}, "condition": {} }, "required": [ "name" ], "additionalProperties": false } }, "buildPresetsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "allOf": [ { "$ref": "#/definitions/buildPresetsItemsV2" } ], "items": { "type": "object", "properties": { "name": {}, "hidden": {}, "inherits": {}, "configurePreset": {}, "vendor": {}, "displayName": {}, "description": {}, "inheritConfigureEnvironment": {}, "environment": {}, "jobs": {}, "targets": {}, "configuration": {}, "cleanFirst": {}, "verbose": {}, "nativeToolOptions": {} }, "required": [ "name" ], "additionalProperties": false } }, "testPresetsItemsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { "type": "object", "properties": { "condition": { "$ref": "#/definitions/topCondition" } } } }, "testPresetsItemsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "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 (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", "description": "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 configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ { "type": "string", "description": "An optional string representing the name of the test preset to inherit from.", "minLength": 1 }, { "type": "array", "description": "An optional array of strings representing the names of test 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 must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", "minLength": 1 } } ] }, "configurePreset": { "type": "string", "description": "An optional string specifying the name of a configure preset to associate with this test preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", "minLength": 1 }, "vendor": { "type": "object", "description": "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.", "properties": {} }, "displayName": { "type": "string", "description": "An optional string with a human-friendly name of the preset." }, "description": { "type": "string", "description": "An optional string with a human-friendly description of the preset." }, "inheritConfigureEnvironment": { "type": "boolean", "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset." }, "environment": { "type": "object", "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). 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.", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "null", "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, { "type": "string", "description": "A string representing the value of the variable." } ] }, "propertyNames": { "pattern": "^.+$" } }, "configuration": { "type": "string", "description": "An optional string. Equivalent to passing --build-config on the command line." }, "overwriteConfigurationFile": { "type": "array", "description": "An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing ``--overwrite`` for each value in the array.", "items": { "type": "string", "description": "An option written as a key-value pair in the form \"key=value\"." } }, "output": { "type": "object", "description": "An optional object specifying output options.", "properties": { "shortProgress": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --progress on the command line." }, "verbosity": { "type": "string", "description": "An optional string specifying verbosity level. Valid values are \"default\" (equivalent to passing no verbosity flags on the command line), \"verbose\" (equivalent to passing --verbose on the command line), and \"extra\" (equivalent to passing --extra-verbose on the command line).", "enum": [ "default", "verbose", "extra" ] }, "debug": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --debug on the command line." }, "outputOnFailure": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --output-on-failure on the command line." }, "quiet": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --quiet on the command line." }, "outputLogFile": { "type": "string", "description": "An optional string specifying a path to a log file. Equivalent to passing --output-log on the command line." }, "labelSummary": { "type": "boolean", "description": "An optional boolean. If false, equivalent to passing --no-label-summary on the command line." }, "subprojectSummary": { "type": "boolean", "description": "An optional boolean. If false, equivalent to passing --no-subproject-summary on the command line." }, "maxPassedTestOutputSize": { "type": "integer", "description": "An optional integer specifying the maximum output for passed tests in bytes. Equivalent to passing --test-output-size-passed on the command line." }, "maxFailedTestOutputSize": { "type": "integer", "description": "An optional integer specifying the maximum output for failed tests in bytes. Equivalent to passing --test-output-size-failed on the command line." }, "maxTestNameWidth": { "type": "integer", "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." } }, "additionalProperties": false }, "filter": { "type": "object", "description": "An optional object specifying how to filter the tests to run.", "properties": { "include": { "type": "object", "description": "An optional object specifying which tests to include.", "properties": { "name": { "type": "string", "description": "An optional string specifying a regex for test names. Equivalent to passing --tests-regex on the command line." }, "label": { "type": "string", "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-regex on the command line." }, "index": { "anyOf": [ { "type": "object", "description": "An optional object specifying tests to include by test index.", "properties": { "start": { "type": "integer", "description": "An optional integer specifying a test index to start testing at." }, "end": { "type": "integer", "description": "An optional integer specifying a test index to stop testing at." }, "stride": { "type": "integer", "description": "An optional integer specifying the increment." }, "specificTests": { "type": "array", "description": "An optional array of integers specifying specific test indices to run.", "items": { "type": "integer", "description": "An integer specifying the test to run by index." } } }, "additionalProperties": false }, { "type": "string", "description": "An optional string specifying a file with the command line syntax for --tests-information." } ] }, "useUnion": { "type": "boolean", "description": "An optional boolean. Equivalent to passing --union on the command line." } }, "additionalProperties": false }, "exclude": { "type": "object", "description": "An optional object specifying which tests to exclude.", "properties": { "name": { "type": "string", "description": "An optional string specifying a regex for test names. Equivalent to passing --exclude-regex on the command line." }, "label": { "type": "string", "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-exclude on the command line." }, "fixtures": { "type": "object", "description": "An optional object specifying which fixtures to exclude from adding tests.", "properties": { "any": { "type": "string", "description": "An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to --fixture-exclude-any on the command line." }, "setup": { "type": "string", "description": "An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to --fixture-exclude-setup on the command line." }, "cleanup": { "type": "string", "description": "An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to --fixture-exclude-cleanup on the command line." } }, "additionalProperties": false } } } }, "additionalProperties": false }, "execution": { "type": "object", "description": "An optional object specifying options for test execution.", "properties": { "stopOnFailure": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --stop-on-failure on the command line." }, "enableFailover": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing -F on the command line." }, "jobs": { "type": "integer", "description": "An optional integer. Equivalent to passing --parallel on the command line." }, "resourceSpecFile": { "type": "string", "description": "An optional string. Equivalent to passing --resource-spec-file on the command line." }, "testLoad": { "type": "integer", "description": "An optional integer. Equivalent to passing --test-load on the command line." }, "showOnly": { "type": "string", "description": "An optional string. Equivalent to passing --show-only on the command line. Value must be \"human\" or \"json-v1\".", "enum": [ "human", "json-v1" ] }, "repeat": { "type": "object", "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", "properties": { "mode": { "type": "string", "description": "A required string. Must be one of the following values: \"until-fail\", \"until-pass\", or \"after-timeout\".", "enum": [ "until-fail", "until-pass", "after-timeout" ] }, "count": { "type": "integer", "description": "A required integer." } }, "required": [ "mode", "count" ], "additionalProperties": false }, "interactiveDebugging": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --interactive-debug-mode 1 on the command line. If false, equivalent to passing --interactive-debug-mode 0 on the command line." }, "scheduleRandom": { "type": "boolean", "description": "An optional boolean. If true, equivalent to passing --schedule-random on the command line." }, "timeout": { "type": "integer", "description": "An optional integer. Equivalent to passing --timeout on the command line." }, "noTestsAction": { "type": "string", "description": "An optional string specifying the behavior if no tests are found. Must be one of the following values: \"default\" (equivalent to not passing any value on the command line), \"error\" (equivalent to passing --no-tests=error on the command line), or \"ignore\" (equivalent to passing --no-tests-ignore on the command line).", "enum": [ "default", "error", "ignore" ] } }, "additionalProperties": false } }, "required": [ "name" ] } }, "testPresetsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "allOf": [ { "$ref": "#/definitions/testPresetsItemsV2" }, { "$ref": "#/definitions/testPresetsItemsV3" } ], "items": { "type": "object", "properties": { "name": {}, "hidden": {}, "inherits": {}, "configurePreset": {}, "vendor": {}, "displayName": {}, "description": {}, "inheritConfigureEnvironment": {}, "environment": {}, "configuration": {}, "overwriteConfigurationFile": {}, "output": {}, "filter": {}, "execution": {}, "condition": {} }, "required": [ "name" ], "additionalProperties": false } }, "testPresetsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "allOf": [ { "$ref": "#/definitions/testPresetsItemsV2" } ], "items": { "type": "object", "properties": { "name": {}, "hidden": {}, "inherits": {}, "configurePreset": {}, "vendor": {}, "displayName": {}, "description": {}, "inheritConfigureEnvironment": {}, "environment": {}, "configuration": {}, "overwriteConfigurationFile": {}, "output": {}, "filter": {}, "execution": {} }, "required": [ "name" ], "additionalProperties": false } }, "condition": { "anyOf": [ { "type": "boolean", "description": "A boolean which provides a constant value for the condition's evaluation." }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "const" }, "value": { "type": "boolean", "description": "A required boolean which provides a constant value for the condition's evaluation." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "equals" }, "lhs": { "type": "string", "description": "First string to compare. This field supports macro expansion." }, "rhs": { "type": "string", "description": "Second string to compare. This field supports macro expansion." } }, "required": [ "type", "lhs", "rhs" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "notEquals" }, "lhs": { "type": "string", "description": "First string to compare. This field supports macro expansion." }, "rhs": { "type": "string", "description": "Second string to compare. This field supports macro expansion." } }, "required": [ "type", "lhs", "rhs" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "inList" }, "string": { "type": "string", "description": "A required string to search for. This field supports macro expansion." }, "list": { "type": "array", "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", "items": { "type": "string" } } }, "required": [ "type", "string", "list" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "notInList" }, "string": { "type": "string", "description": "A required string to search for. This field supports macro expansion." }, "list": { "type": "array", "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", "items": { "type": "string" } } }, "required": [ "type", "string", "list" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "matches" }, "string": { "type": "string", "description": "A required string to search. This field supports macro expansion." }, "regex": { "type": "string", "description": "A required regular expression to search for. This field supports macro expansion." } }, "required": [ "type", "string", "regex" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "notMatches" }, "string": { "type": "string", "description": "A required string to search. This field supports macro expansion." }, "regex": { "type": "string", "description": "A required regular expression to search for. This field supports macro expansion." } }, "required": [ "type", "string", "regex" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "anyOf" }, "conditions": { "type": "array", "description": "A required array of condition objects. These conditions use short-circuit evaluation.", "items": { "$ref": "#/definitions/condition" } } }, "required": [ "type", "conditions" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "allOf" }, "conditions": { "type": "array", "description": "A required array of condition objects. These conditions use short-circuit evaluation.", "items": { "$ref": "#/definitions/condition" } } }, "required": [ "type", "conditions" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "description": "A required string specifying the type of the condition.", "const": "not" }, "condition": { "$ref": "#/definitions/condition" } }, "required": [ "type", "condition" ], "additionalProperties": false } ] }, "topCondition": { "anyOf": [ { "$ref": "#/definitions/condition" }, { "type": "null", "description": "Null indicates that the condition always evaluates to true and is not inherited." } ] } } } PK ! )A�� � cpack-generators.7.rstnu �[��� .. cmake-manual-description: CPack Generator Reference cpack-generators(7) ******************* .. only:: html .. contents:: Generators ========== .. toctree:: :maxdepth: 1 /cpack_gen/archive /cpack_gen/bundle /cpack_gen/cygwin /cpack_gen/deb /cpack_gen/dmg /cpack_gen/external /cpack_gen/freebsd /cpack_gen/ifw /cpack_gen/nsis /cpack_gen/nuget /cpack_gen/packagemaker /cpack_gen/productbuild /cpack_gen/rpm /cpack_gen/wix PK ! cɤ�!H !H cmake-properties.7.rstnu �[��� .. cmake-manual-description: CMake Properties Reference cmake-properties(7) ******************* .. only:: html .. contents:: .. _`Global Properties`: Properties of Global Scope ========================== .. toctree:: :maxdepth: 1 /prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS /prop_gbl/AUTOGEN_SOURCE_GROUP /prop_gbl/AUTOGEN_TARGETS_FOLDER /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/AUTOUIC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/ECLIPSE_EXTRA_NATURES /prop_gbl/ENABLED_FEATURES /prop_gbl/ENABLED_LANGUAGES /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS /prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING /prop_gbl/GENERATOR_IS_MULTI_CONFIG /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES /prop_gbl/IN_TRY_COMPILE /prop_gbl/JOB_POOLS /prop_gbl/PACKAGES_FOUND /prop_gbl/PACKAGES_NOT_FOUND /prop_gbl/PREDEFINED_TARGETS_FOLDER /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM /prop_gbl/RULE_LAUNCH_LINK /prop_gbl/RULE_MESSAGES /prop_gbl/TARGET_ARCHIVES_MAY_BE_SHARED_LIBS /prop_gbl/TARGET_MESSAGES /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS /prop_gbl/USE_FOLDERS /prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME .. _`Directory Properties`: Properties on Directories ========================= .. toctree:: :maxdepth: 1 /prop_dir/ADDITIONAL_CLEAN_FILES /prop_dir/BINARY_DIR /prop_dir/BUILDSYSTEM_TARGETS /prop_dir/CACHE_VARIABLES /prop_dir/CLEAN_NO_CUSTOM /prop_dir/CMAKE_CONFIGURE_DEPENDS /prop_dir/COMPILE_DEFINITIONS /prop_dir/COMPILE_OPTIONS /prop_dir/DEFINITIONS /prop_dir/EXCLUDE_FROM_ALL /prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_dir/IMPORTED_TARGETS /prop_dir/INCLUDE_DIRECTORIES /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_dir/LABELS /prop_dir/LINK_DIRECTORIES /prop_dir/LINK_OPTIONS /prop_dir/LISTFILE_STACK /prop_dir/MACROS /prop_dir/PARENT_DIRECTORY /prop_dir/RULE_LAUNCH_COMPILE /prop_dir/RULE_LAUNCH_CUSTOM /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES /prop_dir/TESTS /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section /prop_dir/VS_STARTUP_PROJECT .. _`Target Properties`: Properties on Targets ===================== .. toctree:: :maxdepth: 1 /prop_tgt/ADDITIONAL_CLEAN_FILES /prop_tgt/AIX_EXPORT_ALL_SYMBOLS /prop_tgt/ALIAS_GLOBAL /prop_tgt/ALIASED_TARGET /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS /prop_tgt/ANDROID_API /prop_tgt/ANDROID_API_MIN /prop_tgt/ANDROID_ARCH /prop_tgt/ANDROID_ASSETS_DIRECTORIES /prop_tgt/ANDROID_GUI /prop_tgt/ANDROID_JAR_DEPENDENCIES /prop_tgt/ANDROID_JAR_DIRECTORIES /prop_tgt/ANDROID_JAVA_SOURCE_DIR /prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES /prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES /prop_tgt/ANDROID_PROCESS_MAX /prop_tgt/ANDROID_PROGUARD /prop_tgt/ANDROID_PROGUARD_CONFIG_PATH /prop_tgt/ANDROID_SECURE_PROPS_PATH /prop_tgt/ANDROID_SKIP_ANT_STEP /prop_tgt/ANDROID_STL_TYPE /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/AUTOGEN_BUILD_DIR /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC_PATH_PREFIX /prop_tgt/AUTORCC /prop_tgt/AUTORCC_EXECUTABLE /prop_tgt/AUTORCC_OPTIONS /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH /prop_tgt/BUILD_RPATH_USE_ORIGIN /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE /prop_tgt/BUNDLE_EXTENSION /prop_tgt/C_EXTENSIONS /prop_tgt/C_STANDARD /prop_tgt/C_STANDARD_REQUIRED /prop_tgt/COMMON_LANGUAGE_RUNTIME /prop_tgt/COMPATIBLE_INTERFACE_BOOL /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN /prop_tgt/COMPATIBLE_INTERFACE_STRING /prop_tgt/COMPILE_DEFINITIONS /prop_tgt/COMPILE_FEATURES /prop_tgt/COMPILE_FLAGS /prop_tgt/COMPILE_OPTIONS /prop_tgt/COMPILE_PDB_NAME /prop_tgt/COMPILE_PDB_NAME_CONFIG /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR /prop_tgt/CUDA_ARCHITECTURES /prop_tgt/CUDA_EXTENSIONS /prop_tgt/CUDA_PTX_COMPILATION /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS /prop_tgt/CUDA_RUNTIME_LIBRARY /prop_tgt/CUDA_SEPARABLE_COMPILATION /prop_tgt/CUDA_STANDARD /prop_tgt/CUDA_STANDARD_REQUIRED /prop_tgt/CXX_EXTENSIONS /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS /prop_tgt/EXCLUDE_FROM_ALL /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXPORT_COMPILE_COMMANDS /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS /prop_tgt/FRAMEWORK /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME /prop_tgt/GHS_INTEGRITY_APP /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/HIP_ARCHITECTURES /prop_tgt/HIP_EXTENSIONS /prop_tgt/HIP_STANDARD /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME /prop_tgt/IMPORTED_CONFIGURATIONS /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_LIBNAME /prop_tgt/IMPORTED_LIBNAME_CONFIG /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/IMPORTED_LOCATION /prop_tgt/IMPORTED_LOCATION_CONFIG /prop_tgt/IMPORTED_NO_SONAME /prop_tgt/IMPORTED_NO_SONAME_CONFIG /prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED_OBJECTS_CONFIG /prop_tgt/IMPORTED_SONAME /prop_tgt/IMPORTED_SONAME_CONFIG /prop_tgt/IMPORT_PREFIX /prop_tgt/IMPORT_SUFFIX /prop_tgt/INCLUDE_DIRECTORIES /prop_tgt/INSTALL_NAME_DIR /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH /prop_tgt/INTERFACE_AUTOUIC_OPTIONS /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERPROCEDURAL_OPTIMIZATION /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/IOS_INSTALL_COMBINED /prop_tgt/ISPC_HEADER_DIRECTORY /prop_tgt/ISPC_HEADER_SUFFIX /prop_tgt/ISPC_INSTRUCTION_SETS /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK /prop_tgt/JOB_POOL_PRECOMPILE_HEADER /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_LINKER_LAUNCHER /prop_tgt/LANG_STANDARD /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG /prop_tgt/LIBRARY_OUTPUT_NAME /prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG /prop_tgt/LINK_DEPENDS /prop_tgt/LINK_DEPENDS_NO_SHARED /prop_tgt/LINK_DIRECTORIES /prop_tgt/LINK_FLAGS /prop_tgt/LINK_FLAGS_CONFIG /prop_tgt/LINK_INTERFACE_LIBRARIES /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LINKER_LANGUAGE /prop_tgt/LOCATION /prop_tgt/LOCATION_CONFIG /prop_tgt/MACHO_COMPATIBILITY_VERSION /prop_tgt/MACHO_CURRENT_VERSION /prop_tgt/MACOSX_BUNDLE /prop_tgt/MACOSX_BUNDLE_INFO_PLIST /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST /prop_tgt/MACOSX_RPATH /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG /prop_tgt/MSVC_RUNTIME_LIBRARY /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED /prop_tgt/OBJC_EXTENSIONS /prop_tgt/OBJC_STANDARD /prop_tgt/OBJC_STANDARD_REQUIRED /prop_tgt/OBJCXX_EXTENSIONS /prop_tgt/OBJCXX_STANDARD /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OPTIMIZE_DEPENDENCIES /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OUTPUT_NAME /prop_tgt/OUTPUT_NAME_CONFIG /prop_tgt/PCH_WARN_INVALID /prop_tgt/PCH_INSTANTIATE_TEMPLATES /prop_tgt/PDB_NAME /prop_tgt/PDB_NAME_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/POSITION_INDEPENDENT_CODE /prop_tgt/PRECOMPILE_HEADERS /prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL /prop_tgt/PUBLIC_HEADER /prop_tgt/RESOURCE /prop_tgt/RULE_LAUNCH_COMPILE /prop_tgt/RULE_LAUNCH_CUSTOM /prop_tgt/RULE_LAUNCH_LINK /prop_tgt/RUNTIME_OUTPUT_DIRECTORY /prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG /prop_tgt/RUNTIME_OUTPUT_NAME /prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG /prop_tgt/SKIP_BUILD_RPATH /prop_tgt/SOURCE_DIR /prop_tgt/SOURCES /prop_tgt/SOVERSION /prop_tgt/STATIC_LIBRARY_FLAGS /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX /prop_tgt/Swift_DEPENDENCIES_FILE /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE /prop_tgt/UNITY_BUILD /prop_tgt/UNITY_BUILD_BATCH_SIZE /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/UNITY_BUILD_MODE /prop_tgt/UNITY_BUILD_UNIQUE_ID /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE /prop_tgt/VS_DEBUGGER_COMMAND /prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS /prop_tgt/VS_DEBUGGER_ENVIRONMENT /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_DOCUMENTATION_FILE /prop_tgt/VS_DOTNET_REFERENCE_refname /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_ROOTNAMESPACE /prop_tgt/VS_GLOBAL_variable /prop_tgt/VS_IOT_EXTENSIONS_VERSION /prop_tgt/VS_IOT_STARTUP_TASK /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_PACKAGE_REFERENCES /prop_tgt/VS_PLATFORM_TOOLSET /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER /prop_tgt/VS_SDK_REFERENCES /prop_tgt/VS_SOLUTION_DEPLOY /prop_tgt/VS_SOURCE_SETTINGS_tool /prop_tgt/VS_USER_PROPS /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS /prop_tgt/VS_WINRT_REFERENCES /prop_tgt/WIN32_EXECUTABLE /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EMBED_type /prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_type_PATH /prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCODE_SCHEME_EXECUTABLE /prop_tgt/XCODE_SCHEME_GUARD_MALLOC /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE /prop_tgt/XCODE_SCHEME_MALLOC_STACK /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCTEST .. _`Test Properties`: Properties on Tests =================== .. toctree:: :maxdepth: 1 /prop_test/ATTACHED_FILES /prop_test/ATTACHED_FILES_ON_FAIL /prop_test/COST /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED /prop_test/FIXTURES_SETUP /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL /prop_test/SKIP_REGULAR_EXPRESSION /prop_test/SKIP_RETURN_CODE /prop_test/TIMEOUT /prop_test/TIMEOUT_AFTER_MATCH /prop_test/WILL_FAIL /prop_test/WORKING_DIRECTORY .. _`Source File Properties`: Properties on Source Files ========================== .. toctree:: :maxdepth: 1 /prop_sf/ABSTRACT /prop_sf/AUTORCC_OPTIONS /prop_sf/AUTOUIC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS /prop_sf/COMPILE_OPTIONS /prop_sf/EXTERNAL_OBJECT /prop_sf/Fortran_FORMAT /prop_sf/Fortran_PREPROCESS /prop_sf/GENERATED /prop_sf/HEADER_FILE_ONLY /prop_sf/INCLUDE_DIRECTORIES /prop_sf/KEEP_EXTENSION /prop_sf/LABELS /prop_sf/LANGUAGE /prop_sf/LOCATION /prop_sf/MACOSX_PACKAGE_LOCATION /prop_sf/OBJECT_DEPENDS /prop_sf/OBJECT_OUTPUTS /prop_sf/SKIP_AUTOGEN /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC /prop_sf/SKIP_PRECOMPILE_HEADERS /prop_sf/SKIP_UNITY_BUILD_INCLUSION /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC /prop_sf/UNITY_GROUP /prop_sf/VS_COPY_TO_OUT_DIR /prop_sf/VS_CSHARP_tagname /prop_sf/VS_DEPLOYMENT_CONTENT /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR /prop_sf/VS_SETTINGS /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL /prop_sf/VS_SHADER_OBJECT_FILE_NAME /prop_sf/VS_SHADER_OUTPUT_HEADER_FILE /prop_sf/VS_SHADER_TYPE /prop_sf/VS_SHADER_VARIABLE_NAME /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE /prop_sf/XCODE_EXPLICIT_FILE_TYPE /prop_sf/XCODE_FILE_ATTRIBUTES /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE .. _`Cache Entry Properties`: Properties on Cache Entries =========================== .. toctree:: :maxdepth: 1 /prop_cache/ADVANCED /prop_cache/HELPSTRING /prop_cache/MODIFIED /prop_cache/STRINGS /prop_cache/TYPE /prop_cache/VALUE .. _`Installed File Properties`: Properties on Installed Files ============================= .. toctree:: :maxdepth: 1 /prop_inst/CPACK_DESKTOP_SHORTCUTS.rst /prop_inst/CPACK_NEVER_OVERWRITE.rst /prop_inst/CPACK_PERMANENT.rst /prop_inst/CPACK_START_MENU_SHORTCUTS.rst /prop_inst/CPACK_STARTUP_SHORTCUTS.rst /prop_inst/CPACK_WIX_ACL.rst Deprecated Properties on Directories ==================================== .. toctree:: :maxdepth: 1 /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES /prop_dir/COMPILE_DEFINITIONS_CONFIG /prop_dir/TEST_INCLUDE_FILE Deprecated Properties on Targets ================================ .. toctree:: :maxdepth: 1 /prop_tgt/COMPILE_DEFINITIONS_CONFIG /prop_tgt/POST_INSTALL_SCRIPT /prop_tgt/PRE_INSTALL_SCRIPT Deprecated Properties on Source Files ===================================== .. toctree:: :maxdepth: 1 /prop_sf/COMPILE_DEFINITIONS_CONFIG PK ! �� �U� U� cmake-buildsystem.7.rstnu �[��� .. cmake-manual-description: CMake Buildsystem Reference cmake-buildsystem(7) ******************** .. only:: html .. contents:: 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. Binary Targets ============== Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. Dependencies between binary targets are expressed using the :command:`target_link_libraries` command: .. code-block:: cmake 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. Binary Executables ------------------ The :command:`add_executable` command defines an executable target: .. code-block:: cmake add_executable(mytool mytool.cpp) Commands such as :command:`add_custom_command`, which generates rules to be run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>` target as a ``COMMAND`` executable. The buildsystem rules will ensure that the executable is built before attempting to run the command. Binary Library Types -------------------- .. _`Normal Libraries`: Normal Libraries ^^^^^^^^^^^^^^^^ By default, the :command:`add_library` command defines a ``STATIC`` library, unless a type is specified. A type may be specified when using the command: .. code-block:: cmake add_library(archive SHARED archive.cpp zip.cpp lzma.cpp) .. code-block:: cmake add_library(archive STATIC archive.cpp zip.cpp lzma.cpp) The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the behavior of :command:`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 :command:`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. .. code-block:: cmake add_library(archive MODULE 7z.cpp) .. _`Apple Frameworks`: Apple Frameworks """""""""""""""" A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS or iOS Framework Bundle. A library with the ``FRAMEWORK`` target property should also set the :prop_tgt:`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. .. code-block:: cmake 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 ) .. _`Object Libraries`: 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 :manual:`generator expression <cmake-generator-expressions(7)>` that can be used to supply the ``OBJECT`` library content to other targets: .. code-block:: cmake 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: .. code-block:: cmake 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 :command:`add_custom_command(TARGET)` command signature. However, the list of objects can be used by :command:`add_custom_command(OUTPUT)` or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. Build Specification and Usage Requirements ========================================== The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands specify the build specifications and the usage requirements of binary targets. The commands populate the :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and :prop_tgt:`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: .. code-block:: cmake 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 :prop_tgt:`COMPILE_OPTIONS` or :prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of the properties must be **requirements**, not merely recommendations or convenience. See the :ref:`Creating Relocatable Packages` section of the :manual:`cmake-packages(7)` manual for discussion of additional care that must be taken when specifying usage requirements while creating packages for redistribution. Target Properties ----------------- The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target properties are used appropriately when compiling the source files of a binary target. Entries in the :prop_tgt:`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 :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or ``/D`` and added to the compile line in an unspecified order. The :prop_tgt:`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 :prop_tgt:`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 :prop_tgt:`POSITION_INDEPENDENT_CODE`. The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and :prop_tgt:`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 :command:`target_link_libraries` command is consumed: .. code-block:: cmake 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 :prop_tgt:`INCLUDE_DIRECTORIES`, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` can be enabled to add the corresponding directories to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of targets in multiple different directories convenient through use of the :command:`target_link_libraries` command. .. _`Target Usage Requirements`: Transitive Usage Requirements ----------------------------- The usage requirements of a target can transitively propagate to dependents. The :command:`target_link_libraries` command has ``PRIVATE``, ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation. .. code-block:: cmake 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 :command:`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 :command:`target_link_libraries` command may be invoked with multiple uses of each keyword: .. code-block:: cmake 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 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases where order is relevant and maintained, and the order resulting from the :command:`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``: .. code-block:: cmake 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 :command:`install(EXPORT)` command. See :ref:`Creating Packages` for more. .. _`Compatible Interface Properties`: Compatible Interface Properties ------------------------------- Some target properties are required to be compatible between a target and the interface of each dependency. For example, the :prop_tgt:`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 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that consumers must be compiled as position-independent-code. .. code-block:: cmake 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 :manual:`cmake(1)` issues a diagnostic: .. code-block:: cmake 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 :prop_tgt:`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 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, if set must be either the same, in a boolean sense, as the :prop_tgt:`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 :prop_tgt:`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: .. code-block:: cmake 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 :prop_tgt:`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: .. code-block:: cmake 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 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies that content will be evaluated numerically and the maximum number among all specified will be calculated: .. code-block:: cmake 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 :prop_tgt:`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. 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. :manual:`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 :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable documentation: .. code-block:: cmake 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 :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or :prop_tgt:`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 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the value of the property from each dependency, and whether the value determines the new extreme. Build Specification with Generator Expressions ---------------------------------------------- Build specifications may use :manual:`generator expressions <cmake-generator-expressions(7)>` 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: .. code-block:: cmake 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``. 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: .. code-block:: cmake 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 :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 :command:`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 :command:`install(EXPORT)` command: .. code-block:: cmake 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 :prop_tgt:`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: .. code-block:: cmake 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 :manual:`cmake-packages(7)` manual. .. _`Include Directories and Usage Requirements`: Include Directories and Usage Requirements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Include directories require some special consideration when specified as usage requirements and when used with generator expressions. The :command:`target_include_directories` command accepts both relative and absolute include directories: .. code-block:: cmake 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 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`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: .. code-block:: cmake 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 :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable may be enabled, with an equivalent effect to: .. code-block:: cmake 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 :command:`install(TARGETS)` command: .. code-block:: cmake 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 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed :prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`. When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an :ref:`imported target <Imported targets>` is consumed, the entries in the property are treated as ``SYSTEM`` include directories, as if they were listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property on the *consumers* of imported targets. If a binary target is linked transitively to a macOS :prop_tgt:`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. Link Libraries and Generator Expressions ---------------------------------------- Like build specifications, :prop_tgt:`link libraries <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: .. code-block:: cmake 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 :prop_tgt:`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 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above contains a cycle. :manual:`cmake(1)` issues an error message. .. _`Output Artifacts`: Output Artifacts ---------------- The buildsystem targets created by the :command:`add_library` and :command:`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. .. _`Runtime Output Artifacts`: 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 :command:`add_executable` command. * On DLL platforms: the executable file (e.g. ``.dll``) of a shared library target created by the :command:`add_library` command with the ``SHARED`` option. The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME` target properties may be used to control runtime output artifact locations and names in the build tree. .. _`Library Output Artifacts`: 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 :command:`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 :command:`add_library` command with the ``SHARED`` option. The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties may be used to control library output artifact locations and names in the build tree. .. _`Archive Output Artifacts`: 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 :command:`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 :command:`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 :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. * On AIX: the linker import file (e.g. ``.imp``) of an executable target created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. Directory-Scoped Commands ------------------------- The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands have an effect on only one target at a time. The commands :command:`add_compile_definitions`, :command:`add_compile_options` and :command:`include_directories` have a similar function, but operate at directory scope instead of target scope for convenience. .. _`Build Configurations`: Build Configurations ==================== Configurations determine specifications for a certain type of build, such as ``Release`` or ``Debug``. The way this is specified depends on the type of :manual:`generator <cmake-generators(7)>` being used. For single configuration generators like :ref:`Makefile Generators` and :generator:`Ninja`, the configuration is specified at configure time by the :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and :generator:`Ninja Multi-Config`, the configuration is chosen by the user at build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the multi-configuration case, the set of *available* configurations is specified at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, but the actual configuration used cannot be known until the build stage. This difference is often misunderstood, leading to problematic code like the following: .. code-block:: cmake # WARNING: This is wrong for multi-config generators because they don't use # and typically don't even set CMAKE_BUILD_TYPE string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) if (build_type STREQUAL debug) target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) endif() :manual:`Generator expressions <cmake-generator-expressions(7)>` should be used instead to handle configuration-specific logic correctly, regardless of the generator used. For example: .. code-block:: cmake # Works correctly for both single and multi-config generators target_compile_definitions(exe1 PRIVATE $<$<CONFIG:Debug>:DEBUG_BUILD> ) In the presence of :prop_tgt:`IMPORTED` targets, the content of :prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also accounted for by the above ``$<CONFIG:Debug>`` expression. Case Sensitivity ---------------- :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are just like other variables in that any string comparisons made with their values will be case-sensitive. The ``$<CONFIG>`` generator expression also preserves the casing of the configuration as set by the user or CMake defaults. For example: .. code-block:: cmake # NOTE: Don't use these patterns, they are for illustration purposes only. set(CMAKE_BUILD_TYPE Debug) if(CMAKE_BUILD_TYPE STREQUAL DEBUG) # ... will never get here, "Debug" != "DEBUG" endif() add_custom_target(print_config ALL # Prints "Config is Debug" in this single-config case COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>" VERBATIM ) set(CMAKE_CONFIGURATION_TYPES Debug Release) if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) # ... will never get here, "Debug" != "DEBUG" endif() In contrast, CMake treats the configuration type case-insensitively when using it internally in places that modify behavior based on the configuration. For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or even ``DeBuG``. Therefore, you can specify configuration types in :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with any mixture of upper and lowercase, although there are strong conventions (see the next section). If you must test the value in string comparisons, always convert the value to upper or lowercase first and adjust the test accordingly. Default And Custom Configurations --------------------------------- By default, CMake defines a number of standard configurations: * ``Debug`` * ``Release`` * ``RelWithDebInfo`` * ``MinSizeRel`` In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable will be populated with (potentially a subset of) the above list by default, unless overridden by the project or user. The actual configuration used is selected by the user at build time. For single-config generators, the configuration is specified with the :variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed at build time. The default value will often be none of the above standard configurations and will instead be an empty string. A common misunderstanding is that this is the same as ``Debug``, but that is not the case. Users should always explicitly specify the build type instead to avoid this common problem. The above standard configuration types provide reasonable behavior on most platforms, but they can be extended to provide other types. Each configuration defines a set of compiler and linker flag variables for the language in use. These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`, where ``<CONFIG>`` is always the uppercase configuration name. When defining a custom configuration type, make sure these variables are set appropriately, typically as cache variables. 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. .. _`Imported Targets`: Imported Targets ---------------- An :prop_tgt:`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 :prop_tgt:`IMPORTED` target one can adjust its target properties by using the customary commands such as :command:`target_compile_definitions`, :command:`target_include_directories`, :command:`target_compile_options` or :command:`target_link_libraries` just like with any other regular target. :prop_tgt:`IMPORTED` targets may have the same usage requirement properties populated as binary targets, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, :prop_tgt:`INTERFACE_COMPILE_OPTIONS`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there is rarely reason to do so. Commands such as :command:`add_custom_command` can transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target as a ``COMMAND`` executable. The scope of the definition of an :prop_tgt:`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`` :prop_tgt:`IMPORTED` target which is accessible globally in the buildsystem. See the :manual:`cmake-packages(7)` manual for more on creating packages with :prop_tgt:`IMPORTED` targets. .. _`Alias Targets`: 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. .. code-block:: cmake 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 :prop_tgt:`IMPORTED` target from a package, or an ``ALIAS`` target if built as part of the same buildsystem. .. code-block:: cmake 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 :prop_tgt:`ALIASED_TARGET` property from it: .. code-block:: cmake get_target_property(_aliased Upstream::lib1 ALIASED_TARGET) if(_aliased) message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.") endif() .. _`Interface Libraries`: Interface Libraries ------------------- An ``INTERFACE`` library target does not compile sources and does not produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`. It may specify usage requirements such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, :prop_tgt:`INTERFACE_COMPILE_OPTIONS`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, :prop_tgt:`INTERFACE_SOURCES`, and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_compile_definitions`, :command:`target_compile_options`, :command:`target_sources`, and :command:`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. .. code-block:: cmake 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: .. code-block:: cmake 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: .. code-block:: cmake 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 ) PK ! �� R R cmake-modules.7.rstnu �[��� .. cmake-manual-description: CMake Modules Reference 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 :variable:`CMAKE_MODULE_PATH` variable. Utility Modules ^^^^^^^^^^^^^^^ These modules are loaded using the :command:`include` command. .. toctree:: :maxdepth: 1 /module/AndroidTestUtilities /module/BundleUtilities /module/CheckCCompilerFlag /module/CheckCompilerFlag /module/CheckCSourceCompiles /module/CheckCSourceRuns /module/CheckCXXCompilerFlag /module/CheckCXXSourceCompiles /module/CheckCXXSourceRuns /module/CheckCXXSymbolExists /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles /module/CheckFortranSourceRuns /module/CheckFunctionExists /module/CheckIncludeFileCXX /module/CheckIncludeFile /module/CheckIncludeFiles /module/CheckIPOSupported /module/CheckLanguage /module/CheckLibraryExists /module/CheckLinkerFlag /module/CheckOBJCCompilerFlag /module/CheckOBJCSourceCompiles /module/CheckOBJCSourceRuns /module/CheckOBJCXXCompilerFlag /module/CheckOBJCXXSourceCompiles /module/CheckOBJCXXSourceRuns /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckSourceCompiles /module/CheckSourceRuns /module/CheckStructHasMember /module/CheckSymbolExists /module/CheckTypeSize /module/CheckVariableExists /module/CMakeAddFortranSubdirectory /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers /module/CMakePrintHelpers /module/CMakePrintSystemInformation /module/CMakePushCheckState /module/CMakeVerifyManifest /module/CPack /module/CPackComponent /module/CPackIFW /module/CPackIFWConfigureFile /module/CSharpUtilities /module/CTest /module/CTestCoverageCollectGCOV /module/CTestScriptMode /module/CTestUseLaunchers /module/Dart /module/DeployQt4 /module/ExternalData /module/ExternalProject /module/FeatureSummary /module/FetchContent /module/FindPackageHandleStandardArgs /module/FindPackageMessage /module/FortranCInterface /module/GenerateExportHeader /module/GetPrerequisites /module/GNUInstallDirs /module/GoogleTest /module/InstallRequiredSystemLibraries /module/ProcessorCount /module/SelectLibraryConfigurations /module/SquishTestScript /module/TestBigEndian /module/TestForANSIForScope /module/TestForANSIStreamHeaders /module/TestForSSTREAM /module/TestForSTDNamespace /module/UseEcos /module/UseJava /module/UseSWIG /module/UsewxWidgets Find Modules ^^^^^^^^^^^^ These modules search for third-party software. They are normally called through the :command:`find_package` command. .. toctree:: :maxdepth: 1 /module/FindALSA /module/FindArmadillo /module/FindASPELL /module/FindAVIFile /module/FindBacktrace /module/FindBISON /module/FindBLAS /module/FindBoost /module/FindBullet /module/FindBZip2 /module/FindCABLE /module/FindCoin3D /module/FindCUDAToolkit /module/FindCups /module/FindCURL /module/FindCurses /module/FindCVS /module/FindCxxTest /module/FindCygwin /module/FindDart /module/FindDCMTK /module/FindDevIL /module/FindDoxygen /module/FindEnvModules /module/FindEXPAT /module/FindFLEX /module/FindFLTK /module/FindFLTK2 /module/FindFontconfig /module/FindFreetype /module/FindGCCXML /module/FindGDAL /module/FindGettext /module/FindGIF /module/FindGit /module/FindGLEW /module/FindGLUT /module/FindGnuplot /module/FindGnuTLS /module/FindGSL /module/FindGTest /module/FindGTK /module/FindGTK2 /module/FindHDF5 /module/FindHg /module/FindHSPELL /module/FindHTMLHelp /module/FindIce /module/FindIconv /module/FindIcotool /module/FindICU /module/FindImageMagick /module/FindIntl /module/FindITK /module/FindJasper /module/FindJava /module/FindJNI /module/FindJPEG /module/FindKDE3 /module/FindKDE4 /module/FindLAPACK /module/FindLATEX /module/FindLibArchive /module/FindLibinput /module/FindLibLZMA /module/FindLibXml2 /module/FindLibXslt /module/FindLTTngUST /module/FindLua /module/FindLua50 /module/FindLua51 /module/FindMatlab /module/FindMFC /module/FindMotif /module/FindMPEG /module/FindMPEG2 /module/FindMPI /module/FindMsys /module/FindODBC /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL /module/FindOpenGL /module/FindOpenMP /module/FindOpenSceneGraph /module/FindOpenSSL /module/FindOpenThreads /module/Findosg /module/Findosg_functions /module/FindosgAnimation /module/FindosgDB /module/FindosgFX /module/FindosgGA /module/FindosgIntrospection /module/FindosgManipulator /module/FindosgParticle /module/FindosgPresentation /module/FindosgProducer /module/FindosgQt /module/FindosgShadow /module/FindosgSim /module/FindosgTerrain /module/FindosgText /module/FindosgUtil /module/FindosgViewer /module/FindosgVolume /module/FindosgWidget /module/FindPatch /module/FindPerl /module/FindPerlLibs /module/FindPHP4 /module/FindPhysFS /module/FindPike /module/FindPkgConfig /module/FindPNG /module/FindPostgreSQL /module/FindProducer /module/FindProtobuf /module/FindPython /module/FindPython2 /module/FindPython3 /module/FindQt3 /module/FindQt4 /module/FindQuickTime /module/FindRTI /module/FindRuby /module/FindSDL /module/FindSDL_image /module/FindSDL_mixer /module/FindSDL_net /module/FindSDL_sound /module/FindSDL_ttf /module/FindSelfPackers /module/FindSquish /module/FindSQLite3 /module/FindSubversion /module/FindSWIG /module/FindTCL /module/FindTclsh /module/FindTclStub /module/FindThreads /module/FindTIFF /module/FindUnixCommands /module/FindVTK /module/FindVulkan /module/FindWget /module/FindWish /module/FindwxWidgets /module/FindX11 /module/FindXalanC /module/FindXCTest /module/FindXercesC /module/FindXMLRPC /module/FindZLIB Deprecated Modules ^^^^^^^^^^^^^^^^^^^ Deprecated Utility Modules ========================== .. toctree:: :maxdepth: 1 /module/AddFileDependencies /module/CMakeDetermineVSServicePack /module/CMakeExpandImportedTargets /module/CMakeForceCompiler /module/CMakeParseArguments /module/Documentation /module/MacroAddFileDependencies /module/TestCXXAcceptsFlag /module/UseJavaClassFilelist /module/UseJavaSymlinks /module/UsePkgConfig /module/Use_wxWindows /module/WriteBasicConfigVersionFile /module/WriteCompilerDetectionHeader Deprecated Find Modules ======================= .. toctree:: :maxdepth: 1 /module/FindCUDA /module/FindPythonInterp /module/FindPythonLibs /module/FindQt /module/FindwxWindows 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. .. toctree:: :maxdepth: 1 /module/CPackArchive /module/CPackBundle /module/CPackCygwin /module/CPackDeb /module/CPackDMG /module/CPackFreeBSD /module/CPackNSIS /module/CPackNuGet /module/CPackPackageMaker /module/CPackProductBuild /module/CPackRPM /module/CPackWIX PK ! ����h �h cmake-variables.7.rstnu �[��� .. cmake-manual-description: CMake Variables Reference cmake-variables(7) ****************** .. only:: html .. contents:: 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 :ref:`Variables <CMake Language Variables>` section in the cmake-language manual. .. include:: ID_RESERVE.txt Variables that Provide Information ================================== .. toctree:: :maxdepth: 1 /variable/CMAKE_AR /variable/CMAKE_ARGC /variable/CMAKE_ARGV0 /variable/CMAKE_BINARY_DIR /variable/CMAKE_BUILD_TOOL /variable/CMAKE_CACHE_MAJOR_VERSION /variable/CMAKE_CACHE_MINOR_VERSION /variable/CMAKE_CACHE_PATCH_VERSION /variable/CMAKE_CACHEFILE_DIR /variable/CMAKE_CFG_INTDIR /variable/CMAKE_COMMAND /variable/CMAKE_CPACK_COMMAND /variable/CMAKE_CROSSCOMPILING /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND /variable/CMAKE_CURRENT_BINARY_DIR /variable/CMAKE_CURRENT_FUNCTION /variable/CMAKE_CURRENT_FUNCTION_LIST_DIR /variable/CMAKE_CURRENT_FUNCTION_LIST_FILE /variable/CMAKE_CURRENT_FUNCTION_LIST_LINE /variable/CMAKE_CURRENT_LIST_DIR /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS /variable/CMAKE_DOTNET_TARGET_FRAMEWORK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXECUTABLE_SUFFIX_LANG /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC /variable/CMAKE_MAJOR_VERSION /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME /variable/CMAKE_PROJECT_VERSION /variable/CMAKE_PROJECT_VERSION_MAJOR /variable/CMAKE_PROJECT_VERSION_MINOR /variable/CMAKE_PROJECT_VERSION_PATCH /variable/CMAKE_PROJECT_VERSION_TWEAK /variable/CMAKE_RANLIB /variable/CMAKE_ROOT /variable/CMAKE_RULE_MESSAGES /variable/CMAKE_SCRIPT_MODE_FILE /variable/CMAKE_SHARED_LIBRARY_PREFIX /variable/CMAKE_SHARED_LIBRARY_SUFFIX /variable/CMAKE_SHARED_MODULE_PREFIX /variable/CMAKE_SHARED_MODULE_SUFFIX /variable/CMAKE_SIZEOF_VOID_P /variable/CMAKE_SKIP_INSTALL_RULES /variable/CMAKE_SKIP_RPATH /variable/CMAKE_SOURCE_DIR /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX /variable/CMAKE_Swift_MODULE_DIRECTORY /variable/CMAKE_Swift_NUM_THREADS /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION /variable/CMAKE_VS_DEVENV_COMMAND /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR /variable/PROJECT-NAME_VERSION_MINOR /variable/PROJECT-NAME_VERSION_PATCH /variable/PROJECT-NAME_VERSION_TWEAK /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION /variable/PROJECT_VERSION_MAJOR /variable/PROJECT_VERSION_MINOR /variable/PROJECT_VERSION_PATCH /variable/PROJECT_VERSION_TWEAK Variables that Change Behavior ============================== .. toctree:: :maxdepth: 1 /variable/BUILD_SHARED_LIBS /variable/CMAKE_ABSOLUTE_DESTINATION_FILES /variable/CMAKE_APPBUNDLE_PATH /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE /variable/CMAKE_CLANG_VFS_OVERLAY /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES /variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT /variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS /variable/CMAKE_ECLIPSE_RESOURCE_ENCODING /variable/CMAKE_ECLIPSE_VERSION /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO /variable/CMAKE_EXPORT_COMPILE_COMMANDS /variable/CMAKE_EXPORT_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK /variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH /variable/CMAKE_FIND_USE_CMAKE_PATH /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MESSAGE_CONTEXT /variable/CMAKE_MESSAGE_CONTEXT_SHOW /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MESSAGE_LOG_LEVEL /variable/CMAKE_MODULE_PATH /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH /variable/CMAKE_PROJECT_INCLUDE /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE /variable/CMAKE_SUPPRESS_REGENERATION /variable/CMAKE_SYSROOT /variable/CMAKE_SYSROOT_COMPILE /variable/CMAKE_SYSROOT_LINK /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH /variable/CMAKE_TLS_CAINFO /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS /variable/PackageName_ROOT Variables that Describe the System ================================== .. toctree:: :maxdepth: 1 /variable/ANDROID /variable/APPLE /variable/BORLAND /variable/CMAKE_ANDROID_NDK_VERSION /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE /variable/CMAKE_HOST_SOLARIS /variable/CMAKE_HOST_SYSTEM /variable/CMAKE_HOST_SYSTEM_NAME /variable/CMAKE_HOST_SYSTEM_PROCESSOR /variable/CMAKE_HOST_SYSTEM_VERSION /variable/CMAKE_HOST_UNIX /variable/CMAKE_HOST_WIN32 /variable/CMAKE_LIBRARY_ARCHITECTURE /variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX /variable/CMAKE_OBJECT_PATH_MAX /variable/CMAKE_SYSTEM /variable/CMAKE_SYSTEM_NAME /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/GHS-MULTI /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 /variable/MSVC11 /variable/MSVC12 /variable/MSVC14 /variable/MSVC60 /variable/MSVC70 /variable/MSVC71 /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION /variable/MSYS /variable/UNIX /variable/WIN32 /variable/WINCE /variable/WINDOWS_PHONE /variable/WINDOWS_STORE /variable/XCODE /variable/XCODE_VERSION Variables that Control the Build ================================ .. toctree:: :maxdepth: 1 /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_API /variable/CMAKE_ANDROID_API_MIN /variable/CMAKE_ANDROID_ARCH /variable/CMAKE_ANDROID_ARCH_ABI /variable/CMAKE_ANDROID_ARM_MODE /variable/CMAKE_ANDROID_ARM_NEON /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES /variable/CMAKE_ANDROID_EXCEPTIONS /variable/CMAKE_ANDROID_GUI /variable/CMAKE_ANDROID_JAR_DEPENDENCIES /variable/CMAKE_ANDROID_JAR_DIRECTORIES /variable/CMAKE_ANDROID_JAVA_SOURCE_DIR /variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES /variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES /variable/CMAKE_ANDROID_NDK /variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION /variable/CMAKE_ANDROID_PROCESS_MAX /variable/CMAKE_ANDROID_PROGUARD /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH /variable/CMAKE_ANDROID_RTTI /variable/CMAKE_ANDROID_SECURE_PROPS_PATH /variable/CMAKE_ANDROID_SKIP_ANT_STEP /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_APPLE_SILICON_PROCESSOR /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC_PATH_PREFIX /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_CROSS_CONFIGS /variable/CMAKE_CTEST_ARGUMENTS /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_CUDA_RUNTIME_LIBRARY /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_DEFAULT_BUILD_TYPE /variable/CMAKE_DEFAULT_CONFIGS /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_DEPENDS_USE_COMPILER /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_FOLDER /variable/CMAKE_FRAMEWORK /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_Fortran_PREPROCESS /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE /variable/CMAKE_GLOBAL_AUTOGEN_TARGET /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME /variable/CMAKE_GLOBAL_AUTORCC_TARGET /variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME /variable/CMAKE_GNUtoMS /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR /variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_LIBRARY_PATH_FLAG /variable/CMAKE_LINK_DEF_FILE_FLAG /variable/CMAKE_LINK_DEPENDS_NO_SHARED /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_MSVC_RUNTIME_LIBRARY /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED /variable/CMAKE_OPTIMIZE_DEPENDENCIES /variable/CMAKE_OSX_ARCHITECTURES /variable/CMAKE_OSX_DEPLOYMENT_TARGET /variable/CMAKE_OSX_SYSROOT /variable/CMAKE_PCH_WARN_INVALID /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_SHARED_LINKER_FLAGS_INIT /variable/CMAKE_SKIP_BUILD_RPATH /variable/CMAKE_SKIP_INSTALL_RPATH /variable/CMAKE_STATIC_LINKER_FLAGS /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE /variable/CMAKE_UNITY_BUILD /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD /variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES /variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES /variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES /variable/CMAKE_VS_WINRT_BY_DEFAULT /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute /variable/EXECUTABLE_OUTPUT_PATH /variable/LIBRARY_OUTPUT_PATH Variables for Languages ======================= .. toctree:: :maxdepth: 1 /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 /variable/CMAKE_CUDA_ARCHITECTURES /variable/CMAKE_CUDA_COMPILE_FEATURES /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED /variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES /variable/CMAKE_CXX_COMPILE_FEATURES /variable/CMAKE_CXX_EXTENSIONS /variable/CMAKE_CXX_STANDARD /variable/CMAKE_CXX_STANDARD_REQUIRED /variable/CMAKE_C_COMPILE_FEATURES /variable/CMAKE_C_EXTENSIONS /variable/CMAKE_C_STANDARD /variable/CMAKE_C_STANDARD_REQUIRED /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG /variable/CMAKE_HIP_ARCHITECTURES /variable/CMAKE_HIP_EXTENSIONS /variable/CMAKE_HIP_STANDARD /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX /variable/CMAKE_LANG_ARCHIVE_APPEND /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_BYTE_ORDER /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_EXTENSIONS /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT /variable/CMAKE_LANG_FLAGS_DEBUG /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_INIT /variable/CMAKE_LANG_FLAGS_MINSIZEREL /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT /variable/CMAKE_LANG_FLAGS_RELEASE /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE /variable/CMAKE_LANG_LINKER_PREFERENCE /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION /variable/CMAKE_LANG_SIMULATE_ID /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED /variable/CMAKE_OBJCXX_EXTENSIONS /variable/CMAKE_OBJCXX_STANDARD /variable/CMAKE_OBJCXX_STANDARD_REQUIRED /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG Variables for CTest =================== .. toctree:: :maxdepth: 1 /variable/CTEST_BINARY_DIRECTORY /variable/CTEST_BUILD_COMMAND /variable/CTEST_BUILD_NAME /variable/CTEST_BZR_COMMAND /variable/CTEST_BZR_UPDATE_OPTIONS /variable/CTEST_CHANGE_ID /variable/CTEST_CHECKOUT_COMMAND /variable/CTEST_CONFIGURATION_TYPE /variable/CTEST_CONFIGURE_COMMAND /variable/CTEST_COVERAGE_COMMAND /variable/CTEST_COVERAGE_EXTRA_FLAGS /variable/CTEST_CURL_OPTIONS /variable/CTEST_CUSTOM_COVERAGE_EXCLUDE /variable/CTEST_CUSTOM_ERROR_EXCEPTION /variable/CTEST_CUSTOM_ERROR_MATCH /variable/CTEST_CUSTOM_ERROR_POST_CONTEXT /variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT /variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE /variable/CTEST_CUSTOM_MEMCHECK_IGNORE /variable/CTEST_CUSTOM_POST_MEMCHECK /variable/CTEST_CUSTOM_POST_TEST /variable/CTEST_CUSTOM_PRE_MEMCHECK /variable/CTEST_CUSTOM_PRE_TEST /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH /variable/CTEST_CVS_CHECKOUT /variable/CTEST_CVS_COMMAND /variable/CTEST_CVS_UPDATE_OPTIONS /variable/CTEST_DROP_LOCATION /variable/CTEST_DROP_METHOD /variable/CTEST_DROP_SITE /variable/CTEST_DROP_SITE_CDASH /variable/CTEST_DROP_SITE_PASSWORD /variable/CTEST_DROP_SITE_USER /variable/CTEST_EXTRA_COVERAGE_GLOB /variable/CTEST_GIT_COMMAND /variable/CTEST_GIT_INIT_SUBMODULES /variable/CTEST_GIT_UPDATE_CUSTOM /variable/CTEST_GIT_UPDATE_OPTIONS /variable/CTEST_HG_COMMAND /variable/CTEST_HG_UPDATE_OPTIONS /variable/CTEST_LABELS_FOR_SUBPROJECTS /variable/CTEST_MEMORYCHECK_COMMAND /variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS /variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS /variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE /variable/CTEST_MEMORYCHECK_TYPE /variable/CTEST_NIGHTLY_START_TIME /variable/CTEST_P4_CLIENT /variable/CTEST_P4_COMMAND /variable/CTEST_P4_OPTIONS /variable/CTEST_P4_UPDATE_OPTIONS /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS /variable/CTEST_SVN_UPDATE_OPTIONS /variable/CTEST_TEST_LOAD /variable/CTEST_TEST_TIMEOUT /variable/CTEST_TRIGGER_SITE /variable/CTEST_UPDATE_COMMAND /variable/CTEST_UPDATE_OPTIONS /variable/CTEST_UPDATE_VERSION_ONLY /variable/CTEST_UPDATE_VERSION_OVERRIDE /variable/CTEST_USE_LAUNCHERS Variables for CPack =================== .. toctree:: :maxdepth: 1 /variable/CPACK_ABSOLUTE_DESTINATION_FILES /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_CUSTOM_INSTALL_VARIABLES /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION Variable Expansion Operators ============================ .. toctree:: :maxdepth: 1 /variable/CACHE /variable/ENV 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. .. toctree:: :maxdepth: 1 /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_INTERNAL_PLATFORM_ABI /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION PK ! H�>�l �l cmake-packages.7.rstnu �[��� .. cmake-manual-description: CMake Packages Reference cmake-packages(7) ***************** .. only:: html .. contents:: Introduction ============ Packages provide dependency information to CMake based buildsystems. Packages are found with the :command:`find_package` command. The result of using :command:`find_package` is either a set of :prop_tgt:`IMPORTED` targets, or a set of variables corresponding to build-relevant information. Using Packages ============== CMake provides direct support for two forms of packages, `Config-file Packages`_ and `Find-module Packages`_. Indirect support for ``pkg-config`` packages is also provided via the :module:`FindPkgConfig` module. In all cases, the basic form of :command:`find_package` calls is the same: .. code-block:: cmake 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 :command:`find_package`: .. code-block:: cmake 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: .. code-block:: cmake 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: .. code-block:: cmake find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql) or as a separate ``COMPONENTS`` list: .. code-block:: cmake find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql) or as a separate ``OPTIONAL_COMPONENTS`` list: .. code-block:: cmake 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 :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always be ``NOTFOUND``. Likewise, setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the package REQUIRED. .. _`Config File Packages`: 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 :command:`find_package` documentation. The most simple way for a CMake user to tell :manual:`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. 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 :command:`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 :manual:`cmake-developer(7)` manual for more information about creating Find-module files. Package Layout ============== A config-file package consists of a `Package Configuration File`_ and optionally a `Package Version File`_ provided with the project distribution. 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 :prop_tgt:`IMPORTED` targets, or defining variables, such as: .. code-block:: cmake # ... # (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 :command:`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 :command:`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. Package Version File -------------------- When the :command:`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 :command:`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 :command:`find_package` command. .. _`Creating Packages`: 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: .. code-block:: cmake 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 :module:`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 :command:`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 :command:`install(EXPORT)` command is used to export the targets in the ``ClimbingStatsTargets`` export-set, defined previously by the :command:`install(TARGETS)` command. This command generates the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`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 :prop_tgt:`IMPORTED` targets have appropriate properties set to define their :ref:`usage requirements <Target Usage Requirements>`, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in ``INTERFACE_`` properties. The ``INTERFACE`` variant of user-defined properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other :ref:`Compatible Interface Properties` are also propagated to the generated :prop_tgt:`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``, :manual:`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 :prop_tgt:`IMPORTED` target when it is used by downstreams with the :command:`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 :command:`install(TARGETS)` the ``INCLUDES DESTINATION`` was specified. This causes the ``IMPORTED`` targets to have their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated with the ``include`` directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` target is used by downstream, it automatically consumes the entries from that property. Creating a Package Configuration File ------------------------------------- In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: .. code-block:: cmake 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: .. code-block:: cmake # ... 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 :module:`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: .. code-block:: cmake 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 :command:`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: .. code-block:: cmake 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. Creating a Package Configuration File for the Build Tree ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :command:`export(EXPORT)` command creates an :prop_tgt:`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 :variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the ``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache. .. _`Creating Relocatable Packages`: 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 :command:`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 :variable:`CMAKE_INSTALL_PREFIX`: .. code-block:: cmake 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>`` :manual:`generator expression <cmake-generator-expressions(7)>` 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: .. code-block:: cmake 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 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. For example, this code may not work well for a relocatable package: .. code-block:: cmake 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 :ref:`IMPORTED targets <Imported Targets>` that have their own :prop_tgt:`IMPORTED_LOCATION` and usage requirement properties such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated appropriately. Those imported targets may then be used with the :command:`target_link_libraries` command for ``ClimbingStats``: .. code-block:: cmake target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar) With this approach the package references its external dependencies only through the names of :ref:`IMPORTED targets <Imported Targets>`. When a consumer uses the installed package, the consumer will run the appropriate :command:`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 :manual:`modules <cmake-modules(7)>` shipped with CMake do not yet provide :ref:`IMPORTED targets <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. .. _`Package Registry`: 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 :command:`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. .. _`User Package Registry`: User Package Registry --------------------- The User Package Registry is stored in a per-user location. The :command:`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. .. _`System Package Registry`: 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. .. _`Disabling the Package Registry`: 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 :command:`export(PACKAGE)` command does not populate the user package registry when :policy:`CMP0090` is set to ``NEW`` unless the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable explicitly enables it. When :policy:`CMP0090` is *not* set to ``NEW`` then :command:`export(PACKAGE)` populates the user package registry unless the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly disables it. * :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the User Package Registry in all the :command:`find_package` calls when set to ``FALSE``. * Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the User Package Registry in all the :command:`find_package` calls when set to ``TRUE``. This variable is ignored when :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set. * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables the System Package Registry in all the :command:`find_package` calls. Package Registry Example ------------------------ A simple convention for naming package registry entries is to use content hashes. They are deterministic and unlikely to collide (:command:`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: .. code-block:: cmake 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 :command:`find_package` whether a specific location is suitable for the version requested. 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 :command:`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 :command:`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 :command:`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. PK ! 9���L L cmake-developer.7.rstnu �[��� .. cmake-manual-description: CMake Developer Reference cmake-developer(7) ****************** .. only:: html .. contents:: Introduction ============ This manual is intended for reference by developers working with :manual:`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. .. _`Find Modules`: Find Modules ============ A "find module" is a ``Find<PackageName>.cmake`` file to be loaded by the :command:`find_package` command when invoked for ``<PackageName>``. The primary task of a find module is to determine whether a package is available, 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 :ref:`config file package <Config File Packages>`. 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 :ref:`config file packages <Config File Packages>` files as possible, by providing :ref:`imported target <Imported targets>`. This has the advantage of propagating :ref:`Target 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 :command:`find_package` documentation for details on what variables are set for the find module. Most of these are dealt with by using :module:`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. .. _`CMake Developer Standard Variable Names`: 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_``, which (unless otherwise noted) must match exactly the name of the ``FindXxx.cmake`` file, including upper/lowercase. This prefix on the variable names ensures that they do not conflict with variables of other Find modules. The same pattern should also be followed for any macros, functions and imported targets defined by the Find module. ``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 (note that this also means this variable should not be used as the result variable of a :command:`find_path` command - see ``Xxx_INCLUDE_DIR`` below for that). ``Xxx_LIBRARIES`` The libraries to use with the module. These may be CMake targets, full absolute paths to a library binary or the name of a library that the linker must find in its search path. This should not be a cache entry (note that this also means this variable should not be used as the result variable of a :command:`find_library` command - see ``Xxx_LIBRARY`` below for that). ``Xxx_DEFINITIONS`` The compile definitions to use when compiling code that uses the module. 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`` The full absolute path to an executable. In this case, ``Xxx`` might not be the name of the module, it might be the name of the tool (usually converted to all uppercase), assuming that tool has such a well-known name that it is unlikely that another tool with the same name exists. It would be appropriate to use this as the result variable of a :command:`find_program` command. ``Xxx_YYY_EXECUTABLE`` Similar to ``Xxx_EXECUTABLE`` except here the ``Xxx`` is always the module name and ``YYY`` is the tool name (again, usually fully uppercase). Prefer this form if the tool name is not very widely known or has the potential to clash with another tool. For greater consistency, also prefer this form if the module provides more than one executable. ``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 the module. ``Xxx_VERSION_VV`` Variables of this form specify whether the ``Xxx`` module being provided is version ``VV`` of the module. There should not be more than one variable of this form set to true for a given module. For example, a module ``Barry`` might have evolved over many years and gone through a number of different major versions. Version 3 of the ``Barry`` module might set the variable ``Barry_VERSION_3`` to true, whereas an older version of the module might set ``Barry_VERSION_2`` to true instead. It would be an error for both ``Barry_VERSION_3`` and ``Barry_VERSION_2`` to both be set to true. ``Xxx_WRAP_YY`` When a variable of this form is set to false, it indicates that the relevant wrapping command should not be used. The wrapping command depends on the module, it may be implied by the module name or it might be specified by the ``YY`` part of the variable. ``Xxx_Yy_FOUND`` For variables of this form, ``Yy`` is the name of a component for the module. It should match exactly one of the valid component names that may be passed to the :command:`find_package` command for the module. If a variable of this form is set to false, it means that the ``Yy`` component of module ``Xxx`` was not found or is not available. Variables of this form would typically be used for optional components so that the caller can check whether an optional component is available. ``Xxx_FOUND`` When the :command:`find_package` command returns to the caller, this variable will be set to true if the module was deemed to have been found successfully. ``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 :command:`find_package` command and by :command:`find_package_handle_standard_args` to inform the user about the problem. Use this instead of calling :command:`message` directly to report a reason for failing to find the module or package. ``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. They are intended for use by Find modules to specify and cache the locations of specific files or directories. Users are typically able to set and edit these variables to control the behavior of Find modules (like entering the path to a library manually): ``Xxx_LIBRARY`` The path of the library. Use this form only when the module provides a single library. It is appropriate to use this as the result variable in a :command:`find_library` command. ``Xxx_Yy_LIBRARY`` The path of library ``Yy`` provided by the module ``Xxx``. Use this form when the module provides more than one library or where other modules may also provide a library of the same name. It is also appropriate to use this form as the result variable in a :command:`find_library` command. ``Xxx_INCLUDE_DIR`` When the module provides only a single library, this variable can be used to specify where to find headers for using the library (or more accurately, the path that consumers of the library should add to their header search path). It would be appropriate to use this as the result variable in a :command:`find_path` command. ``Xxx_Yy_INCLUDE_DIR`` If the module provides more than one library or where other modules may also provide a library of the same name, this form is recommended for specifying where to find headers for using library ``Yy`` provided by the module. Again, it would be appropriate to use this as the result variable in a :command:`find_path` command. 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``. The :module:`SelectLibraryConfigurations` module can be helpful for such cases. 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. 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 :ref:`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. .. code-block:: cmake 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. .. code-block:: cmake 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} ) Alternatively, if the library is available with multiple configurations, you can use :module:`SelectLibraryConfigurations` to automatically set the ``Foo_LIBRARY`` variable instead: .. code-block:: cmake find_library(Foo_LIBRARY_RELEASE NAMES foo PATHS ${PC_Foo_LIBRARY_DIRS}/Release ) find_library(Foo_LIBRARY_DEBUG NAMES foo PATHS ${PC_Foo_LIBRARY_DIRS}/Debug ) include(SelectLibraryConfigurations) select_library_configurations(Foo) 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`` .. code-block:: cmake set(Foo_VERSION ${PC_Foo_VERSION}) Now we can use :module:`FindPackageHandleStandardArgs` to do most of the rest of the work for us .. code-block:: cmake 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 :command:`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 .. code-block:: cmake 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 :command:`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 :policy:`CMP0028`). .. code-block:: cmake 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 :prop_tgt:`IMPORTED` target created in the :command:`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 :prop_tgt:`IMPORTED_CONFIGURATIONS` target property should also be populated: .. code-block:: cmake 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. .. code-block:: cmake 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. .. code-block:: cmake # compatibility variables set(Foo_VERSION_STRING ${Foo_VERSION}) PK ! �_��) �) cmake-compile-features.7.rstnu �[��� .. cmake-manual-description: CMake Compile Features Reference cmake-compile-features(7) ************************* .. only:: html .. contents:: 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 :prop_gbl:`CMAKE_C_KNOWN_FEATURES`, :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`, and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the features known to CMake, regardless of compiler support for the feature. The :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES` , and :variable:`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. Compile Feature Requirements ============================ Compile feature requirements may be specified with the :command:`target_compile_features` command. For example, if a target must be compiled with compiler support for the :prop_gbl:`cxx_constexpr <CMAKE_CXX_KNOWN_FEATURES>` feature: .. code-block:: cmake add_library(mylib requires_constexpr.cpp) target_compile_features(mylib PRIVATE cxx_constexpr) In processing the requirement for the ``cxx_constexpr`` feature, :manual:`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 :command:`target_compile_features`: .. code-block:: cmake 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 :manual:`cmake-buildsystem(7)` for more on transitive behavior of build properties and usage requirements. .. _`Requiring Language Standards`: 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: .. code-block:: cmake 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``). Availability of Compiler Extensions ----------------------------------- The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's default (see :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`). Note that because most compilers enable extensions by default, this may expose portability bugs in user code or in the headers of third-party dependencies. :prop_tgt:`<LANG>_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. Optional Compile Features ========================= Compile features may be preferred if available, without creating a hard requirement. This can be achieved by *not* specifying features with :command:`target_compile_features` and instead checking the compiler capabilities with preprocessor conditions in project code. In this use-case, the project may wish to establish a particular language standard if available from the compiler, and use preprocessor conditions to detect the features actually available. A language standard may be established by `Requiring Language Standards`_ using :command:`target_compile_features` with meta-features like ``cxx_std_11``, or by setting the :prop_tgt:`CXX_STANDARD` target property or :variable:`CMAKE_CXX_STANDARD` variable. See also policy :policy:`CMP0120` and legacy documentation on :ref:`Example Usage <WCDH Example Usage>` of the deprecated :module:`WriteCompilerDetectionHeader` module. 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: .. code-block:: c++ 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: .. code-block:: c++ template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> struct Interface { static int accumulate() { return I1 + I2 + I3 + I4; } }; It may be possible to write an abstraction ``interface.h`` header containing something like: .. code-block:: c++ #ifdef HAVE_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`` :manual:`generator expression <cmake-generator-expressions(7)>` to implement such conditions. This may be used with the build-property commands such as :command:`target_include_directories` and :command:`target_link_libraries` to set the appropriate :manual:`buildsystem <cmake-buildsystem(7)>` properties: .. code-block:: cmake 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 .. code-block:: cmake 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) Supported Compilers =================== CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` 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 :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` 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 :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. * ``Fujitsu``: Fujitsu HPC compiler 4.0+. * ``PGI``: PGI version 12.10+. * ``NVHPC``: NVIDIA HPC compilers version 11.0+. * ``TI``: Texas Instruments compiler. * ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` 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 :prop_tgt:`CUDA standards <CUDA_STANDARD>` and their associated meta-features (e.g. ``cuda_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``Clang``: Clang compiler 5.0+. * ``NVIDIA``: NVIDIA nvcc compiler 7.5+. PK ! ����� � cmake-gui.1.rstnu �[��� PK ! ���I I � cmake-generators.7.rstnu �[��� PK ! ��R� R� R ctest.1.rstnu �[��� PK ! �_�e e � cmake-toolchains.7.rstnu �[��� PK ! w=���= �= �g cmake-policies.7.rstnu �[��� PK ! ir��w� w� p� cmake-presets.7.rstnu �[��� PK ! ��(�� � *- cmake-server.7.rstnu �[��� PK ! L�y y :. ccmake.1.rstnu �[��� PK ! -'8n2 2 �1 OPTIONS_HELP.txtnu �[��� PK ! ��FN�( �( a@ cmake-qt.7.rstnu �[��� PK ! U��� � $i cpack.1.rstnu �[��� PK ! Sh�? z ID_RESERVE.txtnu �[��� PK ! Q�\W� � g{ LINKS.txtnu �[��� PK ! Q �P P N} cmake-env-variables.7.rstnu �[��� PK ! �c��q �q � cmake.1.rstnu �[��� PK ! ���D� � �� OPTIONS_BUILD.txtnu �[��� PK ! ��W#� #� ! � cmake-generator-expressions.7.rstnu �[��� PK ! j��#8� 8� � cmake-file-api.7.rstnu �[��� PK ! �Ч]> > �� cmake-commands.7.rstnu �[��� PK ! ��9��L �L � cmake-language.7.rstnu �[��� PK ! M1�� � �� presets/example.jsonnu �[��� PK ! � ��� �� �� presets/schema.jsonnu �[��� PK ! )A�� � �� cpack-generators.7.rstnu �[��� PK ! cɤ�!H !H � cmake-properties.7.rstnu �[��� PK ! �� �U� U� t cmake-buildsystem.7.rstnu �[��� PK ! �� R R � cmake-modules.7.rstnu �[��� PK ! ����h �h �� cmake-variables.7.rstnu �[��� PK ! H�>�l �l �L cmake-packages.7.rstnu �[��� PK ! 9���L L � cmake-developer.7.rstnu �[��� PK ! �_��) �) : cmake-compile-features.7.rstnu �[��� PK � h0
| ver. 1.1 | |
.
| PHP 8.4.18 | Ð“ÐµÐ½ÐµÑ€Ð°Ñ†Ð¸Ñ Ñтраницы: 0.06 |
proxy
|
phpinfo
|
ÐаÑтройка