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