cotire 1.0.0

First release.

.gitignore

@@ -0,0 +1,3 @@
+# ignore CMake build directories
+build*/
+.DS_Store

CMakeLists.txt

@@ -0,0 +1,11 @@
+# cotire example project
+
+cmake_minimum_required(VERSION 2.8.5)
+
+project (CotireExample)
+
+set (CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/CMake")
+
+include(cotire)
+
+add_subdirectory(src)

HISTORY.md

@@ -0,0 +1,3 @@
+## 1.0.0 (2012-03-11)
+
+* First release

MANUAL.md

@@ -0,0 +1,403 @@
+cotire manual
+=============
+
+Cotire (compile time reducer) is a CMake module that speeds up the build process of CMake based
+build systems by fully automating techniques as [precompiled header][pch] usage and
+[single compilation unit][scu] builds for C and C++.
+
+motivation
+----------
+
+Cotire was born out of a dissatisfaction with the existing CMake solutions for adding
+[precompiled header][1260] support and [unity build][gmixer] support to CMake based build systems.
+The design of cotire tries to adhere to the following principles:
+
+#### as automatic as possible
+
+[Precompiled header][pch] and [unity builds][scu] are good ideas in principle, but in reality
+they do not work if the burdon of maintaining the required additional source files (a
+[prefix header][pfh] and a unity source file) is put on the developer. A modern build system
+like CMake provides enough context information to have the build system generate and update
+these files automatically.
+
+#### non-intrusive
+
+The configuration of precompiled headers usage and single computation unit builds belongs to the
+build system and not in the source code. Nobody wants to litter one's source files with `hdrstop`
+pragmas or be forced to add an include directive to every file. The same source code should build
+properly when a precompiled header isn't used and should build faster when a precompiled header
+is used.
+
+#### minimal interface
+
+Maintaining a build system over time is enough work and the CMake language may often get in your
+way. Thus the solution should only add few public CMake functions. It should be easy to integrate
+it into an existing CMake based build system and it should be just as easy to remove it again.
+
+#### lazy file creation
+
+The additional source files needed for precompiled header support and unity build support should
+only be created when they are required for the compilation of a target. Thus the solution should
+not create these files upon configuring the project, but should set up custom build commands for
+the creation of these files that only kick in when the files are required to exist by the build
+process.
+
+#### cross-platform
+
+C/C++ Compilers and IDEs on different platforms vary widely in how the implement precompiled
+header support. The solution should hide these implementation details and present a uniform
+interface to the developer on all supported platforms.
+
+cotire basic usage
+------------------
+
+Cotire consists of a single CMake module file, which can be easily added to an existing CMake
+project.
+
+The file `CMake/cotire.cmake` needs to be copied to the module directory of a CMake project. In the
+top-level `CMakeList.txt` file, the module directory needs to be added to the CMake module search
+path:
+
+    set (CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/CMake")
+
+To use cotire in a CMake project, one adds the following include directive to the beginning of the
+top-level `CMakeList.txt`:
+
+    include(cotire)
+
+To speed the build process of a CMake library or executable target, the `cotire` function is
+applied to a CMake target. From the example project that ships with cotire:
+
+    add_executable(example main.cpp example.cpp log.cpp log.h example.h)
+    ...
+    cotire(example)
+
+Cotire looks at the properties of the target provided by CMake (e.g., target type, source files,
+compile flags, preprocessor defines, include directories, ...) and modifies the target's build
+process in the following way:
+
+1. cotire adds a custom build rule to produce a unity source file from target's sources.
+2. cotire adds a custom build rule to produce a prefix header file by tracking the header files
+   included by the target's sources.
+3. cotire adds a custom build rule to produce a precompiled header from the prefix header.
+4. cotire modifies the target's compile flags to make use of the generated precompiled header.
+5. cotire adds a couple of new targets.
+
+For makefile based build systems, running `make help` in the terminal reveals the new targets:
+
+    $ make help
+    ...
+    ... all_pch
+    ... all_unity
+    ... clean_cotire
+    ... example
+    ... example_pch
+    ... example_unity
+
+The `example_pch` target triggers the compilation of the precompiled header and as a side effect
+the generation of the unity source and the prefix header. The target `clean_cotire` cleans up all
+files generated by cotire. The `example_unity` target  produces the same output as the original
+`example` target, but does so by performing a unity build. The `all_pch` and `all_unity` serve as
+pool targets for all cotired project targets.
+
+The `example_unity` target inherits all build settings from the original target `example` except
+for linked libraries and target dependencies. To get a linkable unity target, the required
+libraries have to be added manually to the unity target with `target_link_libraries`.
+
+cotire generated files
+----------------------
+
+For a target that has been cotired, three files will be generated as part of the build process:
+
+### the unity source
+
+The unity source file is generated from the target by querying the target's `SOURCES` property.
+It consists of preprocessor include directives for each of the target source files. The files
+are included in the same order that is used in the CMake `add_executable` or `add_library` call.
+Header files are omitted.
+
+This is a unity source generated for the example project under Mac OS X:
+
+    #ifdef __cplusplus
+    #include "/Users/sakra/Documents/cotire/src/main.cpp"
+    #include "/Users/sakra/Documents/cotire/src/example.cpp"
+    #include "/Users/sakra/Documents/cotire/src/log.cpp"
+    #endif
+
+The unity source file uses absolute paths to include the target's source file. The file is not
+intended to be portable across different build folders or machines. It is an intermediate file
+tied to the build folder that is automatically recreated by the build system if it is missing.
+
+### the prefix header
+
+The prefix header is produced from the unity source file by running the unity file through the
+preprocessor and keeping track of each header file used (this is done by using option `-H` with
+GCC / Clang and `/showIncludes` with Visual Studio C++). The path of each used header file is
+compared against an exclude directory list and an include directory list to decide if the header
+file should be added to the prefix header.
+
+By default the include directory list is empty and the exclude directory list is initialized to
+`"${CMAKE_SOURCE_DIR};${CMAKE_BINARY_DIR}"`. This default setting guarantees that project headers
+which are likely to be changed frequently are not added to the prefix header.
+
+Upon generation of the prefix header cotire makes sure that target compile options, include path
+settings and preprocessor defines (e.g., `NDEBUG`) that affect the outcome of the preprocessor
+are correctly set up.
+
+Generating the prefix header from the unity source is much faster than running each individual
+target source file through the preprocessor, because the coalesced unity source will make the
+preprocessor process most header files only once.
+
+This is a prefix header produced for the example project with Visual Studio 2008 under Windows:
+
+    #ifdef __cplusplus
+    #include "C:\Program Files\Microsoft Visual Studio 9.0\VC\include\string"
+    #include "C:\Program Files\Microsoft Visual Studio 9.0\VC\include\algorithm"
+    #include "C:\Program Files\Microsoft Visual Studio 9.0\VC\include\iostream"
+    #endif
+
+Generating the prefix file under Ubuntu Linux with GCC 4.6 yields the following result:
+
+    #ifdef __cplusplus
+    #include "/usr/include/c++/4.6/string"
+    #include "/usr/include/c++/4.6/algorithm"
+    #include "/usr/include/c++/4.6/iterator"
+    #include "/usr/include/c++/4.6/iostream"
+    #endif
+
+Using Clang 3.1 under Mac OS X 10.7 this is the resulting prefix header:
+
+    #ifdef __cplusplus
+    #include "/usr/include/c++/4.2.1/string"
+    #include "/usr/include/c++/4.2.1/iostream"
+    #include "/usr/include/c++/4.2.1/iterator"
+    #endif
+
+Cotire attempts to produce a minimal list of header files by omitting header files indirectly
+included by a header that is already part of the prefix header. Header files with nonstandard
+file extensions like `.inl`, `.inc` of `.ipp` are omitted by default.
+
+The generated prefix file includes the selected header files by their absolute paths. This speeds
+up the precompiling of the prefix header because the compiler does not have to search for header
+files in include directories again.
+
+The prefix header is tailored to the CMake target that it is generated for and cannot be re-used
+for a different CMake target. It is tied to the compiler environment of the local machine and
+is not portable across different compilers or machines. It is automatically recreated by the
+build system if it goes missing.
+
+### the precompiled header
+
+The precompiled header is produced from the generated prefix header by using the proprietary
+precompiling mechanism depending on the compiler used. For GCC and Clang cotire sets up a custom
+build rule and generates the precompiled header as described in the documentation for
+[GCC][gcc_pch] and [Clang][clang_pch]. Cotire then modifies the `COMPILE_FLAGS` property of the
+target to force the inclusion of the prefix header.
+
+Visual Studio C++ uses a [different approach][msvc_pch] to pre-compiling. It requires a host
+source file to generate the precompiled header as a side effect of producing an object file.
+Cotire modifies the `COMPILE_FLAGS` of the first target source file to [generate][msvc_pch_create]
+the precompiled header and then modifies the `COMPILE_FLAGS` of the remaining target source files
+to [include][msvc_pch_use] the generated precompiled header.
+
+For Xcode projects generated with CMake, cotire completely hands off the pre-compilation of
+the prefix header and the inclusion of the precompiled header to the IDE. Cotire attaches a
+pre-build action to the target which generates the unity source file and the prefix header.
+Cotire then modifies Xcode attributes of the generated Xcode project to have Xcode precompile the
+the generated prefix header with the Xcode build steps `ProcessPCH` for C sources and
+`ProcessPCH++` for C++ sources.
+
+For precompiled headers creation flags must match use flags exactly. Cotire uses the same flags,
+include directories and preprocessor defines that are used for the compilation of source files
+for the generation of the precompiled header. Thus the resulting precompiled header binary is only
+usable for the target and cannot be re-used for a different CMake target.
+
+cotire advanced usage
+---------------------
+
+### mixed-language targets
+
+Cotire is able to speed up the build process of mixed language targets, consisting of both C and
+C++ sources. It generates a separate set of unity source files, prefix headers and precompiled
+headers for both languages and modifies the `COMPILE_FLAGS` of each target source file to include
+the correct precompiled header depending on the compilation language of the source file.
+
+### obtaining the names of the generated files and targets
+
+For a cotired target the target properties `COTIRE_<LANG>_UNITY_SOURCE`,
+`COTIRE_<LANG>_PREFIX_HEADER`, `COTIRE_<LANG>_PRECOMPILED_HEADER` will be set to the paths of the
+generated files (`<LANG>` can be set to `CXX` or `C`). The target property
+`COTIRE_UNITY_TARGET_NAME` will be set to the name of the generated unity target.
+
+If a source file's `COMPILE_FLAGS` are modified by cotire, it sets the source file property
+`COTIRE_TARGET` to the name of the target, that the source file's build command has been
+altered for.
+
+### restricting cotire to certain build configurations
+
+To restrict the cotire related modifications to the build process to certain build configurations,
+the `CONFIGURATIONS` parameter can be added to the `cotire` call.
+
+    cotire(example CONFIGURATIONS Release MinSizeRel)
+
+For single build type builds the selected configuration will be checked at configure time, for
+multi-configuration builds the check will be done at build time.
+
+It is recommended to have at least one build configuration that does not make use of cotire to
+ensure that the project builds properly without cotire.
+
+### disabling precompiled headers and unity builds
+
+If the target's build process should not be modified to make us of the generated precompiled
+header, the target property `COTIRE_ENABLE_PRECOMPILED_HEADER` can be set to `FALSE`:
+
+    set_target_properties(example PROPERTIES COTIRE_ENABLE_PRECOMPILED_HEADER FALSE)
+    cotire(example)
+
+If a unity build target should not be added by cotire, the target property
+`COTIRE_ADD_UNITY_BUILD` can be set to `FALSE`:
+
+    set_target_properties(example PROPERTIES COTIRE_ADD_UNITY_BUILD FALSE)
+    cotire(example)
+
+Both properties default to TRUE. If both are set to FALSE, cotire will only set up custom build
+rules for the generation of the unity source and the prefix header.
+
+The properties `COTIRE_ENABLE_PRECOMPILED_HEADER` and `COTIRE_ADD_UNITY_BUILD` can also be set on
+directories. A target inherits the property value from its enclosing directory.
+
+### disabling precompiled headers for small targets
+
+The cache variable `COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES` can be set to the minimum number of
+source files required to enable the use of precompiled header. It defaults to 3.
+
+### configuring the generation of the prefix header
+
+There are multiple target properties which affect the generation of the prefix header:
+
+* `COTIRE_PREFIX_HEADER_IGNORE_PATH` can be set to a semicolon separated list of directories. If a
+header file is found in one of these directories or sub-directories, it will be excluded from the
+generated prefix header.
+
+* `COTIRE_PREFIX_HEADER_INCLUDE_PATH` can be set to a semicolon separated list of directories. If
+a header file is included from one of these directories or sub-directories, it will be included
+in the generated prefix header.
+
+If a header file is matched by both `COTIRE_PREFIX_HEADER_IGNORE_PATH` and
+`COTIRE_PREFIX_HEADER_INCLUDE_PATH`, the option which yields the closer relative path match wins.
+For example, if third-party libraries are part of the source tree in a directory called `Libs`,
+the following setting will make cotire select header files from the third-party directory, but
+ignore other project related headers in `CMAKE_SOURCE_DIR`:
+
+    set_target_properties(example PROPERTIES
+        COTIRE_PREFIX_HEADER_IGNORE_PATH "${CMAKE_SOURCE_DIR}"
+        COTIRE_PREFIX_HEADER_INCLUDE_PATH "${CMAKE_SOURCE_DIR}/Libs")
+
+The properties `COTIRE_PREFIX_HEADER_IGNORE_PATH` and `COTIRE_PREFIX_HEADER_INCLUDE_PATH` can
+also be set on directories.
+
+The following cache variables also affect the selection of prefix headers.
+
+* Directory paths in `COTIRE_ADDITIONAL_PREFIX_HEADER_IGNORE_PATH` will be added to the list of
+ignored directories when the prefix header file is created.
+
+* `COTIRE_ADDITIONAL_PREFIX_HEADER_IGNORE_EXTENSIONS` can be used to ignore header files by file
+extension. It defaults to the CMake list `inc;inl;ipp`.
+
+During development changes to the project source files may affect the list of header files that
+should be selected for inclusion in the prefix header (e.g., a standard include may be added or
+removed from a target source file). Cotire does not automatically recreate the prefix header,
+when a target source file is changed, because this would always trigger a re-compilation of the
+precompiled header and would result in a rebuild of the whole target. To make the prefix header
+creation dependent on changes to certain target source files, the source file property
+`COTIRE_DEPENDENCY` can be set to `TRUE` for those files.
+
+### configuring the generation of the unity source
+
+By default cotire adds all target source file to the generated unity source. In most cases a
+unity build will not work out of the box, because unity builds [break][EoUB] the use of some C
+and C++ language features. Unity build problems can be tackled in the following way:
+
+* Change the order of the source files in the `add_executable` or `add_library` calls.
+Problematic source files should be moved towards the end.
+
+* Set the source file property `COTIRE_EXCLUDED` on problematic source files. The source file
+will not be included in the unity source file and will be compiled separately when the unity build
+is performed.
+
+* If the unity source file is too large and the compilation process runs into a compiler limit,
+the target property `COTIRE_UNITY_SOURCE_MAXIMUM_NUMBER_OF_INCLUDES` can be set. If the target
+contains more than that number of source files, cotire will create multiple unity source files
+for it. Each unity source file is compiled separately when the unity build is performed.
+The property is initialized by value of the cache variable
+`COTIRE_MAXIMUM_NUMBER_OF_UNITY_INCLUDES`.
+
+* Another way to break up a large unity source file is to set the source file property
+`COTIRE_START_NEW_UNITY_SOURCE` to `TRUE` on selected target source files. If cotire encounters
+this property, it will complete the current unity file and start a new one. The new unity source
+file will include the source file as the first one. This property essentially works as a separator
+for unity source files.
+
+### fixing macro definition clashes
+
+Many unity build problems stem from macro definitions leaking into other target source files,
+where they may conflict with other definitions of the same name. Cotire adds the properties
+`COTIRE_UNITY_SOURCE_PRE_UNDEFS` and `COTIRE_UNITY_SOURCE_POST_UNDEFS` to fix macro definition
+clashes.
+
+As an example, if these properties are set on a source file of the example project:
+
+    set_source_files_properties (log.cpp PROPERTIES
+        COTIRE_UNITY_SOURCE_PRE_UNDEFS "max;min"
+        COTIRE_UNITY_SOURCE_POST_UNDEFS "DEBUG_TYPE")
+
+This will make cotire add #undefs to the generated unity source file.
+
+    #ifdef __cplusplus
+    #include "/Users/sakra/Documents/cotire/src/main.cpp"
+    #undef min
+    #undef max
+    #include "/Users/sakra/Documents/cotire/src/example.cpp"
+    #undef DEBUG_TYPE
+    #include "/Users/sakra/Documents/cotire/src/log.cpp"
+    #endif
+
+The properties `COTIRE_UNITY_SOURCE_PRE_UNDEFS` and `COTIRE_UNITY_SOURCE_POST_UNDEFS` can also be
+set on targets. Cotire will add #undefs for each source file in the unity source then.
+
+### enabling verbose builds
+
+The cache variable `COTIRE_VERBOSE` can be set to `TRUE` to see all compile commands used when
+generating the cotire related files. Cotire will also print the contents of the generated unity
+source and the prefix header for verbose builds. `COTIRE_VERBOSE` defaults to `FALSE`.
+When using a Makefile generator `COTIRE_VERBOSE` defaults to the value of the makefile variable
+`VERBOSE` (i.e., `make VERBOSE=1`).
+
+cotire usage restrictions
+-------------------------
+
+### using source files for multiple targets
+
+When the same set of source files is used for different targets (e.g., for producing a static
+and a shared library variant from the same sources), using a precompiled header may not work.
+Under certain circumstances, cotire cannot enable the precompiled header usage by changing the
+`COMPILE_FLAGS` property of the whole target, but must set the `COMPILE_FLAGS` properties of
+individual target source files instead. This will break the usage of the source file for
+multiple targets.
+
+### multi-architecture builds under Mac OS X
+
+Neither GCC nor Clang support the use of precompiled headers when performing a Mac OS X
+multi-architecture build (e.g., using option `-DCMAKE_OSX_ARCHITECTURES=i386;x86_64`).
+
+[1260]:http://www.cmake.org/Bug/view.php?id=1260
+[gmixer]:http://www.gmixer.com/archives/46
+[gcc_pch]:http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html
+[clang_pch]:http://clang.llvm.org/docs/UsersManual.html#precompiledheaders
+[msvc_pch]:http://msdn.microsoft.com/en-us/library/szfdksca(v=vs.90).aspx
+[msvc_pch_create]:http://msdn.microsoft.com/en-us/library/7zc28563(v=vs.90).aspx
+[msvc_pch_use]:http://msdn.microsoft.com/en-us/library/z0atkd6c(v=vs.90).aspx
+[EoUB]:http://leewinder.co.uk/blog/?p=394
+[pch]:http://en.wikipedia.org/wiki/Precompiled_header
+[scu]:http://en.wikipedia.org/wiki/Single_Compilation_Unit
+[pfh]:http://en.wikipedia.org/wiki/Prefix_header

README.md

@@ -0,0 +1,116 @@
+cotire
+======
+
+Cotire (compile time reducer) is a CMake module that speeds up the build process of CMake based
+build systems by fully automating techniques as [precompiled header][pch] usage and
+[single compilation unit][scu] builds for C and C++.
+
+features
+--------
+
+* Non-intrusive. Requires no source code modification and only minimal changes to CMake list files.
+* Automatically generates a single compilation unit (aka unity source file) for a CMake target.
+* Automatically generates a [prefix header][pfh] by tracking includes used by a CMake target.
+* Automatically precompiles prefix header and applies resulting precompiled header to a CMake target.
+* Supports C/C++ compilers Clang, GCC and Visual Studio C++.
+* Supports mixed language CMake targets.
+* Supports console (Makefile generator) and IDE (Visual Studio and Xcode) based builds.
+* Compatible with CMake single build type and CMake multi-configuration builds.
+* Compatible with most CMake generators.
+* Compatible with parallel builds (make -j, Visual Studio, Xcode).
+* Leverages native precompiled header generation features of IDEs (Visual Studio and Xcode).
+* Compatible with CMake's [cross-compiling][ccrc] support.
+* Tested with Windows, Linux and OS X.
+* MIT licensed.
+
+requirements
+------------
+
+* [CMake 2.8.5][cmk] or newer. The executable `cmake` should be on the system path.
+* [Visual Studio C++][vslstd], [MinGW][mingw] or [Cygwin][cgwn] under Windows.
+* [GCC][gcc] under Linux.
+* [Xcode][xcdt] developer tools package under OS X. This includes [Clang][clang].
+
+installation
+------------
+
+Copy the file `CMake/cotire.cmake` to the module directory of your CMake project. In the
+top-level `CMakeList.txt` file, add the module directory to the CMake module search path:
+
+    set (CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/CMake")
+
+usage
+-----
+
+To use cotire in your CMake project, add the following include directive to the beginning of the
+top-level `CMakeList.txt`:
+
+    include(cotire)
+
+To speed the build process of a CMake library or executable target, just apply the `cotire` function
+to the target:
+
+    add_executable(MyExecutable ${MyExecutableSources})
+    target_link_libraries(MyExecutable ${MyExecutableLibraries})
+    cotire(MyExecutable)
+
+Cotire looks at the properties of the target provided by CMake (e.g., target type, source files,
+compile flags, preprocessor defines, include directories, ...) and sets up custom commands that
+will generate a unity source file, a prefix header and a precompiled header at build time
+specially tailored to the target.
+
+For the generation of the prefix header, cotire will automatically choose headers used by the
+target that are outside of the project directory and thus are likely to change infrequently.
+The precompiled prefix header is then applied to the target to speed up the compilation process.
+
+As a side effect, cotire generates a new target named `MyExecutable_unity`, which lets you perform
+a unity build for the original target. The unity target inherits all build settings from the
+original target except for linked libraries and target dependencies. To get a workable unity
+target, add another `target_link_libraries` call:
+
+    cotire(MyExecutable)
+    target_link_libraries(MyExecutable_unity ${MyExecutableLibraries})
+
+For Makefile based generators you can then invoke a unity build that produces the same output as
+the original target, but does so much faster by entering:
+
+    $ make MyExecutable_unity
+
+See the advanced usage section of the cotire manual for information on how to configure the cotire
+process (e.g., how to apply cotire to a certain build configuration only).
+
+speedup
+-------
+
+Depending on factors like hardware, compiler, the number of files in the target and the complexity
+of the C/C++ code, the build process of targets that use a cotire generated precompiled header
+will be sped up from 10 to 40 percent. Using precompiled headers however is not without
+[issues][PCHH] and may not work for some programs.
+
+A unity build may be up to 90 percent faster than the one file at a time build of the original
+target. Single compilation unit builds however are very unlikely to work without source code
+modifications, because they [break][EoUB] the use of some C and C++ language features.
+
+Generally, modern C++ code which makes heavy use of header-only libraries will profit the most from
+cotiring.
+
+limitations
+-----------
+
+* CMake configure time will increase for cotired targets.
+* The size of the CMake build folder will increase, because precompiled headers are large binaries.
+* It is not possible to share precompiled headers generated by cotire between CMake targets.
+
+[ccrc]:http://www.cmake.org/Wiki/CMake_Cross_Compiling
+[cgwn]:http://www.cygwin.com/
+[clang]:http://clang.llvm.org/
+[cmk]:http://www.cmake.org/cmake/resources/software.html
+[gcc]:http://gcc.gnu.org/
+[mingw]:http://www.mingw.org/
+[pch]:http://en.wikipedia.org/wiki/Precompiled_header
+[pfh]:http://en.wikipedia.org/wiki/Prefix_header
+[scu]:http://en.wikipedia.org/wiki/Single_Compilation_Unit
+[vslstd]:http://msdn.microsoft.com/vstudio/
+[xcdt]:http://developer.apple.com/tools/xcode/
+[PCHH]:http://gcc.gnu.org/wiki/PCHHaters
+[EoUB]:http://leewinder.co.uk/blog/?p=394

license

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Sascha Kratky
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

src/CMakeLists.txt

@@ -0,0 +1,28 @@
+# cotire example project
+
+add_executable(example main.cpp example.cpp log.cpp log.h example.h)
+
+if (CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+	set_target_properties(example PROPERTIES COMPILE_FLAGS "-Wall")
+endif()
+
+cotire(example)
+
+# cotire sets the following properties
+get_target_property(_unitySource example COTIRE_CXX_UNITY_SOURCE)
+get_target_property(_prefixHeader example COTIRE_CXX_PREFIX_HEADER)
+get_target_property(_precompiledHeader example COTIRE_CXX_PRECOMPILED_HEADER)
+get_target_property(_unityTargetName example COTIRE_UNITY_TARGET_NAME)
+
+if (_unitySource)
+	message(STATUS "example unity source: ${_unitySource}")
+endif()
+if (_prefixHeader)
+	message(STATUS "example prefix header: ${_prefixHeader}")
+endif()
+if (_precompiledHeader)
+	message(STATUS "example precompiled header: ${_precompiledHeader}")
+endif()
+if (TARGET ${_unityTargetName})
+	message(STATUS "example unity target: ${_unityTargetName}")
+endif()

src/example.cpp

@@ -0,0 +1,24 @@
+// cotire example project
+
+#include "example.h"
+
+#ifndef NDEBUG
+#include <algorithm>
+#include <iterator>
+#endif
+
+namespace example {
+
+std::string get_message() {
+	char msg_chrs[] = { 'C', 'o', 't', 'i', 'r', 'e', 'd', '!' };
+#ifdef NDEBUG
+	return std::string(&msg_chrs[0], &msg_chrs[sizeof(msg_chrs)]);
+#else
+	std::string msg;
+	msg.reserve(sizeof(msg_chrs));
+	std::copy(msg_chrs, msg_chrs + sizeof(msg_chrs), std::back_inserter(msg));
+	return msg;
+#endif
+}
+
+}

src/example.h

@@ -0,0 +1,10 @@
+// cotire example project
+
+#include <string>
+
+namespace example {
+
+std::string get_message();
+
+}
+

src/log.cpp

@@ -0,0 +1,17 @@
+// cotire example project
+
+#include "log.h"
+
+#include <iostream>
+
+namespace log {
+
+void error(const std::string& msg) {
+	std::cerr << msg << std::endl;
+}
+
+void info(const std::string& msg) {
+	std::cout << msg << std::endl;
+}
+
+}

src/log.h

@@ -0,0 +1,10 @@
+// cotire example project
+
+#include <string>
+
+namespace log {
+
+void error(const std::string& msg);
+void info(const std::string& msg);
+
+}

src/main.cpp

@@ -0,0 +1,12 @@
+// cotire example project main
+
+#include <string>
+
+#include "example.h"
+#include "log.h"
+
+int main(int argc, char** argv)
+{
+	std::string msg = example::get_message();
+	log::info(msg);
+}