file.rst 13.8 KB
Newer Older
1
2
3
4
5
file
----

File manipulation command.

6
7
------------------------------------------------------------------------------

8
9
::

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  file(WRITE <filename> <content>...)
  file(APPEND <filename> <content>...)

Write ``<content>`` into a file called ``<filename>``.  If the file does
not exist, it will be created.  If the file already exists, ``WRITE``
mode will overwrite it and ``APPEND`` mode will append to the end.
(If the file is a build input, use the :command:`configure_file` command
to update the file only when its content changes.)

------------------------------------------------------------------------------

::

  file(READ <filename> <variable>
       [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Read content from a file called ``<filename>`` and store it in a
``<variable>``.  Optionally start from the given ``<offset>`` and
read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
be converted to a hexadecimal representation (useful for binary data).

------------------------------------------------------------------------------
32
33
34

::

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
  file(STRINGS <filename> <variable> [<options>...])

Parse a list of ASCII strings from ``<filename>`` and store it in
``<variable>``.  Binary data in the file are ignored.  Carriage return
(``\r``, CR) characters are ignored.  The options are:

``LENGTH_MAXIMUM <max-len>``
 Consider only strings of at most a given length.

``LENGTH_MINIMUM <min-len>``
 Consider only strings of at least a given length.

``LIMIT_COUNT <max-num>``
 Limit the number of distinct strings to be extracted.

``LIMIT_INPUT <max-in>``
 Limit the number of input bytes to read from the file.

``LIMIT_OUTPUT <max-out>``
 Limit the number of total bytes to store in the ``<variable>``.

``NEWLINE_CONSUME``
 Treat newline characters (``\n``, LF) as part of string content
 instead of terminating at them.

``NO_HEX_CONVERSION``
 Intel Hex and Motorola S-record files are automatically converted to
 binary while reading unless this option is given.

``REGEX <regex>``
 Consider only strings that match the given regular expression.

67
``ENCODING <encoding-type>``
68
69
70
71
 Consider strings of a given encoding.  Currently supported encodings are:
 UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.  If the ENCODING option
 is not provided and the file has a Byte Order Mark, the ENCODING option
 will be defaulted to respect the Byte Order Mark.
72

73
74
75
76
For example, the code

.. code-block:: cmake

77
78
  file(STRINGS myfile.txt myfile)

79
stores a list in the variable ``myfile`` in which each item is a line
80
81
from the input file.

82
83
84
85
------------------------------------------------------------------------------

::

86
  file(<HASH> <filename> <variable>)
87
88

Compute a cryptographic hash of the content of ``<filename>`` and
89
90
91
store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
command.
92
93
94
95
96

------------------------------------------------------------------------------

::

97
98
99
100
101
102
  file(GLOB <variable>
       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
       [<globbing-expressions>...])
  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
       [<globbing-expressions>...])
103
104
105
106
107

Generate a list of files that match the ``<globbing-expressions>`` and
store it into the ``<variable>``.  Globbing expressions are similar to
regular expressions, but much simpler.  If ``RELATIVE`` flag is
specified, the results will be returned as relative paths to the given
108
path.  The results will be ordered lexicographically.
109

110
111
112
By default ``GLOB`` lists directories - directories are omited in result if
``LIST_DIRECTORIES`` is set to false.

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
.. note::
  We do not recommend using GLOB to collect a list of source files from
  your source tree.  If no CMakeLists.txt file changes when a source is
  added or removed then the generated build system cannot know when to
  ask CMake to regenerate.

Examples of globbing expressions include::

  *.cxx      - match all files with extension cxx
  *.vt?      - match all files with extension vta,...,vtz
  f[3-5].txt - match files f3.txt, f4.txt, f5.txt

The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
matched directory and match the files.  Subdirectories that are symlinks
are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
:policy:`CMP0009` is not set to ``NEW``.

130
131
132
133
134
By default ``GLOB_RECURSE`` omits directories from result list - setting
``LIST_DIRECTORIES`` to true adds directories to result list.
If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories.

135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
Examples of recursive globbing include::

  /dir/*.py  - match all python files in /dir and subdirectories

------------------------------------------------------------------------------

::

  file(RENAME <oldname> <newname>)

Move a file or directory within a filesystem from ``<oldname>`` to
``<newname>``, replacing the destination atomically.

------------------------------------------------------------------------------

::

  file(REMOVE [<files>...])
  file(REMOVE_RECURSE [<files>...])

Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
156
157
files and directories, also non-empty directories. No error is emitted if a
given file does not exist.
158
159
160
161
162
163

------------------------------------------------------------------------------

::

  file(MAKE_DIRECTORY [<directories>...])
164

165
166
167
Create the given directories and their parents as needed.

------------------------------------------------------------------------------
168
169
170

::

171
  file(RELATIVE_PATH <variable> <directory> <file>)
172

173
174
Compute the relative path from a ``<directory>`` to a ``<file>`` and
store it in the ``<variable>``.
175

176
------------------------------------------------------------------------------
177
178
179

::

180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
  file(TO_CMAKE_PATH "<path>" <variable>)
  file(TO_NATIVE_PATH "<path>" <variable>)

The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
path with forward-slashes (``/``).  The input can be a single path or a
system search path like ``$ENV{PATH}``.  A search path will be converted
to a cmake-style list separated by ``;`` characters.

The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).

Always use double quotes around the ``<path>`` to be sure it is treated
as a single argument to this command.

------------------------------------------------------------------------------

::

  file(DOWNLOAD <url> <file> [<options>...])
  file(UPLOAD   <file> <url> [<options>...])

The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``.
The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.

Options to both ``DOWNLOAD`` and ``UPLOAD`` are:

``INACTIVITY_TIMEOUT <seconds>``
  Terminate the operation after a period of inactivity.

``LOG <variable>``
  Store a human-readable log of the operation in a variable.

``SHOW_PROGRESS``
  Print progress information as status messages until the operation is
  complete.

``STATUS <variable>``
  Store the resulting status of the operation in a variable.
  The status is a ``;`` separated list of length 2.
  The first element is the numeric return value for the operation,
  and the second element is a string value for the error.
  A ``0`` numeric error means no error in the operation.

``TIMEOUT <seconds>``
  Terminate the operation after a given total time has elapsed.

226
227
228
``USERPWD <username>:<password>``
  Set username and password for operation.

229
230
231
``HTTPHEADER <HTTP-header>``
  HTTP header for operation. Suboption can be repeated several times.

232
233
234
235
236
Additional options to ``DOWNLOAD`` are:

``EXPECTED_HASH ALGO=<value>``

  Verify that the downloaded content hash matches the expected value, where
237
238
  ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
  If it does not match, the operation fails with an error.
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272

``EXPECTED_MD5 <value>``
  Historical short-hand for ``EXPECTED_HASH MD5=<value>``.

``TLS_VERIFY <ON|OFF>``
  Specify whether to verify the server certificate for ``https://`` URLs.
  The default is to *not* verify.

``TLS_CAINFO <file>``
  Specify a custom Certificate Authority file for ``https://`` URLs.

For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
If neither ``TLS`` option is given CMake will check variables
``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.

------------------------------------------------------------------------------

::

  file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Compute a string representation of the modification time of ``<filename>``
and store it in ``<variable>``.  Should the command be unable to obtain a
timestamp variable will be set to the empty string ("").

See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.

------------------------------------------------------------------------------

::

273
274
275
  file(GENERATE OUTPUT output-file
       <INPUT input-file|CONTENT content>
       [CONDITION expression])
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291

Generate an output file for each build configuration supported by the current
:manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
:manual:`generator expressions <cmake-generator-expressions(7)>`
from the input content to produce the output content.  The options are:

``CONDITION <condition>``
  Generate the output file for a particular configuration only if
  the condition is true.  The condition must be either ``0`` or ``1``
  after evaluating generator expressions.

``CONTENT <content>``
  Use the content given explicitly as input.

``INPUT <input-file>``
  Use the content from a given file as input.
292
293
  A relative path is treated with respect to the value of
  :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
294
295
296
297
298
299
300

``OUTPUT <output-file>``
  Specify the output file name to generate.  Use generator expressions
  such as ``$<CONFIG>`` to specify a configuration-specific output file
  name.  Multiple configurations may generate the same output file only
  if the generated content is identical.  Otherwise, the ``<output-file>``
  must evaluate to an unique name for each configuration.
301
302
303
  A relative path (after evaluating generator expressions) is treated
  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
  See policy :policy:`CMP0070`.
304
305
306

Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
307
308
Generated files are modified and their timestamp updated on subsequent cmake
runs only if their content is changed.
309

310
311
312
313
314
Note also that ``file(GENERATE)`` does not create the output file until the
generation phase. The output file will not yet have been written when the
``file(GENERATE)`` command returns, it is written only after processing all
of a project's ``CMakeLists.txt`` files.

315
------------------------------------------------------------------------------
316
317
318

::

319
320
321
  file(<COPY|INSTALL> <files>... DESTINATION <dir>
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...]
322
323
324
       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
       [FILES_MATCHING]
       [[PATTERN <pattern> | REGEX <regex>]
325
        [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
326

327
The ``COPY`` signature copies files, directories, and symlinks to a
328
329
330
331
332
destination folder.  Relative input paths are evaluated with respect
to the current source directory, and a relative destination is
evaluated with respect to the current build directory.  Copying
preserves input file timestamps, and optimizes out a file if it exists
at the destination with the same timestamp.  Copying preserves input
333
334
permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
are given (default is ``USE_SOURCE_PERMISSIONS``).
335

336
See the :command:`install(DIRECTORY)` command for documentation of
337
338
339
340
permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
``EXCLUDE`` options.  Copying directories preserves the structure
of their content even if options are used to select a subset of
files.
341
342

The ``INSTALL`` signature differs slightly from ``COPY``: it prints
343
344
status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
and ``NO_SOURCE_PERMISSIONS`` is default.
345
346
Installation scripts generated by the :command:`install` command
use this signature (with some undocumented options for internal use).
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376

------------------------------------------------------------------------------

::

  file(LOCK <path> [DIRECTORY] [RELEASE]
       [GUARD <FUNCTION|FILE|PROCESS>]
       [RESULT_VARIABLE <variable>]
       [TIMEOUT <seconds>])

Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file
``<path>/cmake.lock`` otherwise. File will be locked for scope defined by
``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used
to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will
wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to
``0`` lock will be tried once and result will be reported immediately. If
``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified
by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no
``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>``
and will be ``0`` on success or error message on failure.

Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to ``DIRECTORY`` option -
locking parent directory doesn't prevent other ``LOCK`` commands to lock any
child directory or file.

Trying to lock file twice is not allowed.  Any intermediate directories and
file itself will be created if they not exist.  ``GUARD`` and ``TIMEOUT``
options ignored on ``RELEASE`` operation.