diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/add_compile_definitions.rst | 2 | ||||
| -rw-r--r-- | Help/command/add_link_options.rst | 2 | ||||
| -rw-r--r-- | Help/command/cmake_language.rst | 2 | ||||
| -rw-r--r-- | Help/command/cmake_parse_arguments.rst | 2 | ||||
| -rw-r--r-- | Help/command/configure_file.rst | 6 | ||||
| -rw-r--r-- | Help/command/continue.rst | 2 | ||||
| -rw-r--r-- | Help/command/get_property.rst | 31 | ||||
| -rw-r--r-- | Help/command/get_source_file_property.rst | 41 | ||||
| -rw-r--r-- | Help/command/include_guard.rst | 2 | ||||
| -rw-r--r-- | Help/command/install.rst | 3 | ||||
| -rw-r--r-- | Help/command/set_property.rst | 32 | ||||
| -rw-r--r-- | Help/command/set_source_files_properties.rst | 36 | ||||
| -rw-r--r-- | Help/command/target_compile_features.rst | 2 | ||||
| -rw-r--r-- | Help/command/target_link_directories.rst | 2 | ||||
| -rw-r--r-- | Help/command/target_link_options.rst | 2 | ||||
| -rw-r--r-- | Help/command/target_precompile_headers.rst | 2 | ||||
| -rw-r--r-- | Help/command/target_sources.rst | 2 | ||||
| -rw-r--r-- | Help/command/variable_watch.rst | 39 |
18 files changed, 151 insertions, 59 deletions
diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst index e10aba0..48e33be 100644 --- a/Help/command/add_compile_definitions.rst +++ b/Help/command/add_compile_definitions.rst @@ -1,6 +1,8 @@ add_compile_definitions ----------------------- +.. versionadded:: 3.12 + Add preprocessor definitions to the compilation of source files. .. code-block:: cmake diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index faa4afb..f03e7c0 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -1,6 +1,8 @@ add_link_options ---------------- +.. versionadded:: 3.13 + Add options to the link step for executable, shared library or module library targets in the current directory and below that are added after this command is invoked. diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 0988097..9e98d79 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -1,6 +1,8 @@ cmake_language -------------- +.. versionadded:: 3.18 + Call meta-operations on CMake commands. Synopsis diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index fcd36d0..8803ec8 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -1,6 +1,8 @@ cmake_parse_arguments --------------------- +.. versionadded:: 3.5 + Parse function or macro arguments. .. code-block:: cmake diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 29e85bd..46d1a05 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -7,6 +7,7 @@ Copy a file to another location and modify its contents. configure_file(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY] + [NO_SOURCE_PERMISSIONS] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) Copies an ``<input>`` file to an ``<output>`` file and substitutes @@ -82,6 +83,11 @@ The arguments are: Restrict variable replacement to references of the form ``@VAR@``. This is useful for configuring scripts that use ``${VAR}`` syntax. + ``NO_SOURCE_PERMISSIONS`` + Does not transfer the file permissions of the original file to the copy. + The copied file permissions default to the standard 644 value + (-rw-r--r--). + ``NEWLINE_STYLE <style>`` Specify the newline style for the output file. Specify ``UNIX`` or ``LF`` for ``\n`` newlines, or specify diff --git a/Help/command/continue.rst b/Help/command/continue.rst index 31c7089..f62802e 100644 --- a/Help/command/continue.rst +++ b/Help/command/continue.rst @@ -1,6 +1,8 @@ continue -------- +.. versionadded:: 3.2 + Continue to the top of enclosing foreach or while loop. .. code-block:: cmake diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 123cd45..0602518 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -10,7 +10,7 @@ Get a property. DIRECTORY [<dir>] | TARGET <target> | SOURCE <source> | - [TARGET_DIRECTORY <target> | DIRECTORY <dir>] | + [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | INSTALL <file> | TEST <test> | CACHE <entry> | @@ -31,18 +31,36 @@ It must be one of the following: Scope defaults to the current directory but another directory (already processed by CMake) may be named by the full or relative path ``<dir>``. + See also the :command:`get_directory_property` command. ``TARGET`` Scope must name one existing target. + See also the :command:`get_target_property` command. ``SOURCE`` - Scope must name one source file. + Scope must name one source file. By default, the source file's property + will be read from the current source directory's scope, but this can be + overridden with one of the following sub-options: + + ``DIRECTORY <dir>`` + The source file property will be read from the ``<dir>`` directory's + scope. CMake must already know about that source directory, either by + having added it through a call to :command:`add_subdirectory` or ``<dir>`` + being the top level source directory. Relative paths are treated as + relative to the current source directory. + + ``TARGET_DIRECTORY <target>`` + The source file property will be read from the directory scope in which + ``<target>`` was created (``<target>`` must therefore already exist). + + See also the :command:`get_source_file_property` command. ``INSTALL`` Scope must name one installed file path. ``TEST`` Scope must name one existing test. + See also the :command:`get_test_property` command. ``CACHE`` Scope must name one cache entry. @@ -50,15 +68,6 @@ It must be one of the following: ``VARIABLE`` Scope is unique and does not accept a name. -In the ``SOURCE`` case, the queried source file scope can be changed by -specifying one of the additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``. - -``DIRECTORY`` takes a path to a processed directory, and the source file property -will be read from that directory scope. - -``TARGET_DIRECTORY`` takes the name of an existing target. The source file -property will be read from this target's directory scope. - The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is returned, although some properties support inheriting from a parent scope diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 1060251..76ed776 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -5,24 +5,33 @@ Get a property for a source file. .. code-block:: cmake - get_source_file_property(VAR file [TARGET_DIRECTORY <target> | DIRECTORY <dir>] property) + get_source_file_property(<variable> <file> + [DIRECTORY <dir> | TARGET_DIRECTORY <target>] + <property>) Gets a property from a source file. The value of the property is -stored in the variable ``VAR``. If the source 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 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. - -The queried source file scope can be changed by specifying one of the -additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``. - -``DIRECTORY`` takes a path to a processed directory, and the source file property -will be read from that directory scope. - -``TARGET_DIRECTORY`` takes the name of an existing target. The source file -property will be read from this target's directory scope. +stored in the specified ``<variable>``. If the source property is not found, +the behavior depends on whether it has been defined to be an ``INHERITED`` +property or not (see :command:`define_property`). Non-inherited properties +will set ``variable`` 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, ``variable`` will be set to +an empty string. + +By default, the source file's property will be read from the current source +directory's scope, but this can be overridden with one of the following +sub-options: + +``DIRECTORY <dir>`` + The source file property will be read from the ``<dir>`` directory's + scope. CMake must already know about that source directory, either by + having added it through a call to :command:`add_subdirectory` or ``<dir>`` + being the top level source directory. Relative paths are treated as + relative to the current source directory. + +``TARGET_DIRECTORY <target>`` + The source file property will be read from the directory scope in which + ``<target>`` was created (``<target>`` must therefore already exist). Use :command:`set_source_files_properties` to set property values. Source file properties usually control how the file is built. One property that is diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst index 877aa86..dca3b6f 100644 --- a/Help/command/include_guard.rst +++ b/Help/command/include_guard.rst @@ -1,6 +1,8 @@ include_guard ------------- +.. versionadded:: 3.10 + Provides an include guard for the file currently being processed by CMake. .. code-block:: cmake diff --git a/Help/command/install.rst b/Help/command/install.rst index c8df7d9..c11eaf4 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -45,6 +45,9 @@ signatures that specify them. The common options are: As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer generators, it is preferable to use relative paths throughout. + In particular, there is no need to make paths absolute by prepending + :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if + the DESTINATION is a relative path. ``PERMISSIONS`` Specify permissions for installed files. Valid permissions are diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index ccbd635..93c2d9c 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,13 +9,13 @@ Set a named property in a given scope. DIRECTORY [<dir>] | TARGET [<target1> ...] | SOURCE [<src1> ...] - [TARGET_DIRECTORY <target1> ...] - [DIRECTORY <dir1> ...] | + [DIRECTORY <dirs> ...] | + [TARGET_DIRECTORY <targets> ...] INSTALL [<file1> ...] | TEST [<test1> ...] | CACHE [<entry1> ...] > [APPEND] [APPEND_STRING] - PROPERTY <name> [value1 ...]) + PROPERTY <name> [<value1> ...]) Sets one property on zero or more objects of a scope. @@ -35,17 +35,23 @@ It must be one of the following: See also the :command:`set_target_properties` command. ``SOURCE`` - Scope may name zero or more source files. Note that source - file properties are by default visible only to targets added in the same - directory (``CMakeLists.txt``). - The file properties can be made visible in a different directory by specifying - one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``. + Scope may name zero or more source files. By default, source file properties + are only visible to targets added in the same directory (``CMakeLists.txt``). + Visibility can be set in other directory scopes using one or both of the + following sub-options: + + ``DIRECTORY <dirs>...`` + The source file property will be set in each of the ``<dirs>`` + directories' scopes. CMake must already know about each of these + source directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. + + ``TARGET_DIRECTORY <targets>...`` + The source file property will be set in each of the directory scopes + where any of the specified ``<targets>`` were created (the ``<targets>`` + must therefore already exist). - ``DIRECTORY`` takes a list of processed directories paths, and sets the file - properties in those directory scopes. - - ``TARGET_DIRECTORY`` takes a list of existing targets. The file - properties will be set in these targets' directory scopes. See also the :command:`set_source_files_properties` command. ``INSTALL`` diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 59d5ba3..9558b40 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -5,29 +5,33 @@ Source files can have properties that affect how they are built. .. code-block:: cmake - set_source_files_properties([file1 [file2 [...]]] - [TARGET_DIRECTORY <target1> ...] - [DIRECTORY <dir1> ...] - PROPERTIES prop1 value1 - [prop2 value2 [...]]) + set_source_files_properties(<files> ... + [DIRECTORY <dirs> ...] + [TARGET_DIRECTORY <targets> ...] + PROPERTIES <prop1> <value1> + [<prop2> <value2>] ...) Sets properties associated with source files using a key/value paired list. -Note that source file properties are by default visible only to -targets added in the same directory (``CMakeLists.txt``). +By default, source file properties are only visible to targets added in the +same directory (``CMakeLists.txt``). Visibility can be set in other directory +scopes using one or both of the following options: -The file properties can be made visible in a different directory by specifying -one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``. +``DIRECTORY <dirs>...`` + The source file properties will be set in each of the ``<dirs>`` + directories' scopes. CMake must already know about each of these + source directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. -``DIRECTORY`` takes a list of processed directories paths, and sets the file -properties in those directory scopes. - -``TARGET_DIRECTORY`` takes a list of existing targets. The file -properties will be set in these targets' directory scopes. +``TARGET_DIRECTORY <targets>...`` + The source file properties will be set in each of the directory scopes + where any of the specified ``<targets>`` were created (the ``<targets>`` + must therefore already exist). +Use :command:`get_source_file_property` to get property values. 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``). +to CMake. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index c5401e6..b50be34 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -1,6 +1,8 @@ target_compile_features ----------------------- +.. versionadded:: 3.1 + Add expected compiler features to a target. .. code-block:: cmake diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index 76da94d..bb75a3d 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -1,6 +1,8 @@ target_link_directories ----------------------- +.. versionadded:: 3.13 + Add link directories to a target. .. code-block:: cmake diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 89038e3..e59e0e1 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -1,6 +1,8 @@ target_link_options ------------------- +.. versionadded:: 3.13 + Add options to the link step for an executable, shared library or module library target. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index d4280b1..7005180 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -1,6 +1,8 @@ target_precompile_headers ------------------------- +.. versionadded:: 3.16 + Add a list of header files to precompile. Precompiling header files can speed up compilation by creating a partially diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 27e737b..856d869 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -1,6 +1,8 @@ target_sources -------------- +.. versionadded:: 3.1 + Add sources to a target. .. code-block:: cmake diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst index ce69bcf..8293f5a 100644 --- a/Help/command/variable_watch.rst +++ b/Help/command/variable_watch.rst @@ -7,9 +7,42 @@ Watch the CMake variable for change. variable_watch(<variable> [<command>]) -If the specified ``<variable>`` changes, a message will be printed -to inform about the change. +If the specified ``<variable>`` changes and no ``<command>`` is given, +a message will be printed to inform about the change. -Additionally, if ``<command>`` is given, this command will be executed. +If ``<command>`` is given, this command will be executed instead. The command will receive the following arguments: ``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` + +``<variable>`` + Name of the variable being accessed. + +``<access>`` + One of ``READ_ACCESS``, ``UNKNOWN_READ_ACCESS``, ``MODIFIED_ACCESS``, + ``UNKNOWN_MODIFIED_ACCESS``, or ``REMOVED_ACCESS``. The ``UNKNOWN_`` + values are only used when the variable has never been set. Once set, + they are never used again during the same CMake run, even if the + variable is later unset. + +``<value>`` + The value of the variable. On a modification, this is the new + (modified) value of the variable. On removal, the value is empty. + +``<current_list_file>`` + Full path to the file doing the access. + +``<stack>`` + List of absolute paths of all files currently on the stack of file + inclusion, with the bottom-most file first and the currently + processed file (that is, ``current_list_file``) last. + +Note that for some accesses such as :command:`list(APPEND)`, the watcher +is executed twice, first with a read access and then with a write one. +Also note that an :command:`if(DEFINED)` query on the variable does not +register as an access and the watcher is not executed. + +Only non-cache variables can be watched using this command. Access to +cache variables is never watched. However, the existence of a cache +variable ``var`` causes accesses to the non-cache variable ``var`` to +not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var`` +has never existed. |