add a configure_file example

03-code-generation/configure-files/CMakeLists.txt

@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 2.8)
+
+# Set the project name
+project (cf_example)
+
+# set a project version
+set (cf_example_VERSION_MAJOR 0)
+set (cf_example_VERSION_MINOR 2)
+set (cf_example_VERSION_PATCH 1)
+set (cf_example_VERSION "${cf_example_VERSION_MAJOR}.${cf_example_VERSION_MINOR}.${cf_example_VERSION_PATCH}")
+
+# Call configure files on ver.h.in to set the version.
+# Uses the standard ${VARIABLE} syntax in the file
+configure_file(ver.h.in ${PROJECT_BINARY_DIR}/ver.h)
+
+# configure the path.h.in file.
+# This file can only use the @VARIABLE@ syntax in the file
+configure_file(path.h.in ${PROJECT_BINARY_DIR}/path.h @ONLY)
+
+# include the directory with the new files
+include_directories(${CMAKE_BINARY_DIR})
+
+# Add an executable
+add_executable(cf_example
+    main.cpp
+    )

03-code-generation/configure-files/README.adoc

@@ -0,0 +1,123 @@
+= Configure Files Generation
+
+:toc:
+:toc-placement!:
+
+toc::[]
+
+
+[[intro]]
+Introduction
+------------
+
+During the call to cmake it is possible to create files that use variables from
+the CMakeLists.txt and cmake cache. During CMake generation the file is copied to a
+new location and any cmake variables are replaced.
+
+The files in this tutorial are below:
+
+```
+$ tree
+.
+├── CMakeLists.txt
+├── main.cpp
+├── path.h.in
+├── ver.h.in
+```
+
+  * CMakeLists.txt - Contains the CMake commands you wish to run
+  * main.cpp - The source file with main
+  * path.h.in - File to contain a path to the build directory
+  * ver.h.in - File to contain the version of the project
+
+[[concepts]]
+Concepts
+~~~~~~~~
+
+[[configure_files]]
+Configure Files
+^^^^^^^^^^^^^^^
+
+To do variable substitution in a file you can use the `configure_file()` function
+in CMake. This core arguments for this function are source file and destination file.
+
+[source,cmake]
+----
+configure_file(ver.h.in ${PROJECT_BINARY_DIR}/ver.h)
+
+configure_file(path.h.in ${PROJECT_BINARY_DIR}/path.h @ONLY)
+----
+
+The first example above, allows the variable to be defined like a CMake variables using
+the `${}` syntax or an `@@` in the ver.h.in file. After generation a new file ver.h will be available
+in the `PROJECT_BINARY_DIR`.
+
+```
+const char* ver = "${cf_example_VERSION}";
+```
+
+The second example, only allows variables to be defined using the `@@` syntax in the path.h.in file.
+After generation a new file path.h will be available in the `PROJECT_BINARY_DIR`.
+
+```
+const char* path = "@CMAKE_SOURCE_DIR@";
+```
+
+[[building-the-example]]
+Building the Example
+~~~~~~~~~~~~~~~~~~~~
+
+[source,bash]
+----
+$ mkdir build
+
+$ cd build/
+
+$ cmake ..
+-- The C compiler identification is GNU 4.8.4
+-- The CXX compiler identification is GNU 4.8.4
+-- Check for working C compiler: /usr/bin/cc
+-- Check for working C compiler: /usr/bin/cc -- works
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Check for working CXX compiler: /usr/bin/c++
+-- Check for working CXX compiler: /usr/bin/c++ -- works
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/matrim/workspace/cmake-examples/03-code-generation/configure-files/build
+
+$ ls
+CMakeCache.txt  CMakeFiles  cmake_install.cmake  Makefile  path.h  ver.h
+
+$ cat path.h
+#ifndef __PATH_H__
+#define __PATH_H__
+
+// version variable that will be substituted by cmake
+// This shows an example using the @ variable type
+const char* path = "/home/matrim/workspace/cmake-examples/03-code-generation/configure-files";
+
+#endif
+
+$ cat ver.h
+#ifndef __VER_H__
+#define __VER_H__
+
+// version variable that will be substituted by cmake
+// This shows an example using the $ variable type
+const char* ver = "0.2.1";
+
+#endif
+
+$ make
+Scanning dependencies of target cf_example
+[100%] Building CXX object CMakeFiles/cf_example.dir/main.cpp.o
+Linking CXX executable cf_example
+[100%] Built target cf_example
+
+$ ./cf_example
+Hello Version 0.2.1!
+Path is /home/matrim/workspace/cmake-examples/03-code-generation/configure-files
+----

03-code-generation/configure-files/main.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include "ver.h"
+#include "path.h"
+
+int main(int argc, char *argv[])
+{
+    std::cout << "Hello Version " << ver << "!" << std::endl;
+    std::cout << "Path is " << path << std::endl;
+   return 0;
+}

03-code-generation/configure-files/path.h.in

@@ -0,0 +1,8 @@
+#ifndef __PATH_H__
+#define __PATH_H__
+
+// version variable that will be substituted by cmake
+// This shows an example using the @ variable type
+const char* path = "@CMAKE_SOURCE_DIR@";
+
+#endif

03-code-generation/configure-files/ver.h.in

@@ -0,0 +1,8 @@
+#ifndef __VER_H__
+#define __VER_H__
+
+// version variable that will be substituted by cmake
+// This shows an example using the $ variable type
+const char* ver = "${cf_example_VERSION}";
+
+#endif