From d5b2745b34cba326a634bee677bb80c79ada52d9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 4 May 2018 09:10:32 -0400 Subject: Help: Re-order file command docs Prepare for the addition of section headers for grouping commands. --- Help/command/file.rst | 250 +++++++++++++++++++++++++------------------------- 1 file changed, 125 insertions(+), 125 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index 43ce3d9..518ba9d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -7,22 +7,6 @@ File manipulation command. :: - file(WRITE ...) - file(APPEND ...) - -Write ```` into a file called ````. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ```` that do not -exist will be created. - -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. - ------------------------------------------------------------------------------- - -:: - file(READ [OFFSET ] [LIMIT ] [HEX]) @@ -97,6 +81,98 @@ command. :: + file(TIMESTAMP [] [UTC]) + +Compute a string representation of the modification time of ```` +and store it in ````. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ```` and ``UTC`` options. + +------------------------------------------------------------------------------ + +:: + + file(WRITE ...) + file(APPEND ...) + +Write ```` into a file called ````. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ```` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +------------------------------------------------------------------------------ + +:: + + file(TOUCH [...]) + file(TOUCH_NOCREATE [...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +------------------------------------------------------------------------------ + +:: + + file(GENERATE OUTPUT output-file + + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator `. Evaluate +:manual:`generator expressions ` +from the input content to produce the output content. The options are: + +``CONDITION `` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT `` + Use the content given explicitly as input. + +``INPUT `` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT `` + Specify the output file name to generate. Use generator expressions + such as ``$`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ```` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +------------------------------------------------------------------------------ + +:: + file(GLOB [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) @@ -180,6 +256,39 @@ Create the given directories and their parents as needed. :: + file( ... DESTINATION + [FILE_PERMISSIONS ...] + [DIRECTORY_PERMISSIONS ...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN | REGEX ] + [EXCLUDE] [PERMISSIONS ...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +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``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +------------------------------------------------------------------------------ + +:: + file(RELATIVE_PATH ) Compute the relative path from a ```` to a ```` and @@ -294,115 +403,6 @@ If neither ``TLS`` option is given CMake will check variables :: - file(TOUCH [...]) - file(TOUCH_NOCREATE [...]) - -Create a file with no content if it does not yet exist. If the file already -exists, its access and/or modification will be updated to the time when the -function call is executed. - -Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file -does not exist it will be silently ignored. - -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. - ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP [] [UTC]) - -Compute a string representation of the modification time of ```` -and store it in ````. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ```` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator `. Evaluate -:manual:`generator expressions ` -from the input content to produce the output content. The options are: - -``CONDITION `` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT `` - Use the content given explicitly as input. - -``INPUT `` - Use the content from a given file as input. - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - -``OUTPUT `` - Specify the output file name to generate. Use generator expressions - such as ``$`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ```` - must evaluate to an unique name for each configuration. - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. - -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- - -:: - - file( ... DESTINATION - [FILE_PERMISSIONS ...] - [DIRECTORY_PERMISSIONS ...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN | REGEX ] - [EXCLUDE] [PERMISSIONS ...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -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``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). - ------------------------------------------------------------------------------- - -:: - file(LOCK [DIRECTORY] [RELEASE] [GUARD ] [RESULT_VARIABLE ] -- cgit v0.12