diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/add_custom_command.rst | 36 | ||||
| -rw-r--r-- | Help/command/add_custom_target.rst | 123 | ||||
| -rw-r--r-- | Help/command/get_property.rst | 42 | ||||
| -rw-r--r-- | Help/command/set_property.rst | 49 | ||||
| -rw-r--r-- | Help/command/string.rst | 7 | ||||
| -rw-r--r-- | Help/command/target_include_directories.rst | 3 | ||||
| -rw-r--r-- | Help/command/target_link_libraries.rst | 3 |
7 files changed, 202 insertions, 61 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index e8b7cc8..9fbad4b 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -15,10 +15,12 @@ The first signature is for adding a custom command to produce an output:: [COMMAND command2 [ARGS] [args2...] ...] [MAIN_DEPENDENCY depend] [DEPENDS [depends...]] + [BYPRODUCTS [files...]] [IMPLICIT_DEPENDS <lang1> depend1 [<lang2> depend2] ...] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM] [APPEND]) + [COMMENT comment] + [VERBATIM] [APPEND] [USES_TERMINAL]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -43,6 +45,27 @@ The options are: options are currently ignored when APPEND is given, but may be used in the future. +``BYPRODUCTS`` + Specify the files the command is expected to produce but whose + modification time may or may not be newer than the dependencies. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -114,10 +137,17 @@ The options are: If an output name is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + Each output file will be marked with the :prop_sf:`GENERATED` + source file property automatically. If the output of the custom command is not actually created as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` source file property. +``USES_TERMINAL`` + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` pool. + ``VERBATIM`` All arguments to the commands will be escaped properly for the build tool so that the invoked command receives each argument @@ -148,8 +178,10 @@ target is already built, the command will not execute. PRE_BUILD | PRE_LINK | POST_BUILD COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] + [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM]) + [COMMENT comment] + [VERBATIM] [USES_TERMINAL]) This defines a new command that will be associated with building the specified target. When the command will happen is determined by which diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 1bf70bf..996d08e 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -8,38 +8,101 @@ Add a target with no output so it will always be built. add_custom_target(Name [ALL] [command1 [args1...]] [COMMAND command2 [args2...] ...] [DEPENDS depend depend depend ... ] + [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM] + [COMMENT comment] + [VERBATIM] [USES_TERMINAL] [SOURCES src1 [src2...]]) Adds a target with the given name that executes the given commands. -The target has no output file and is ALWAYS CONSIDERED OUT OF DATE +The target has no output file and is *always considered out of date* even if the commands try to create a file with the name of the target. -Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By -default nothing depends on the custom target. Use ADD_DEPENDENCIES to -add dependencies to or from other targets. If the ALL option is -specified it indicates that this target should be added to the default -build target so that it will be run every time (the command cannot be -called ALL). The command and arguments are optional and if not -specified an empty target will be created. If WORKING_DIRECTORY is -set, then the command will be run in that directory. If it is a -relative path it will be interpreted relative to the build tree -directory corresponding to the current source directory. If COMMENT -is set, the value will be displayed as a message before the commands -are executed at build time. Dependencies listed with the DEPENDS -argument may reference files and outputs of custom commands created -with add_custom_command() in the same directory (CMakeLists.txt file). - -If VERBATIM is given then all arguments to the commands will be -escaped properly for the build tool so that the invoked command -receives each argument unchanged. Note that one level of escapes is -still used by the CMake language processor before add_custom_target -even sees the arguments. Use of VERBATIM is recommended as it enables -correct behavior. When VERBATIM is not given the behavior is platform -specific because there is no protection of tool-specific special -characters. - -The SOURCES option specifies additional source files to be included in -the custom target. Specified source files will be added to IDE -project files for convenience in editing even if they have not build -rules. +Use the :command:`add_custom_command` command to generate a file with +dependencies. By default nothing depends on the custom target. Use +the :command:`add_dependencies` command to add dependencies to or +from other targets. + +The options are: + +``ALL`` + Indicate that this target should be added to the default build + target so that it will be run every time (the command cannot be + called ``ALL``). + +``BYPRODUCTS`` + Specify the files the command is expected to produce but whose + modification time may or may not be updated on subsequent builds. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + but *not* necessarily composed into a stateful shell or batch script. + (To run a full script, use the :command:`configure_file` command or the + :command:`file(GENERATE)` command to create it, and then specify + a ``COMMAND`` to launch it.) + + If ``COMMAND`` specifies an executable target (created by the + :command:`add_executable` command) it will automatically be replaced + by the location of the executable created at build time. + Additionally a target-level dependency will be added so that the + executable target will be built before this custom target. + + Arguments to ``COMMAND`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + References to target names in generator expressions imply target-level + dependencies. + + The command and arguments are optional and if not specified an empty + target will be created. + +``COMMENT`` + Display the given message before the commands are executed at + build time. + +``DEPENDS`` + Reference files and outputs of custom commands created with + :command:`add_custom_command` command calls in the same directory + (``CMakeLists.txt`` file). They will be brought up to date when + the target is built. + +``SOURCES`` + Specify additional source files to be included in the custom target. + Specified source files will be added to IDE project files for + convenience in editing even if they have no build rules. + +``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before ``add_custom_target`` even sees + the arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + +``USES_TERMINAL`` + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` pool. + +``WORKING_DIRECTORY`` + Execute the command with the given current working directory. + If it is a relative path it will be interpreted relative to the + build tree directory corresponding to the current source directory. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index c2937be..632ece6 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -10,6 +10,7 @@ Get a property. DIRECTORY [dir] | TARGET <target> | SOURCE <source> | + INSTALL <file> | TEST <test> | CACHE <entry> | VARIABLE> @@ -21,29 +22,40 @@ specifies the variable in which to store the result. The second argument determines the scope from which to get the property. It must be one of the following: -GLOBAL scope is unique and does not accept a name. +``GLOBAL`` + Scope is unique and does not accept a name. -DIRECTORY scope defaults to the current directory but another -directory (already processed by CMake) may be named by full or -relative path. +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. -TARGET scope must name one existing target. +``TARGET`` + Scope must name one existing target. -SOURCE scope must name one source file. +``SOURCE`` + Scope must name one source file. -TEST scope must name one existing test. +``INSTALL`` + Scope must name one installed file path. -CACHE scope must name one cache entry. +``TEST`` + Scope must name one existing test. -VARIABLE scope is unique and does not accept a name. +``CACHE`` + Scope must name one cache entry. -The required PROPERTY option is immediately followed by the name of +``VARIABLE`` + Scope is unique and does not accept a name. + +The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is -returned. If the SET option is given the variable is set to a boolean -value indicating whether the property has been set. If the DEFINED +returned. If the ``SET`` option is given the variable is set to a boolean +value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating -whether the property has been defined such as with define_property. -If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a +whether the property has been defined such as with the +:command:`define_property` command. +If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a string containing documentation for the requested property. If documentation is requested for a property that has not been defined -NOTFOUND is returned. +``NOTFOUND`` is returned. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 8cb963e..6200230 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,6 +9,7 @@ Set a named property in a given scope. DIRECTORY [dir] | TARGET [target1 [target2 ...]] | SOURCE [src1 [src2 ...]] | + INSTALL [file1 [file2 ...]] | TEST [test1 [test2 ...]] | CACHE [entry1 [entry2 ...]]> [APPEND] [APPEND_STRING] @@ -18,26 +19,48 @@ Set one property on zero or more objects of a scope. The first argument determines the scope in which the property is set. It must be one of the following: -GLOBAL scope is unique and does not accept a name. +``GLOBAL`` + Scope is unique and does not accept a name. -DIRECTORY scope defaults to the current directory but another -directory (already processed by CMake) may be named by full or -relative path. +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. -TARGET scope may name zero or more existing targets. +``TARGET`` + Scope may name zero or more existing targets. -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). +``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). -TEST scope may name zero or more existing tests. +``INSTALL`` + Scope may name zero or more installed file paths. + These are made available to CPack to influence deployment. -CACHE scope must name zero or more cache existing entries. + Both the property key and value may use generator expressions. + Specific properties may apply to installed files and/or directories. -The required PROPERTY option is immediately followed by the name of + Path components have to be separated by forward slashes, + must be normalized and are case sensitive. + + To reference the installation prefix itself with a relative path use ".". + + Currently installed file properties are only defined for + the WIX generator where the given paths are relative + to the installation prefix. + +``TEST`` + Scope may name zero or more existing tests. + +``CACHE`` + Scope must name zero or more cache existing entries. + +The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the property value in the form of a semicolon-separated list. If the -APPEND option is given the list is appended to any existing property -value.If the APPEND_STRING option is given the string is append to any +``APPEND`` option is given the list is appended to any existing property +value. If the ``APPEND_STRING`` option is given the string is append to any existing property value as string, i.e. it results in a longer string and not a list of strings. diff --git a/Help/command/string.rst b/Help/command/string.rst index 07d0ff3..351385b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -73,8 +73,13 @@ TOUPPER/TOLOWER will convert string to upper/lower characters. LENGTH will return a given string's length. -SUBSTRING will return a substring of a given string. If length is -1 +SUBSTRING will return a substring of a given string. If length is -1 the remainder of the string starting at begin will be returned. +If string is shorter than length then end of string is used instead. + +.. note:: + CMake 3.1 and below reported an error if length pointed past + the end of string. STRIP will return a substring of a given string with leading and trailing spaces removed. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index fd433a8..1d236ce 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -54,3 +54,6 @@ installation prefix. For example: $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 39537a7..e6a82b6 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -49,6 +49,9 @@ CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` from linked library targets. Usage requirements of dependencies affect compilation of sources in the ``<target>``. +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt + If an ``<item>`` is a library in a Mac OX framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same |