mirror of
https://github.com/mod-playerbots/azerothcore-wotlk.git
synced 2026-01-13 01:08:35 +00:00
feat(Cmake/PCH): use target_precompile_headers instead of cotire (#5082)
This commit is contained in:
Kargatum
@@ -10,13 +10,8 @@
|
||||
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||
#
|
||||
|
||||
# Require a min version Cmake
|
||||
cmake_minimum_required(VERSION 3.8...3.19)
|
||||
|
||||
# Fallback for using newer policies on CMake <3.12.
|
||||
if(${CMAKE_VERSION} VERSION_LESS 3.12)
|
||||
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
|
||||
endif()
|
||||
# Require version Cmake
|
||||
cmake_minimum_required(VERSION 3.16...3.21)
|
||||
|
||||
message(STATUS "CMake version: ${CMAKE_VERSION}")
|
||||
|
||||
@@ -40,8 +35,7 @@ set(AC_PATH_ROOT "${CMAKE_SOURCE_DIR}")
|
||||
|
||||
# set macro-directory
|
||||
list(APPEND CMAKE_MODULE_PATH
|
||||
"${CMAKE_SOURCE_DIR}/src/cmake/macros"
|
||||
"${CMAKE_SOURCE_DIR}/deps/cotire/CMake")
|
||||
"${CMAKE_SOURCE_DIR}/src/cmake/macros")
|
||||
|
||||
include(CheckCXXSourceRuns)
|
||||
include(CheckIncludeFiles)
|
||||
|
||||
4
deps/PackageList.txt
vendored
4
deps/PackageList.txt
vendored
@@ -8,10 +8,6 @@ bzip2 (a freely available, patent free, high-quality data compressor)
|
||||
http://www.bzip.org/
|
||||
Version: 1.0.6
|
||||
|
||||
cotire (CMake module to speed up builds)
|
||||
https://github.com/sakra/cotire
|
||||
Version: 1.8.0 391bf6b7609e14f5976bd5247b68d63cbf8d4d12
|
||||
|
||||
G3D (a commercial-grade C++ 3D engine available as Open Source (BSD License)
|
||||
http://g3d.sourceforge.net/
|
||||
Version: 8.01-Release
|
||||
|
||||
4190
deps/cotire/CMake/cotire.cmake
vendored
4190
deps/cotire/CMake/cotire.cmake
vendored
File diff suppressed because it is too large
Load Diff
354
deps/cotire/HISTORY.md
vendored
354
deps/cotire/HISTORY.md
vendored
@@ -1,354 +0,0 @@
|
||||
## 1.8.0 (2018-03-18)
|
||||
|
||||
* support for clang-cl.exe under Windows.
|
||||
* faster prefix header generation for Clang.
|
||||
* enable parallel compilation of unity target for MSVC.
|
||||
* CMake 3.9 and 3.10 compatibility fixes.
|
||||
* disable inclusion of timestamp in precompiled headers for Clang.
|
||||
* work around ccache reporting incorrect configuration.
|
||||
* honor `MANUALLY_ADDED_DEPENDENCIES` property upon generation of unity targets.
|
||||
* use default setting of 2 for `COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES`.
|
||||
* drop broken support for unity building of targets with automatic CMake Qt processing turned on.
|
||||
* manual updates.
|
||||
|
||||
## 1.7.10 (2017-06-16)
|
||||
|
||||
* CMake 3.8 compatibility.
|
||||
* CMake 3.8.0 Qt automoc support (thanks bilke).
|
||||
* fix Xcode recompiling every time builds happen (thanks gcamp).
|
||||
* disable PCH messages when `-Wno-pch-messages` flag exists (thanks kbinani).
|
||||
* work around ccache incompatibility with newer versions of GCC and Clang.
|
||||
* fix MinGW incompatibility with `BUILD_INTERFACE` generator expression.
|
||||
* fix handling of `CMAKE_INCLUDE_FLAG_SEP_<LANG>` variables.
|
||||
|
||||
## 1.7.9 (2016-12-08)
|
||||
|
||||
* CMake 3.6 and 3.7 compatibility.
|
||||
* fix ccache 3.2 compatibility issues.
|
||||
* fix bugs with handling language standard related properties (e.g., `CXX_STANDARD`, `CXX_EXTENSIONS`).
|
||||
* make prefix header generation and precompiled header compilation depend on the compiler executable.
|
||||
* fix Qt automoc handling for Windows (thanks jcelerier).
|
||||
* convert Windows paths in include directories to CMake paths (thanks wdx04).
|
||||
* replace object library with corresponding unity object library when using `COPY_UNITY` linking strategy.
|
||||
* better error reporting from prefix header generation.
|
||||
|
||||
## 1.7.8 (2016-03-27)
|
||||
|
||||
* fix `COPY_UNITY` linking strategy for private link dependencies.
|
||||
* honor `CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` upon handling of target usage requirements.
|
||||
* reworked setting up of `LINK_LIBRARIES` and `INTERFACE_LINK_LIBRARIES` properties for unity targets.
|
||||
|
||||
## 1.7.7 (2016-03-20)
|
||||
|
||||
* CMake 3.5 compatibility.
|
||||
* fix bugs related to handling of interface libraries.
|
||||
* output shorter log messages when using Visual Studio IDE.
|
||||
* don't disable PCH if CMAKE_<LANG>_COMPILER_ID is not set (thanks jcelerier).
|
||||
* add support for compiler launchers introduced in CMake 3.4 (thanks misery).
|
||||
|
||||
## 1.7.6 (2015-12-06)
|
||||
|
||||
* fix CMake 3.4 compatibility issues.
|
||||
* prevent redundant re-generation of prefix header when a target has generated source files.
|
||||
|
||||
## 1.7.5 (2015-10-27)
|
||||
|
||||
* handle visibility target properties (`CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN`).
|
||||
* better handling of include directories and system include directories.
|
||||
* parse additional system include directories from target compile flags.
|
||||
* activate select CMake policies.
|
||||
|
||||
## 1.7.4 (2015-10-10)
|
||||
|
||||
* set up single unity source file for prefix header generation.
|
||||
* increase MSVC default PCH memory to 128M.
|
||||
* remove obsolete code.
|
||||
|
||||
## 1.7.3 (2015-07-25)
|
||||
|
||||
* handle language standard target properties (e.g., `CXX_STANDARD`).
|
||||
* apply user provided prefix header to unity build target.
|
||||
* remove effect of `COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES` on generated unity target.
|
||||
* manual updates.
|
||||
|
||||
## 1.7.2 (2015-04-22)
|
||||
|
||||
* reduce configure time overhead.
|
||||
* fix bug with dependency checking when using Xcode.
|
||||
* remove obsolete code required for CMake versions older than 2.8.12.
|
||||
* streamline debugging output.
|
||||
|
||||
## 1.7.1 (2015-04-06)
|
||||
|
||||
* fix problem with CMake's automatic Qt processing for generated unity targets.
|
||||
* added a section on common pitfalls when using cotire to the manual.
|
||||
* remove obsolete code required for CMake versions older than 2.8.12.
|
||||
* streamline debugging output.
|
||||
* activate select CMake policies.
|
||||
|
||||
## 1.7.0 (2015-03-29)
|
||||
|
||||
* fix CMake 3.2 compatibility issues.
|
||||
* cotire now requires CMake 2.8.12 or newer.
|
||||
* copy `IMPORT_PREFIX` and `IMPORT_SUFFIX` target properties for unity targets (thanks peterhuene).
|
||||
* new property `COTIRE_PREFIX_HEADER_INCLUDE_PRIORITY_PATH` allows for organizing includes
|
||||
added to the prefix header by priority (thanks ArnaudD-FR).
|
||||
* for Visual Studio C++, increase static precompiled header memory allocation.
|
||||
* the default strategy for setting up a unity target's linked libraries is now `COPY_UNITY`.
|
||||
* for Qt projects, fix problem with handling of `AUTOMOC` in generated unity target.
|
||||
* fix problem with generating the cotire intermediate directory.
|
||||
* documentation updates.
|
||||
|
||||
## 1.6.9 (2015-01-18)
|
||||
|
||||
* fix bug with parsing of localized MSVC `/showIncludes` output.
|
||||
|
||||
## 1.6.8 (2014-12-28)
|
||||
|
||||
* fix bug with generation of unity source file segments for parallel builds.
|
||||
|
||||
## 1.6.7 (2014-12-21)
|
||||
|
||||
* fix CMake 3.1 compatibility issues.
|
||||
* fix ccache 3.2 compatibility issues.
|
||||
* handle `COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES` correctly for mixed-language targets.
|
||||
* correctly compute absolute paths of generated source files added to the unity source file.
|
||||
* fix bug with checking unity source and prefix header dependencies under Xcode.
|
||||
* fix bug with handling of unity source file dependencies.
|
||||
* move code to determine build configurations to function of its own.
|
||||
* documentation updates.
|
||||
|
||||
## 1.6.6 (2014-09-21)
|
||||
|
||||
* fix GCC issue with prefix header generation when source files are missing.
|
||||
* fix bug where some target properties were not properly propagated to the generated unity target.
|
||||
* use `target_link_libraries` to set up the unity target link libraries.
|
||||
* add Qt4 and Qt5 examples to the `Patches` directory.
|
||||
* documentation updates.
|
||||
|
||||
## 1.6.5 (2014-08-26)
|
||||
|
||||
* correctly handle generator expressions used in compile definitions, compile flags and include
|
||||
directories (requires CMake 2.8.12 or newer).
|
||||
* fix `-isystem` includes being incorrectly passed to `execute_process` (thanks nickhutchinson).
|
||||
* make some error messages more verbose.
|
||||
|
||||
## 1.6.4 (2014-07-14)
|
||||
|
||||
* fix CMake 3.0 compatibility issues.
|
||||
* preserve system flag for includes when generating PCH (thanks gjasny).
|
||||
* fix bug with setting up `EXPORTS` symbol for shared libraries.
|
||||
|
||||
## 1.6.3 (2014-06-11)
|
||||
|
||||
* correctly handle usage requirements for transitive link targets.
|
||||
* use indirect inclusion for prefix header when using generator Xcode.
|
||||
|
||||
## 1.6.2 (2014-06-09)
|
||||
|
||||
* don't use `-w` flag for pre-compiling the prefix header, because it has unwanted side effects.
|
||||
* correctly handle linked targets' `INTERFACE_COMPILE_OPTIONS`, `INTERFACE_INCLUDE_DIRECTORIES`
|
||||
and `INTERFACE_COMPILE_DEFINITIONS` properties upon pre-compiling and prefix header generation.
|
||||
* For Clang and GCC, pre-compile prefix header through indirect inclusion via a prefix source file,
|
||||
to make both compilers honor the `system_header` pragma in the prefix header correctly.
|
||||
* fix ccache incompatibility.
|
||||
|
||||
## 1.6.1 (2014-04-20)
|
||||
|
||||
* fixed bug where precompiled headers did not work with Clang (thanks to nh2 for reporting).
|
||||
* when using ccache, require that environment variable `CCACHE_SLOPPINESS` is set to `time_macros`.
|
||||
|
||||
## 1.6.0 (2014-03-16)
|
||||
|
||||
* suppress compiler warnings from precompiled headers.
|
||||
* fix Clang compatibility issue with prefix header generation.
|
||||
* use file extension `.pch` for precompiled headers generated with Clang.
|
||||
* manual updates.
|
||||
|
||||
## 1.5.2 (2014-01-17)
|
||||
|
||||
* honor framework includes under OS X correctly.
|
||||
* fix handling of OS X specific variables `CMAKE_OSX_SYSROOT` and `CMAKE_OSX_DEPLOYMENT_TARGET`.
|
||||
* add new examples to the `Patches` directory.
|
||||
|
||||
## 1.5.1 (2013-11-12)
|
||||
|
||||
* fixed string quoting bugs.
|
||||
|
||||
## 1.5.0 (2013-10-13)
|
||||
|
||||
* CMake 2.8.12 compatibility fixes.
|
||||
* Upon generation of a unity target, cotire can now be configured to automatically copy all the
|
||||
linked libraries and targets from the original target. See the section on the new target property
|
||||
`COTIRE_UNITY_LINK_LIBRARIES_INIT` in the cotire manual.
|
||||
* fixed bug with copying target properties to generated unity target.
|
||||
* cotire manual updates.
|
||||
* add new examples to the `Patches` directory.
|
||||
* fix typos.
|
||||
|
||||
## 1.4.3 (2013-09-28)
|
||||
|
||||
* fixed bug with generation of unity source file when `COTIRE_MINIMUM_NUMBER_OF_TARGET_SOURCES` is
|
||||
set to 0.
|
||||
|
||||
## 1.4.2 (2013-08-24)
|
||||
|
||||
* CMake 2.8.11 compatibility fixes.
|
||||
* always force the inclusion of a user provided prefix header, even if the target
|
||||
contains too few sources to enable the use of a precompiled header.
|
||||
|
||||
## 1.4.1 (2013-06-08)
|
||||
|
||||
* fixed bug with determination of compiler version.
|
||||
* fixed bug with generation of unity source when target source files are used for multiple targets.
|
||||
* fixed bug with multi-core optimized prefix header generation.
|
||||
|
||||
## 1.4.0 (2013-03-11)
|
||||
|
||||
* one year anniversary release.
|
||||
* add support for multi-core optimized unity builds for some CMake generators.
|
||||
* add support for multi-core optimized prefix header generation.
|
||||
* add more examples to cotire manual.
|
||||
|
||||
## 1.3.6 (2013-03-06)
|
||||
|
||||
* fix bug with prefix header initialization for generator Xcode.
|
||||
* print cotire version upon inclusion.
|
||||
|
||||
## 1.3.5 (2013-03-01)
|
||||
|
||||
* fix typos in function names and property descriptions.
|
||||
|
||||
## 1.3.4 (2013-02-07)
|
||||
|
||||
* fixed bug with computing to output directory of the generated unity target (thanks shaunew).
|
||||
* fixed wrong variable reference in debugging output (thanks shaunew).
|
||||
|
||||
## 1.3.3 (2013-02-03)
|
||||
|
||||
* fixed bug with handling of policy CMP0018 relating to target property `POSITION_INDEPENDENT_CODE`.
|
||||
* fixed warnings relating to uninitialized variables.
|
||||
* Intel XE 2013 Update 2 compatibility fixes.
|
||||
|
||||
## 1.3.2 (2013-02-02)
|
||||
|
||||
* fixed missing curly brace (thanks shaunew).
|
||||
|
||||
## 1.3.1 (2013-01-29)
|
||||
|
||||
* fix bug with filtering of compile options.
|
||||
|
||||
## 1.3.0 (2013-01-09)
|
||||
|
||||
* add support for Intel C and C++ compilers.
|
||||
* CMake 2.8.10 compatibility fixes.
|
||||
* properly clean up generated cotire log files upon invoking `clean` target.
|
||||
* documentation updates.
|
||||
|
||||
## 1.2.0 (2012-11-01)
|
||||
|
||||
* add support for manually maintained prefix header and unity source files.
|
||||
* the target property `COTIRE_<LANG>_PREFIX_HEADER_INIT` can be set to a user provided prefix
|
||||
header file to be used instead of the automatically generated one (e.g., `stdafx.h`).
|
||||
* the new target property `COTIRE_<LANG>_UNITY_SOURCE_INIT` can be set to a user provided unity
|
||||
source file to be used instead of the automatically generated one.
|
||||
* the target property `COTIRE_UNITY_TARGET_NAME` is no longer read-only. It can be set to the
|
||||
desired name of the unity target that will be added by cotire.
|
||||
* add parameters `SOURCE_DIR` and `BINARY_DIR` to function `cotire` to allow for explicitly
|
||||
specifying a target's source and binary directory, if target to be cotired has been added in a
|
||||
different directory.
|
||||
|
||||
## 1.1.8 (2012-10-27)
|
||||
|
||||
* when using MSVC, apply option `/bigobj` to compilation of generated unity files.
|
||||
|
||||
## 1.1.7 (2012-10-26)
|
||||
|
||||
* cope with double slash characters in scanned include paths.
|
||||
|
||||
## 1.1.6 (2012-09-22)
|
||||
|
||||
* check result code upon scanning includes.
|
||||
* always add a `clean_cotire` target to easily clean up cotire generated files.
|
||||
* add section on `extern "C"` linkage issues to manual.
|
||||
|
||||
## 1.1.5 (2012-08-17)
|
||||
|
||||
* new cache variable `COTIRE_UNITY_SOURCE_EXCLUDE_EXTENSIONS` can be set to globally exclude
|
||||
sources with the listed file extensions from the generated unity source.
|
||||
* fix check for multi-architecture builds under OS X.
|
||||
|
||||
## 1.1.4 (2012-08-15)
|
||||
|
||||
* prevent redundant re-generation of the unity source, prefix header and precompiled header files
|
||||
(this makes cotire more applicable to C++ projects that use Qt).
|
||||
|
||||
## 1.1.3 (2012-08-12)
|
||||
|
||||
* fix out of range index operation upon building list of target include directories.
|
||||
* honor target properties `POSITION_INDEPENDENT_CODE` and `NO_SONAME` introduced with CMake 2.8.9.
|
||||
* make selection of target source files for requested target language more careful.
|
||||
* prevent modification of the CMake policy stack upon CMake version check.
|
||||
|
||||
## 1.1.2 (2012-05-06)
|
||||
|
||||
* make handling of include directories more robust against invalid paths.
|
||||
|
||||
## 1.1.1 (2012-04-20)
|
||||
|
||||
* fixed bug with generation of unity targets for `WIN32_EXECUTABLE` targets.
|
||||
* fixed bug with parsing of localized MSVC `/showIncludes` output.
|
||||
|
||||
## 1.1.0 (2012-04-19)
|
||||
|
||||
* tested with CMake 2.8.8.
|
||||
* added example to manual that shows how to apply cotire to CMake object library targets.
|
||||
* fixed multiple bugs with handling of CMake single build type and multiple configuration builds.
|
||||
* added more robust parsing of localized MSVC `/showIncludes` output.
|
||||
|
||||
## 1.0.9 (2012-04-09)
|
||||
|
||||
* add support for compiler wrappers like ccache.
|
||||
* under OS X, apply `CMAKE_OSX_SYSROOT` to prefix header include and ignore paths.
|
||||
|
||||
## 1.0.8 (2012-04-05)
|
||||
|
||||
* require CMake 2.8.6 since we are using `set_property` option `APPEND_STRING`.
|
||||
|
||||
## 1.0.7 (2012-04-02)
|
||||
|
||||
* add support for Ninja generator introduced in CMake 2.8.8.
|
||||
* fix bug with initialization of variable `COTIRE_VERBOSE`.
|
||||
|
||||
## 1.0.6 (2012-04-01)
|
||||
|
||||
* correctly handle builds where both `CMAKE_BUILD_TYPE` and `CMAKE_CONFIGURATION_TYPES` are set.
|
||||
|
||||
## 1.0.5 (2012-03-26)
|
||||
|
||||
* fix Visual Studio C++ 2010 compilation of example project.
|
||||
* enhance heuristic for #include_next directive detection.
|
||||
* fix llvm-3.0.src.patch for GCC 4.6 compilation.
|
||||
|
||||
## 1.0.4 (2012-03-24)
|
||||
|
||||
* honor target property INCLUDE_DIRECTORIES introduced in CMake 2.8.8.
|
||||
|
||||
## 1.0.3 (2012-03-23)
|
||||
|
||||
* handle OBJECT_LIBRARY targets introduced in CMake 2.8.8.
|
||||
* use predefined compiler version variable, if available.
|
||||
|
||||
## 1.0.2 (2012-03-16)
|
||||
|
||||
* fix Xcode 4.3 compatibility.
|
||||
* Cotire manual corrections.
|
||||
|
||||
## 1.0.1 (2012-03-15)
|
||||
|
||||
* Cotire manual corrections.
|
||||
* Add prefix header to the generated unity build target.
|
||||
|
||||
## 1.0.0 (2012-03-11)
|
||||
|
||||
* First release.
|
||||
791
deps/cotire/MANUAL.md
vendored
791
deps/cotire/MANUAL.md
vendored
@@ -1,791 +0,0 @@
|
||||
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 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 burden 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. 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 the 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.
|
||||
|
||||
By default, the `example_unity` target inherits all build settings from the original target
|
||||
`example` including linked libraries and target dependencies.
|
||||
|
||||
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 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
|
||||
|
||||
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
|
||||
|
||||
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++ and Intel C++ use a [different approach][msvc_pch] 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][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
|
||||
---------------------
|
||||
|
||||
### applying cotire to multiple targets at the same time
|
||||
|
||||
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)
|
||||
|
||||
### 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:
|
||||
|
||||
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()
|
||||
|
||||
### changing the name of the generated unity build target
|
||||
|
||||
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.
|
||||
|
||||
### 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 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.
|
||||
|
||||
### 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 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>
|
||||
|
||||
### using a manually maintained prefix header instead of the automatically generated one
|
||||
|
||||
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.
|
||||
|
||||
### using a generated prefix header for multiple targets
|
||||
|
||||
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.
|
||||
|
||||
### 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:
|
||||
|
||||
set_property (SOURCE "example.cpp" PROPERTY COTIRE_DEPENDENCY "TRUE")
|
||||
|
||||
### fixing linkage issues
|
||||
|
||||
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.
|
||||
|
||||
### using a manually maintained unity source instead of the automatically generated one
|
||||
|
||||
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.
|
||||
|
||||
### configuring the generation of the unity source
|
||||
|
||||
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][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.
|
||||
|
||||
* `COTIRE_UNITY_SOURCE_EXCLUDE_EXTENSIONS` can be used to exclude source files by file extension
|
||||
from inclusion in the generated unity source. It defaults to the CMake list `m;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_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.
|
||||
|
||||
### optimizing the build process for multiple processor cores
|
||||
|
||||
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
|
||||
|
||||
### 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 (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.
|
||||
|
||||
### 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`).
|
||||
|
||||
### conditionally loading cotire
|
||||
|
||||
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.
|
||||
|
||||
### using cotire with compiler wrappers
|
||||
|
||||
Cotire is compatible with CMake compiler wrappers. For example, the use of [ccache][ccch] 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][ccch_pch].
|
||||
|
||||
### applying cotire to object library targets
|
||||
|
||||
CMake 2.8.8 introduced a new type of library target called [object library][objlib]. 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.
|
||||
|
||||
### automatically setting up linked libraries in the unity target
|
||||
|
||||
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")
|
||||
|
||||
### using cotire with Qt
|
||||
|
||||
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.
|
||||
|
||||
### installing files generated by unity targets
|
||||
|
||||
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.
|
||||
|
||||
### customized inclusion of system headers
|
||||
|
||||
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.
|
||||
|
||||
### organize includes added to 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.
|
||||
|
||||
common pitfalls
|
||||
---------------
|
||||
|
||||
### include the `cotire.cmake` module correctly
|
||||
|
||||
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".
|
||||
|
||||
### do not modify a target's build related properties after applying cotire
|
||||
|
||||
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
|
||||
|
||||
|
||||
### always apply cotire in the same source directory where a target has been added
|
||||
|
||||
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.
|
||||
|
||||
known issues
|
||||
------------
|
||||
|
||||
### generator expressions
|
||||
|
||||
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.
|
||||
|
||||
### Ninja compatibility
|
||||
|
||||
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][ninja_issue].
|
||||
|
||||
### 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`).
|
||||
|
||||
### Objective-C
|
||||
|
||||
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++
|
||||
|
||||
Intel C++ support has only been tested with [Intel C++ Composer XE 2013 for Linux][icc_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.
|
||||
|
||||
### IncrediBuild
|
||||
|
||||
Cotire is not compatible with [Xoreax IncrediBuild][XGE].
|
||||
|
||||
[1260]:https://cmake.org/Bug/view.php?id=1260
|
||||
[ccch]:https://ccache.samba.org/
|
||||
[ccch_pch]:https://ccache.samba.org/manual.html#_precompiled_headers
|
||||
[clang_pch]:https://clang.llvm.org/docs/UsersManual.html#precompiled-headers
|
||||
[gcc_pch]:https://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html
|
||||
[msvc_pch]:https://msdn.microsoft.com/en-us/library/szfdksca(v=vs.90).aspx
|
||||
[msvc_pch_create]:https://msdn.microsoft.com/en-us/library/7zc28563(v=vs.90).aspx
|
||||
[msvc_pch_use]:https://msdn.microsoft.com/en-us/library/z0atkd6c(v=vs.90).aspx
|
||||
[ninja_issue]:https://cmake.org/Bug/view.php?id=13234
|
||||
[EoUB]:http://altdevblog.com/2011/08/14/the-evils-of-unity-builds/
|
||||
[pch]:https://en.wikipedia.org/wiki/Precompiled_header
|
||||
[scu]:https://en.wikipedia.org/wiki/Single_Compilation_Unit
|
||||
[objlib]:https://cmake.org/cmake/help/latest/command/add_library.html#object-libraries
|
||||
[pfh]:https://en.wikipedia.org/wiki/Prefix_header
|
||||
[icc_linux]:https://software.intel.com/en-us/c-compilers/ipsxe-support
|
||||
[XGE]:https://www.incredibuild.com/
|
||||
137
deps/cotire/README.md
vendored
137
deps/cotire/README.md
vendored
@@ -1,137 +0,0 @@
|
||||
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][scu] (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][pch] to a CMake target.
|
||||
* Alternatively, allows for using manually maintained unity source and prefix header files.
|
||||
* Supports C/C++ compilers Clang, GCC, Intel 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 (including [Ninja][ninja]).
|
||||
* Supports multi-core unity builds for some generators (make -j, [jom][jom], Visual Studio, Ninja).
|
||||
* Leverages native precompiled header generation features of IDEs (Visual Studio and Xcode).
|
||||
* Compatible with CMake's [cross-compiling][ccrc] support.
|
||||
* Compatible with compiler wrappers like [ccache][ccch].
|
||||
* Tested with Windows, Linux and OS X.
|
||||
* MIT licensed.
|
||||
|
||||
requirements
|
||||
------------
|
||||
|
||||
* [CMake 2.8.12][cmk] or newer. The executable `cmake` should be on the system path.
|
||||
* [Visual Studio C++][vslstd], [MinGW][mingw] or [Cygwin][cgwn] under Windows.
|
||||
* [Clang][clang] under Windows, Linux or OS X.
|
||||
* [GCC][gcc] under Linux or OS X.
|
||||
* [Intel C++ compiler][intel] under Windows, Linux or OS X.
|
||||
* [Xcode][xcdt] application or Xcode Command Line Tools under OS X.
|
||||
|
||||
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.
|
||||
|
||||
To use an existing manually maintained prefix header instead of the automatically generated one,
|
||||
set the `COTIRE_CXX_PREFIX_HEADER_INIT` property before invoking cotire:
|
||||
|
||||
set_target_properties(MyExecutable PROPERTIES COTIRE_CXX_PREFIX_HEADER_INIT "stdafx.h")
|
||||
cotire(MyExecutable)
|
||||
|
||||
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, including linked library dependencies.
|
||||
|
||||
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][manual] for information on how to
|
||||
configure the cotire process (e.g., how to make the unity build use all available processor
|
||||
cores).
|
||||
|
||||
The directory `Patches` contains patch files to enable cotire for some popular open sources
|
||||
packages that use CMake as a build system.
|
||||
|
||||
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.
|
||||
|
||||
This [blog post][shrp] discusses speedup results obtained for real-world projects.
|
||||
|
||||
known issues
|
||||
------------
|
||||
|
||||
* 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.
|
||||
Multiple targets can share a generated prefix header, though (see the [cotire manual][manual]).
|
||||
* Cotire is not compatible with [Xoreax IncrediBuild][XGE].
|
||||
|
||||
[ccch]:https://ccache.samba.org/
|
||||
[ccrc]:https://cmake.org/Wiki/CMake_Cross_Compiling
|
||||
[cgwn]:https://www.cygwin.com/
|
||||
[clang]:https://clang.llvm.org/
|
||||
[cmk]:https://cmake.org/download/
|
||||
[gcc]:https://gcc.gnu.org/
|
||||
[manual]:https://github.com/sakra/cotire/blob/master/MANUAL.md
|
||||
[mingw]:http://www.mingw.org/
|
||||
[ninja]:https://ninja-build.org/
|
||||
[pch]:https://en.wikipedia.org/wiki/Precompiled_header
|
||||
[pfh]:https://en.wikipedia.org/wiki/Prefix_header
|
||||
[scu]:https://en.wikipedia.org/wiki/Single_Compilation_Unit
|
||||
[vslstd]:https://www.visualstudio.com/
|
||||
[xcdt]:https://developer.apple.com/xcode/
|
||||
[PCHH]:https://gcc.gnu.org/wiki/PCHHaters
|
||||
[EoUB]:http://altdevblog.com/2011/08/14/the-evils-of-unity-builds/
|
||||
[jom]:https://wiki.qt.io/Jom
|
||||
[intel]:https://software.intel.com/en-us/c-compilers
|
||||
[XGE]:https://www.incredibuild.com/
|
||||
[shrp]:https://unriskinsight.blogspot.co.at/2014/09/sharpen-your-tools.html
|
||||
22
deps/cotire/license
vendored
22
deps/cotire/license
vendored
@@ -1,22 +0,0 @@
|
||||
Copyright (c) 2012-2018 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.
|
||||
@@ -1,24 +1,9 @@
|
||||
if (MSVC)
|
||||
# Specify the maximum PreCompiled Header memory allocation limit
|
||||
# Fixes a compiler-problem when using PCH - the /Ym flag is adjusted by the compiler in MSVC2012,
|
||||
# hence we need to set an upper limit with /Zm to avoid discrepancies)
|
||||
# (And yes, this is a verified, unresolved bug with MSVC... *sigh*)
|
||||
#
|
||||
# Note: This workaround was verified to be required on MSVC 2017 as well
|
||||
set(COTIRE_PCH_MEMORY_SCALING_FACTOR 500)
|
||||
endif()
|
||||
|
||||
include(cotire)
|
||||
#
|
||||
# Copyright (C) 2016+ AzerothCore <www.azerothcore.org>, released under GNU AGPL v3 license: https://github.com/azerothcore/azerothcore-wotlk/blob/master/LICENSE-AGPL3
|
||||
#
|
||||
|
||||
function(ADD_CXX_PCH TARGET_NAME_LIST PCH_HEADER)
|
||||
# Use the header for every target
|
||||
foreach(TARGET_NAME ${TARGET_NAME_LIST})
|
||||
# Disable unity builds
|
||||
set_target_properties(${TARGET_NAME} PROPERTIES COTIRE_ADD_UNITY_BUILD OFF)
|
||||
|
||||
# Set the prefix header
|
||||
set_target_properties(${TARGET_NAME} PROPERTIES COTIRE_CXX_PREFIX_HEADER_INIT ${PCH_HEADER})
|
||||
target_precompile_headers(${TARGET_NAME} PRIVATE ${PCH_HEADER})
|
||||
endforeach()
|
||||
|
||||
cotire(${TARGET_NAME_LIST})
|
||||
endfunction(ADD_CXX_PCH)
|
||||
|
||||
Reference in New Issue
Block a user