1file 2---- 3 4File manipulation command. 5 6This command is dedicated to file and path manipulation requiring access to the 7filesystem. 8 9For other path manipulation, handling only syntactic aspects, have a look at 10:command:`cmake_path` command. 11 12.. note:: 13 14 The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has 15 been superseded, respectively, by sub-commands 16 :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, 17 :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and 18 :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of 19 :command:`cmake_path` command. 20 21Synopsis 22^^^^^^^^ 23 24.. parsed-literal:: 25 26 `Reading`_ 27 file(`READ`_ <filename> <out-var> [...]) 28 file(`STRINGS`_ <filename> <out-var> [...]) 29 file(`\<HASH\> <HASH_>`_ <filename> <out-var>) 30 file(`TIMESTAMP`_ <filename> <out-var> [...]) 31 file(`GET_RUNTIME_DEPENDENCIES`_ [...]) 32 33 `Writing`_ 34 file({`WRITE`_ | `APPEND`_} <filename> <content>...) 35 file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) 36 file(`GENERATE`_ OUTPUT <output-file> [...]) 37 file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...]) 38 39 `Filesystem`_ 40 file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) 41 file(`MAKE_DIRECTORY`_ [<dir>...]) 42 file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) 43 file(`RENAME`_ <oldname> <newname> [...]) 44 file(`COPY_FILE`_ <oldname> <newname> [...]) 45 file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) 46 file(`SIZE`_ <filename> <out-var>) 47 file(`READ_SYMLINK`_ <linkname> <out-var>) 48 file(`CREATE_LINK`_ <original> <linkname> [...]) 49 file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) 50 file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) 51 52 `Path Conversion`_ 53 file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) 54 file(`RELATIVE_PATH`_ <out-var> <directory> <file>) 55 file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) 56 57 `Transfer`_ 58 file(`DOWNLOAD`_ <url> [<file>] [...]) 59 file(`UPLOAD`_ <file> <url> [...]) 60 61 `Locking`_ 62 file(`LOCK`_ <path> [...]) 63 64 `Archiving`_ 65 file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...]) 66 file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...]) 67 68Reading 69^^^^^^^ 70 71.. _READ: 72 73.. code-block:: cmake 74 75 file(READ <filename> <variable> 76 [OFFSET <offset>] [LIMIT <max-in>] [HEX]) 77 78Read content from a file called ``<filename>`` and store it in a 79``<variable>``. Optionally start from the given ``<offset>`` and 80read at most ``<max-in>`` bytes. The ``HEX`` option causes data to 81be converted to a hexadecimal representation (useful for binary data). If the 82``HEX`` option is specified, letters in the output (``a`` through ``f``) are in 83lowercase. 84 85.. _STRINGS: 86 87.. code-block:: cmake 88 89 file(STRINGS <filename> <variable> [<options>...]) 90 91Parse a list of ASCII strings from ``<filename>`` and store it in 92``<variable>``. Binary data in the file are ignored. Carriage return 93(``\r``, CR) characters are ignored. The options are: 94 95``LENGTH_MAXIMUM <max-len>`` 96 Consider only strings of at most a given length. 97 98``LENGTH_MINIMUM <min-len>`` 99 Consider only strings of at least a given length. 100 101``LIMIT_COUNT <max-num>`` 102 Limit the number of distinct strings to be extracted. 103 104``LIMIT_INPUT <max-in>`` 105 Limit the number of input bytes to read from the file. 106 107``LIMIT_OUTPUT <max-out>`` 108 Limit the number of total bytes to store in the ``<variable>``. 109 110``NEWLINE_CONSUME`` 111 Treat newline characters (``\n``, LF) as part of string content 112 instead of terminating at them. 113 114``NO_HEX_CONVERSION`` 115 Intel Hex and Motorola S-record files are automatically converted to 116 binary while reading unless this option is given. 117 118``REGEX <regex>`` 119 Consider only strings that match the given regular expression, 120 as described under :ref:`string(REGEX) <Regex Specification>`. 121 122``ENCODING <encoding-type>`` 123 .. versionadded:: 3.1 124 125 Consider strings of a given encoding. Currently supported encodings are: 126 ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. 127 If the ``ENCODING`` option is not provided and the file has a Byte Order Mark, 128 the ``ENCODING`` option will be defaulted to respect the Byte Order Mark. 129 130 .. versionadded:: 3.2 131 Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. 132 133For example, the code 134 135.. code-block:: cmake 136 137 file(STRINGS myfile.txt myfile) 138 139stores a list in the variable ``myfile`` in which each item is a line 140from the input file. 141 142.. _HASH: 143 144.. code-block:: cmake 145 146 file(<HASH> <filename> <variable>) 147 148Compute a cryptographic hash of the content of ``<filename>`` and 149store it in a ``<variable>``. The supported ``<HASH>`` algorithm names 150are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` 151command. 152 153.. _TIMESTAMP: 154 155.. code-block:: cmake 156 157 file(TIMESTAMP <filename> <variable> [<format>] [UTC]) 158 159Compute a string representation of the modification time of ``<filename>`` 160and store it in ``<variable>``. Should the command be unable to obtain a 161timestamp variable will be set to the empty string (""). 162 163See the :command:`string(TIMESTAMP)` command for documentation of 164the ``<format>`` and ``UTC`` options. 165 166.. _GET_RUNTIME_DEPENDENCIES: 167 168.. code-block:: cmake 169 170 file(GET_RUNTIME_DEPENDENCIES 171 [RESOLVED_DEPENDENCIES_VAR <deps_var>] 172 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] 173 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] 174 [EXECUTABLES [<executable_files>...]] 175 [LIBRARIES [<library_files>...]] 176 [MODULES [<module_files>...]] 177 [DIRECTORIES [<directories>...]] 178 [BUNDLE_EXECUTABLE <bundle_executable_file>] 179 [PRE_INCLUDE_REGEXES [<regexes>...]] 180 [PRE_EXCLUDE_REGEXES [<regexes>...]] 181 [POST_INCLUDE_REGEXES [<regexes>...]] 182 [POST_EXCLUDE_REGEXES [<regexes>...]] 183 [POST_INCLUDE_FILES [<files>...]] 184 [POST_EXCLUDE_FILES [<files>...]] 185 ) 186 187.. versionadded:: 3.16 188 189Recursively get the list of libraries depended on by the given files. 190 191Please note that this sub-command is not intended to be used in project mode. 192It is intended for use at install time, either from code generated by the 193:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by 194the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. 195For example: 196 197.. code-block:: cmake 198 199 install(CODE [[ 200 file(GET_RUNTIME_DEPENDENCIES 201 # ... 202 ) 203 ]]) 204 205The arguments are as follows: 206 207``RESOLVED_DEPENDENCIES_VAR <deps_var>`` 208 Name of the variable in which to store the list of resolved dependencies. 209 210``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` 211 Name of the variable in which to store the list of unresolved dependencies. 212 If this variable is not specified, and there are any unresolved dependencies, 213 an error is issued. 214 215``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` 216 Variable prefix in which to store conflicting dependency information. 217 Dependencies are conflicting if two files with the same name are found in 218 two different directories. The list of filenames that conflict are stored in 219 ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths 220 that were found for that filename are stored in 221 ``<conflicting_deps_prefix>_<filename>``. 222 223``EXECUTABLES <executable_files>`` 224 List of executable files to read for dependencies. These are executables that 225 are typically created with :command:`add_executable`, but they do not have to 226 be created by CMake. On Apple platforms, the paths to these files determine 227 the value of ``@executable_path`` when recursively resolving the libraries. 228 Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here 229 will result in undefined behavior. 230 231``LIBRARIES <library_files>`` 232 List of library files to read for dependencies. These are libraries that are 233 typically created with :command:`add_library(SHARED)`, but they do not have 234 to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` 235 libraries, or executables here will result in undefined behavior. 236 237``MODULES <module_files>`` 238 List of loadable module files to read for dependencies. These are modules 239 that are typically created with :command:`add_library(MODULE)`, but they do 240 not have to be created by CMake. They are typically used by calling 241 ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. 242 Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here 243 will result in undefined behavior. 244 245``DIRECTORIES <directories>`` 246 List of additional directories to search for dependencies. On Linux 247 platforms, these directories are searched if the dependency is not found in 248 any of the other usual paths. If it is found in such a directory, a warning 249 is issued, because it means that the file is incomplete (it does not list all 250 of the directories that contain its dependencies). On Windows platforms, 251 these directories are searched if the dependency is not found in any of the 252 other search paths, but no warning is issued, because searching other paths 253 is a normal part of Windows dependency resolution. On Apple platforms, this 254 argument has no effect. 255 256``BUNDLE_EXECUTABLE <bundle_executable_file>`` 257 Executable to treat as the "bundle executable" when resolving libraries. On 258 Apple platforms, this argument determines the value of ``@executable_path`` 259 when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. 260 It has no effect on ``EXECUTABLES`` files. On other platforms, it has no 261 effect. This is typically (but not always) one of the executables in the 262 ``EXECUTABLES`` argument which designates the "main" executable of the 263 package. 264 265The following arguments specify filters for including or excluding libraries to 266be resolved. See below for a full description of how they work. 267 268``PRE_INCLUDE_REGEXES <regexes>`` 269 List of pre-include regexes through which to filter the names of 270 not-yet-resolved dependencies. 271 272``PRE_EXCLUDE_REGEXES <regexes>`` 273 List of pre-exclude regexes through which to filter the names of 274 not-yet-resolved dependencies. 275 276``POST_INCLUDE_REGEXES <regexes>`` 277 List of post-include regexes through which to filter the names of resolved 278 dependencies. 279 280``POST_EXCLUDE_REGEXES <regexes>`` 281 List of post-exclude regexes through which to filter the names of resolved 282 dependencies. 283 284``POST_INCLUDE_FILES <files>`` 285 .. versionadded:: 3.21 286 287 List of post-include filenames through which to filter the names of resolved 288 dependencies. Symlinks are resolved when attempting to match these filenames. 289 290``POST_EXCLUDE_FILES <files>`` 291 .. versionadded:: 3.21 292 293 List of post-exclude filenames through which to filter the names of resolved 294 dependencies. Symlinks are resolved when attempting to match these filenames. 295 296These arguments can be used to exclude unwanted system libraries when 297resolving the dependencies, or to include libraries from a specific 298directory. The filtering works as follows: 299 3001. If the not-yet-resolved dependency matches any of the 301 ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency 302 resolution proceeds to step 4. 3032. If the not-yet-resolved dependency matches any of the 304 ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. 3053. Otherwise, dependency resolution proceeds. 3064. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to 307 the linking rules of the platform (see below). 3085. If the dependency is found, and its full path matches one of the 309 ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added 310 to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` 311 recursively resolves that library's own dependencies. Otherwise, resolution 312 proceeds to step 6. 3136. If the dependency is found, but its full path matches one of the 314 ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the 315 resolved dependencies, and dependency resolution stops for that dependency. 3167. If the dependency is found, and its full path does not match either 317 ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, 318 or ``POST_EXCLUDE_FILES``, the full path is added to the resolved 319 dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves 320 that library's own dependencies. 321 322Different platforms have different rules for how dependencies are resolved. 323These specifics are described here. 324 325On Linux platforms, library resolution works as follows: 326 3271. If the depending file does not have any ``RUNPATH`` entries, and the library 328 exists in one of the depending file's ``RPATH`` entries, or its parents', in 329 that order, the dependency is resolved to that file. 3302. Otherwise, if the depending file has any ``RUNPATH`` entries, and the 331 library exists in one of those entries, the dependency is resolved to that 332 file. 3333. Otherwise, if the library exists in one of the directories listed by 334 ``ldconfig``, the dependency is resolved to that file. 3354. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the 336 dependency is resolved to that file. In this case, a warning is issued, 337 because finding a file in one of the ``DIRECTORIES`` means that the 338 depending file is not complete (it does not list all the directories from 339 which it pulls dependencies). 3405. Otherwise, the dependency is unresolved. 341 342On Windows platforms, library resolution works as follows: 343 3441. The dependent DLL name is converted to lowercase. Windows DLL names are 345 case-insensitive, and some linkers mangle the case of the DLL dependency 346 names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, 347 ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and 348 ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would 349 have to check for both uppercase and lowercase letters. For example: 350 351 .. code-block:: cmake 352 353 file(GET_RUNTIME_DEPENDENCIES 354 # ... 355 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" 356 ) 357 358 Converting the DLL name to lowercase allows the regexes to only match 359 lowercase names, thus simplifying the regex. For example: 360 361 .. code-block:: cmake 362 363 file(GET_RUNTIME_DEPENDENCIES 364 # ... 365 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" 366 ) 367 368 This regex will match ``mylibrary.dll`` regardless of how it is cased, 369 either on disk or in the depending file. (For example, it will match 370 ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) 371 372 Please note that the directory portion of any resolved DLLs retains its 373 casing and is not converted to lowercase. Only the filename portion is 374 converted. 375 3762. (**Not yet implemented**) If the depending file is a Windows Store app, and 377 the dependency is listed as a dependency in the application's package 378 manifest, the dependency is resolved to that file. 3793. Otherwise, if the library exists in the same directory as the depending 380 file, the dependency is resolved to that file. 3814. Otherwise, if the library exists in either the operating system's 382 ``system32`` directory or the ``Windows`` directory, in that order, the 383 dependency is resolved to that file. 3845. Otherwise, if the library exists in one of the directories specified by 385 ``DIRECTORIES``, in the order they are listed, the dependency is resolved to 386 that file. In this case, a warning is not issued, because searching other 387 directories is a normal part of Windows library resolution. 3886. Otherwise, the dependency is unresolved. 389 390On Apple platforms, library resolution works as follows: 391 3921. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` 393 argument is in the process of being resolved, and replacing 394 ``@executable_path/`` with the directory of the executable yields an 395 existing file, the dependency is resolved to that file. 3962. Otherwise, if the dependency starts with ``@executable_path/``, and there is 397 a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with 398 the directory of the bundle executable yields an existing file, the 399 dependency is resolved to that file. 4003. Otherwise, if the dependency starts with ``@loader_path/``, and replacing 401 ``@loader_path/`` with the directory of the depending file yields an 402 existing file, the dependency is resolved to that file. 4034. Otherwise, if the dependency starts with ``@rpath/``, and replacing 404 ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields 405 an existing file, the dependency is resolved to that file. Note that 406 ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` 407 also have these items replaced with the appropriate path. 4085. Otherwise, if the dependency is an absolute file that exists, the dependency 409 is resolved to that file. 4106. Otherwise, the dependency is unresolved. 411 412This function accepts several variables that determine which tool is used for 413dependency resolution: 414 415.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM 416 417 Determines which operating system and executable format the files are built 418 for. This could be one of several values: 419 420 * ``linux+elf`` 421 * ``windows+pe`` 422 * ``macos+macho`` 423 424 If this variable is not specified, it is determined automatically by system 425 introspection. 426 427.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL 428 429 Determines the tool to use for dependency resolution. It could be one of 430 several values, depending on the value of 431 :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: 432 433 ================================================= ============================================= 434 ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` 435 ================================================= ============================================= 436 ``linux+elf`` ``objdump`` 437 ``windows+pe`` ``dumpbin`` 438 ``windows+pe`` ``objdump`` 439 ``macos+macho`` ``otool`` 440 ================================================= ============================================= 441 442 If this variable is not specified, it is determined automatically by system 443 introspection. 444 445.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND 446 447 Determines the path to the tool to use for dependency resolution. This is the 448 actual path to ``objdump``, ``dumpbin``, or ``otool``. 449 450 If this variable is not specified, it is determined by the value of 451 ``CMAKE_OBJDUMP`` if set, else by system introspection. 452 453 .. versionadded:: 3.18 454 Use ``CMAKE_OBJDUMP`` if set. 455 456Writing 457^^^^^^^ 458 459.. _WRITE: 460.. _APPEND: 461 462.. code-block:: cmake 463 464 file(WRITE <filename> <content>...) 465 file(APPEND <filename> <content>...) 466 467Write ``<content>`` into a file called ``<filename>``. If the file does 468not exist, it will be created. If the file already exists, ``WRITE`` 469mode will overwrite it and ``APPEND`` mode will append to the end. 470Any directories in the path specified by ``<filename>`` that do not 471exist will be created. 472 473If the file is a build input, use the :command:`configure_file` command 474to update the file only when its content changes. 475 476.. _TOUCH: 477.. _TOUCH_NOCREATE: 478 479.. code-block:: cmake 480 481 file(TOUCH [<files>...]) 482 file(TOUCH_NOCREATE [<files>...]) 483 484.. versionadded:: 3.12 485 486Create a file with no content if it does not yet exist. If the file already 487exists, its access and/or modification will be updated to the time when the 488function call is executed. 489 490Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file 491does not exist it will be silently ignored. 492 493With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be 494modified. 495 496.. _GENERATE: 497 498.. code-block:: cmake 499 500 file(GENERATE OUTPUT output-file 501 <INPUT input-file|CONTENT content> 502 [CONDITION expression] [TARGET target] 503 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | 504 FILE_PERMISSIONS <permissions>...] 505 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) 506 507Generate an output file for each build configuration supported by the current 508:manual:`CMake Generator <cmake-generators(7)>`. Evaluate 509:manual:`generator expressions <cmake-generator-expressions(7)>` 510from the input content to produce the output content. The options are: 511 512``CONDITION <condition>`` 513 Generate the output file for a particular configuration only if 514 the condition is true. The condition must be either ``0`` or ``1`` 515 after evaluating generator expressions. 516 517``CONTENT <content>`` 518 Use the content given explicitly as input. 519 520``INPUT <input-file>`` 521 Use the content from a given file as input. 522 523 .. versionchanged:: 3.10 524 A relative path is treated with respect to the value of 525 :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. 526 527``OUTPUT <output-file>`` 528 Specify the output file name to generate. Use generator expressions 529 such as ``$<CONFIG>`` to specify a configuration-specific output file 530 name. Multiple configurations may generate the same output file only 531 if the generated content is identical. Otherwise, the ``<output-file>`` 532 must evaluate to an unique name for each configuration. 533 534 .. versionchanged:: 3.10 535 A relative path (after evaluating generator expressions) is treated 536 with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. 537 See policy :policy:`CMP0070`. 538 539``TARGET <target>`` 540 .. versionadded:: 3.19 541 542 Specify which target to use when evaluating generator expressions that 543 require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``, 544 ``$<TARGET_PROPERTY:prop>``). 545 546``NO_SOURCE_PERMISSIONS`` 547 .. versionadded:: 3.20 548 549 The generated file permissions default to the standard 644 value 550 (-rw-r--r--). 551 552``USE_SOURCE_PERMISSIONS`` 553 .. versionadded:: 3.20 554 555 Transfer the file permissions of the ``INPUT`` file to the generated file. 556 This is already the default behavior if none of the three permissions-related 557 keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` 558 or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly 559 serves as a way of making the intended behavior clearer at the call site. 560 It is an error to specify this option without ``INPUT``. 561 562``FILE_PERMISSIONS <permissions>...`` 563 .. versionadded:: 3.20 564 565 Use the specified permissions for the generated file. 566 567``NEWLINE_STYLE <style>`` 568 .. versionadded:: 3.20 569 570 Specify the newline style for the generated file. Specify 571 ``UNIX`` or ``LF`` for ``\n`` newlines, or specify 572 ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. 573 574Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific 575``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. 576Generated files are modified and their timestamp updated on subsequent cmake 577runs only if their content is changed. 578 579Note also that ``file(GENERATE)`` does not create the output file until the 580generation phase. The output file will not yet have been written when the 581``file(GENERATE)`` command returns, it is written only after processing all 582of a project's ``CMakeLists.txt`` files. 583 584.. _CONFIGURE: 585 586.. code-block:: cmake 587 588 file(CONFIGURE OUTPUT output-file 589 CONTENT content 590 [ESCAPE_QUOTES] [@ONLY] 591 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) 592 593.. versionadded:: 3.18 594 595Generate an output file using the input given by ``CONTENT`` and substitute 596variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The 597substitution rules behave the same as the :command:`configure_file` command. 598In order to match :command:`configure_file`'s behavior, generator expressions 599are not supported for both ``OUTPUT`` and ``CONTENT``. 600 601The arguments are: 602 603``OUTPUT <output-file>`` 604 Specify the output file name to generate. A relative path is treated with 605 respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. 606 ``<output-file>`` does not support generator expressions. 607 608``CONTENT <content>`` 609 Use the content given explicitly as input. 610 ``<content>`` does not support generator expressions. 611 612``ESCAPE_QUOTES`` 613 Escape any substituted quotes with backslashes (C-style). 614 615``@ONLY`` 616 Restrict variable replacement to references of the form ``@VAR@``. 617 This is useful for configuring scripts that use ``${VAR}`` syntax. 618 619``NEWLINE_STYLE <style>`` 620 Specify the newline style for the output file. Specify 621 ``UNIX`` or ``LF`` for ``\n`` newlines, or specify 622 ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. 623 624Filesystem 625^^^^^^^^^^ 626 627.. _GLOB: 628.. _GLOB_RECURSE: 629 630.. code-block:: cmake 631 632 file(GLOB <variable> 633 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] 634 [<globbing-expressions>...]) 635 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] 636 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] 637 [<globbing-expressions>...]) 638 639Generate a list of files that match the ``<globbing-expressions>`` and 640store it into the ``<variable>``. Globbing expressions are similar to 641regular expressions, but much simpler. If ``RELATIVE`` flag is 642specified, the results will be returned as relative paths to the given 643path. 644 645.. versionchanged:: 3.6 646 The results will be ordered lexicographically. 647 648On Windows and macOS, globbing is case-insensitive even if the underlying 649filesystem is case-sensitive (both filenames and globbing expressions are 650converted to lowercase before matching). On other platforms, globbing is 651case-sensitive. 652 653.. versionadded:: 3.3 654 By default ``GLOB`` lists directories - directories are omitted in result if 655 ``LIST_DIRECTORIES`` is set to false. 656 657.. versionadded:: 3.12 658 If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic 659 to the main build system check target to rerun the flagged ``GLOB`` commands 660 at build time. If any of the outputs change, CMake will regenerate the build 661 system. 662 663.. note:: 664 We do not recommend using GLOB to collect a list of source files from 665 your source tree. If no CMakeLists.txt file changes when a source is 666 added or removed then the generated build system cannot know when to 667 ask CMake to regenerate. 668 The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if 669 a new generator is added in the future that cannot support it, projects using 670 it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is 671 still a cost to perform the check on every rebuild. 672 673Examples of globbing expressions include:: 674 675 *.cxx - match all files with extension cxx 676 *.vt? - match all files with extension vta,...,vtz 677 f[3-5].txt - match files f3.txt, f4.txt, f5.txt 678 679The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the 680matched directory and match the files. Subdirectories that are symlinks 681are only traversed if ``FOLLOW_SYMLINKS`` is given or policy 682:policy:`CMP0009` is not set to ``NEW``. 683 684.. versionadded:: 3.3 685 By default ``GLOB_RECURSE`` omits directories from result list - setting 686 ``LIST_DIRECTORIES`` to true adds directories to result list. 687 If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to 688 ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. 689 690Examples of recursive globbing include:: 691 692 /dir/*.py - match all python files in /dir and subdirectories 693 694.. _MAKE_DIRECTORY: 695 696.. code-block:: cmake 697 698 file(MAKE_DIRECTORY [<directories>...]) 699 700Create the given directories and their parents as needed. 701 702.. _REMOVE: 703.. _REMOVE_RECURSE: 704 705.. code-block:: cmake 706 707 file(REMOVE [<files>...]) 708 file(REMOVE_RECURSE [<files>...]) 709 710Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given 711files and directories, also non-empty directories. No error is emitted if a 712given file does not exist. Relative input paths are evaluated with respect 713to the current source directory. 714 715.. versionchanged:: 3.15 716 Empty input paths are ignored with a warning. Previous versions of CMake 717 interpreted empty strings as a relative path with respect to the current 718 directory and removed its contents. 719 720.. _RENAME: 721 722.. code-block:: cmake 723 724 file(RENAME <oldname> <newname> 725 [RESULT <result>] 726 [NO_REPLACE]) 727 728Move a file or directory within a filesystem from ``<oldname>`` to 729``<newname>``, replacing the destination atomically. 730 731The options are: 732 733``RESULT <result>`` 734 .. versionadded:: 3.21 735 736 Set ``<result>`` variable to ``0`` on success or an error message otherwise. 737 If ``RESULT`` is not specified and the operation fails, an error is emitted. 738 739``NO_REPLACE`` 740 .. versionadded:: 3.21 741 742 If the ``<newname>`` path already exists, do not replace it. 743 If ``RESULT <result>`` is used, the result variable will be 744 set to ``NO_REPLACE``. Otherwise, an error is emitted. 745 746.. _COPY_FILE: 747 748.. code-block:: cmake 749 750 file(COPY_FILE <oldname> <newname> 751 [RESULT <result>] 752 [ONLY_IF_DIFFERENT]) 753 754.. versionadded:: 3.21 755 756Copy a file from ``<oldname>`` to ``<newname>``. Directories are not 757supported. Symlinks are ignored and ``<oldfile>``'s content is read and 758written to ``<newname>`` as a new file. 759 760The options are: 761 762``RESULT <result>`` 763 Set ``<result>`` variable to ``0`` on success or an error message otherwise. 764 If ``RESULT`` is not specified and the operation fails, an error is emitted. 765 766``ONLY_IF_DIFFERENT`` 767 If the ``<newname>`` path already exists, do not replace it if the file's 768 contents are already the same as ``<oldname>`` (this avoids updating 769 ``<newname>``'s timestamp). 770 771This sub-command has some similarities to :command:`configure_file` with the 772``COPYONLY`` option. An important difference is that :command:`configure_file` 773creates a dependency on the source file, so CMake will be re-run if it changes. 774The ``file(COPY_FILE)`` sub-command does not create such a dependency. 775 776See also the ``file(COPY)`` sub-command just below which provides 777further file-copying capabilities. 778 779.. _COPY: 780.. _INSTALL: 781 782.. code-block:: cmake 783 784 file(<COPY|INSTALL> <files>... DESTINATION <dir> 785 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS] 786 [FILE_PERMISSIONS <permissions>...] 787 [DIRECTORY_PERMISSIONS <permissions>...] 788 [FOLLOW_SYMLINK_CHAIN] 789 [FILES_MATCHING] 790 [[PATTERN <pattern> | REGEX <regex>] 791 [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) 792 793.. note:: 794 795 For a simple file copying operation, the ``file(COPY_FILE)`` sub-command 796 just above may be easier to use. 797 798The ``COPY`` signature copies files, directories, and symlinks to a 799destination folder. Relative input paths are evaluated with respect 800to the current source directory, and a relative destination is 801evaluated with respect to the current build directory. Copying 802preserves input file timestamps, and optimizes out a file if it exists 803at the destination with the same timestamp. Copying preserves input 804permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` 805are given (default is ``USE_SOURCE_PERMISSIONS``). 806 807.. versionadded:: 3.15 808 If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve 809 the symlinks at the paths given until a real file is found, and install 810 a corresponding symlink in the destination for each symlink encountered. For 811 each symlink that is installed, the resolution is stripped of the directory, 812 leaving only the filename, meaning that the new symlink points to a file in 813 the same directory as the symlink. This feature is useful on some Unix systems, 814 where libraries are installed as a chain of symlinks with version numbers, with 815 less specific versions pointing to more specific versions. 816 ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library 817 itself into the destination directory. For example, if you have the following 818 directory structure: 819 820* ``/opt/foo/lib/libfoo.so.1.2.3`` 821* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` 822* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` 823* ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` 824 825and you do: 826 827.. code-block:: cmake 828 829 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) 830 831This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into 832``lib``. 833 834See the :command:`install(DIRECTORY)` command for documentation of 835permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and 836``EXCLUDE`` options. Copying directories preserves the structure 837of their content even if options are used to select a subset of 838files. 839 840The ``INSTALL`` signature differs slightly from ``COPY``: it prints 841status messages, and ``NO_SOURCE_PERMISSIONS`` is default. 842 843Installation scripts generated by the :command:`install` command 844use this signature (with some undocumented options for internal use). 845 846.. versionchanged:: 3.22 847 848 The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the 849 default copying behavior of :command:`file(INSTALL)`. 850 851.. _SIZE: 852 853.. code-block:: cmake 854 855 file(SIZE <filename> <variable>) 856 857.. versionadded:: 3.14 858 859Determine the file size of the ``<filename>`` and put the result in 860``<variable>`` variable. Requires that ``<filename>`` is a valid path 861pointing to a file and is readable. 862 863.. _READ_SYMLINK: 864 865.. code-block:: cmake 866 867 file(READ_SYMLINK <linkname> <variable>) 868 869.. versionadded:: 3.14 870 871This subcommand queries the symlink ``<linkname>`` and stores the path it 872points to in the result ``<variable>``. If ``<linkname>`` does not exist or 873is not a symlink, CMake issues a fatal error. 874 875Note that this command returns the raw symlink path and does not resolve 876a relative path. The following is an example of how to ensure that an 877absolute path is obtained: 878 879.. code-block:: cmake 880 881 set(linkname "/path/to/foo.sym") 882 file(READ_SYMLINK "${linkname}" result) 883 if(NOT IS_ABSOLUTE "${result}") 884 get_filename_component(dir "${linkname}" DIRECTORY) 885 set(result "${dir}/${result}") 886 endif() 887 888.. _CREATE_LINK: 889 890.. code-block:: cmake 891 892 file(CREATE_LINK <original> <linkname> 893 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) 894 895.. versionadded:: 3.14 896 897Create a link ``<linkname>`` that points to ``<original>``. 898It will be a hard link by default, but providing the ``SYMBOLIC`` option 899results in a symbolic link instead. Hard links require that ``original`` 900exists and is a file, not a directory. If ``<linkname>`` already exists, 901it will be overwritten. 902 903The ``<result>`` variable, if specified, receives the status of the operation. 904It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` 905is not specified and the operation fails, a fatal error is emitted. 906 907Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if 908creating the link fails. It can be useful for handling situations such as 909``<original>`` and ``<linkname>`` being on different drives or mount points, 910which would make them unable to support a hard link. 911 912.. _CHMOD: 913 914.. code-block:: cmake 915 916 file(CHMOD <files>... <directories>... 917 [PERMISSIONS <permissions>...] 918 [FILE_PERMISSIONS <permissions>...] 919 [DIRECTORY_PERMISSIONS <permissions>...]) 920 921.. versionadded:: 3.19 922 923Set the permissions for the ``<files>...`` and ``<directories>...`` specified. 924Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, 925``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, 926``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``. 927 928Valid combination of keywords are: 929 930``PERMISSIONS`` 931 All items are changed. 932 933``FILE_PERMISSIONS`` 934 Only files are changed. 935 936``DIRECTORY_PERMISSIONS`` 937 Only directories are changed. 938 939``PERMISSIONS`` and ``FILE_PERMISSIONS`` 940 ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files. 941 942``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` 943 ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories. 944 945``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` 946 Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for 947 directories. 948 949 950.. _CHMOD_RECURSE: 951 952.. code-block:: cmake 953 954 file(CHMOD_RECURSE <files>... <directories>... 955 [PERMISSIONS <permissions>...] 956 [FILE_PERMISSIONS <permissions>...] 957 [DIRECTORY_PERMISSIONS <permissions>...]) 958 959.. versionadded:: 3.19 960 961Same as `CHMOD`_, but change the permissions of files and directories present in 962the ``<directories>...`` recursively. 963 964Path Conversion 965^^^^^^^^^^^^^^^ 966 967.. _REAL_PATH: 968 969.. code-block:: cmake 970 971 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) 972 973.. versionadded:: 3.19 974 975Compute the absolute path to an existing file or directory with symlinks 976resolved. 977 978``BASE_DIRECTORY <dir>`` 979 If the provided ``<path>`` is a relative path, it is evaluated relative to the 980 given base directory ``<dir>``. If no base directory is provided, the default 981 base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. 982 983``EXPAND_TILDE`` 984 .. versionadded:: 3.21 985 986 If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced by 987 the user's home directory. The path to the home directory is obtained from 988 environment variables. On Windows, the ``USERPROFILE`` environment variable 989 is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` 990 is not defined. On all other platforms, only ``HOME`` is used. 991 992.. _RELATIVE_PATH: 993 994.. code-block:: cmake 995 996 file(RELATIVE_PATH <variable> <directory> <file>) 997 998Compute the relative path from a ``<directory>`` to a ``<file>`` and 999store it in the ``<variable>``. 1000 1001.. _TO_CMAKE_PATH: 1002.. _TO_NATIVE_PATH: 1003 1004.. code-block:: cmake 1005 1006 file(TO_CMAKE_PATH "<path>" <variable>) 1007 file(TO_NATIVE_PATH "<path>" <variable>) 1008 1009The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style 1010path with forward-slashes (``/``). The input can be a single path or a 1011system search path like ``$ENV{PATH}``. A search path will be converted 1012to a cmake-style list separated by ``;`` characters. 1013 1014The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native 1015path with platform-specific slashes (``\`` on Windows hosts and ``/`` 1016elsewhere). 1017 1018Always use double quotes around the ``<path>`` to be sure it is treated 1019as a single argument to this command. 1020 1021Transfer 1022^^^^^^^^ 1023 1024.. _DOWNLOAD: 1025.. _UPLOAD: 1026 1027.. code-block:: cmake 1028 1029 file(DOWNLOAD <url> [<file>] [<options>...]) 1030 file(UPLOAD <file> <url> [<options>...]) 1031 1032The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. 1033The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. 1034 1035.. versionadded:: 3.19 1036 If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. 1037 This can be useful if you want to know if a file can be downloaded (for example, 1038 to check that it exists) without actually saving it anywhere. 1039 1040Options to both ``DOWNLOAD`` and ``UPLOAD`` are: 1041 1042``INACTIVITY_TIMEOUT <seconds>`` 1043 Terminate the operation after a period of inactivity. 1044 1045``LOG <variable>`` 1046 Store a human-readable log of the operation in a variable. 1047 1048``SHOW_PROGRESS`` 1049 Print progress information as status messages until the operation is 1050 complete. 1051 1052``STATUS <variable>`` 1053 Store the resulting status of the operation in a variable. 1054 The status is a ``;`` separated list of length 2. 1055 The first element is the numeric return value for the operation, 1056 and the second element is a string value for the error. 1057 A ``0`` numeric error means no error in the operation. 1058 1059``TIMEOUT <seconds>`` 1060 Terminate the operation after a given total time has elapsed. 1061 1062``USERPWD <username>:<password>`` 1063 .. versionadded:: 3.7 1064 1065 Set username and password for operation. 1066 1067``HTTPHEADER <HTTP-header>`` 1068 .. versionadded:: 3.7 1069 1070 HTTP header for operation. Suboption can be repeated several times. 1071 1072``NETRC <level>`` 1073 .. versionadded:: 3.11 1074 1075 Specify whether the .netrc file is to be used for operation. If this 1076 option is not specified, the value of the :variable:`CMAKE_NETRC` variable 1077 will be used instead. 1078 Valid levels are: 1079 1080 ``IGNORED`` 1081 The .netrc file is ignored. 1082 This is the default. 1083 ``OPTIONAL`` 1084 The .netrc file is optional, and information in the URL is preferred. 1085 The file will be scanned to find which ever information is not specified 1086 in the URL. 1087 ``REQUIRED`` 1088 The .netrc file is required, and information in the URL is ignored. 1089 1090``NETRC_FILE <file>`` 1091 .. versionadded:: 3.11 1092 1093 Specify an alternative .netrc file to the one in your home directory, 1094 if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option 1095 is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will 1096 be used instead. 1097 1098``TLS_VERIFY <ON|OFF>`` 1099 Specify whether to verify the server certificate for ``https://`` URLs. 1100 The default is to *not* verify. If this option is not specified, the value 1101 of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. 1102 1103 .. versionadded:: 3.18 1104 Added support to ``file(UPLOAD)``. 1105 1106``TLS_CAINFO <file>`` 1107 Specify a custom Certificate Authority file for ``https://`` URLs. If this 1108 option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO` 1109 variable will be used instead. 1110 1111 .. versionadded:: 3.18 1112 Added support to ``file(UPLOAD)``. 1113 1114For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` 1115certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to 1116check certificates. 1117 1118Additional options to ``DOWNLOAD`` are: 1119 1120``EXPECTED_HASH ALGO=<value>`` 1121 1122 Verify that the downloaded content hash matches the expected value, where 1123 ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. 1124 If it does not match, the operation fails with an error. It is an error to 1125 specify this if ``DOWNLOAD`` is not given a ``<file>``. 1126 1127``EXPECTED_MD5 <value>`` 1128 Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to 1129 specify this if ``DOWNLOAD`` is not given a ``<file>``. 1130 1131Locking 1132^^^^^^^ 1133 1134.. _LOCK: 1135 1136.. code-block:: cmake 1137 1138 file(LOCK <path> [DIRECTORY] [RELEASE] 1139 [GUARD <FUNCTION|FILE|PROCESS>] 1140 [RESULT_VARIABLE <variable>] 1141 [TIMEOUT <seconds>]) 1142 1143.. versionadded:: 3.2 1144 1145Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file 1146``<path>/cmake.lock`` otherwise. File will be locked for scope defined by 1147``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used 1148to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will 1149wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to 1150``0`` lock will be tried once and result will be reported immediately. If 1151``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified 1152by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no 1153``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>`` 1154and will be ``0`` on success or error message on failure. 1155 1156Note that lock is advisory - there is no guarantee that other processes will 1157respect this lock, i.e. lock synchronize two or more CMake instances sharing 1158some modifiable resources. Similar logic applied to ``DIRECTORY`` option - 1159locking parent directory doesn't prevent other ``LOCK`` commands to lock any 1160child directory or file. 1161 1162Trying to lock file twice is not allowed. Any intermediate directories and 1163file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` 1164options ignored on ``RELEASE`` operation. 1165 1166Archiving 1167^^^^^^^^^ 1168 1169.. _ARCHIVE_CREATE: 1170 1171.. code-block:: cmake 1172 1173 file(ARCHIVE_CREATE OUTPUT <archive> 1174 PATHS <paths>... 1175 [FORMAT <format>] 1176 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] 1177 [MTIME <mtime>] 1178 [VERBOSE]) 1179 1180.. versionadded:: 3.18 1181 1182Creates the specified ``<archive>`` file with the files and directories 1183listed in ``<paths>``. Note that ``<paths>`` must list actual files or 1184directories, wildcards are not supported. 1185 1186Use the ``FORMAT`` option to specify the archive format. Supported values 1187for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and 1188``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. 1189 1190Some archive formats allow the type of compression to be specified. 1191The ``7zip`` and ``zip`` archive formats already imply a specific type of 1192compression. The other formats use no compression by default, but can be 1193directed to do so with the ``COMPRESSION`` option. Valid values for 1194``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. 1195 1196.. versionadded:: 3.19 1197 The compression level can be specified with the ``COMPRESSION_LEVEL`` option. 1198 The ``<compression-level>`` should be between 0-9, with the default being 0. 1199 The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. 1200 1201.. note:: 1202 With ``FORMAT`` set to ``raw`` only one file will be compressed with the 1203 compression type specified by ``COMPRESSION``. 1204 1205The ``VERBOSE`` option enables verbose output for the archive operation. 1206 1207To specify the modification time recorded in tarball entries, use 1208the ``MTIME`` option. 1209 1210.. _ARCHIVE_EXTRACT: 1211 1212.. code-block:: cmake 1213 1214 file(ARCHIVE_EXTRACT INPUT <archive> 1215 [DESTINATION <dir>] 1216 [PATTERNS <patterns>...] 1217 [LIST_ONLY] 1218 [VERBOSE]) 1219 1220.. versionadded:: 3.18 1221 1222Extracts or lists the content of the specified ``<archive>``. 1223 1224The directory where the content of the archive will be extracted to can 1225be specified using the ``DESTINATION`` option. If the directory does not 1226exist, it will be created. If ``DESTINATION`` is not given, the current 1227binary directory will be used. 1228 1229If required, you may select which files and directories to list or extract 1230from the archive using the specified ``<patterns>``. Wildcards are supported. 1231If the ``PATTERNS`` option is not given, the entire archive will be listed or 1232extracted. 1233 1234``LIST_ONLY`` will list the files in the archive rather than extract them. 1235 1236With ``VERBOSE``, the command will produce verbose output. 1237