From 66ea634b4c4ed75e3c5a56acd7d312f8ad764c49 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 13 Nov 2014 11:52:54 -0500 Subject: [PATCH] Help: Revise and format 'add_custom_target' 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_target.rst | 89 +++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 27 deletions(-) diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 1bf70bffd..4f8e1903a 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -13,33 +13,68 @@ Add a target with no output so it will always be built. [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). +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. -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 options are: -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. +``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``). + +``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 `. + 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. + +``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.