diff options
Diffstat (limited to 'Help/command/file.rst')
| -rw-r--r-- | Help/command/file.rst | 183 |
1 files changed, 143 insertions, 40 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index e963be0fb6..3db605d6a8 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,6 +3,21 @@ file File manipulation command. +This command is dedicated to file and path manipulation requiring access to the +filesystem. + +For other path manipulation, handling only syntactic aspects, have a look at +:command:`cmake_path` command. + +.. note:: + + The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has + been superseded, respectively, by sub-commands + :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, + :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and + :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of + :command:`cmake_path` command. + Synopsis ^^^^^^^^ @@ -103,10 +118,15 @@ Parse a list of ASCII strings from ``<filename>`` and store it in Consider only strings that match the given regular expression. ``ENCODING <encoding-type>`` + .. versionadded:: 3.1 + Consider strings of a given encoding. Currently supported encodings are: - UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If the ENCODING option - is not provided and the file has a Byte Order Mark, the ENCODING option - will be defaulted to respect the Byte Order Mark. + ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. + If the ``ENCODING`` option is not provided and the file has a Byte Order Mark, + the ``ENCODING`` option will be defaulted to respect the Byte Order Mark. + + .. versionadded:: 3.2 + Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. For example, the code @@ -160,6 +180,8 @@ the ``<format>`` and ``UTC`` options. [POST_EXCLUDE_REGEXES [<regexes>...]] ) +.. versionadded:: 3.16 + Recursively get the list of libraries depended on by the given files. Please note that this sub-command is not intended to be used in project mode. @@ -408,6 +430,9 @@ dependency resolution: If this variable is not specified, it is determined by the value of ``CMAKE_OBJDUMP`` if set, else by system introspection. + .. versionadded:: 3.18 + Use ``CMAKE_OBJDUMP`` if set. + Writing ^^^^^^^ @@ -436,6 +461,8 @@ to update the file only when its content changes. file(TOUCH [<files>...]) file(TOUCH_NOCREATE [<files>...]) +.. versionadded:: 3.12 + 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. @@ -452,7 +479,10 @@ modified. file(GENERATE OUTPUT output-file <INPUT input-file|CONTENT content> - [CONDITION expression] [TARGET target]) + [CONDITION expression] [TARGET target] + [FILE_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) Generate an output file for each build configuration supported by the current :manual:`CMake Generator <cmake-generators(7)>`. Evaluate @@ -469,8 +499,10 @@ from the input content to produce the output content. The options are: ``INPUT <input-file>`` 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`. + + .. versionchanged:: 3.10 + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. ``OUTPUT <output-file>`` Specify the output file name to generate. Use generator expressions @@ -478,15 +510,37 @@ from the input content to produce the output content. The options are: name. Multiple configurations may generate the same output file only if the generated content is identical. Otherwise, the ``<output-file>`` 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`. + + .. versionchanged:: 3.10 + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. ``TARGET <target>`` + .. versionadded:: 3.19 + Specify which target to use when evaluating generator expressions that require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``, ``$<TARGET_PROPERTY:prop>``). +``FILE_PERMISSIONS <permissions>...`` + Use user provided permissions for the generated file. + +``NO_SOURCE_PERMISSIONS`` + The generated file permissions default to the standard 644 value + (-rw-r--r--). + +``USE_SOURCE_PERMISSIONS`` + Transfer the file permissions of the original file to the generated file. + This option expects INPUT option. + +``NEWLINE_STYLE <style>`` + .. versionadded:: 3.20 + + Specify the newline style for the generated file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + 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 @@ -506,6 +560,8 @@ of a project's ``CMakeLists.txt`` files. [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) +.. versionadded:: 3.18 + Generate an output file using the input given by ``CONTENT`` and substitute variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The substitution rules behave the same as the :command:`configure_file` command. @@ -554,20 +610,25 @@ Generate a list of 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, the results will be returned as relative paths to the given -path. The results will be ordered lexicographically. +path. + +.. versionchanged:: 3.6 + The results will be ordered lexicographically. On Windows and macOS, globbing is case-insensitive even if the underlying filesystem is case-sensitive (both filenames and globbing expressions are converted to lowercase before matching). On other platforms, globbing is case-sensitive. -If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic -to the main build system check target to rerun the flagged ``GLOB`` commands -at build time. If any of the outputs change, CMake will regenerate the build -system. +.. versionadded:: 3.3 + By default ``GLOB`` lists directories - directories are omitted in result if + ``LIST_DIRECTORIES`` is set to false. -By default ``GLOB`` lists directories - directories are omitted in result if -``LIST_DIRECTORIES`` is set to false. +.. versionadded:: 3.12 + If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic + to the main build system check target to rerun the flagged ``GLOB`` commands + at build time. If any of the outputs change, CMake will regenerate the build + system. .. note:: We do not recommend using GLOB to collect a list of source files from @@ -590,10 +651,11 @@ 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``. -By default ``GLOB_RECURSE`` omits directories from result list - setting -``LIST_DIRECTORIES`` to true adds directories to result list. -If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to -``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. +.. versionadded:: 3.3 + By default ``GLOB_RECURSE`` omits directories from result list - setting + ``LIST_DIRECTORIES`` to true adds directories to result list. + If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to + ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. Examples of recursive globbing include:: @@ -619,7 +681,12 @@ Move a file or directory within a filesystem from ``<oldname>`` to Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a given file does not exist. Relative input paths are evaluated with respect -to the current source directory. Empty input paths are ignored with a warning. +to the current source directory. + +.. versionchanged:: 3.15 + Empty input paths are ignored with a warning. Previous versions of CMake + interpreted empty string as a relative path with respect to the current + directory and removed its contents. .. _MAKE_DIRECTORY: @@ -652,17 +719,18 @@ 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``). -If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve -the symlinks at the paths given until a real file is found, and install -a corresponding symlink in the destination for each symlink encountered. For -each symlink that is installed, the resolution is stripped of the directory, -leaving only the filename, meaning that the new symlink points to a file in -the same directory as the symlink. This feature is useful on some Unix systems, -where libraries are installed as a chain of symlinks with version numbers, with -less specific versions pointing to more specific versions. -``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library -itself into the destination directory. For example, if you have the following -directory structure: +.. versionadded:: 3.15 + If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve + the symlinks at the paths given until a real file is found, and install + a corresponding symlink in the destination for each symlink encountered. For + each symlink that is installed, the resolution is stripped of the directory, + leaving only the filename, meaning that the new symlink points to a file in + the same directory as the symlink. This feature is useful on some Unix systems, + where libraries are installed as a chain of symlinks with version numbers, with + less specific versions pointing to more specific versions. + ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library + itself into the destination directory. For example, if you have the following + directory structure: * ``/opt/foo/lib/libfoo.so.1.2.3`` * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` @@ -696,6 +764,8 @@ use this signature (with some undocumented options for internal use). file(SIZE <filename> <variable>) +.. versionadded:: 3.14 + Determine the file size of the ``<filename>`` and put the result in ``<variable>`` variable. Requires that ``<filename>`` is a valid path pointing to a file and is readable. @@ -706,6 +776,8 @@ pointing to a file and is readable. file(READ_SYMLINK <linkname> <variable>) +.. versionadded:: 3.14 + This subcommand queries the symlink ``<linkname>`` and stores the path it points to in the result ``<variable>``. If ``<linkname>`` does not exist or is not a symlink, CMake issues a fatal error. @@ -730,6 +802,8 @@ absolute path is obtained: file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) +.. versionadded:: 3.14 + Create a link ``<linkname>`` that points to ``<original>``. It will be a hard link by default, but providing the ``SYMBOLIC`` option results in a symbolic link instead. Hard links require that ``original`` @@ -754,10 +828,12 @@ which would make them unable to support a hard link. [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]) +.. versionadded:: 3.19 + Set the permissions for the ``<files>...`` and ``<directories>...`` specified. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, -``WORLD_WRITE``, ``WORLD_EXECUTE``. +``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``. Valid combination of keywords are: @@ -790,6 +866,8 @@ Valid combination of keywords are: [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]) +.. versionadded:: 3.19 + Same as `CHMOD`_, but change the permissions of files and directories present in the ``<directories>...`` recursively. @@ -802,6 +880,8 @@ Path Conversion file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) +.. versionadded:: 3.19 + Compute the absolute path to an existing file or directory with symlinks resolved. @@ -849,10 +929,12 @@ Transfer file(UPLOAD <file> <url> [<options>...]) The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. -If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. -This can be useful if you want to know if a file can be downloaded (for example, -to check that it exists) without actually saving it anywhere. The ``UPLOAD`` -mode uploads a local ``<file>`` to a given ``<url>``. +The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + +.. versionadded:: 3.19 + If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. + This can be useful if you want to know if a file can be downloaded (for example, + to check that it exists) without actually saving it anywhere. Options to both ``DOWNLOAD`` and ``UPLOAD`` are: @@ -877,12 +959,18 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: Terminate the operation after a given total time has elapsed. ``USERPWD <username>:<password>`` + .. versionadded:: 3.7 + Set username and password for operation. ``HTTPHEADER <HTTP-header>`` + .. versionadded:: 3.7 + HTTP header for operation. Suboption can be repeated several times. ``NETRC <level>`` + .. versionadded:: 3.11 + Specify whether the .netrc file is to be used for operation. If this option is not specified, the value of the ``CMAKE_NETRC`` variable will be used instead. @@ -899,6 +987,8 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: The .netrc file is required, and information in the URL is ignored. ``NETRC_FILE <file>`` + .. versionadded:: 3.11 + Specify an alternative .netrc file to the one in your home directory, if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will @@ -911,9 +1001,15 @@ If neither ``NETRC`` option is given CMake will check variables Specify whether to verify the server certificate for ``https://`` URLs. The default is to *not* verify. + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. + ``TLS_CAINFO <file>`` Specify a custom Certificate Authority file for ``https://`` URLs. + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. + 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. If neither ``TLS`` option is given CMake will check @@ -944,6 +1040,8 @@ Locking [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>]) +.. versionadded:: 3.2 + Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file ``<path>/cmake.lock`` otherwise. File will be locked for scope defined by ``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used @@ -979,6 +1077,8 @@ Archiving [MTIME <mtime>] [VERBOSE]) +.. versionadded:: 3.18 + Creates the specified ``<archive>`` file with the files and directories listed in ``<paths>``. Note that ``<paths>`` must list actual files or directories, wildcards are not supported. @@ -993,9 +1093,10 @@ compression. The other formats use no compression by default, but can be directed to do so with the ``COMPRESSION`` option. Valid values for ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. -The compression level can be specified with the ``COMPRESSION_LEVEL`` option. -The ``<compression-level>`` should be between 0-9, with the default being 0. -The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. +.. versionadded:: 3.19 + The compression level can be specified with the ``COMPRESSION_LEVEL`` option. + The ``<compression-level>`` should be between 0-9, with the default being 0. + The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. .. note:: With ``FORMAT`` set to ``raw`` only one file will be compressed with the @@ -1016,6 +1117,8 @@ the ``MTIME`` option. [LIST_ONLY] [VERBOSE]) +.. versionadded:: 3.18 + Extracts or lists the content of the specified ``<archive>``. The directory where the content of the archive will be extracted to can |