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 usage and single compilation unit builds for C and C++.
Cotire was born out of a dissatisfaction with the existing CMake solutions for adding precompiled header support and unity build support to CMake based build systems. The design of cotire tries to adhere to the following principles:
Precompiled header and unity builds are good ideas in principle, but in reality they do not work if the burden of maintaining the required additional source files (a prefix header 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.
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. Source code should build properly
when a precompiled header isn't used and should build faster when a precompiled header is used.
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.
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.
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 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:
- cotire adds a custom build rule to produce a unity source file from the target's sources.
- cotire adds a custom build rule to produce a prefix header file by tracking the header files included by the target's sources.
- cotire adds a custom build rule to produce a precompiled header from the prefix header.
- cotire modifies the target's compile flags to make use of the generated precompiled header.
- 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.
By default, the example_unity target inherits all build settings from the original target
example including linked libraries and target dependencies.
For a target that has been cotired, three files will be generated as part of the build process:
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 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.
For multi-core machines cotire can be configured to generate multiple unity file segments that can be built in parallel by the chosen CMake generator (see below).
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 2013 under Windows 7:
#pragma warning(push, 0)
#ifdef __cplusplus
#include "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\include\string"
#include "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\include\algorithm"
#include "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\include\iostream"
#endif
#pragma warning(pop)
Generating the prefix file under Ubuntu 12.04 with GCC 4.6 yields the following result:
#pragma GCC system_header
#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 Xcode 5.1 under OS X 10.9, this is the resulting prefix header:
#pragma clang system_header
#ifdef __cplusplus
#include "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/c++/v1/string"
#include "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/c++/v1/iostream"
#endif
Besides include directives, cotire also adds compiler specific pragmas to the generated prefix header to suppress compiler warnings upon inclusion.
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. 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 generated prefix header can be applied to a different target added in the same source directory (see below).
Optionally, cotire will also create a prefix source file that consists of a single include directive
for the prefix header. This file is needed for pre-compiling the prefix header with Clang or GCC
to make both compilers handle the system_header pragma correctly.
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 and Clang. Cotire then modifies the COMPILE_FLAGS property of the
target to force the inclusion of the prefix header.
Visual Studio C++ and Intel C++ use a different approach to pre-compiling. Both
compilers require 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 the precompiled header and then modifies the COMPILE_FLAGS of the
remaining target source files to include 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.
The cotire function can be applied to multiple targets added in the same source directory in one
call:
add_library(libA STATIC ...)
add_library(libB SHARED ...)
add_executable(example ...)
...
cotire(example libA libB)
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.
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:
cotire(example)
...
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 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:
cotire(example)
...
get_source_file_property(_cotireTargetName "example.cpp" COTIRE_TARGET)
if (_cotireTargetName)
message(STATUS "example.cpp has been cotired for target ${_cotireTargetName}")
endif()
By default cotire uses the name of the the original target with the suffix _unity appended
for the name of the generated unity build target. To create the unity build target under a
different name, set the COTIRE_UNITY_TARGET_NAME property:
add_executable(example_template main.cpp example.cpp log.cpp log.h example.h)
set_target_properties(example_template PROPERTIES COTIRE_UNITY_TARGET_NAME "example")
...
cotire(example_template)
Invoking the example target will then run the unity build.
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.
If the target's build process should not be modified to make use 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)
The property COTIRE_ADD_UNITY_BUILD only affects the addition of the unity build target. Custom
build rules for the generation of the unity source file will always be set up, because the
unity source file is needed for the generation of the prefix header.
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.
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 a precompiled header. It defaults to 2. To override the
default, run cmake with the following options:
$ cmake -D COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES=5 <path-to-source>
cotire can be configured to use an existing manually maintained prefix header (e.g., Visual Studio
projects often use a prefix header named stdafx.h) instead of the automatically generated one.
Set the target property COTIRE_CXX_PREFIX_HEADER_INIT to the path of the existing prefix header
file. The path is interpreted relative to the target source directory:
set_target_properties(example PROPERTIES COTIRE_CXX_PREFIX_HEADER_INIT "stdafx.h")
cotire(example)
If the prefix header stdafx.h needs an accompanying source file (e.g., stdafx.cpp) in order
to be precompiled properly, that source file needs to be the first one on the list of source
files in the target's add_executable or add_library call.
The property COTIRE_CXX_PREFIX_HEADER_INIT can also be set to a list of header files which will
then make up the contents of the generated prefix header.
A manually maintained prefix header will always be applied to the corresponding target, even if the target contains too few sources to enable the use of a precompiled header.
A prefix header that is generated for a cotired target can be applied to a different target added in the same source directory:
cotire(example)
get_target_property(_prefixHeader example COTIRE_CXX_PREFIX_HEADER)
...
set_target_properties(other_target PROPERTIES COTIRE_CXX_PREFIX_HEADER_INIT "${_prefixHeader}")
cotire(other_target)
The compilation of either target will trigger the generation of the prefix header.
There are multiple target properties which affect the generation of the prefix header:
-
COTIRE_PREFIX_HEADER_IGNORE_PATHcan 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_PATHcan 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_PATHwill be added to the list of ignored directories when the prefix header file is created. -
COTIRE_ADDITIONAL_PREFIX_HEADER_IGNORE_EXTENSIONScan be used to ignore header files by file extension. It defaults to the CMake listinc;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:
set_property (SOURCE "example.cpp" PROPERTY COTIRE_DEPENDENCY "TRUE")
When a C++ program uses extern "C" on a system header file, cotire will not be able to detect
that the include file needs C linkage and will include the file with C++ linkage in the generated
prefix header instead. For example, the C interface to BLAS cblas.h usually has to be included
as extern "C" in a C++ program:
extern "C" {
#include <cblas.h>
}
The presence of extern "C" includes will prevent cotired targets from being linked successfully
because of unresolved function references using the wrong linkage. To work around the problem,
the property COTIRE_PREFIX_HEADER_IGNORE_PATH can also include the full path of header files
besides directories. Here is an example:
set_property(DIRECTORY
PROPERTY COTIRE_PREFIX_HEADER_IGNORE_PATH
"${ATLAS_INCLUDE_DIR}/cblas.h"
"${CMAKE_SOURCE_DIR}" "${CMAKE_BINARY_DIR}")
That way cblas.h will not be included in the generated prefix header and will not cause problems
upon linking.
Cotire can be configured to use an existing manually maintained unity source file instead of the
automatically generated one. Set the target property COTIRE_CXX_UNITY_SOURCE_INIT to the path
of the existing unity source file. Its path is interpreted relative to the target source directory:
set_target_properties(example PROPERTIES COTIRE_CXX_UNITY_SOURCE_INIT "example-all.cpp")
cotire(example)
The property can also be set to a list of source files which will then make up the contents of the generated unity source file.
By default cotire adds all target source files to the generated unity source. In most cases a unity build will not work out of the box, because unity builds break 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_executableoradd_librarycalls. Problematic source files should be moved towards the end. -
Set the source file property
COTIRE_EXCLUDEDon 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. -
COTIRE_UNITY_SOURCE_EXCLUDE_EXTENSIONScan be used to exclude source files by file extension from inclusion in the generated unity source. It defaults to the CMake listm;mm. -
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_INCLUDEScan 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 variableCOTIRE_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_SOURCEtoTRUEon 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.
To make use of all the machine's CPU cores for the unity compilation of a target, the target
property COTIRE_UNITY_SOURCE_MAXIMUM_NUMBER_OF_INCLUDES can be set to the string -j. Cotire
will then create as many unity file segments as there are CPU cores on the machine. Because
the unity file segments do not depend on each other, a multi-core aware build process can compile
the file segments in parallel.
To explicitly specify the number of cores, append the number after -j, e.g. -j 4 or -j4.
For CMake generators that are multi-core aware by default (i.e., Visual Studio, JOM, Ninja), cotire
will automatically initialize the property to -j. For makefile based generators, this has to be
done explicitly by setting the cache variable COTIRE_MAXIMUM_NUMBER_OF_UNITY_INCLUDES, i.e.:
$ cmake -D COTIRE_MAXIMUM_NUMBER_OF_UNITY_INCLUDES=-j4 <path-to-source>
$ make -j 4
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 (example.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 #undef directives for each source file in the unity source then.
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).
To make a CMakeLists.txt robust against a missing cotire.cmake module, the following strategy
can be applied to using cotire:
include(cotire OPTIONAL)
...
add_executable(example main.cpp example.cpp log.cpp log.h example.h)
...
if (COMMAND cotire)
cotire(example)
endif()
The include(cotire OPTIONAL) will prevent CMake from raising an error if cotire cannot be
found. The actual calls to cotire need to be guarded by if (COMMAND cotire) blocks.
Cotire is compatible with CMake compiler wrappers. For example, the use of ccache may be enabled in the following way upon configuring the project:
$ export CC="/usr/local/bin/ccache /usr/bin/gcc"
$ export CXX="/usr/local/bin/ccache /usr/bin/g++"
$ export CCACHE_SLOPPINESS=pch_defines,time_macros
$ cmake ..
Alternatively, for CMake 3.4 or later compiler wrappers can be enabled by pointing the CMake
variable CMAKE_CXX_COMPILER_LAUNCHER to the compiler wrapper executable upon configuring:
$ cmake -D CMAKE_CXX_COMPILER_LAUNCHER=/usr/local/bin/ccache <path-to-source>
Note that with ccache in order for precompiled headers to work properly, it is necessary to set
the environment variable CCACHE_SLOPPINESS to pch_defines,time_macros. Otherwise the build
process may abort with the following error message:
fatal error: file 'example_CXX_prefix.hxx' has been modified since the precompiled header
'example_CXX_prefix.hxx.gch' was built
Also see the ccache manual.
CMake 2.8.8 introduced a new type of library target called object library. An object library is a convenience target that compiles multiple source files but does not create a linked target library for them, e.g.:
add_library(myLib OBJECT lib1.cpp lib2.cpp lib3.cpp)
add_executable(exeA $<TARGET_OBJECTS:myLib> mainA.cpp)
add_executable(exeB $<TARGET_OBJECTS:myLib> mainB.cpp)
The cotire function can be applied to an object library target in a familiar fashion:
add_library(myLib OBJECT lib1.cpp lib2.cpp lib3.cpp)
cotire(myLib)
# use unity object library for executables
add_executable(exeA $<TARGET_OBJECTS:myLib_unity> mainA.cpp)
add_executable(exeB $<TARGET_OBJECTS:myLib_unity> mainB.cpp)
Because object library targets do not support PRE_BUILD actions, precompiled header usage cannot
be enabled for them for Xcode projects generated with CMake. Unity builds work as expected, though.
The setting of the target property COTIRE_UNITY_LINK_LIBRARIES_INIT controls the linking
strategy for the generated unit target.
If this property is empty or set to NONE, the generated unity target's link libraries have to be
set up manually with subsequent target_link_libraries calls:
set_target_properties(example PROPERTIES COTIRE_UNITY_LINK_LIBRARIES_INIT "NONE")
...
cotire(example)
target_link_libraries(MyExecutable_unity ${MyExecutableLibraries})
If this property is set to COPY, the unity target's link libraries will be copied from the
original target.
If this property is set to COPY_UNITY, the unity target's link libraries will be copied from the
original target but instead of copying a linked target verbatim, the target's corresponding unity
target will be preferred, provided one exists. This also applies to object libraries, which have
been added to the original target with a TARGET_OBJECTS generator expression.
As of cotire 1.7.0, the default linking strategy for unit targets is COPY_UNITY.
The property COTIRE_UNITY_LINK_LIBRARIES_INIT can also be set on directories. A target inherits
the property value from its enclosing directory. To make all targets in the project use the
COPY strategy, the directory property can be set in the outermost CMakeList.txt file:
include(cotire)
...
set_property(DIRECTORY PROPERTY COTIRE_UNITY_LINK_LIBRARIES_INIT "COPY")
Cotire is compatible with both Qt projects that use CMake as build system, provided Qt targets do not use CMake automatic moc, uid or rcc scanning.
Cotire cannot set up a install_unity target that mimics the install target automatically,
because CMake does not provide the necessary information about the existing install rules
programmatically.
When using a Makefile generator, you can use the following workaround (thanks to peterhuene):
$ make all_unity
$ make install/fast
The install/fast does not trigger a build, but will use the binaries built by the all_unity
target.
For other generators, set up an install_unity target manually. First set up install rules for
all unity targets, that mimic the install rules for the original targets:
install(TARGETS example_unity RUNTIME DESTINATION "bin" OPTIONAL COMPONENT "unity")
This installs the example executable built by the unity target to the bin folder. The install
rules for unity targets must use a custom install component. Then add a global install_unity
target that performs the installation of all unity targets:
add_custom_target(install_unity
COMMAND ${CMAKE_COMMAND} -DCOMPONENT=unity -P cmake_install.cmake
COMMENT "Install the unity-built project..."
WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
add_dependencies(unity_install example_unity)
The global install_unity target must depend on all unity targets that should be installed.
If a system header ends up in a precompiled header, it is not possible to customize the inclusion of that header in a source file through preprocessor defines.
For example, under Windows one may want to include Windows.h with NOMINMAX defined to prevent
the definition of the min and max macros:
#define NOMINMAX
#include <Windows.h>
The dependency of Windows.h on the preprocessor define NOMINMAX will not be picked up by cotire
automatically upon adding Windows.h to the prefix header. To work around the problem, make the
dependency explicit by using add_definitions in the corresponding CMakeLists.txt:
if (WIN32)
# prevent definition of min and max macros through inclusion of Windows.h
add_definitions("-DNOMINMAX")
endif()
That way, the preprocessor define NOMINMAX will be picked up by cotire and applied to the
pre-compilation of the prefix header.
Sometimes the order of the includes in the automatically generated prefix header may result in compilation errors due to subtile header dependencies.
To work around the problem, the target property COTIRE_PREFIX_HEADER_INCLUDE_PRIORITY_PATH
can be set to a list of directories. Header files whose path matches one of these directories will
be inserted at the beginning of generated prefix header. Header files are sorted according to
the order of the directories in the property. Headers not matching one of these directories are
left untouched.
The property COTIRE_PREFIX_HEADER_INCLUDE_PRIORITY_PATH can also be set on directories. A target
inherits the property value from its enclosing directory.
If CMake issues the message Unknown CMake command "cotire", double check that the cotire module
has been included correctly in your project. See the manual section "cotire basic usage".
Cotire only considers build related settings of a target at the time of the cotire function call.
If target properties that control the build are changed after the call to the cotire function,
the build rules set up by cotire for the precompiled header and unity build may not work correctly.
Don't do this:
add_executable(example main.cpp example.cpp log.cpp log.h example.h)
cotire(example)
...
set_target_properties(example PROPERTIES POSITION_INDEPENDENT_CODE ON) # affects build
CMake targets are globally visible. Nevertheless, it is important that the cotire function is
called for a target in the exact same directory that creates the target with add_library or
add_executable.
Don't do this:
add_subdirectory(src)
...
cotire(mytarget) # mytarget added in src directory
Cotire may fail to inspect the target's source files correctly, if the target has been added in a different directory and you may get odd messages about missing source files.
cotire uses the CMake command file(GENERATE ... to expand generator expressions used in various
compilation settings. This command does not handle certain CMake generator expressions like
$<CXX_COMPILER_ID:...> correctly.
Under Ninja indirect prefix header dependencies are ignored by the generated build system. Cotire
uses the IMPLICIT_DEPENDS option of add_custom_command to make the precompiled header depend
on header files indirectly included by the prefix header. The IMPLICIT_DEPENDS option is not
supported by CMake's Ninja generator. See CMake issue.
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.
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).
CMake targets that contain Objective-C or Objective-C++ source files cannot be cotired. Source
files ending with .m and .mm are excluded by default through the initial default setting of
COTIRE_UNITY_SOURCE_EXCLUDE_EXTENSIONS.
Intel C++ support has only been tested with Intel C++ Composer XE 2013 for Linux and may not work with other platforms or versions.
The Intel compiler may issue incorrect warnings #672 (the command line options do not match those used when precompiled header was created) or #673 (the initial sequence of preprocessing directives is not compatible with those of precompiled header file) upon compilation of cotired targets.
Cotire is not compatible with Xoreax IncrediBuild.