4 File manipulation command.
6 This command is dedicated to file and path manipulation requiring access to the
9 For other path manipulation, handling only syntactic aspects, have a look at
10 :command:`cmake_path` command.
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.
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`_ [...])
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> [...])
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>... [...])
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>)
58 file(`DOWNLOAD`_ <url> [<file>] [...])
59 file(`UPLOAD`_ <file> <url> [...])
62 file(`LOCK`_ <path> [...])
65 file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
66 file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
75 file(READ <filename> <variable>
76 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
78 Read content from a file called ``<filename>`` and store it in a
79 ``<variable>``. Optionally start from the given ``<offset>`` and
80 read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
81 be 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
89 file(STRINGS <filename> <variable> [<options>...])
91 Parse 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:
95 ``LENGTH_MAXIMUM <max-len>``
96 Consider only strings of at most a given length.
98 ``LENGTH_MINIMUM <min-len>``
99 Consider only strings of at least a given length.
101 ``LIMIT_COUNT <max-num>``
102 Limit the number of distinct strings to be extracted.
104 ``LIMIT_INPUT <max-in>``
105 Limit the number of input bytes to read from the file.
107 ``LIMIT_OUTPUT <max-out>``
108 Limit the number of total bytes to store in the ``<variable>``.
111 Treat newline characters (``\n``, LF) as part of string content
112 instead of terminating at them.
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.
119 Consider only strings that match the given regular expression,
120 as described under :ref:`string(REGEX) <Regex Specification>`.
122 ``ENCODING <encoding-type>``
123 .. versionadded:: 3.1
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.
130 .. versionadded:: 3.2
131 Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings.
133 For example, the code
135 .. code-block:: cmake
137 file(STRINGS myfile.txt myfile)
139 stores a list in the variable ``myfile`` in which each item is a line
144 .. code-block:: cmake
146 file(<HASH> <filename> <variable>)
148 Compute a cryptographic hash of the content of ``<filename>`` and
149 store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
150 are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
155 .. code-block:: cmake
157 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
159 Compute a string representation of the modification time of ``<filename>``
160 and store it in ``<variable>``. Should the command be unable to obtain a
161 timestamp variable will be set to the empty string ("").
163 See the :command:`string(TIMESTAMP)` command for documentation of
164 the ``<format>`` and ``UTC`` options.
166 .. _GET_RUNTIME_DEPENDENCIES:
168 .. code-block:: cmake
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>...]]
187 .. versionadded:: 3.16
189 Recursively get the list of libraries depended on by the given files.
191 Please note that this sub-command is not intended to be used in project mode.
192 It 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
194 the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
197 .. code-block:: cmake
200 file(GET_RUNTIME_DEPENDENCIES
205 The arguments are as follows:
207 ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
208 Name of the variable in which to store the list of resolved dependencies.
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,
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>``.
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.
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.
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.
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.
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
265 The following arguments specify filters for including or excluding libraries to
266 be resolved. See below for a full description of how they work.
268 ``PRE_INCLUDE_REGEXES <regexes>``
269 List of pre-include regexes through which to filter the names of
270 not-yet-resolved dependencies.
272 ``PRE_EXCLUDE_REGEXES <regexes>``
273 List of pre-exclude regexes through which to filter the names of
274 not-yet-resolved dependencies.
276 ``POST_INCLUDE_REGEXES <regexes>``
277 List of post-include regexes through which to filter the names of resolved
280 ``POST_EXCLUDE_REGEXES <regexes>``
281 List of post-exclude regexes through which to filter the names of resolved
284 ``POST_INCLUDE_FILES <files>``
285 .. versionadded:: 3.21
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.
290 ``POST_EXCLUDE_FILES <files>``
291 .. versionadded:: 3.21
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.
296 These arguments can be used to exclude unwanted system libraries when
297 resolving the dependencies, or to include libraries from a specific
298 directory. The filtering works as follows:
300 1. 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.
303 2. If the not-yet-resolved dependency matches any of the
304 ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
305 3. Otherwise, dependency resolution proceeds.
306 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to
307 the linking rules of the platform (see below).
308 5. 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
313 6. 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.
316 7. 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.
322 Different platforms have different rules for how dependencies are resolved.
323 These specifics are described here.
325 On Linux platforms, library resolution works as follows:
327 1. 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.
330 2. 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
333 3. Otherwise, if the library exists in one of the directories listed by
334 ``ldconfig``, the dependency is resolved to that file.
335 4. 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).
340 5. Otherwise, the dependency is unresolved.
342 On Windows platforms, library resolution works as follows:
344 1. 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:
351 .. code-block:: cmake
353 file(GET_RUNTIME_DEPENDENCIES
355 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
358 Converting the DLL name to lowercase allows the regexes to only match
359 lowercase names, thus simplifying the regex. For example:
361 .. code-block:: cmake
363 file(GET_RUNTIME_DEPENDENCIES
365 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
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``.)
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
376 2. (**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.
379 3. Otherwise, if the library exists in the same directory as the depending
380 file, the dependency is resolved to that file.
381 4. 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.
384 5. 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.
388 6. Otherwise, the dependency is unresolved.
390 On Apple platforms, library resolution works as follows:
392 1. 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.
396 2. 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.
400 3. 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.
403 4. 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.
408 5. Otherwise, if the dependency is an absolute file that exists, the dependency
409 is resolved to that file.
410 6. Otherwise, the dependency is unresolved.
412 This function accepts several variables that determine which tool is used for
413 dependency resolution:
415 .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
417 Determines which operating system and executable format the files are built
418 for. This could be one of several values:
424 If this variable is not specified, it is determined automatically by system
427 .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
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`:
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 ================================================= =============================================
442 If this variable is not specified, it is determined automatically by system
445 .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
447 Determines the path to the tool to use for dependency resolution. This is the
448 actual path to ``objdump``, ``dumpbin``, or ``otool``.
450 If this variable is not specified, it is determined by the value of
451 ``CMAKE_OBJDUMP`` if set, else by system introspection.
453 .. versionadded:: 3.18
454 Use ``CMAKE_OBJDUMP`` if set.
462 .. code-block:: cmake
464 file(WRITE <filename> <content>...)
465 file(APPEND <filename> <content>...)
467 Write ``<content>`` into a file called ``<filename>``. If the file does
468 not exist, it will be created. If the file already exists, ``WRITE``
469 mode will overwrite it and ``APPEND`` mode will append to the end.
470 Any directories in the path specified by ``<filename>`` that do not
471 exist will be created.
473 If the file is a build input, use the :command:`configure_file` command
474 to update the file only when its content changes.
479 .. code-block:: cmake
481 file(TOUCH [<files>...])
482 file(TOUCH_NOCREATE [<files>...])
484 .. versionadded:: 3.12
486 Create a file with no content if it does not yet exist. If the file already
487 exists, its access and/or modification will be updated to the time when the
488 function call is executed.
490 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
491 does not exist it will be silently ignored.
493 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
498 .. code-block:: cmake
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] ])
507 Generate 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)>`
510 from the input content to produce the output content. The options are:
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.
517 ``CONTENT <content>``
518 Use the content given explicitly as input.
520 ``INPUT <input-file>``
521 Use the content from a given file as input.
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`.
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.
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`.
540 .. versionadded:: 3.19
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>``).
546 ``NO_SOURCE_PERMISSIONS``
547 .. versionadded:: 3.20
549 The generated file permissions default to the standard 644 value
552 ``USE_SOURCE_PERMISSIONS``
553 .. versionadded:: 3.20
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``.
562 ``FILE_PERMISSIONS <permissions>...``
563 .. versionadded:: 3.20
565 Use the specified permissions for the generated file.
567 ``NEWLINE_STYLE <style>``
568 .. versionadded:: 3.20
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.
574 Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific
575 ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
576 Generated files are modified and their timestamp updated on subsequent cmake
577 runs only if their content is changed.
579 Note also that ``file(GENERATE)`` does not create the output file until the
580 generation phase. The output file will not yet have been written when the
581 ``file(GENERATE)`` command returns, it is written only after processing all
582 of a project's ``CMakeLists.txt`` files.
586 .. code-block:: cmake
588 file(CONFIGURE OUTPUT output-file
590 [ESCAPE_QUOTES] [@ONLY]
591 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
593 .. versionadded:: 3.18
595 Generate an output file using the input given by ``CONTENT`` and substitute
596 variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
597 substitution rules behave the same as the :command:`configure_file` command.
598 In order to match :command:`configure_file`'s behavior, generator expressions
599 are not supported for both ``OUTPUT`` and ``CONTENT``.
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.
608 ``CONTENT <content>``
609 Use the content given explicitly as input.
610 ``<content>`` does not support generator expressions.
613 Escape any substituted quotes with backslashes (C-style).
616 Restrict variable replacement to references of the form ``@VAR@``.
617 This is useful for configuring scripts that use ``${VAR}`` syntax.
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.
630 .. code-block:: cmake
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>...])
639 Generate a list of files that match the ``<globbing-expressions>`` and
640 store it into the ``<variable>``. Globbing expressions are similar to
641 regular expressions, but much simpler. If ``RELATIVE`` flag is
642 specified, the results will be returned as relative paths to the given
645 .. versionchanged:: 3.6
646 The results will be ordered lexicographically.
648 On Windows and macOS, globbing is case-insensitive even if the underlying
649 filesystem is case-sensitive (both filenames and globbing expressions are
650 converted to lowercase before matching). On other platforms, globbing is
653 .. versionadded:: 3.3
654 By default ``GLOB`` lists directories - directories are omitted in result if
655 ``LIST_DIRECTORIES`` is set to false.
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
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.
673 Examples of globbing expressions include::
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
679 The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
680 matched directory and match the files. Subdirectories that are symlinks
681 are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
682 :policy:`CMP0009` is not set to ``NEW``.
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.
690 Examples of recursive globbing include::
692 /dir/*.py - match all python files in /dir and subdirectories
696 .. code-block:: cmake
698 file(MAKE_DIRECTORY [<directories>...])
700 Create the given directories and their parents as needed.
705 .. code-block:: cmake
707 file(REMOVE [<files>...])
708 file(REMOVE_RECURSE [<files>...])
710 Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
711 files and directories, also non-empty directories. No error is emitted if a
712 given file does not exist. Relative input paths are evaluated with respect
713 to the current source directory.
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.
722 .. code-block:: cmake
724 file(RENAME <oldname> <newname>
728 Move a file or directory within a filesystem from ``<oldname>`` to
729 ``<newname>``, replacing the destination atomically.
734 .. versionadded:: 3.21
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.
740 .. versionadded:: 3.21
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.
748 .. code-block:: cmake
750 file(COPY_FILE <oldname> <newname>
754 .. versionadded:: 3.21
756 Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
757 supported. Symlinks are ignored and ``<oldfile>``'s content is read and
758 written to ``<newname>`` as a new file.
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.
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).
771 This sub-command has some similarities to :command:`configure_file` with the
772 ``COPYONLY`` option. An important difference is that :command:`configure_file`
773 creates a dependency on the source file, so CMake will be re-run if it changes.
774 The ``file(COPY_FILE)`` sub-command does not create such a dependency.
776 See also the ``file(COPY)`` sub-command just below which provides
777 further file-copying capabilities.
782 .. code-block:: cmake
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]
790 [[PATTERN <pattern> | REGEX <regex>]
791 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
795 For a simple file copying operation, the ``file(COPY_FILE)`` sub-command
796 just above may be easier to use.
798 The ``COPY`` signature copies files, directories, and symlinks to a
799 destination folder. Relative input paths are evaluated with respect
800 to the current source directory, and a relative destination is
801 evaluated with respect to the current build directory. Copying
802 preserves input file timestamps, and optimizes out a file if it exists
803 at the destination with the same timestamp. Copying preserves input
804 permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
805 are given (default is ``USE_SOURCE_PERMISSIONS``).
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
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``
827 .. code-block:: cmake
829 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
831 This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
834 See the :command:`install(DIRECTORY)` command for documentation of
835 permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
836 ``EXCLUDE`` options. Copying directories preserves the structure
837 of their content even if options are used to select a subset of
840 The ``INSTALL`` signature differs slightly from ``COPY``: it prints
841 status messages, and ``NO_SOURCE_PERMISSIONS`` is default.
843 Installation scripts generated by the :command:`install` command
844 use this signature (with some undocumented options for internal use).
846 .. versionchanged:: 3.22
848 The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
849 default copying behavior of :command:`file(INSTALL)`.
853 .. code-block:: cmake
855 file(SIZE <filename> <variable>)
857 .. versionadded:: 3.14
859 Determine the file size of the ``<filename>`` and put the result in
860 ``<variable>`` variable. Requires that ``<filename>`` is a valid path
861 pointing to a file and is readable.
865 .. code-block:: cmake
867 file(READ_SYMLINK <linkname> <variable>)
869 .. versionadded:: 3.14
871 This subcommand queries the symlink ``<linkname>`` and stores the path it
872 points to in the result ``<variable>``. If ``<linkname>`` does not exist or
873 is not a symlink, CMake issues a fatal error.
875 Note that this command returns the raw symlink path and does not resolve
876 a relative path. The following is an example of how to ensure that an
877 absolute path is obtained:
879 .. code-block:: cmake
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}")
890 .. code-block:: cmake
892 file(CREATE_LINK <original> <linkname>
893 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
895 .. versionadded:: 3.14
897 Create a link ``<linkname>`` that points to ``<original>``.
898 It will be a hard link by default, but providing the ``SYMBOLIC`` option
899 results in a symbolic link instead. Hard links require that ``original``
900 exists and is a file, not a directory. If ``<linkname>`` already exists,
901 it will be overwritten.
903 The ``<result>`` variable, if specified, receives the status of the operation.
904 It is set to ``0`` upon success or an error message otherwise. If ``RESULT``
905 is not specified and the operation fails, a fatal error is emitted.
907 Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
908 creating the link fails. It can be useful for handling situations such as
909 ``<original>`` and ``<linkname>`` being on different drives or mount points,
910 which would make them unable to support a hard link.
914 .. code-block:: cmake
916 file(CHMOD <files>... <directories>...
917 [PERMISSIONS <permissions>...]
918 [FILE_PERMISSIONS <permissions>...]
919 [DIRECTORY_PERMISSIONS <permissions>...])
921 .. versionadded:: 3.19
923 Set the permissions for the ``<files>...`` and ``<directories>...`` specified.
924 Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``,
925 ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``,
926 ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``.
928 Valid combination of keywords are:
931 All items are changed.
934 Only files are changed.
936 ``DIRECTORY_PERMISSIONS``
937 Only directories are changed.
939 ``PERMISSIONS`` and ``FILE_PERMISSIONS``
940 ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.
942 ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
943 ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.
945 ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
946 Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
952 .. code-block:: cmake
954 file(CHMOD_RECURSE <files>... <directories>...
955 [PERMISSIONS <permissions>...]
956 [FILE_PERMISSIONS <permissions>...]
957 [DIRECTORY_PERMISSIONS <permissions>...])
959 .. versionadded:: 3.19
961 Same as `CHMOD`_, but change the permissions of files and directories present in
962 the ``<directories>...`` recursively.
969 .. code-block:: cmake
971 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
973 .. versionadded:: 3.19
975 Compute the absolute path to an existing file or directory with symlinks
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`.
984 .. versionadded:: 3.21
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.
994 .. code-block:: cmake
996 file(RELATIVE_PATH <variable> <directory> <file>)
998 Compute the relative path from a ``<directory>`` to a ``<file>`` and
999 store it in the ``<variable>``.
1004 .. code-block:: cmake
1006 file(TO_CMAKE_PATH "<path>" <variable>)
1007 file(TO_NATIVE_PATH "<path>" <variable>)
1009 The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
1010 path with forward-slashes (``/``). The input can be a single path or a
1011 system search path like ``$ENV{PATH}``. A search path will be converted
1012 to a cmake-style list separated by ``;`` characters.
1014 The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
1015 path with platform-specific slashes (``\`` on Windows hosts and ``/``
1018 Always use double quotes around the ``<path>`` to be sure it is treated
1019 as a single argument to this command.
1027 .. code-block:: cmake
1029 file(DOWNLOAD <url> [<file>] [<options>...])
1030 file(UPLOAD <file> <url> [<options>...])
1032 The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``.
1033 The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.
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.
1040 Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
1042 ``INACTIVITY_TIMEOUT <seconds>``
1043 Terminate the operation after a period of inactivity.
1046 Store a human-readable log of the operation in a variable.
1049 Print progress information as status messages until the operation is
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.
1059 ``TIMEOUT <seconds>``
1060 Terminate the operation after a given total time has elapsed.
1062 ``USERPWD <username>:<password>``
1063 .. versionadded:: 3.7
1065 Set username and password for operation.
1067 ``HTTPHEADER <HTTP-header>``
1068 .. versionadded:: 3.7
1070 HTTP header for operation. Suboption can be repeated several times.
1073 .. versionadded:: 3.11
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.
1081 The .netrc file is ignored.
1082 This is the default.
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
1088 The .netrc file is required, and information in the URL is ignored.
1090 ``NETRC_FILE <file>``
1091 .. versionadded:: 3.11
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
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.
1103 .. versionadded:: 3.18
1104 Added support to ``file(UPLOAD)``.
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.
1111 .. versionadded:: 3.18
1112 Added support to ``file(UPLOAD)``.
1114 For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
1115 certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
1118 Additional options to ``DOWNLOAD`` are:
1120 ``EXPECTED_HASH ALGO=<value>``
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>``.
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>``.
1131 ``RANGE_START <value>``
1132 .. versionadded:: 3.24
1134 Offset of the start of the range in file in bytes. Could be omitted to
1135 download up to the specified ``RANGE_END``.
1137 ``RANGE_END <value>``
1138 .. versionadded:: 3.24
1140 Offset of the end of the range in file in bytes. Could be omitted to
1141 download everything from the specified ``RANGE_START`` to the end of file.
1148 .. code-block:: cmake
1150 file(LOCK <path> [DIRECTORY] [RELEASE]
1151 [GUARD <FUNCTION|FILE|PROCESS>]
1152 [RESULT_VARIABLE <variable>]
1153 [TIMEOUT <seconds>])
1155 .. versionadded:: 3.2
1157 Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file
1158 ``<path>/cmake.lock`` otherwise. File will be locked for scope defined by
1159 ``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used
1160 to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will
1161 wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to
1162 ``0`` lock will be tried once and result will be reported immediately. If
1163 ``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified
1164 by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no
1165 ``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>``
1166 and will be ``0`` on success or error message on failure.
1168 Note that lock is advisory - there is no guarantee that other processes will
1169 respect this lock, i.e. lock synchronize two or more CMake instances sharing
1170 some modifiable resources. Similar logic applied to ``DIRECTORY`` option -
1171 locking parent directory doesn't prevent other ``LOCK`` commands to lock any
1172 child directory or file.
1174 Trying to lock file twice is not allowed. Any intermediate directories and
1175 file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT``
1176 options ignored on ``RELEASE`` operation.
1183 .. code-block:: cmake
1185 file(ARCHIVE_CREATE OUTPUT <archive>
1188 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
1192 .. versionadded:: 3.18
1194 Creates the specified ``<archive>`` file with the files and directories
1195 listed in ``<paths>``. Note that ``<paths>`` must list actual files or
1196 directories, wildcards are not supported.
1198 Use the ``FORMAT`` option to specify the archive format. Supported values
1199 for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
1200 ``zip``. If ``FORMAT`` is not given, the default format is ``paxr``.
1202 Some archive formats allow the type of compression to be specified.
1203 The ``7zip`` and ``zip`` archive formats already imply a specific type of
1204 compression. The other formats use no compression by default, but can be
1205 directed to do so with the ``COMPRESSION`` option. Valid values for
1206 ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
1208 .. versionadded:: 3.19
1209 The compression level can be specified with the ``COMPRESSION_LEVEL`` option.
1210 The ``<compression-level>`` should be between 0-9, with the default being 0.
1211 The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given.
1214 With ``FORMAT`` set to ``raw`` only one file will be compressed with the
1215 compression type specified by ``COMPRESSION``.
1217 The ``VERBOSE`` option enables verbose output for the archive operation.
1219 To specify the modification time recorded in tarball entries, use
1220 the ``MTIME`` option.
1222 .. _ARCHIVE_EXTRACT:
1224 .. code-block:: cmake
1226 file(ARCHIVE_EXTRACT INPUT <archive>
1228 [PATTERNS <patterns>...]
1233 .. versionadded:: 3.18
1235 Extracts or lists the content of the specified ``<archive>``.
1237 The directory where the content of the archive will be extracted to can
1238 be specified using the ``DESTINATION`` option. If the directory does not
1239 exist, it will be created. If ``DESTINATION`` is not given, the current
1240 binary directory will be used.
1242 If required, you may select which files and directories to list or extract
1243 from the archive using the specified ``<patterns>``. Wildcards are supported.
1244 If the ``PATTERNS`` option is not given, the entire archive will be listed or
1247 ``LIST_ONLY`` will list the files in the archive rather than extract them.
1249 .. versionadded:: 3.24
1250 The ``TOUCH`` option gives extracted files a current local
1251 timestamp instead of extracting file timestamps from the archive.
1253 With ``VERBOSE``, the command will produce verbose output.