diff --git a/Help/command/file.rst b/Help/command/file.rst index 83ade1d20..14ca20c33 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,211 +3,299 @@ file File manipulation command. -:: - - file(WRITE filename "message to write"... ) - file(APPEND filename "message to write"... ) - file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX]) - file( filename variable) - file(STRINGS filename variable [LIMIT_COUNT num] - [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes] - [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes] - [NEWLINE_CONSUME] [REGEX regex] - [NO_HEX_CONVERSION]) - file(GLOB variable [RELATIVE path] [globbing expressions]...) - file(GLOB_RECURSE variable [RELATIVE path] - [FOLLOW_SYMLINKS] [globbing expressions]...) - file(RENAME ) - file(REMOVE [file1 ...]) - file(REMOVE_RECURSE [file1 ...]) - file(MAKE_DIRECTORY [directory1 directory2 ...]) - file(RELATIVE_PATH variable directory file) - file(TO_CMAKE_PATH path result) - file(TO_NATIVE_PATH path result) - file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout] - [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS] - [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum] - [TLS_VERIFY on|off] [TLS_CAINFO file]) - file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout] - [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]) - file(TIMESTAMP filename variable [] [UTC]) - file(GENERATE OUTPUT output_file - - [CONDITION expression]) - -WRITE will write a message into a file called 'filename'. It -overwrites the file if it already exists, and creates the file if it -does not exist. (If the file is a build input, use configure_file to -update the file only when its content changes.) - -APPEND will write a message into a file same as WRITE, except it will -append it to the end of the file - -READ will read the content of a file and store it into the variable. -It will start at the given offset and read up to numBytes. If the -argument HEX is given, the binary data will be converted to -hexadecimal representation and this will be stored in the variable. - -MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a -cryptographic hash of the content of a file. - -STRINGS will parse a list of ASCII strings from a file and store it in -a variable. Binary data in the file are ignored. Carriage return -(CR) characters are ignored. It works also for Intel Hex and Motorola -S-record files, which are automatically converted to binary format -when reading them. Disable this using NO_HEX_CONVERSION. - -LIMIT_COUNT sets the maximum number of strings to return. LIMIT_INPUT -sets the maximum number of bytes to read from the input file. -LIMIT_OUTPUT sets the maximum number of bytes to store in the output -variable. LENGTH_MINIMUM sets the minimum length of a string to -return. Shorter strings are ignored. LENGTH_MAXIMUM sets the maximum -length of a string to return. Longer strings are split into strings -no longer than the maximum length. NEWLINE_CONSUME allows newlines to -be included in strings instead of terminating them. - -REGEX specifies a regular expression that a string must match to be -returned. Typical usage +------------------------------------------------------------------------------ :: + 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. +(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]) + +Read content from a file called ```` and store it in a +````. Optionally start from the given ```` and +read at most ```` bytes. The ``HEX`` option causes data to +be converted to a hexadecimal representation (useful for binary data). + +------------------------------------------------------------------------------ + +:: + + file(STRINGS [...]) + +Parse a list of ASCII strings from ```` and store it in +````. Binary data in the file are ignored. Carriage return +(``\r``, CR) characters are ignored. The options are: + +``LENGTH_MAXIMUM `` + Consider only strings of at most a given length. + +``LENGTH_MINIMUM `` + Consider only strings of at least a given length. + +``LIMIT_COUNT `` + Limit the number of distinct strings to be extracted. + +``LIMIT_INPUT `` + Limit the number of input bytes to read from the file. + +``LIMIT_OUTPUT `` + Limit the number of total bytes to store in the ````. + +``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. + +``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. + +``REGEX `` + Consider only strings that match the given regular expression. + +For example, the code + +.. code-block:: cmake + file(STRINGS myfile.txt myfile) -stores a list in the variable "myfile" in which each item is a line +stores a list in the variable ``myfile`` in which each item is a line from the input file. -GLOB will generate a list of all files that match the globbing -expressions and store it into the variable. Globbing expressions are -similar to regular expressions, but much simpler. If RELATIVE flag is -specified for an expression, the results will be returned as a -relative path to the given path. (We do not recommend using GLOB to -collect a list of source files from your source tree. If no -CMakeLists.txt file changes when a source is added or removed then the -generated build system cannot know when to ask CMake to regenerate.) - -Examples of globbing expressions include: +------------------------------------------------------------------------------ :: - *.cxx - match all files with extension cxx - *.vt? - match all files with extension vta,...,vtz - f[3-5].txt - match files f3.txt, f4.txt, f5.txt + file( ) -GLOB_RECURSE will generate a list similar to the regular GLOB, except -it will traverse all the subdirectories of the matched directory and -match the files. Subdirectories that are symlinks are only traversed -if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW. -See cmake --help-policy CMP0009 for more information. +Compute a cryptographic hash of the content of ```` and +store it in a ````. -Examples of recursive globbing include: +------------------------------------------------------------------------------ :: - /dir/*.py - match all python files in /dir and subdirectories + file(GLOB [RELATIVE ] [...]) + file(GLOB_RECURSE [RELATIVE ] + [FOLLOW_SYMLINKS] [...]) -MAKE_DIRECTORY will create the given directories, also if their parent -directories don't exist yet +Generate a list of files that match the ```` and +store it into the ````. Globbing expressions are similar to +regular expressions, but much simpler. If ``RELATIVE`` flag is +specified, the results will be returned as relative paths to the given +path. -RENAME moves a file or directory within a filesystem, replacing the -destination atomically. +.. note:: + We do not recommend using GLOB to collect a list of source files from + your source tree. If no CMakeLists.txt file changes when a source is + added or removed then the generated build system cannot know when to + ask CMake to regenerate. -REMOVE will remove the given files, also in subdirectories +Examples of globbing expressions include:: -REMOVE_RECURSE will remove the given files and directories, also -non-empty directories + *.cxx - match all files with extension cxx + *.vt? - match all files with extension vta,...,vtz + f[3-5].txt - match files f3.txt, f4.txt, f5.txt -RELATIVE_PATH will determine relative path from directory to the given -file. +The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the +matched directory and match the files. Subdirectories that are symlinks +are only traversed if ``FOLLOW_SYMLINKS`` is given or policy +:policy:`CMP0009` is not set to ``NEW``. -TO_CMAKE_PATH will convert path into a cmake style path with unix /. -The input can be a single path or a system path like "$ENV{PATH}". -Note the double quotes around the ENV call TO_CMAKE_PATH only takes -one argument. This command will also convert the native list -delimiters for a list of paths like the PATH environment variable. +Examples of recursive globbing include:: -TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a -cmake style path into the native path style \ for windows and / for -UNIX. + /dir/*.py - match all python files in /dir and subdirectories -DOWNLOAD will download the given URL to the given file. If LOG var is -specified a log of the download will be put in var. If STATUS var is -specified the status of the operation will be put in var. The status -is returned in a list of length 2. The first element is the numeric -return value for the operation, and the second element is a string -value for the error. A 0 numeric error means no error in the -operation. If TIMEOUT time is specified, the operation will timeout -after time seconds, time should be specified as an integer. The -INACTIVITY_TIMEOUT specifies an integer number of seconds of -inactivity after which the operation should terminate. If -EXPECTED_HASH ALGO=value is specified, the operation will verify that -the downloaded file's actual hash matches the expected value, where -ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512. If it -does not match, the operation fails with an error. ("EXPECTED_MD5 -sum" is short-hand for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is -specified, progress information will be printed as status messages -until the operation is complete. For https URLs CMake must be built -with OpenSSL. TLS/SSL certificates are not checked by default. Set -TLS_VERIFY to ON to check certificates and/or use EXPECTED_HASH to -verify downloaded content. Set TLS_CAINFO to specify a custom -Certificate Authority file. If either TLS option is not given CMake -will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, -respectively. - -UPLOAD will upload the given file to the given URL. If LOG var is -specified a log of the upload will be put in var. If STATUS var is -specified the status of the operation will be put in var. The status -is returned in a list of length 2. The first element is the numeric -return value for the operation, and the second element is a string -value for the error. A 0 numeric error means no error in the -operation. If TIMEOUT time is specified, the operation will timeout -after time seconds, time should be specified as an integer. The -INACTIVITY_TIMEOUT specifies an integer number of seconds of -inactivity after which the operation should terminate. If -SHOW_PROGRESS is specified, progress information will be printed as -status messages until the operation is complete. - -TIMESTAMP will write a string representation of the modification time -of filename to variable. - -Should the command be unable to obtain a timestamp variable will be -set to the empty string "". - -See documentation of the string TIMESTAMP sub-command for more -details. - -The file() command also provides COPY and INSTALL signatures: +------------------------------------------------------------------------------ :: - file( files... DESTINATION - [FILE_PERMISSIONS permissions...] - [DIRECTORY_PERMISSIONS permissions...] + file(RENAME ) + +Move a file or directory within a filesystem from ```` to +````, replacing the destination atomically. + +------------------------------------------------------------------------------ + +:: + + file(REMOVE [...]) + file(REMOVE_RECURSE [...]) + +Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given +files and directories, also non-empty directories + +------------------------------------------------------------------------------ + +:: + + file(MAKE_DIRECTORY [...]) + +Create the given directories and their parents as needed. + +------------------------------------------------------------------------------ + +:: + + file(RELATIVE_PATH ) + +Compute the relative path from a ```` to a ```` and +store it in the ````. + +------------------------------------------------------------------------------ + +:: + + file(TO_CMAKE_PATH "" ) + file(TO_NATIVE_PATH "" ) + +The ``TO_CMAKE_PATH`` mode converts a native ```` into a cmake-style +path with forward-slashes (``/``). The input can be a single path or a +system search path like ``$ENV{PATH}``. A search path will be converted +to a cmake-style list separated by ``;`` characters. + +The ``TO_NATIVE_PATH`` mode converts a cmake-style ```` into a native +path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). + +Always use double quotes around the ```` to be sure it is treated +as a single argument to this command. + +------------------------------------------------------------------------------ + +:: + + file(DOWNLOAD [...]) + file(UPLOAD [...]) + +The ``DOWNLOAD`` mode downloads the given ```` to a local ````. +The ``UPLOAD`` mode uploads a local ```` to a given ````. + +Options to both ``DOWNLOAD`` and ``UPLOAD`` are: + +``INACTIVITY_TIMEOUT `` + Terminate the operation after a period of inactivity. + +``LOG `` + Store a human-readable log of the operation in a variable. + +``SHOW_PROGRESS`` + Print progress information as status messages until the operation is + complete. + +``STATUS `` + Store the resulting status of the operation in a variable. + The status is a ``;`` separated list of length 2. + The first element is the numeric return value for the operation, + and the second element is a string value for the error. + A ``0`` numeric error means no error in the operation. + +``TIMEOUT `` + Terminate the operation after a given total time has elapsed. + +Additional options to ``DOWNLOAD`` are: + +``EXPECTED_HASH ALGO=`` + + Verify that the downloaded content hash matches the expected value, where + ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or + ``SHA512``. If it does not match, the operation fails with an error. + +``EXPECTED_MD5 `` + Historical short-hand for ``EXPECTED_HASH MD5=``. + +``TLS_VERIFY `` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. + +``TLS_CAINFO `` + Specify a custom Certificate Authority file for ``https://`` URLs. + +For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` +certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to +check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. +If neither ``TLS`` option is given CMake will check variables +``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. + +------------------------------------------------------------------------------ + +:: + + 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 ...) + +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. + +``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. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. + +------------------------------------------------------------------------------ + +:: + + file( ... DESTINATION + [FILE_PERMISSIONS ...] + [DIRECTORY_PERMISSIONS ...] [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] [FILES_MATCHING] [[PATTERN | REGEX ] - [EXCLUDE] [PERMISSIONS permissions...]] [...]) + [EXCLUDE] [PERMISSIONS ...]] [...]) -The COPY signature copies files, directories, and symlinks to a +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 install(DIRECTORY) -command for documentation of permissions, PATTERN, REGEX, and EXCLUDE -options. +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, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options. -The INSTALL signature differs slightly from COPY: it prints status -messages, and NO_SOURCE_PERMISSIONS is default. Installation scripts -generated by the install() command use this signature (with some -undocumented options for internal use). - -GENERATE will write an with content from an -, or from . The output is generated -conditionally based on the content of the . The file is -written at CMake generate-time and the input may contain generator -expressions. The , and may also -contain generator expressions. The must evaluate to -either '0' or '1'. The must evaluate to a unique name -among all configurations and among all invocations of file(GENERATE). +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages, and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use).