cmake-3.0.0-win32-x86.zip

.. cmake-manual-description: CMake Buildsystem Reference cmake-buildsystem(7) ******************** .. only:: html or latex .. contents:: Introduction ============ A CMake-based buildsystem is organized as a set of high-level logical targets. Each target corresponds to an executable or library, or is a custom target containing custom commands. Dependencies between the targets are expressed in the buildsystem to determine the build order and the rules for regeneration in response to change. Binary Targets ============== Executables and libraries are defined using the :command:`add_library` and :command:`add_executable` commands. The resulting binary files have appropriate prefixes, suffixes and extensions for the platform targeted. Dependencies between binary targets are expressed using the :command:`target_link_libraries` command: .. code-block:: cmake add_library(archive archive.cpp zip.cpp lzma.cpp) add_executable(zipapp zipapp.cpp) target_link_libraries(zipapp archive) ``archive`` is defined as a static library -- an archive containing objects compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp`` is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is linked in. Binary Library Types -------------------- By default, the :command:`add_library` command defines a static library, unless a type is specified. A type may be specified when using the command: .. code-block:: cmake add_library(archive SHARED archive.cpp zip.cpp lzma.cpp) .. code-block:: cmake add_library(archive STATIC archive.cpp zip.cpp lzma.cpp) The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the behavior of :command:`add_library` to build shared libraries by default. In the context of the buildsystem definition as a whole, it is largely irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` -- the commands, dependency specifications and other APIs work similarly regardless of the library type. The ``MODULE`` library type is dissimilar in that it is generally not linked to -- it is not used in the right-hand-side of the :command:`target_link_libraries` command. It is a type which is loaded as a plugin using runtime techniques. .. code-block:: cmake add_library(archive MODULE 7z.cpp) The ``OBJECT`` library type is also not linked to. It defines a non-archival collection of object files resulting from compiling the given source files. The object files collection can be used as source inputs to other targets: .. code-block:: cmake add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp) add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) ``OBJECT`` libraries may only be used locally as sources in a buildsystem -- they may not be installed, exported, or used in the right hand side of :command:`target_link_libraries`. They also may not be used as the ``TARGET`` in a use of the :command:`add_custom_command(TARGET)` command signature. Commands such as :command:`add_custom_command`, which generates rules to be run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>` target as a ``COMMAND`` executable. The buildsystem rules will ensure that the executable is built before attempting to run the command. Build Specification and Usage Requirements ========================================== The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands specify the build specifications and the usage requirements of binary targets. The commands populate the :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The ``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants. The ``PUBLIC`` mode populates both variants of the repective target property. Each command may be invoked with multiple uses of each keyword: .. code-block:: cmake target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA INTERFACE USING_ARCHIVE_LIB ) Note that usage requirements are not designed as a way to make downstreams use particular :prop_tgt:`COMPILE_OPTIONS` or :prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of the properties must be **requirements**, not merely recommendations or convenience. Target Properties ----------------- The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target properties are used appropriately when compiling the source files of a binary target. Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the property value. Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or ``/D`` and added to the compile line in an unspecified order. The :prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile definition as a special convenience case for ``SHARED`` and ``MODULE`` library targets. Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added in the order of appearance in the property value. Several compile options have special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are *Usage Requirements* -- they specify content which consumers must use to correctly compile and link with the target they appear on. For any binary target, the contents of each ``INTERFACE_`` property on each target specified in a :command:`target_link_libraries` command is consumed: .. code-block:: cmake set(srcs archive.cpp zip.cpp) if (LZMA_FOUND) list(APPEND srcs lzma.cpp) endif() add_library(archive SHARED ${srcs}) if (LZMA_FOUND) # The archive library sources are compiled with -DBUILDING_WITH_LZMA target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA) endif() target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) add_executable(consumer) # Link consumer to archive and consume its usage requirements. The consumer # executable sources are compiled with -DUSING_ARCHIVE_LIB. target_link_libraries(consumer archive) Because it is common to require that the source directory and corresponding build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` can be enabled to add the corresponding directories to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of targets in multiple different directories convenient through use of the :command:`target_link_libraries` command. .. _`Target Usage Requirements`: Transitive Usage Requirements ----------------------------- The usage requirements of a target can transitively propagate to dependents. The :command:`target_link_libraries` command has ``PRIVATE``, ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation. .. code-block:: cmake add_library(archive archive.cpp) target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) add_library(serialization serialization.cpp) target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB) add_libra