diff options
Diffstat (limited to 'Help/command')
41 files changed, 673 insertions, 181 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index dde4dbb..40f1c1a 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -89,7 +89,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: searched after paths from the current module, i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. See policy :policy:`CMP0074`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -97,7 +98,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -107,7 +109,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -119,13 +122,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: Hard-coded guesses should be specified with the ``PATHS`` option. 5. Search the standard system environment variables. - This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by + setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. * |SYSTEM_ENVIRONMENT_PATH_XXX| + * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed. + is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 9bf0d87..ed321fc 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -23,6 +23,7 @@ The first signature is for adding a custom command to produce an output: [WORKING_DIRECTORY dir] [COMMENT comment] [DEPFILE depfile] + [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] [COMMAND_EXPAND_LISTS]) @@ -144,6 +145,13 @@ The options are: Note that the ``IMPLICIT_DEPENDS`` option is currently supported only for Makefile generators and will be ignored by other generators. +``JOB_POOL`` + Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` + generator. Incompatible with ``USES_TERMINAL``, which implies + the ``console`` pool. + Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes + an error by ninja at build time. + ``MAIN_DEPENDENCY`` Specify the primary input source file to the command. This is treated just like any value given to the ``DEPENDS`` option diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index c63dd23..08b9516 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -11,6 +11,7 @@ Add a target with no output so it will always be built. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] + [JOB_POOL job_pool] [VERBATIM] [USES_TERMINAL] [COMMAND_EXPAND_LISTS] [SOURCES src1 [src2...]]) @@ -97,6 +98,13 @@ The options are: ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` to be properly expanded. +``JOB_POOL`` + Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` + generator. Incompatible with ``USES_TERMINAL``, which implies + the ``console`` pool. + Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes + an error by ninja at build time. + ``SOURCES`` Specify additional source files to be included in the custom target. Specified source files will be added to IDE project files for diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index 39a43f4..d06b01c 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -20,7 +20,7 @@ preprocessor definitions. * Use :command:`include_directories` to add include directories. * Use :command:`add_compile_options` to add other options. -Flags beginning in -D or /D that look like preprocessor definitions are +Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory property for the current directory. Definitions with non-trivial values may be left in the set of flags instead of being converted for reasons of diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index ec6cb9d..7274e44 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -80,15 +80,26 @@ option extends visibility. It may be referenced like any target built within the project. ``IMPORTED`` libraries are useful for convenient reference from commands like :command:`target_link_libraries`. Details about the imported library are specified by setting properties whose names -begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such -property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration -variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the -location of the main library file on disk. Or, for object libraries, -:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) -specifies the locations of object files on disk. +begin in ``IMPORTED_`` and ``INTERFACE_``. + +The most important properties are: + +* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the + location of the main library file on disk. +* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) + for object libraries, specifies the locations of object files on disk. +* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation + See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. +An ``UNKNOWN`` library type is typically only used in the implementation of +:ref:`Find Modules`. It allows the path to an imported library (often found +using the :command:`find_library` command) to be used without having to know +what type of library it is. This is especially useful on Windows where a +static library and a DLL's import library both have the same file extension. + Object Libraries ^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index 1b02bee..a83005b 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -1,20 +1,25 @@ add_link_options ---------------- -Add options to the link of shared library, module and executable targets. +Add options to the link step for executable, shared library or module +library targets in the current directory and below that are added after +this command is invoked. .. code-block:: cmake add_link_options(<option> ...) -Adds options to the link step for targets in the current directory and below -that are added after this command is invoked. See documentation of the +This command can be used to add any link options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and :prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. -This command can be used to add any options, but alternative commands -exist to add libraries (:command:`target_link_libraries` or -:command:`link_libraries`). +.. note:: + + This command cannot be used to add options for static library targets, + since they do not use a linker. To add archiver or MSVC librarian flags, + see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. Arguments to ``add_link_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index a8c257d..884b2ee 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -7,7 +7,8 @@ Add a test to the project to be run by :manual:`ctest(1)`. add_test(NAME <name> COMMAND <command> [<arg>...] [CONFIGURATIONS <config>...] - [WORKING_DIRECTORY <dir>]) + [WORKING_DIRECTORY <dir>] + [COMMAND_EXPAND_LISTS]) Adds a test called ``<name>``. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: @@ -28,6 +29,11 @@ quotes, or other characters special in CMake syntax. The options are: directory set to the build directory corresponding to the current source directory. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`. + The given test command is expected to exit with code ``0`` to pass and non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test property is set. Any output written to stdout or stderr will be @@ -55,7 +61,8 @@ file produced by target ``myexe``. CMake will generate tests only if the :command:`enable_testing` command has been invoked. The :module:`CTest` module invokes the - command automatically when the ``BUILD_TESTING`` option is ``ON``. + command automatically unless the ``BUILD_TESTING`` option is turned + ``OFF``. --------------------------------------------------------------------- diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst index e0af665..9619f35 100644 --- a/Help/command/aux_source_directory.rst +++ b/Help/command/aux_source_directory.rst @@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory and stores the list in the ``<variable>`` provided. This command is intended to be used by projects that use explicit template instantiation. Template instantiation files can be stored in a -"Templates" subdirectory and collected automatically using this +``Templates`` subdirectory and collected automatically using this command to avoid manually listing all instantiations. It is tempting to use this command to avoid writing the list of source files for a library or executable target. While this seems to work, there is no way for CMake to generate a build system that knows when a new source file has been added. Normally the generated build system -knows when it needs to rerun CMake because the CMakeLists.txt file is +knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is modified to add a new source. When the source is just added to the directory without modifying this file, one would have to manually rerun CMake to generate a build system incorporating the new file. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index b83edaf..6659005 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module. Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>] [-- -i] + <cmake> --build . [--config <config>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index c8327e2..fcd36d0 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -55,12 +55,17 @@ For the ``<options>`` keywords, these will always be defined, to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. All remaining arguments are collected in a variable -``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument -where recognized. This can be checked afterwards to see +``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments +were recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. -As an example here a ``my_install()`` macro, which takes similar arguments -as the real :command:`install` command: +``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no +values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES`` +that will be undefined if all keywords received values. This can be checked +to see if there were keywords without any values given. + +Consider the following example macro, ``my_install()``, which takes similar +arguments to the real :command:`install` command: .. code-block:: cmake @@ -77,7 +82,7 @@ Assume ``my_install()`` has been called like this: .. code-block:: cmake - my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) After the ``cmake_parse_arguments`` call the macro will have set or undefined the following variables:: @@ -89,13 +94,16 @@ the following variables:: MY_INSTALL_TARGETS = "foo;bar" MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" + MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" + # No value for "CONFIGURATIONS" given You can then continue and process these variables. -Keywords terminate lists of values, e.g. if directly after a -one_value_keyword another recognized keyword follows, this is +Keywords terminate lists of values, e.g. if directly after a +``one_value_keyword`` another recognized keyword follows, this is interpreted as the beginning of the new option. E.g. ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in ``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and -``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added +to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will +therefore be set to ``TRUE``. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index a80f982..4bc7807 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -80,7 +80,7 @@ CMake Policy Stack ^^^^^^^^^^^^^^^^^^ CMake keeps policy settings on a stack, so changes made by the -cmake_policy command affect only the top of the stack. A new entry on +``cmake_policy`` command affect only the top of the stack. A new entry on the policy stack is managed automatically for each subdirectory to protect its parents and siblings. CMake also manages a new entry for scripts loaded by :command:`include` and :command:`find_package` commands diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index fba03fd..983fc20 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. ctest_submit([PARTS <part>...] [FILES <file>...] [SUBMIT_URL <url>] + [BUILD_ID <result-var>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] @@ -44,9 +45,21 @@ The options are: The ``http`` or ``https`` URL of the dashboard server to send the submission to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used. +``BUILD_ID <result-var>`` + Store in the ``<result-var>`` variable the ID assigned to this build by + CDash. + ``HTTPHEADER <HTTP-header>`` Specify HTTP header to be included in the request to CDash during submission. - This suboption can be repeated several times. + For example, CDash can be configured to only accept submissions from + authenticated clients. In this case, you should provide a bearer token in your + header: + + .. code-block:: cmake + + ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>") + + This suboption can be repeated several times for multiple headers. ``RETRY_COUNT <count>`` Specify how many times to retry a timed-out submission. @@ -86,5 +99,6 @@ with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. -This signature accepts the ``SUBMIT_URL``, ``HTTPHEADER``, ``RETRY_COUNT``, -``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options as described above. +This signature accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``, +``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options +as described above. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index df1a4e5..96a11c9 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -35,4 +35,5 @@ The options are: The update always follows the version control branch currently checked out in the source directory. See the :ref:`CTest Update Step` -documentation for more information. +documentation for information about variables that change the behavior +of ``ctest_update()``. diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index e2028d2..3ac1a19 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst @@ -7,7 +7,14 @@ Enable testing for current directory and below. enable_testing() -Enables testing for this directory and below. See also the -:command:`add_test` command. Note that ctest expects to find a test file -in the build directory root. Therefore, this command should be in the -source directory root. +Enables testing for this directory and below. + +This command should be in the source directory root +because ctest expects to find a test file in the build +directory root. + +This command is automatically invoked when the :module:`CTest` +module is included, except if the ``BUILD_TESTING`` option is +turned off. + +See also the :command:`add_test` command. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 3a56dce..14f879d 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -18,11 +18,14 @@ Execute one or more child processes. [ERROR_FILE <file>] [OUTPUT_QUIET] [ERROR_QUIET] + [COMMAND_ECHO <where>] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] [ENCODING <name>]) -Runs the given sequence of one or more commands in parallel with the standard +Runs the given sequence of one or more commands. + +Commands are executed concurrently as a pipeline, with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. @@ -46,8 +49,9 @@ Options: the child processes. ``TIMEOUT`` - The child processes will be terminated if they do not finish in the - specified number of seconds (fractions are allowed). + After the specified number of seconds (fractions allowed), all unfinished + child processes will be terminated, and the ``RESULT_VARIABLE`` will be + set to a string mentioning the "timeout". ``RESULT_VARIABLE`` The variable will be set to contain the result of last child process. @@ -56,9 +60,9 @@ Options: ``RESULTS_VARIABLE <variable>`` The variable will be set to contain the result of all processes as a - :ref:`semicolon-separated list <CMake Language Lists>`, in order of the given ``COMMAND`` - arguments. Each entry will be an integer return code from the - corresponding child or a string describing an error condition. + :ref:`semicolon-separated list <CMake Language Lists>`, in order of the + given ``COMMAND`` arguments. Each entry will be an integer return code + from the corresponding child or a string describing an error condition. ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output @@ -74,6 +78,12 @@ Options: ``OUTPUT_QUIET``, ``ERROR_QUIET`` The standard output or standard error results will be quietly ignored. +``COMMAND_ECHO <where>`` + The command being run will be echo'ed to ``<where>`` with ``<where>`` + being set to one of ``STDERR``, ``STDOUT`` or ``NONE``. + See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way + to control the default behavior when this option is not present. + ``ENCODING <name>`` On Windows, the encoding that is used to decode output from the process. Ignored on other platforms. diff --git a/Help/command/export.rst b/Help/command/export.rst index b255ee8..2ca7056 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -54,7 +54,7 @@ unspecified. export(PACKAGE <PackageName>) Store the current build directory in the CMake user package registry -for package ``<PackageName>``. The find_package command may consider the +for package ``<PackageName>``. The :command:`find_package` command may consider the directory while searching for package ``<PackageName>``. This helps dependent projects find and use a package from the current project's build tree without help from the user. Note that the entry in the package @@ -62,8 +62,13 @@ registry that this command creates works only in conjunction with a package configuration file (``<PackageName>Config.cmake``) that works with the build tree. In some cases, for example for packaging and for system wide installations, it is not desirable to write the user package -registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable -is enabled, the ``export(PACKAGE)`` command will do nothing. +registry. + +By default the ``export(PACKAGE)`` command does nothing (see policy +:policy:`CMP0090`) because populating the user package registry has effects +outside the source and build trees. Set the +:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to +the CMake user package registry. .. code-block:: cmake diff --git a/Help/command/file.rst b/Help/command/file.rst index 465e567..666a532 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -13,6 +13,7 @@ Synopsis file(`STRINGS`_ <filename> <out-var> [...]) file(`\<HASH\> <HASH_>`_ <filename> <out-var>) file(`TIMESTAMP`_ <filename> <out-var> [...]) + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) `Writing`_ file({`WRITE`_ | `APPEND`_} <filename> <content>...) @@ -130,6 +131,273 @@ timestamp variable will be set to the empty string (""). See the :command:`string(TIMESTAMP)` command for documentation of the ``<format>`` and ``UTC`` options. +.. _GET_RUNTIME_DEPENDENCIES: + +.. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENICES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + ) + +Recursively get the list of libraries depended on by the given files. + +Please note that this sub-command is not intended to be used in project mode. +Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` +block. For example: + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + +The arguments are as follows: + +``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + +``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved dependencies. + If this variable is not specified, and there are any unresolved dependencies, + an error is issued. + +``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored in + ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths + that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + +``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables that + are typically created with :command:`add_executable`, but they do not have to + be created by CMake. On Apple platforms, the paths to these files determine + the value of ``@executable_path`` when recursively resolving the libraries. + Specifying ``STATIC`` libraries, ``MODULE`` s, or ``SHARED`` libraries here + will result in undefined behavior. + +``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that are + typically created with :command:`add_library(SHARED)`, but they do not have + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` s, or + executables here will result in undefined behavior. + +``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they do + not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here + will result in undefined behavior. + +``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found in + any of the other usual paths. If it is found in such a directory, a warning + is issued, because it means that the file is incomplete (it does not list all + of the directories that contain its dependencies.) On Windows platforms, + these directories are searched if the dependency is not found in any of the + other search paths, but no warning is issued, because searching other paths + is a normal part of Windows dependency resolution. On Apple platforms, this + argument has no effect. + +``BUNDLE_EXECTUBLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. On + Apple platforms, this argument determines the value of ``@executable_path`` + when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. + It has no effect on ``EXECUTABLES`` files. On other platforms, it has no + effect. This is typically (but not always) one of the executables in the + ``EXECUTABLES`` argument which designates the "main" executable of the + package. + +The following arguments specify filters for including or excluding libraries to +be resolved. See below for a full description of how they work. + +``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + +``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + +``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of resolved + dependencies. + +``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of resolved + dependencies. + +These arguments can be used to blacklist unwanted system libraries when +resolving the dependencies, or to whitelist libraries from a specific +directory. The filtering works as follows: + +1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. +2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. +3. Otherwise, dependency resolution proceeds. +4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to + the linking rules of the platform (see below). +5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Otherwise, resolution proceeds to step 6. +6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and + dependency resolution stops for that dependency. +7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. + +Different platforms have different rules for how dependencies are resolved. +These specifics are described here. + +On Linux platforms, library resolution works as follows: + +1. If the depending file does not have any ``RUNPATH`` entries, and the library + exists in one of the depending file's ``RPATH`` entries, or its parents', in + that order, the dependency is resolved to that file. +2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. +3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. +4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the + dependency is resolved to that file. In this case, a warning is issued, + because finding a file in one of the ``DIRECTORIES`` means that the + depending file is not complete (it does not list all the directories from + which it pulls dependencies.) +5. Otherwise, the dependency is unresolved. + +On Windows platforms, library resolution works as follows: + +1. The dependent DLL name is converted to lowercase. Windows DLL names are + case-insensitive, and some linkers mangle the case of the DLL dependency + names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, + ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and + ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would + have to check for both uppercase and lowercase letters. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) + + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) + + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) + + Please note that the directory portion of any resolved DLLs retains its + casing and is not converted to lowercase. Only the filename portion is + converted. + +2. (**Not yet implemented**) If the depending file is a Windows Store app, and + the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. +3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. +4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. +5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved to + that file. (In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution.) +6. Otherwise, the dependency is unresolved. + +On Apple platforms, library resolution works as follows: + +1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` + argument is in the process of being resolved, and replacing + ``@executable_path/`` with the directory of the executable yields an + existing file, the dependency is resolved to that file. +2. Otherwise, if the dependency starts with ``@executable_path/``, and there is + a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with + the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. +3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. +4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields + an existing file, the dependency is resolved to that file. (Note that + ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` + also have these items replaced with the appropriate path.) +5. Otherwise, if the dependency is an absolute file that exists, the dependency + is resolved to that file. +6. Otherwise, the dependency is unresolved. + +This function accepts several variables that determine which tool is used for +dependency resolution: + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM + + Determines which operating system and executable format the files are built + for. This could be one of several values: + + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL + + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: + + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``dumpbin`` + ``windows+pe`` ``objdump`` + ``macos+macho`` ``otool`` + ================================================= ============================================= + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND + + Determines the path to the tool to use for dependency resolution. This is the + actual path to ``objdump``, ``dumpbin``, or ``otool``. + + If this variable is not specified, it is determined automatically by system + introspection. + Writing ^^^^^^^ @@ -292,7 +560,8 @@ Move a file or directory within a filesystem from ``<oldname>`` to Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a -given file does not exist. +given file does not exist. Relative input paths are evaluated with respect +to the current source directory. Empty input paths are ignored with a warning. .. _MAKE_DIRECTORY: @@ -311,6 +580,7 @@ Create the given directories and their parents as needed. [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...] [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FOLLOW_SYMLINK_CHAIN] [FILES_MATCHING] [[PATTERN <pattern> | REGEX <regex>] [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) @@ -324,6 +594,32 @@ at the destination with the same timestamp. Copying preserves input permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` are given (default is ``USE_SOURCE_PERMISSIONS``). +If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve +the symlinks at the paths given until a real file is found, and install +a corresponding symlink in the destination for each symlink encountered. For +each symlink that is installed, the resolution is stripped of the directory, +leaving only the filename, meaning that the new symlink points to a file in +the same directory as the symlink. This feature is useful on some Unix systems, +where libraries are installed as a chain of symlinks with version numbers, with +less specific versions pointing to more specific versions. +``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library +itself into the destination directory. For example, if you have the following +directory structure: + +* ``/opt/foo/lib/libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` +* ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` + +and you do: + +.. code-block:: cmake + + file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) + +This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into +``lib``. + See the :command:`install(DIRECTORY)` command for documentation of permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options. Copying directories preserves the structure diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 2a14ad7..3f03f37 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -17,11 +17,10 @@ find_file .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 0861d67..8a55aca 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -17,11 +17,10 @@ find_library .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``. - On Windows hosts: - ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, - and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 54d5f68..6e1d232 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -59,6 +59,13 @@ for finding the package, checking the version, and producing any needed messages. Some find-modules provide limited or no support for versioning; check the module documentation. +If the ``MODULE`` option is not specfied in the above signature, +CMake first searches for the package using Module mode. Then, if the +package is not found, it searches again using Config mode. A user +may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to +``TRUE`` to direct CMake first search using Config mode before falling +back to Module mode. + Full Signature and Config Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -180,7 +187,7 @@ sets these variables: These variables are checked by the ``find_package`` command to determine whether the configuration file provides an acceptable version. They -are not available after the find_package call returns. If the version +are not available after the ``find_package`` call returns. If the version is acceptable the following variables are set: ``<PackageName>_VERSION`` @@ -220,8 +227,8 @@ Search Procedure CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. -Each entry is meant for installation trees following Windows (W), UNIX -(U), or Apple (A) conventions:: +Each entry is meant for installation trees following Windows (``W``), UNIX +(``U``), or Apple (``A``) conventions:: <prefix>/ (W) <prefix>/(cmake|CMake)/ (W) @@ -234,8 +241,8 @@ Each entry is meant for installation trees following Windows (W), UNIX <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) -On systems supporting macOS Frameworks and Application Bundles the -following directories are searched for frameworks or bundles +On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the +following directories are searched for Frameworks or Application Bundles containing a configuration file:: <prefix>/<name>.framework/Resources/ (A) @@ -262,16 +269,16 @@ that order). * The ``lib`` path is always searched. If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each -(W) or (U) directory entry one-by-one. +(``W``) or (``U``) directory entry one-by-one. This set of directories is intended to work in cooperation with projects that provide configuration files in their installation trees. -Directories above marked with (W) are intended for installations on +Directories above marked with (``W``) are intended for installations on Windows where the prefix may point at the top of an application's -installation directory. Those marked with (U) are intended for +installation directory. Those marked with (``U``) are intended for installations on UNIX platforms where the prefix is shared by multiple -packages. This is merely a convention, so all (W) and (U) directories -are still searched on all platforms. Directories marked with (A) are +packages. This is merely a convention, so all (``W``) and (``U``) directories +are still searched on all platforms. Directories marked with (``A``) are intended for installations on Apple platforms. The :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of preference. @@ -323,8 +330,10 @@ enabled. 6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. + setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` + to ``FALSE`` or the deprecated variable + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user package registry. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 988a3fa..52ffe3c 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -17,11 +17,10 @@ find_path .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index 4f00773..e2ff693 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -15,7 +15,8 @@ find_program .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH`` +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 58bf741..96764a3 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -9,7 +9,7 @@ Get a global property of the CMake instance. Gets a global property from the CMake instance. The value of the ``<property>`` is stored in the variable ``<var>``. -If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``. +If the property is not found, ``<var>`` will be set to ``NOTFOUND``. See the :manual:`cmake-properties(7)` manual for available properties. See also the :command:`get_property` command ``GLOBAL`` option. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 4327681..11e07ea 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -11,7 +11,7 @@ Get a property from a target. The value of the property is stored in the variable ``VAR``. If the target property is not found, the behavior depends on whether it has been defined to be an ``INHERITED`` property or not (see :command:`define_property`). Non-inherited properties will -set ``VAR`` to "NOTFOUND", whereas inherited properties will search the +set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the relevant parent scope as described for the :command:`define_property` command and if still unable to find the property, ``VAR`` will be set to an empty string. diff --git a/Help/command/if.rst b/Help/command/if.rst index a48a0fa..d8e3a45 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -88,7 +88,9 @@ Possible conditions are: ``if(EXISTS path-to-file-or-directory)`` True if the named file or directory exists. Behavior is well-defined - only for full paths. + only for full paths. Resolves symbolic links, i.e. if the named file or + directory is a symbolic link, returns true if the target of the + symbolic link exists. ``if(file1 IS_NEWER_THAN file2)`` True if ``file1`` is newer than ``file2`` or if one of the two files doesn't @@ -227,7 +229,7 @@ above. The result is ``OFF`` which is false. However, if we remove the if(var2) -which is true because ``var2`` is defined to "var1" which is not a false +which is true because ``var2`` is defined to ``var1`` which is not a false constant. Automatic evaluation applies in the other cases whenever the diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst index 375baf2..540a13a 100644 --- a/Help/command/include_external_msproject.rst +++ b/Help/command/include_external_msproject.rst @@ -13,11 +13,11 @@ Include an external Microsoft project file in a workspace. Includes an external Microsoft project in the generated workspace file. Currently does nothing on UNIX. This will create a target -named [projectname]. This can be used in the :command:`add_dependencies` +named ``[projectname]``. This can be used in the :command:`add_dependencies` command to make things depend on the external project. ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to -specify the type of project, id (GUID) of the project and the name of +specify the type of project, id (``GUID``) of the project and the name of the target platform. This is useful for projects requiring values other than the default (e.g. WIX projects). diff --git a/Help/command/install.rst b/Help/command/install.rst index 6910d6d..ab6fef6 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -99,6 +99,7 @@ Windows platforms are unaffected. Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _`install(TARGETS)`: .. _TARGETS: .. code-block:: cmake @@ -147,13 +148,13 @@ project. There are several kinds of target files that may be installed: property are treated as ``FRAMEWORK`` targets on macOS. ``BUNDLE`` - Executables marked with the ``MACOSX_BUNDLE`` property are treated as + Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as ``BUNDLE`` targets on macOS. ``PUBLIC_HEADER`` - Any ``PUBLIC_HEADER`` files associated with a library are installed in + Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple - platforms. Rules defined by this argument are ignored for ``FRAMEWORK`` + platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK` libraries on Apple platforms because the associated files are installed into the appropriate locations inside the framework folder. See :prop_tgt:`PUBLIC_HEADER` for details. @@ -288,18 +289,20 @@ the following additional arguments: is not recommended to use ``NAMELINK_SKIP`` in conjunction with ``NAMELINK_COMPONENT``. -The ``install(TARGETS)`` command can also accept the following options at the +The `install(TARGETS)`_ command can also accept the following options at the top level: ``EXPORT`` This option associates the installed target files with an export called ``<export-name>``. It must appear before any target options. To actually - install the export file itself, call ``install(EXPORT)``, documented below. + install the export file itself, call `install(EXPORT)`_, documented below. + See documentation of the :prop_tgt:`EXPORT_NAME` target property to change + the name of the exported target. ``INCLUDES DESTINATION`` This option specifies a list of directories which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the - ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a + ``<targets>`` when exported by the `install(EXPORT)`_ command. If a relative path is specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. @@ -333,7 +336,7 @@ targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. -:command:`install(TARGETS)` can install targets that were created in +`install(TARGETS)`_ can install targets that were created in other directories. When using such cross-directory install rules, running ``make install`` (or similar) from a subdirectory will not guarantee that targets from other directories are up-to-date. You can use @@ -348,6 +351,8 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Files ^^^^^^^^^^^^^^^^ +.. _`install(FILES)`: +.. _`install(PROGRAMS)`: .. _FILES: .. _PROGRAMS: @@ -436,6 +441,7 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(DIRECTORY)`: .. _DIRECTORY: .. code-block:: cmake @@ -560,6 +566,8 @@ manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(CODE)`: +.. _`install(SCRIPT)`: .. _CODE: .. _SCRIPT: @@ -589,6 +597,7 @@ name, not the file's contents). See the Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _`install(EXPORT)`: .. _EXPORT: .. code-block:: cmake @@ -605,7 +614,7 @@ Installing Exports The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the ``install(TARGETS)`` signature +using the ``EXPORT`` option of the `install(TARGETS)`_ signature documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to the target names as they are written to the import file. By default the generated file will be called ``<export-name>.cmake`` but the ``FILE`` @@ -651,9 +660,9 @@ and installed by the current project. For example, the code install(TARGETS myexe EXPORT myproj DESTINATION bin) install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) - install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules) + install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules) -will install the executable myexe to ``<prefix>/bin`` and code to import +will install the executable ``myexe`` to ``<prefix>/bin`` and code to import it in the file ``<prefix>/lib/myproj/myproj.cmake`` and ``<prefix>/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index f5fb46d..ff074a8 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -21,7 +21,7 @@ or its corresponding location in the binary tree may be listed. If a file specified already has an extension, that extension will be removed first. This is useful for providing lists of source files such as foo.cxx when you want the corresponding foo.h to be installed. -A typical extension is '.h'. +A typical extension is ``.h``. :: diff --git a/Help/command/list.rst b/Help/command/list.rst index bfcdf34..39e7e2a 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -21,6 +21,9 @@ Synopsis list(`APPEND`_ <list> [<element>...]) list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) list(`INSERT`_ <list> <index> [<element>...]) + list(`POP_BACK`_ <list> [<out-var>...]) + list(`POP_FRONT`_ <list> [<out-var>...]) + list(`PREPEND`_ <list> [<element>...]) list(`REMOVE_ITEM`_ <list> <value>...) list(`REMOVE_AT`_ <list> <index>...) list(`REMOVE_DUPLICATES`_ <list>) @@ -33,8 +36,9 @@ Synopsis Introduction ^^^^^^^^^^^^ -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, +``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, +``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new values for the list within the current CMake variable scope. Similar to the :command:`set` command, the LIST command creates new variable values in the current scope, even if the list itself is actually defined in a parent @@ -142,6 +146,34 @@ For more information on regular expressions see also the Inserts elements to the list to the specified location. +.. _POP_BACK: + +.. code-block:: cmake + + list(POP_BACK <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the last element's value to the given variable and removes it, +up to the last variable name given. + +.. _POP_FRONT: + +.. code-block:: cmake + + list(POP_FRONT <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the first element's value to the given variable and removes it, +up to the last variable name given. + +.. _PREPEND: + +.. code-block:: cmake + + list(PREPEND <list> [<element> ...]) + +Insert elements to the 0th position in the list. + .. _REMOVE_ITEM: .. code-block:: cmake @@ -164,7 +196,8 @@ Removes items at given indices from the list. list(REMOVE_DUPLICATES <list>) -Removes duplicated items in the list. +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. .. _TRANSFORM: @@ -174,84 +207,81 @@ Removes duplicated items in the list. [OUTPUT_VARIABLE <output variable>]) Transforms the list by applying an action to all or, by specifying a -``<SELECTOR>``, to the selected elements of the list, storing result in-place -or in the specified output variable. +``<SELECTOR>``, to the selected elements of the list, storing the result +in-place or in the specified output variable. .. note:: - ``TRANSFORM`` sub-command does not change the number of elements of the + The ``TRANSFORM`` sub-command does not change the number of elements in the list. If a ``<SELECTOR>`` is specified, only some elements will be changed, - the other ones will remain same as before the transformation. - -``<ACTION>`` specify the action to apply to the elements of list. -The actions have exactly the same semantics as sub-commands of -:command:`string` command. + the other ones will remain the same as before the transformation. -The ``<ACTION>`` may be one of: +``<ACTION>`` specifies the action to apply to the elements of the list. +The actions have exactly the same semantics as sub-commands of the +:command:`string` command. ``<ACTION>`` must be one of the following: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower characters. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) ``STRIP``: Remove leading and trailing spaces from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> STRIP ...) + list(TRANSFORM <list> STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> GENEX_STRIP ...) + list(TRANSFORM <list> GENEX_STRIP ...) ``REPLACE``: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list (Same semantic as ``REGEX REPLACE`` from :command:`string` command). -.. code-block:: cmake - - list(TRANSFORM <list> REPLACE <regular_expression> - <replace_expression> ...) + .. code-block:: cmake -``<SELECTOR>`` select which elements of the list will be transformed. Only one -type of selector can be specified at a time. + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) -The ``<SELECTOR>`` may be one of: +``<SELECTOR>`` determines which elements of the list will be transformed. +Only one type of selector can be specified at a time. When given, +``<SELECTOR>`` must be one of the following: ``AT``: Specify a list of indexes. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over the range. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular expression will be transformed. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) Ordering diff --git a/Help/command/math.rst b/Help/command/math.rst index 4fa55f6..3cbe719 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -16,7 +16,7 @@ Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, ``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning as in C code. -Hexadecimal numbers are recognized when prefixed with "0x", as in C code. +Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code. The result is formatted according to the option ``OUTPUT_FORMAT``, where ``<format>`` is one of diff --git a/Help/command/message.rst b/Help/command/message.rst index 2b4b1aa..5dca6b4 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -9,24 +9,56 @@ Display a message to the user. The optional ``<mode>`` keyword determines the type of message: -:: - - (none) = Important information - STATUS = Incidental information - WARNING = CMake Warning, continue processing - AUTHOR_WARNING = CMake Warning (dev), continue processing - SEND_ERROR = CMake Error, continue processing, - but skip generation - FATAL_ERROR = CMake Error, stop processing and generation - DEPRECATION = CMake Deprecation Error or Warning if variable - CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED - is enabled, respectively, else no message. - -The CMake command-line tool displays STATUS messages on stdout and all -other message types on stderr. The CMake GUI displays all messages in -its log area. The interactive dialogs (ccmake and CMakeSetup) show -STATUS messages one at a time on a status line and other messages in -interactive pop-up boxes. +``FATAL_ERROR`` + CMake Error, stop processing and generation. + +``SEND_ERROR`` + CMake Error, continue processing, but skip generation. + +``WARNING`` + CMake Warning, continue processing. + +``AUTHOR_WARNING`` + CMake Warning (dev), continue processing. + +``DEPRECATION`` + CMake Deprecation Error or Warning if variable + :variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED` + is enabled, respectively, else no message. + +(none) or ``NOTICE`` + Important message printed to stderr to attract user's attention. + +``STATUS`` + The main interesting messages that project users might be interested in. + Ideally these should be concise, no more than a single line, but still + informative. + +``VERBOSE`` + Detailed informational messages intended for project users. These messages + should provide additional details that won't be of interest in most cases, + but which may be useful to those building the project when they want deeper + insight into what's happening. + +``DEBUG`` + Detailed informational messages intended for developers working on the + project itself as opposed to users who just want to build it. These messages + will not typically be of interest to other users building the project and + will often be closely related to internal implementation details. + +``TRACE`` + Fine-grained messages with very low-level implementation details. Messages + using this log level would normally only be temporary and would expect to be + removed before releasing the project, packaging up the files, etc. + +The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout +with the message preceded by two hyphens and a space. All other message types +are sent to stderr and are not prefixed with hyphens. The +:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. +The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` +messages one at a time on a status line and other messages in an +interactive pop-up box. The ``--loglevel`` command-line option to each of +these tools can be used to control which messages will be shown. CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst index 8bc6a73..b3a6e86 100644 --- a/Help/command/output_required_files.rst +++ b/Help/command/output_required_files.rst @@ -14,6 +14,6 @@ more advanced scanner. output_required_files(srcfile outputfile) Outputs a list of all the source files that are required by the -specified srcfile. This list is written into outputfile. This is -similar to writing out the dependencies for srcfile except that it -jumps from .h files into .cxx, .c and .cpp files if possible. +specified ``srcfile``. This list is written into ``outputfile``. This is +similar to writing out the dependencies for ``srcfile`` except that it +jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible. diff --git a/Help/command/project.rst b/Help/command/project.rst index 688e56c..baf18be 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -31,10 +31,6 @@ Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are set to the empty string. -If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` exists, -the file pointed to by that variable will be included as the last step of the -project command. - Options ^^^^^^^ @@ -59,7 +55,7 @@ The options are: * :variable:`PROJECT_VERSION_TWEAK`, :variable:`<PROJECT-NAME>_VERSION_TWEAK`. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. ``DESCRIPTION <project-description-string>`` @@ -72,7 +68,7 @@ The options are: It is recommended that this description is a relatively short string, usually no more than a few words. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. ``HOMEPAGE_URL <url-string>`` @@ -83,7 +79,7 @@ The options are: to ``<url-string>``, which should be the canonical home URL for the project. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. ``LANGUAGES <language-name>...`` @@ -102,18 +98,32 @@ The options are: The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` options are intended for use as default values in package metadata and documentation. +Code Injection +^^^^^^^^^^^^^^ + +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file +pointed to by that variable will be included as the first step of the +``project()`` command. + +If the :variable:`CMAKE_PROJECT_INCLUDE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files +they point to will be included as the last step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`. + Usage ^^^^^ The top-level ``CMakeLists.txt`` file for a project must contain a -literal, direct call to the :command:`project` command; loading one +literal, direct call to the ``project()`` command; loading one through the :command:`include` command is not sufficient. If no such -call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). +call exists, CMake will issue a warning and pretend there is a +``project(Project)`` at the top to enable the default languages +(``C`` and ``CXX``). .. note:: - Call the :command:`cmake_minimum_required` command at the beginning - of the top-level ``CMakeLists.txt`` file even before calling the - :command:`project()` command. It is important to establish version and - policy settings before invoking other commands whose behavior they - may affect. See also policy :policy:`CMP0000`. + Call the ``project()`` command near the top of the top-level + ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`. + It is important to establish version and policy settings before invoking + other commands whose behavior they may affect. + See also policy :policy:`CMP0000`. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 2624b4b..ec08c8f 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -35,7 +35,7 @@ It must be one of the following: ``SOURCE`` Scope may name zero or more source files. Note that source file properties are visible only to targets added in the same - directory (CMakeLists.txt). + directory (``CMakeLists.txt``). See also the :command:`set_source_files_properties` command. ``INSTALL`` @@ -48,7 +48,7 @@ It must be one of the following: Path components have to be separated by forward slashes, must be normalized and are case sensitive. - To reference the installation prefix itself with a relative path use ".". + To reference the installation prefix itself with a relative path use ``.``. Currently installed file properties are only defined for the WIX generator where the given paths are relative diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 91f995c..ab95d70 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -16,4 +16,4 @@ See also the :command:`set_property(SOURCE)` command. See :ref:`Source File Properties` for the list of properties known to CMake. Source file properties are visible only to targets added -in the same directory (CMakeLists.txt). +in the same directory (``CMakeLists.txt``). diff --git a/Help/command/string.rst b/Help/command/string.rst index 893fb43..2e89d7b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -28,6 +28,7 @@ Synopsis string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`STRIP`_ <string> <out-var>) string(`GENEX_STRIP`_ <string> <out-var>) + string(`REPEAT`_ <string> <count> <out-var>) `Comparison`_ string(`COMPARE`_ <op> <string1> <string2> <out-var>) @@ -269,6 +270,14 @@ trailing spaces removed. Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from the ``input string`` and store the result in the ``output variable``. +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <input string> <count> <output variable>) + +Produce the output string as repetion of ``input string`` ``count`` times. + Comparison ^^^^^^^^^^ diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index c5e4f9f..c2e7e8a 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -57,7 +57,7 @@ Each ``<item>`` may be: as when a shared library is detected to have no ``SONAME`` field. See policy :policy:`CMP0060` for discussion of another case. - If the library file is in a Mac OSX framework, the ``Headers`` directory + If the library file is in a macOS framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same effect as passing the framework directory as an include directory. diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 285455a..b5abbc4 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -1,7 +1,8 @@ target_link_options ------------------- -Add link options to a target. +Add options to the link step for an executable, shared library or module +library target. .. code-block:: cmake @@ -9,20 +10,25 @@ Add link options to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specifies link options to use when linking a given target. The -named ``<target>`` must have been created by a command such as +The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. +This command can be used to add any link options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +.. note:: + + This command cannot be used to add options for static library targets, + since they do not use a linker. To add archiver or MSVC librarian flags, + see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. -This command can be used to add any options, but -alternative commands exist to add libraries -(:command:`target_link_libraries` and :command:`link_libraries`). -See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and -:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. - The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS` property of diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index ca8fc77..0bc2ca3 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -135,6 +135,7 @@ default values: * :variable:`CMAKE_ENABLE_EXPORTS` * :variable:`CMAKE_LINK_SEARCH_START_STATIC` * :variable:`CMAKE_LINK_SEARCH_END_STATIC` +* :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` If :policy:`CMP0056` is set to ``NEW``, then diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 4d9e12b..5b0e2ee 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -9,7 +9,7 @@ Copy mesa headers for use in combination with system GL. use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) -The path to mesa includes, should contain gl_mangle.h. The mesa +The path to mesa includes, should contain ``gl_mangle.h``. The mesa headers are copied to the specified output directory. This allows mangled mesa headers to override other GL headers by being added to the include directory path earlier. diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst index b4742a5..322b154 100644 --- a/Help/command/variable_requires.rst +++ b/Help/command/variable_requires.rst @@ -18,5 +18,5 @@ tested, if that variable is false nothing else is done. If ``TEST_VARIABLE`` is true, then the next argument (``RESULT_VARIABLE``) is a variable that is set to true if all the required variables are set. The rest of the arguments are variables that must be true or not set -to NOTFOUND to avoid an error. If any are not true, an error is +to ``NOTFOUND`` to avoid an error. If any are not true, an error is reported. |