Ryan Prichard | f6283ab | 2022-01-13 17:30:19 -0800 | [diff] [blame^] | 1 | configure_file |
| 2 | -------------- |
| 3 | |
| 4 | Copy 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 | |
| 14 | Copies an ``<input>`` file to an ``<output>`` file and substitutes |
| 15 | variable values referenced as ``@VAR@`` or ``${VAR}`` in the input |
| 16 | file content. Each variable reference will be replaced with the |
| 17 | current value of the variable, or the empty string if the variable |
| 18 | is not defined. Furthermore, input lines of the form |
| 19 | |
| 20 | .. code-block:: c |
| 21 | |
| 22 | #cmakedefine VAR ... |
| 23 | |
| 24 | will be replaced with either |
| 25 | |
| 26 | .. code-block:: c |
| 27 | |
| 28 | #define VAR ... |
| 29 | |
| 30 | or |
| 31 | |
| 32 | .. code-block:: c |
| 33 | |
| 34 | /* #undef VAR */ |
| 35 | |
| 36 | depending on whether ``VAR`` is set in CMake to any value not considered |
| 37 | a false constant by the :command:`if` command. The "..." content on the |
| 38 | line after the variable name, if any, is processed as above. |
| 39 | |
| 40 | Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form |
| 41 | ``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` |
| 42 | rather than being assigned the value ``...``. Therefore, input lines of the form |
| 43 | |
| 44 | .. code-block:: c |
| 45 | |
| 46 | #cmakedefine01 VAR |
| 47 | |
| 48 | will be replaced with either |
| 49 | |
| 50 | .. code-block:: c |
| 51 | |
| 52 | #define VAR 0 |
| 53 | |
| 54 | or |
| 55 | |
| 56 | .. code-block:: c |
| 57 | |
| 58 | #define VAR 1 |
| 59 | |
| 60 | Input lines of the form ``#cmakedefine01 VAR ...`` will expand |
| 61 | as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, |
| 62 | which 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 | |
| 82 | If the input file is modified the build system will re-run CMake to |
| 83 | re-configure the file and generate the build system again. |
| 84 | The generated file is modified and its timestamp updated on subsequent |
| 85 | cmake runs only if its content is changed. |
| 86 | |
| 87 | The 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 | |
| 140 | Example |
| 141 | ^^^^^^^ |
| 142 | |
| 143 | Consider 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 | |
| 150 | An adjacent ``CMakeLists.txt`` may use ``configure_file`` to |
| 151 | configure 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 | |
| 161 | This creates a ``foo.h`` in the build directory corresponding to |
| 162 | this source directory. If the ``FOO_ENABLE`` option is on, the |
| 163 | configured file will contain: |
| 164 | |
| 165 | .. code-block:: c |
| 166 | |
| 167 | #define FOO_ENABLE |
| 168 | #define FOO_STRING "foo" |
| 169 | |
| 170 | Otherwise it will contain: |
| 171 | |
| 172 | .. code-block:: c |
| 173 | |
| 174 | /* #undef FOO_ENABLE */ |
| 175 | /* #undef FOO_STRING */ |
| 176 | |
| 177 | One may then use the :command:`include_directories` command to |
| 178 | specify the output directory as an include directory: |
| 179 | |
| 180 | .. code-block:: cmake |
| 181 | |
| 182 | include_directories(${CMAKE_CURRENT_BINARY_DIR}) |
| 183 | |
| 184 | so that sources may include the header as ``#include <foo.h>``. |