Commit 3765a415 authored by Brad King's avatar Brad King
Browse files

Merge branch 'master' into doc-3_19_release-fixes

parents ff4d1d44 adc6a4c5
Pipeline #204516 waiting for manual action with stages
in 4 minutes and 58 seconds
......@@ -52,7 +52,7 @@ prep:doc-package:
- .cmake_doc_artifacts
- .run_only_for_package
.upload:source-package:
upload:source-package:
extends:
- .rsync_upload
- .run_only_for_package
......@@ -175,7 +175,7 @@ build:linux-x86_64-package:
needs:
- prep:doc-package
.upload:linux-x86_64-package:
upload:linux-x86_64-package:
extends:
- .rsync_upload
- .run_only_for_package
......@@ -250,7 +250,7 @@ build:macos-package:
needs:
- prep:doc-package
.upload:macos-package:
upload:macos-package:
extends:
- .rsync_upload
- .run_only_for_package
......
......@@ -19,6 +19,7 @@ set(CMake_TEST_FindGSL "ON" CACHE BOOL "")
set(CMake_TEST_FindGTest "ON" CACHE BOOL "")
set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "")
set(CMake_TEST_FindIconv "ON" CACHE BOOL "")
set(CMake_TEST_FindIntl "ON" CACHE BOOL "")
set(CMake_TEST_FindJPEG "ON" CACHE BOOL "")
set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "")
set(CMake_TEST_FindLAPACK "ON" CACHE BOOL "")
......
......@@ -19,6 +19,7 @@ set(CMake_TEST_FindGSL "ON" CACHE BOOL "")
set(CMake_TEST_FindGTest "ON" CACHE BOOL "")
set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "")
set(CMake_TEST_FindIconv "ON" CACHE BOOL "")
set(CMake_TEST_FindIntl "ON" CACHE BOOL "")
set(CMake_TEST_FindJPEG "ON" CACHE BOOL "")
set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "")
set(CMake_TEST_FindLAPACK "ON" CACHE BOOL "")
......
......@@ -52,7 +52,7 @@
image: "kitware/cmake:ci-fedora33-x86_64-2020-11-13"
variables:
GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci"
GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci/long file name for testing purposes"
#### Lint builds
......
......@@ -27,6 +27,8 @@
;; cmake-command-help Written by James Bigler
;;
(require 'rst)
(defcustom cmake-mode-cmake-executable "cmake"
"*The name of the cmake executable.
......@@ -258,7 +260,27 @@ optional argument topic will be appended to the argument list."
(save-selected-window
(select-window (display-buffer buffer 'not-this-window))
(cmake-mode)
(read-only-mode 1))
(read-only-mode 1)
(view-mode 1))
)
)
;;;###autoload
(defun cmake-command-run-help (type &optional topic buffer)
"`cmake-command-run' but rendered in `rst-mode'."
(interactive "s")
(let* ((bufname (if buffer buffer (concat "*CMake" type (if topic "-") topic "*")))
(buffer (if (get-buffer bufname) (get-buffer bufname) (generate-new-buffer bufname)))
(command (concat cmake-mode-cmake-executable " " type " " topic))
;; Turn of resizing of mini-windows for shell-command.
(resize-mini-windows nil)
)
(shell-command command buffer)
(save-selected-window
(select-window (display-buffer buffer 'not-this-window))
(rst-mode)
(read-only-mode 1)
(view-mode 1))
)
)
......@@ -266,7 +288,7 @@ optional argument topic will be appended to the argument list."
(defun cmake-help-list-commands ()
"Prints out a list of the cmake commands."
(interactive)
(cmake-command-run "--help-command-list")
(cmake-command-run-help "--help-command-list")
)
(defvar cmake-commands '() "List of available topics for --help-command.")
......@@ -292,7 +314,7 @@ and store the result as a list in LISTVAR."
(if (not (symbol-value listvar))
(let ((temp-buffer-name "*CMake Temporary*"))
(save-window-excursion
(cmake-command-run (concat "--help-" listname "-list") nil temp-buffer-name)
(cmake-command-run-help (concat "--help-" listname "-list") nil temp-buffer-name)
(with-current-buffer temp-buffer-name
; FIXME: Ignore first line if it is "cmake version ..." from CMake < 3.0.
(set listvar (split-string (buffer-substring-no-properties (point-min) (point-max)) "\n" t)))))
......@@ -326,25 +348,25 @@ and store the result as a list in LISTVAR."
(defun cmake-help-command ()
"Prints out the help message for the command the cursor is on."
(interactive)
(cmake-command-run "--help-command" (cmake-help-type "command") "*CMake Help*"))
(cmake-command-run-help "--help-command" (cmake-help-type "command") "*CMake Help*"))
;;;###autoload
(defun cmake-help-module ()
"Prints out the help message for the module the cursor is on."
(interactive)
(cmake-command-run "--help-module" (cmake-help-type "module") "*CMake Help*"))
(cmake-command-run-help "--help-module" (cmake-help-type "module") "*CMake Help*"))
;;;###autoload
(defun cmake-help-variable ()
"Prints out the help message for the variable the cursor is on."
(interactive)
(cmake-command-run "--help-variable" (cmake-help-type "variable") "*CMake Help*"))
(cmake-command-run-help "--help-variable" (cmake-help-type "variable") "*CMake Help*"))
;;;###autoload
(defun cmake-help-property ()
"Prints out the help message for the property the cursor is on."
(interactive)
(cmake-command-run "--help-property" (cmake-help-type "property") "*CMake Help*"))
(cmake-command-run-help "--help-property" (cmake-help-type "property") "*CMake Help*"))
;;;###autoload
(defun cmake-help ()
......@@ -367,13 +389,13 @@ and store the result as a list in LISTVAR."
(if (string= input "")
(error "No argument given")
(if (member input command-list)
(cmake-command-run "--help-command" input "*CMake Help*")
(cmake-command-run-help "--help-command" input "*CMake Help*")
(if (member input variable-list)
(cmake-command-run "--help-variable" input "*CMake Help*")
(cmake-command-run-help "--help-variable" input "*CMake Help*")
(if (member input module-list)
(cmake-command-run "--help-module" input "*CMake Help*")
(cmake-command-run-help "--help-module" input "*CMake Help*")
(if (member input property-list)
(cmake-command-run "--help-property" input "*CMake Help*")
(cmake-command-run-help "--help-property" input "*CMake Help*")
(error "Not a know help topic.") ; this really should not happen
))))))
)
......
......@@ -3,6 +3,8 @@
use strict;
use warnings;
use POSIX qw(strftime);
use JSON;
use File::Basename;
#my $cmake = "/home/pboettch/devel/upstream/cmake/build/bin/cmake";
my $cmake = "cmake";
......@@ -96,6 +98,28 @@ close(CMAKE);
# transform all properties in a hash
my %properties = map { $_ => 1 } @properties;
# read in manually written files
my $modules_dir = dirname(__FILE__) . "/modules";
opendir(DIR, $modules_dir) || die "can't opendir $modules_dir: $!";
my @json_files = grep { /\.json$/ && -f "$modules_dir/$_" } readdir(DIR);
closedir DIR;
foreach my $file (@json_files) {
local $/; # Enable 'slurp' mode
open my $fh, "<", $modules_dir."/".$file;
my $json = <$fh>;
close $fh;
my $mod = decode_json($json);
foreach my $var (@{$mod->{variables}}) {
$variables{$var} = 1;
}
while (my ($cmd, $keywords) = each %{$mod->{commands}}) {
$keywords{$cmd} = [ sort @{$keywords} ];
}
}
# version
open(CMAKE, "$cmake --version|");
my $version = 'unknown';
......
This diff is collapsed.
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.1...3.15 FATAL_ERROR)
cmake_minimum_required(VERSION 3.1...3.18 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
project(CMake)
......
When a device link step is involved, which is controlled by
:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
the raw options will be delivered to the host and device link steps (wrapped in
``-Xcompiler`` or equivalent for device link). Options wrapped with
``$<DEVICE_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the host link step.
.. versionadded:: 3.18
When a device link step is involved, which is controlled by
:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
the raw options will be delivered to the host and device link steps (wrapped in
``-Xcompiler`` or equivalent for device link). Options wrapped with
``$<DEVICE_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the host link step.
......@@ -33,9 +33,6 @@ of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be ``<VAR>-NOTFOUND``.
The ``REQUIRED`` option stops processing with an error message if nothing
is found, otherwise the search will be attempted again the
next time |FIND_XXX| is invoked with the same variable.
Options include:
......@@ -60,7 +57,11 @@ Options include:
Specify the documentation string for the ``<VAR>`` cache entry.
``REQUIRED``
Stop processing with an error message if nothing is found.
.. versionadded:: 3.18
Stop processing with an error message if nothing is found, otherwise
the search will be attempted again the next time |FIND_XXX| is invoked
with the same variable.
If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
......@@ -84,20 +85,21 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
1. If called from within a find module or any other script loaded by a call to
:command:`find_package(<PackageName>)`, search prefixes unique to the
current package being found. Specifically, look in the
:variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable.
The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package. In other words, the search order would be
``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
See policy :policy:`CMP0074`.
1. .. versionadded:: 3.12
If called from within a find module or any other script loaded by a call to
:command:`find_package(<PackageName>)`, search prefixes unique to the
current package being found. Specifically, look in the
:variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable.
The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package. In other words, the search order would be
``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
See policy :policy:`CMP0074`.
* |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
......@@ -151,6 +153,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
or in the short-hand version of the command.
These are typically hard-coded guesses.
.. versionadded:: 3.16
Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
various search locations.
.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
......
The final set of compile or link options used for a target is constructed by
accumulating options from the current target and the usage requirements of
its dependencies. The set of options is de-duplicated to avoid repetition.
While beneficial for individual options, the de-duplication step can break
up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may
specify a group of options using shell-like quoting along with a ``SHELL:``
prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string
is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode.
For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``.
.. versionadded:: 3.12
While beneficial for individual options, the de-duplication step can break
up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may
specify a group of options using shell-like quoting along with a ``SHELL:``
prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string
is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode.
For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``.
......@@ -51,6 +51,8 @@ The options are:
used in the future.
``BYPRODUCTS``
.. versionadded:: 3.2
Specify the files the command is expected to produce but whose
modification time may or may not be newer than the dependencies.
If a byproduct name is a relative path it will be interpreted
......@@ -88,10 +90,11 @@ The options are:
* The target is not being cross-compiled (i.e. the
:variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
* The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
* .. versionadded:: 3.6
The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
If neither of the above conditions are met, it is assumed that the
command name is a program to be found on the ``PATH`` at build time.
......@@ -153,18 +156,23 @@ The options are:
If any dependency is an ``OUTPUT`` of another custom command in the same
directory (``CMakeLists.txt`` file), CMake automatically brings the other
custom command into the target in which this command is built.
A target-level dependency is added if any dependency is listed as
``BYPRODUCTS`` of a target or any of its build events in the same
directory to ensure the byproducts will be available.
.. versionadded:: 3.16
A target-level dependency is added if any dependency is listed as
``BYPRODUCTS`` of a target or any of its build events in the same
directory to ensure the byproducts will be available.
If ``DEPENDS`` is not specified, the command will run whenever
the ``OUTPUT`` is missing; if the command does not actually
create the ``OUTPUT``, the rule will always run.
Arguments to ``DEPENDS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. versionadded:: 3.1
Arguments to ``DEPENDS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.8
Lists in ``COMMAND`` arguments will be expanded, including those
created with
:manual:`generator expressions <cmake-generator-expressions(7)>`,
......@@ -184,6 +192,8 @@ The options are:
only for Makefile generators and will be ignored by other generators.
``JOB_POOL``
.. versionadded:: 3.15
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
......@@ -211,6 +221,8 @@ The options are:
source file property.
``USES_TERMINAL``
.. versionadded:: 3.2
The command will be given direct access to the terminal if possible.
With the :generator:`Ninja` generator, this places the command in
the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
......@@ -230,15 +242,23 @@ The options are:
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPFILE``
.. versionadded:: 3.7
Specify a ``.d`` depfile for the :generator:`Ninja` generator.
A ``.d`` file holds dependencies usually emitted by the custom
command itself.
Using ``DEPFILE`` with other generators than Ninja is an error.
If the ``DEPFILE`` argument is relative, it should be relative to
:variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the
``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`
(see policy :policy:`CMP0116`.)
Build Events
^^^^^^^^^^^^
......
......@@ -32,6 +32,8 @@ The options are:
called ``ALL``).
``BYPRODUCTS``
.. versionadded:: 3.2
Specify the files the command is expected to produce but whose
modification time may or may not be updated on subsequent builds.
If a byproduct name is a relative path it will be interpreted
......@@ -67,10 +69,11 @@ The options are:
* The target is not being cross-compiled (i.e. the
:variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
* The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
* .. versionadded:: 3.6
The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
If neither of the above conditions are met, it is assumed that the
command name is a program to be found on the ``PATH`` at build time.
......@@ -103,14 +106,18 @@ The options are:
:command:`add_custom_command` command calls in the same directory
(``CMakeLists.txt`` file). They will be brought up to date when
the target is built.
A target-level dependency is added if any dependency is a byproduct
of a target or any of its build events in the same directory to ensure
the byproducts will be available before this target is built.
.. versionchanged:: 3.16
A target-level dependency is added if any dependency is a byproduct
of a target or any of its build events in the same directory to ensure
the byproducts will be available before this target is built.
Use the :command:`add_dependencies` command to add dependencies
on other targets.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.8
Lists in ``COMMAND`` arguments will be expanded, including those
created with
:manual:`generator expressions <cmake-generator-expressions(7)>`,
......@@ -119,6 +126,8 @@ The options are:
to be properly expanded.
``JOB_POOL``
.. versionadded:: 3.15
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
......@@ -141,6 +150,8 @@ The options are:
tool-specific special characters.
``USES_TERMINAL``
.. versionadded:: 3.2
The command will be given direct access to the terminal if possible.
With the :generator:`Ninja` generator, this places the command in
the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
......@@ -150,5 +161,6 @@ The options are:
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
......@@ -17,6 +17,9 @@ Dependencies added to an :ref:`imported target <Imported Targets>`
or an :ref:`interface library <Interface Libraries>` are followed
transitively in its place since the target itself does not build.
.. versionadded:: 3.3
Allow adding dependencies to interface libraries.
See the ``DEPENDS`` option of :command:`add_custom_target` and
:command:`add_custom_command` commands for adding file-level
dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS`
......
......@@ -17,13 +17,21 @@ Normal Executables
[source1] [source2 ...])
Adds an executable target called ``<name>`` to be built from the source
files listed in the command invocation. (The source files can be omitted
here if they are added later using :command:`target_sources`.) The
files listed in the command invocation. The
``<name>`` corresponds to the logical target name and must be globally
unique within a project. The actual file name of the executable built is
constructed based on conventions of the native platform (such as
``<name>.exe`` or just ``<name>``).
.. versionadded:: 3.1
Source arguments to ``add_executable`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. versionadded:: 3.11
The source files can be omitted if they are added later using
:command:`target_sources`.
By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked. See documentation of the
......@@ -43,10 +51,8 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
Source arguments to ``add_executable`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
......@@ -85,10 +91,14 @@ be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be an ``ALIAS``.
An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
has scope in the directory in which the alias is created and below.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
.. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
.. versionadded:: 3.18
An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
scoped to the directory in which it is created and subdirectories.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets. They can also be
......
......@@ -17,13 +17,21 @@ Normal Libraries
[<source>...])
Adds a library target called ``<name>`` to be built from the source files
listed in the command invocation. (The source files can be omitted here
if they are added later using :command:`target_sources`.) The ``<name>``
listed in the command invocation. The ``<name>``
corresponds to the logical target name and must be globally unique within
a project. The actual file name of the library built is constructed based
on conventions of the native platform (such as ``lib<name>.a`` or
``<name>.lib``).
.. versionadded:: 3.1
Source arguments to ``add_library`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. versionadded:: 3.11
The source files can be omitted if they are added later using
:command:`target_sources`.
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
library to be created. ``STATIC`` libraries are archives of object files
for use when linking other targets. ``SHARED`` libraries are linked
......@@ -34,9 +42,13 @@ type is ``STATIC`` or ``SHARED`` based on whether the current value of the
variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an macOS Framework.
.. versionadded:: 3.8
A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create a static Framework.
If a library does not export any symbols, it must not be declared as a
``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI
DLL that exports no unmanaged symbols would need to be a ``MODULE`` library.
......@@ -55,10 +67,8 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
Source arguments to ``add_library`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
......@@ -93,6 +103,9 @@ systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
``$<TARGET_OBJECTS:objlib>``.
.. versionadded:: 3.12
Object libraries can be linked to with :command:`target_link_libraries`.
Interface Libraries
^^^^^^^^^^^^^^^^^^^
......@@ -121,23 +134,28 @@ like any other target.
An interface library created with the above signature has no source files
itself and is not included as a target in the generated buildsystem.
Since CMake 3.19, an interface library target may be created with
source files:
.. versionadded:: 3.15
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
properties can be installed using the :command:`install(TARGETS)` command.
.. code-block:: cmake
.. versionadded:: 3.19
An interface library target may be created with source files:
.. code-block:: cmake
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
Source files may be listed directly in the ``add_library`` call or added