diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/add_compile_definitions.rst | 23 | ||||
| -rw-r--r-- | Help/command/add_compile_options.rst | 2 | ||||
| -rw-r--r-- | Help/command/add_definitions.rst | 12 | ||||
| -rw-r--r-- | Help/command/install.rst | 23 | ||||
| -rw-r--r-- | Help/command/target_compile_options.rst | 4 | ||||
| -rw-r--r-- | Help/envvar/DESTDIR.rst | 19 | ||||
| -rw-r--r-- | Help/index.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/prop_dir/COMPILE_DEFINITIONS.rst | 2 | ||||
| -rw-r--r-- | Help/release/dev/cmake-install-doc.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/command-add_compile_definitions.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_INSTALL_PREFIX.rst | 16 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst | 15 |
15 files changed, 106 insertions, 30 deletions
diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst new file mode 100644 index 0000000..37f6650 --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,23 @@ +add_compile_definitions +----------------------- + +Adds preprocessor definitions to the compilation of source files. + +:: + + add_compile_definitions(<definition> ...) + +Adds preprocessor definitions to the compiler command line for targets in the +current directory and below that are added after this command is invoked. +See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>` and +:prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties. + +Definitions are specified using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will automatically +escape the value correctly for the native build system (note that CMake +language syntax may require escapes to specify some values). + +Arguments to ``add_compile_definitions`` 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. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 44924e6..c445608 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,7 +14,7 @@ See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and This command can be used to add any options, but alternative commands exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_definitions`) or include directories +and :command:`add_compile_definitions`) or include directories (:command:`target_include_directories` and :command:`include_directories`). Arguments to ``add_compile_options`` may use "generator expressions" with diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index a04faf5..1da15a6 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -10,8 +10,16 @@ Adds -D define flags to the compilation of source files. Adds definitions to the compiler command line for targets in the current directory and below (whether added before or after this command is invoked). This command can be used to add any flags, but it is intended to add -preprocessor definitions (see the :command:`add_compile_options` command -to add other flags). +preprocessor definitions. + +.. note:: + + This command has been superseded by alternatives: + + * Use :command:`add_compile_definitions` to add preprocessor definitions. + * Use :command:`include_directories` to add include directories. + * Use :command:`add_compile_options` to add other options. + Flags beginning in -D or /D that look like preprocessor definitions are automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory property for the current directory. Definitions with non-trivial values diff --git a/Help/command/install.rst b/Help/command/install.rst index e9c185c..d3818d6 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -400,3 +400,26 @@ executable from the installation tree using the imported target name those generated by :command:`install_targets`, :command:`install_files`, and :command:`install_programs` commands is not defined. + +Generated Installation Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``install()`` command generates a file, ``cmake_install.cmake``, inside +the build directory, which is used internally by the generated install target +and by CPack. You can also invoke this script manually with ``cmake -P``. This +script accepts several variables: + +``COMPONENT`` + Set this variable to install only a single CPack component as opposed to all + of them. For example, if you only want to install the ``Development`` + component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``. + +``BUILD_TYPE`` + Set this variable to change the build type if you are using a multi-config + generator. For example, to install with the ``Debug`` configuration, run + ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``. + +``DESTDIR`` + This is an environment variable rather than a CMake variable. It allows you + to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for + details. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index b7b4dc1..194d008 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -19,8 +19,8 @@ instead of being appended. This command can be used to add any options, but alternative commands exist to add preprocessor definitions -(:command:`target_compile_definitions` and :command:`add_definitions`) or -include directories (:command:`target_include_directories` and +(:command:`target_compile_definitions` and :command:`add_compile_definitions`) +or include directories (:command:`target_include_directories` and :command:`include_directories`). See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and :prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst new file mode 100644 index 0000000..87f1115 --- /dev/null +++ b/Help/envvar/DESTDIR.rst @@ -0,0 +1,19 @@ +DESTDIR +------- + +On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the +whole installation. ``DESTDIR`` means DESTination DIRectory. It is +commonly used by makefile users in order to install software at +non-default location. It is usually invoked like this: + +:: + + make DESTDIR=/home/john install + +which will install the concerned software using the installation +prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which +finally gives ``/home/john/usr/local``. + +WARNING: ``DESTDIR`` may not be used on Windows because installation +prefix usually contains a drive letter like in ``C:/Program Files`` +which cannot be prepended with some other prefix. diff --git a/Help/index.rst b/Help/index.rst index 3dccdda..fa5273c 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -29,18 +29,18 @@ Reference Manuals /manual/cmake-commands.7 /manual/cmake-compile-features.7 /manual/cmake-developer.7 + /manual/cmake-env-variables.7 /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 /manual/cmake-language.7 - /manual/cmake-server.7 /manual/cmake-modules.7 /manual/cmake-packages.7 /manual/cmake-policies.7 /manual/cmake-properties.7 /manual/cmake-qt.7 + /manual/cmake-server.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 - /manual/cmake-env-variables.7 .. only:: html or text diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 50c4087..49375e9 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -821,7 +821,7 @@ Directory-Scoped Commands The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands have an effect on only one -target at a time. The commands :command:`add_definitions`, +target at a time. The commands :command:`add_compile_definitions`, :command:`add_compile_options` and :command:`include_directories` have a similar function, but operate at directory scope instead of target scope for convenience. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index f8bfb32..408a3a0 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -70,6 +70,7 @@ These commands are available only in CMake projects. .. toctree:: :maxdepth: 1 + /command/add_compile_definitions /command/add_compile_options /command/add_custom_command /command/add_custom_target diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index fed129e..2d8869f 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -16,6 +16,7 @@ Environment Variables that Control the Build /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst index 85adcb5..18f4567 100644 --- a/Help/prop_dir/COMPILE_DEFINITIONS.rst +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -4,7 +4,7 @@ COMPILE_DEFINITIONS Preprocessor definitions for compiling a directory's sources. This property specifies the list of options given so far to the -:command:`add_definitions` command. +:command:`add_compile_definitions` (or :command:`add_definitions`) command. The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. diff --git a/Help/release/dev/cmake-install-doc.rst b/Help/release/dev/cmake-install-doc.rst new file mode 100644 index 0000000..028aa43 --- /dev/null +++ b/Help/release/dev/cmake-install-doc.rst @@ -0,0 +1,7 @@ +cmake-install-doc +----------------- + +* The existence and functionality of the file + ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the + :command:`install` documentation so that external packaging software can take + advantage of CPack-style component installs. diff --git a/Help/release/dev/command-add_compile_definitions.rst b/Help/release/dev/command-add_compile_definitions.rst new file mode 100644 index 0000000..504481f --- /dev/null +++ b/Help/release/dev/command-add_compile_definitions.rst @@ -0,0 +1,5 @@ +command-add_compile_definitions +------------------------------- + +* The :command:`add_compile_definitions` command was added to set preprocessor + definitions at directory level. This supersedes :command:`add_definitions`. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 7bd87d6..02ba645 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -10,21 +10,7 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a project might choose its own default. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the -whole installation. ``DESTDIR`` means DESTination DIRectory. It is -commonly used by makefile users in order to install software at -non-default location. It is usually invoked like this: - -:: - - make DESTDIR=/home/john install - -which will install the concerned software using the installation -prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which -finally gives ``/home/john/usr/local``. - -WARNING: ``DESTDIR`` may not be used on Windows because installation -prefix usually contains a drive letter like in ``C:/Program Files`` -which cannot be prepended with some other prefix. +whole installation. See :envvar:`DESTDIR` for more information. The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` so that :command:`find_package`, :command:`find_program`, diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index a0bd830..e9e04be 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -9,9 +9,12 @@ These paths are implicit linker search directories for the compiler's language. CMake automatically detects these directories for each language and reports the results in this variable. -When a library in one of these directories is given by full path to -:command:`target_link_libraries` CMake will generate the ``-l<name>`` form on -link lines to ensure the linker searches its implicit directories for the -library. Note that some toolchains read implicit directories from an -environment variable such as ``LIBRARY_PATH`` so keep its value consistent -when operating in a given build tree. +Some toolchains read implicit directories from an environment variable such as +``LIBRARY_PATH``. If using such an environment variable, keep its value +consistent when operating in a given build tree because CMake saves the value +detected when first creating a build tree. + +If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one +of these directories is given by full path to :command:`target_link_libraries` +CMake will generate the ``-l<name>`` form on link lines for historical +purposes. |