mirror of
https://github.com/reactos/CMake.git
synced 2024-12-08 03:49:04 +00:00
029d38fa61
Format the documentation with better reST markup. Revise the wording to clarify how relative paths are handled. Also add an example section.
112 lines
3.1 KiB
ReStructuredText
112 lines
3.1 KiB
ReStructuredText
configure_file
|
|
--------------
|
|
|
|
Copy a file to another location and modify its contents.
|
|
|
|
::
|
|
|
|
configure_file(<input> <output>
|
|
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
|
|
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
|
|
|
|
Copies an ``<input>`` file to an ``<output>`` file and substitutes
|
|
variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
|
|
file content. Each variable reference will be replaced with the
|
|
current value of the variable, or the empty string if the variable
|
|
is not defined. Furthermore, input lines of the form::
|
|
|
|
#cmakedefine VAR ...
|
|
|
|
will be replaced with either::
|
|
|
|
#define VAR ...
|
|
|
|
or::
|
|
|
|
/* #undef VAR */
|
|
|
|
depending on whether ``VAR`` is set in CMake to any value not considered
|
|
a false constant by the :command:`if` command. The "..." content on the
|
|
line after the variable name, if any, is processed as above.
|
|
Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with
|
|
either ``#define VAR 1`` or ``#define VAR 0`` similarly.
|
|
|
|
If the input file is modified the build system will re-run CMake to
|
|
re-configure the file and generate the build system again.
|
|
|
|
The arguments are:
|
|
|
|
``<input>``
|
|
Path to the input file. A relative path is treated with respect to
|
|
the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path
|
|
must be a file, not a directory.
|
|
|
|
``<output>``
|
|
Path to the output file or directory. A relative path is treated
|
|
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
|
|
If the path names an existing directory the output file is placed
|
|
in that directory with the same file name as the input file.
|
|
|
|
``COPYONLY``
|
|
Copy the file without replacing any variable references or other
|
|
content. This option may not be used with ``NEWLINE_STYLE``.
|
|
|
|
``ESCAPE_QUOTES``
|
|
Escape any substituted quotes with backslashes (C-style).
|
|
|
|
``@ONLY``
|
|
Restrict variable replacement to references of the form ``@VAR@``.
|
|
This is useful for configuring scripts that use ``${VAR}`` syntax.
|
|
|
|
``NEWLINE_STYLE <style>``
|
|
Specify the newline style for the output file. Specify
|
|
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
|
|
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
|
|
This option may not be used with ``COPYONLY``.
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
Consider a source tree containing a ``foo.h.in`` file:
|
|
|
|
.. code-block:: c
|
|
|
|
#cmakedefine FOO_ENABLE
|
|
#cmakedefine FOO_STRING "@FOO_STRING@"
|
|
|
|
An adjacent ``CMakeLists.txt`` may use ``configure_file`` to
|
|
configure the header:
|
|
|
|
.. code-block:: cmake
|
|
|
|
option(FOO_ENABLE "Enable Foo" ON)
|
|
if(FOO_ENABLE)
|
|
set(FOO_STRING "foo")
|
|
endif()
|
|
configure_file(foo.h.in foo.h @ONLY)
|
|
|
|
This creates a ``foo.h`` in the build directory corresponding to
|
|
this source directory. If the ``FOO_ENABLE`` option is on, the
|
|
configured file will contain:
|
|
|
|
.. code-block:: c
|
|
|
|
#define FOO_ENABLE
|
|
#define FOO_STRING "foo"
|
|
|
|
Otherwise it will contain:
|
|
|
|
.. code-block:: c
|
|
|
|
/* #undef FOO_ENABLE */
|
|
/* #undef FOO_STRING */
|
|
|
|
One may then use the :command:`include_directories` command to
|
|
specify the output directory as an include directory:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include_directories(${CMAKE_CURRENT_BINARY_DIR})
|
|
|
|
so that sources may include the header as ``#include <foo.h>``.
|