[Cmake-commits] CMake branch, next, updated. v3.1.3-1337-ged0721a
Brad King
brad.king at kitware.com
Thu Feb 12 16:21:22 EST 2015
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via ed0721a37ab40da95e49a3d79b31f082d0c49cba (commit)
via 029d38fa61a666bff89b522904e05a88f903d051 (commit)
from 3df0a0aa91f24dbd08d310e13cd44e8d88524922 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=ed0721a37ab40da95e49a3d79b31f082d0c49cba
commit ed0721a37ab40da95e49a3d79b31f082d0c49cba
Merge: 3df0a0a 029d38f
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Feb 12 16:21:20 2015 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Thu Feb 12 16:21:20 2015 -0500
Merge topic 'doc-configure_file-output-location' into next
029d38fa Help: Revise configure_file documentation (#15403)
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=029d38fa61a666bff89b522904e05a88f903d051
commit 029d38fa61a666bff89b522904e05a88f903d051
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Feb 12 16:06:07 2015 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Thu Feb 12 16:20:32 2015 -0500
Help: Revise configure_file documentation (#15403)
Format the documentation with better reST markup. Revise the
wording to clarify how relative paths are handled. Also add
an example section.
diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst
index 70357f2..4304f09 100644
--- a/Help/command/configure_file.rst
+++ b/Help/command/configure_file.rst
@@ -9,38 +9,103 @@ Copy a file to another location and modify its contents.
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
-Copies a file <input> to file <output> and substitutes variable values
-referenced in the file content. If <input> is a relative path it is
-evaluated with respect to the current source directory. The <input>
-must be a file, not a directory. If <output> is a relative path it is
-evaluated with respect to the current binary directory. If <output>
-names an existing directory the input file is placed in that directory
-with its original name.
-
-If the <input> file is modified the build system will re-run CMake to
+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.
-This command replaces any variables in the input file referenced as
-${VAR} or @VAR@ with their values as determined by CMake. If a
-variable is not defined, it will be replaced with nothing. If
-COPYONLY is specified, then no variable expansion will take place. If
-ESCAPE_QUOTES is specified then any substituted quotes will be C-style
-escaped. The file will be configured with the current values of CMake
-variables. If @ONLY is specified, only variables of the form @VAR@
-will be replaced and ${VAR} will be ignored. This is useful for
-configuring scripts that use ${VAR}.
-
-Input file 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 if() command. (Content of "...", 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.
-
-With NEWLINE_STYLE the line ending could be adjusted:
+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
- 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
+ include_directories(${CMAKE_CURRENT_BINARY_DIR})
-COPYONLY must not be used with NEWLINE_STYLE.
+so that sources may include the header as ``#include <foo.h>``.
-----------------------------------------------------------------------
Summary of changes:
Help/command/configure_file.rst | 125 +++++++++++++++++++++++++++++----------
1 file changed, 95 insertions(+), 30 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list