1configure_file
2--------------
3
4Copy a file to another location and modify its contents.
5
6.. code-block:: cmake
7
8  configure_file(<input> <output>
9                 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
10                  FILE_PERMISSIONS <permissions>...]
11                 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
12                 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
13
14Copies an ``<input>`` file to an ``<output>`` file and substitutes
15variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
16file content.  Each variable reference will be replaced with the
17current value of the variable, or the empty string if the variable
18is not defined.  Furthermore, input lines of the form
19
20.. code-block:: c
21
22  #cmakedefine VAR ...
23
24will be replaced with either
25
26.. code-block:: c
27
28  #define VAR ...
29
30or
31
32.. code-block:: c
33
34  /* #undef VAR */
35
36depending on whether ``VAR`` is set in CMake to any value not considered
37a false constant by the :command:`if` command.  The "..." content on the
38line after the variable name, if any, is processed as above.
39
40Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
41``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
42rather than being assigned the value ``...``. Therefore, input lines of the form
43
44.. code-block:: c
45
46  #cmakedefine01 VAR
47
48will be replaced with either
49
50.. code-block:: c
51
52  #define VAR 0
53
54or
55
56.. code-block:: c
57
58  #define VAR 1
59
60Input lines of the form ``#cmakedefine01 VAR ...`` will expand
61as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``,
62which may lead to undefined behavior.
63
64.. versionadded:: 3.10
65  The result lines (with the exception of the ``#undef`` comments) can be
66  indented using spaces and/or tabs between the ``#`` character
67  and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
68  indentation will be preserved in the output lines:
69
70  .. code-block:: c
71
72    #  cmakedefine VAR
73    #  cmakedefine01 VAR
74
75  will be replaced, if ``VAR`` is defined, with
76
77  .. code-block:: c
78
79    #  define VAR
80    #  define VAR 1
81
82If the input file is modified the build system will re-run CMake to
83re-configure the file and generate the build system again.
84The generated file is modified and its timestamp updated on subsequent
85cmake runs only if its content is changed.
86
87The arguments are:
88
89``<input>``
90  Path to the input file.  A relative path is treated with respect to
91  the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`.  The input path
92  must be a file, not a directory.
93
94``<output>``
95  Path to the output file or directory.  A relative path is treated
96  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
97  If the path names an existing directory the output file is placed
98  in that directory with the same file name as the input file.
99  If the path contains non-existent directories, they are created.
100
101``NO_SOURCE_PERMISSIONS``
102  .. versionadded:: 3.19
103
104  Do not transfer the permissions of the input file to the output file.
105  The copied file permissions default to the standard 644 value
106  (-rw-r--r--).
107
108``USE_SOURCE_PERMISSIONS``
109  .. versionadded:: 3.20
110
111  Transfer the permissions of the input file to the output file.
112  This is already the default behavior if none of the three permissions-related
113  keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
114  or ``FILE_PERMISSIONS``).  The ``USE_SOURCE_PERMISSIONS`` keyword mostly
115  serves as a way of making the intended behavior clearer at the call site.
116
117``FILE_PERMISSIONS <permissions>...``
118  .. versionadded:: 3.20
119
120  Ignore the input file's permissions and use the specified ``<permissions>``
121  for the output file instead.
122
123``COPYONLY``
124  Copy the file without replacing any variable references or other
125  content.  This option may not be used with ``NEWLINE_STYLE``.
126
127``ESCAPE_QUOTES``
128  Escape any substituted quotes with backslashes (C-style).
129
130``@ONLY``
131  Restrict variable replacement to references of the form ``@VAR@``.
132  This is useful for configuring scripts that use ``${VAR}`` syntax.
133
134``NEWLINE_STYLE <style>``
135  Specify the newline style for the output file.  Specify
136  ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
137  ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
138  This option may not be used with ``COPYONLY``.
139
140Example
141^^^^^^^
142
143Consider a source tree containing a ``foo.h.in`` file:
144
145.. code-block:: c
146
147  #cmakedefine FOO_ENABLE
148  #cmakedefine FOO_STRING "@FOO_STRING@"
149
150An adjacent ``CMakeLists.txt`` may use ``configure_file`` to
151configure the header:
152
153.. code-block:: cmake
154
155  option(FOO_ENABLE "Enable Foo" ON)
156  if(FOO_ENABLE)
157    set(FOO_STRING "foo")
158  endif()
159  configure_file(foo.h.in foo.h @ONLY)
160
161This creates a ``foo.h`` in the build directory corresponding to
162this source directory.  If the ``FOO_ENABLE`` option is on, the
163configured file will contain:
164
165.. code-block:: c
166
167  #define FOO_ENABLE
168  #define FOO_STRING "foo"
169
170Otherwise it will contain:
171
172.. code-block:: c
173
174  /* #undef FOO_ENABLE */
175  /* #undef FOO_STRING */
176
177One may then use the :command:`include_directories` command to
178specify the output directory as an include directory:
179
180.. code-block:: cmake
181
182  include_directories(${CMAKE_CURRENT_BINARY_DIR})
183
184so that sources may include the header as ``#include <foo.h>``.
185