From 2a58c872d7764e9a4c618662ae49da289789e44f Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 5 Aug 2014 10:12:59 -0400 Subject: [PATCH] Help: Revise and format 'add_custom_command' docs Format the reStructuredText markup manually. Organize the command options into a definition list. Use inline markup to cross-reference related documents. --- Help/command/add_custom_command.rst | 219 ++++++++++++++++------------ 1 file changed, 122 insertions(+), 97 deletions(-) diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index a7390efcf..48e2a5dd4 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -3,10 +3,12 @@ add_custom_command Add a custom build rule to the generated build system. -There are two main signatures for add_custom_command The first -signature is for adding a custom command to produce an output. +There are two main signatures for ``add_custom_command``. -:: +Generating Files +^^^^^^^^^^^^^^^^ + +The first signature is for adding a custom command to produce an output:: add_custom_command(OUTPUT output1 [output2 ...] COMMAND command1 [ARGS] [args1...] @@ -18,28 +20,117 @@ signature is for adding a custom command to produce an output. [WORKING_DIRECTORY dir] [COMMENT comment] [VERBATIM] [APPEND]) -This defines a command to generate specified OUTPUT file(s). A target -created in the same directory (CMakeLists.txt file) that specifies any -output of the custom command as a source file is given a rule to -generate the file using the command at build time. Do not list the -output in more than one independent target that may build in parallel -or the two instances of the rule may conflict (instead use -add_custom_target to drive the command and make the other targets -depend on that one). If an output name is a relative path it will be -interpreted relative to the build tree directory corresponding to the -current source directory. Note that MAIN_DEPENDENCY is completely -optional and is used as a suggestion to visual studio about where to -hang the custom command. In makefile terms this creates a new target -in the following form: - -:: +This defines a command to generate specified ``OUTPUT`` file(s). +A target created in the same directory (``CMakeLists.txt`` file) +that specifies any output of the custom command as a source file +is given a rule to generate the file using the command at build time. +Do not list the output in more than one independent target that +may build in parallel or the two instances of the rule may conflict +(instead use the :command:`add_custom_target` command to drive the +command and make the other targets depend on that one). +In makefile terms this creates a new target in the following form:: OUTPUT: MAIN_DEPENDENCY DEPENDS COMMAND -If more than one command is specified they will be executed in order. -The optional ARGS argument is for backward compatibility and will be -ignored. +The options are: + +``APPEND`` + Append the ``COMMAND`` and ``DEPENDS`` option values to the custom + command for the first output specified. There must have already + been a previous call to this command with the same output. + The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` + options are currently ignored when APPEND is given, but may be + used in the future. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one command is specified they will be executed in order. + The optional ``ARGS`` argument is for backward compatibility and + will be ignored. + + 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 any target using this custom + command. However this does NOT add a file-level dependency that + would cause the custom command to re-run whenever the executable is + recompiled. + + Arguments to ``COMMAND`` may use + :manual:`generator expressions `. + References to target names in generator expressions imply target-level + dependencies, but NOT file-level dependencies. List target names with + the ``DEPENDS`` option to add file-level dependencies. + +``COMMENT`` + Display the given message before the commands are executed at + build time. + +``DEPENDS`` + Specify files on which the command depends. If any dependency is + an ``OUTPUT`` of another custom command in the same directory + (``CMakeLists.txt`` file) CMake automatically brings the other + custom command into the target in which this command is built. + If ``DEPENDS`` is not specified the command will run whenever + the ``OUTPUT`` is missing; if the command does not actually + create the ``OUTPUT`` then the rule will always run. + If ``DEPENDS`` specifies any target (created by the + :command:`add_custom_target`, :command:`add_executable`, or + :command:`add_library` command) a target-level dependency is + created to make sure the target is built before any target + using this custom command. Additionally, if the target is an + executable or library a file-level dependency is created to + cause the custom command to re-run whenever the target is + recompiled. + + Arguments to ``DEPENDS`` may use + :manual:`generator expressions `. + +``IMPLICIT_DEPENDS`` + Request scanning of implicit dependencies of an input file. + The language given specifies the programming language whose + corresponding dependency scanner should be used. + Currently only ``C`` and ``CXX`` language scanners are supported. + The language has to be specified for every file in the + ``IMPLICIT_DEPENDS`` list. Dependencies discovered from the + scanning are added to those of the custom command at build time. + Note that the ``IMPLICIT_DEPENDS`` option is currently supported + only for Makefile generators and will be ignored by other generators. + +``MAIN_DEPENDENCY`` + Specify the primary input source file to the command. This is + treated just like any value given to the ``DEPENDS`` option + but also suggests to Visual Studio generators where to hang + the custom command. + +``OUTPUT`` + Specify the output files the command is expected to produce. + If an output name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + 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. + +``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before add_custom_command even sees the + arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + +``WORKING_DIRECTORY`` + Execute the command with the given current working directory. + If it is a relative path it will be interpreted relative to the + build tree directory corresponding to the current source directory. + +Build Events +^^^^^^^^^^^^ The second signature adds a custom command to a target such as a library or executable. This is useful for performing an operation @@ -60,79 +151,13 @@ This defines a new command that will be associated with building the specified target. When the command will happen is determined by which of the following is specified: -:: - - PRE_BUILD - run before all other dependencies - PRE_LINK - run after other dependencies - POST_BUILD - run after the target has been built - -Note that the PRE_BUILD option is only supported on Visual Studio 7 or -later. For all other generators PRE_BUILD will be treated as -PRE_LINK. - -If WORKING_DIRECTORY is specified the command will be executed in the -directory given. 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. If APPEND is -specified the COMMAND and DEPENDS option values are appended to the -custom command for the first output specified. There must have -already been a previous call to this command with the same output. -The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are -currently ignored when APPEND is given, but may be used in the future. - -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_command -even sees the arguments. Use of VERBATIM is recommended as it enables -correct behavior. When VERBATIM is not given the behavior is platform -specific because there is no protection of tool-specific special -characters. - -If the output of the custom command is not actually created as a file -on disk it should be marked as SYMBOLIC with -SET_SOURCE_FILES_PROPERTIES. - -The IMPLICIT_DEPENDS option requests scanning of implicit dependencies -of an input file. The language given specifies the programming -language whose corresponding dependency scanner should be used. -Currently only C and CXX language scanners are supported. The -language has to be specified for every file in the IMPLICIT_DEPENDS -list. Dependencies discovered from the scanning are added to those of -the custom command at build time. Note that the IMPLICIT_DEPENDS -option is currently supported only for Makefile generators and will be -ignored by other generators. - -If COMMAND specifies an executable target (created by ADD_EXECUTABLE) -it will automatically be replaced by the location of the executable -created at build time. Additionally a target-level dependency will be -added so that the executable target will be built before any target -using this custom command. However this does NOT add a file-level -dependency that would cause the custom command to re-run whenever the -executable is recompiled. - -Arguments to COMMAND may use "generator expressions" with the syntax -``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for -available expressions. - -References to target names in generator expressions imply target-level -dependencies, but NOT file-level dependencies. List target names with -the DEPENDS option to add file dependencies. - -The DEPENDS option specifies files on which the command depends. If -any dependency is an OUTPUT of another custom command in the same -directory (CMakeLists.txt file) CMake automatically brings the other -custom command into the target in which this command is built. If -DEPENDS is not specified the command will run whenever the OUTPUT is -missing; if the command does not actually create the OUTPUT then the -rule will always run. If DEPENDS specifies any target (created by an -ADD_* command) a target-level dependency is created to make sure the -target is built before any target using this custom command. -Additionally, if the target is an executable or library a file-level -dependency is created to cause the custom command to re-run whenever -the target is recompiled. - -Arguments to ``DEPENDS`` may use "generator expressions" with the syntax -``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for -available expressions. +``PRE_BUILD`` + Run before any other rules are executed within the target. + This is supported only on Visual Studio 7 or later. + For all other generators ``PRE_BUILD`` will be treated as + ``PRE_LINK``. +``PRE_LINK`` + Run after sources have been compiled but before linking the binary + or running the librarian or archiver tool of a static library. +``POST_BUILD`` + Run after all other rules within the target have been executed.