Changes between Initial Version and Version 1 of CMakeBuildFeatures

Timestamp:

Jun 12, 2007, 5:33:04 AM (15 years ago)

Author:

Douglas Gregor

Comment:

Initial description of build features and variants

CMakeBuildFeatures

@@ +1 @@
+= Build Features in CMake =
+Different compilation and linking flags affect how source code and libraries are compiled. Boost's build system abstracts some of these properties into specific ''features'' of the build, which indicate (at a high level) what options are being used, e.g., multi-threaded, release-mode, shared libraries, etc. Each feature brings with it certain compilation options (which vary from one compiler to the next) that need to be used when building that variant. For example, on Unix systems, one often must link against the `pthread` library for multi-threaded programs and libraries, which requires the addition of the `-lpthread` flag to the link line. The ''features'' feature of the build system encapsulates this knowledge.
+
+A library built with a given set of features is called a library `variant`. For example, we could have a multi-threaded release variant of a shared library, which would be built with all of the options needed to support multi-threading, optimization, elimination of debugging symbols, and for building a shared library. Each variant of a library is given a unique name based on the features in that variant, so that one can readily identify the library, for example, `libboost_signals-gcc40-mt-d.so` is the multi-threaded, debug version of the shared library for Boost.Signals on a typical Linux system. The [http://www.boost.org/more/getting_started/windows.html#library-naming Boost Getting Started guide] describes the library naming conventions used for the variants. 
+
+This page describes each of the featues supported by Boost.Build, and the default variants that are built for each platform.
+
+== Features ==
+The CMake-based build system for Boost supports the following features.
+
+  STATIC::
+    The `STATIC` feature identifies static builds of libraries, i.e., a `.lib` (library) file on Microsoft Windows or a `.a` (archive) file on Unix systems.
+
+  SHARED::
+    The `SHARED` feature identifies shared builds of libraries, i.e., a `.dll` (dynamically linked library) file on Microsoft Windows or a `.so`(shared object) or `.dylib` (dynamic library) file on Unix systems. In some cases, `SHARED` variants actually refer to "modules", which are a special kind of shared library on some systems (e.g., Mac OS X).
+
+  DEBUG::
+    The `DEBUG` feature identifies builds of libraries that retain complete debugging information and prohibit optimization, making these builds far easier to use for debugging programs.
+
+  RELEASE::
+    The `RELEASE` feature identifies builds of libraries that use full optimization and eliminate extraneous information such as debug symbols, resulting in builds of libraries that are typically much smaller than (and execute faster than) their debug library counterparts.
+
+  SINGLE_THREADED::
+    The `SINGLE_THREADED` feature identifies builds of libraries that assume that the program using them is single-threaded. These libraries typically avoid costly atomic operations or locks, and make use of no multi-threaded features.
+
+  MULTI_THREADED::
+    The `MULTI_THREADED` feature identifies builds of libraries that assume that the program using them is multi-threaded. These libraries may introduce additional code (relative to their single-threaded variants) that improves the behavior of the library in a multi-threade context, often at the cost of single-thread performance.
+
+  STATIC_RUNTIME::
+    The `STATIC_RUNTIME` feature identifies builds that link against the C and C++ run-time libraries statically, which directly includes the code from those run-time libraries into the Boost library or executable.
+
+  DYNAMIC_RUNTIME::
+    The `DYNAMIC_RUNTIME` feature identifies builds that link against the dynamic C and C++ run-time libraries.
+
+== Compilation and Linker Options ==
+For each feature, the Boost build system defines three macros providing compilation flags, linking flags, and extra libraries to link against when using that feature. These flags are automatically added to the build commands for variants using that feature. The particular flags and libraries are described by the following global variables:
+
+  feature_COMPILE_FLAGS::
+    A string containing extra flags that will be added to the compile line, including macro definitions and compiler-specific flags needed to enable this particular feature.
+
+  feature_LINK_FLAGS:
+    A string containing extra flags that will be added to the beginning of the link line. Note that these flags should '''not''' contain extra libraries that one needs to link against. Those should go into `feature_LINK_LIBS`.
+
+  feature_LINK_LIBS:
+    A CMake list containing the names of additional libraries that will be linked into libraries and executables that require this feature. The elements in this list should name the library (e.g., `pthread`) rather than providing the link command itself (e.g., `-lpthread`), so that linking will be more portable.
+
+Each of these variables can be expanded for any feature, e.g., `MULTI_THREADED_LINK_LIBS` contains libraries that multi-threaded variants should link against.
+
+All of the flags provided for each feature are typically detected by the Boost CMake configuration module in [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/tools/build/CMake/BoostConfig.cmake tools/build/CMake/BoostConfig.cmake].
+
+== Default Variants ==
+By default, Boost's build system will build every permutation of libraries in the space (`STATIC` or  `SHARED) x (`DEBUG` or `RELEASE`) x (`SINGLE_THREADED` or `MULTI_THREADED`), resulting in 8 different copies of each library. On Windows, where the distinction between static and dynamic run-time libraries is very important, the default build also creates permutations with (`STATIC_RUNTIME` or `DYNAMIC_RUNTIME`). Certain non-sensical combinations of libraries will automatically be eliminated, e.g., it does not generally make sense to create a shared library that links against the static C and C++ run-time libraries. However, this still means that the default build creates between 8 and 12 different variants of each Boost library.
+
+Users who only need a few variants of each library can change which variants of Boost libraries are build by default using various configuration options. For each feature, CMake's configuration will contain an option `BUILD_feature`. When the feature is ON, the build system will produce variants with that feature. When the feature is OFF, the build system will suppress variants with that feature. For example, toggling `BUILD_DEBUG` to `OFF` will inhibit the creation of the debug variants, drastically improving overall build times.