diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/build_command.rst | 2 | ||||
| -rw-r--r-- | Help/command/install.rst | 136 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 60 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/cmake-build-multiply-targets.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MACOSX_BUNDLE.rst | 3 | ||||
| -rw-r--r-- | Help/variable/IOS.rst | 4 |
8 files changed, 160 insertions, 55 deletions
diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index b83edaf..6659005 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module. Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>] [-- -i] + <cmake> --build . [--config <config>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the diff --git a/Help/command/install.rst b/Help/command/install.rst index 4cef787..a4cee71 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,11 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ <target>... [...]) - install({`FILES`_ | `PROGRAMS`_} <file>... [DESTINATION <dir>] [...]) - install(`DIRECTORY`_ <dir>... [DESTINATION <dir>] [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... [...]) + install(`DIRECTORY`_ <dir>... [...]) install(`SCRIPT`_ <file> [...]) install(`CODE`_ <code> [...]) - install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) + install(`EXPORT`_ <export-name> [...]) Introduction ^^^^^^^^^^^^ @@ -173,11 +173,20 @@ installation properties apply to all target types. If only one is given then only targets of that type will be installed (which can be used to install just a DLL or just an import library.) -For some target types, the ``DESTINATION`` argument is optional. If no -``DESTINATION`` argument is specified for these target types, the destination -will default to either the appropriate variable from :module:`GNUInstallDirs` -(if it is defined) or a built-in default (if the variable is not defined.) These -defaults are outlined below: +For regular executables, static libraries and shared libraries, the +``DESTINATION`` argument is not required. For these target types, when +``DESTINATION`` is omitted, a default destination will be taken from the +appropriate variable from :module:`GNUInstallDirs`, or set to a built-in +default value if that variable is not defined. The same is true for the +public and private headers associated with the installed targets through the +:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. +A destination must always be provided for module libraries, Apple bundles and +frameworks. A destination can be omitted for interface and object libraries, +but they are handled differently (see the discussion of this topic toward the +end of this section). + +The following table shows the target types with their associated variables and +built-in defaults that apply when no destination is given: ================== =============================== ====================== Target Type GNUInstallDirs Variable Built-In Default @@ -189,12 +198,28 @@ defaults are outlined below: ``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` ================== =============================== ====================== -To make your package compliant with distribution filesystem layout policies, it -is not recommended that you specify a ``DESTINATION`` for a target unless it -must be installed in a nonstandard location. That way, package maintainers can -control the install destination by setting the appropriate cache variables. In -any case, it is recommended that you use the :module:`GNUInstallDirs` variables -in your ``DESTINATION`` arguments whenever possible. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows a static library +being installed to the default destination provided by +:module:`GNUInstallDirs`, but with its headers installed to a project-specific +subdirectory that follows the above recommendation: + +.. code-block:: cmake + + add_library(mylib STATIC ...) + set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) + include(GNUInstallDirs) + install(TARGETS mylib + PUBLIC_HEADER + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) In addition to the common options listed above, each target can accept the following additional arguments: @@ -219,11 +244,9 @@ the following additional arguments: install(TARGETS mylib LIBRARY - DESTINATION lib COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER - DESTINATION include COMPONENT Development ) @@ -321,7 +344,7 @@ targets from other directories are up-to-date. You can use to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. -The install destination given to the target install ``DESTINATION`` may +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -335,7 +358,8 @@ Installing Files .. code-block:: cmake - install(<FILES|PROGRAMS> files... [DESTINATION <dir> | TYPE <type>] + install(<FILES|PROGRAMS> files... + TYPE <type> | DESTINATION <dir> [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] @@ -359,12 +383,14 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use However, if any item begins in a generator expression it must evaluate to a full path. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files being +installed. A destination will then be set automatically by taking the +corresponding variable from :module:`GNUInstallDirs`, or by using a +built-in default if that variable is not defined. See the table below for +the supported file types and their corresponding variables and built-in +defaults. Projects can provide a ``DESTINATION`` argument instead of a +file type if they wish to explicitly define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -384,7 +410,9 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with @@ -392,15 +420,21 @@ a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows how to follow +this advice while installing headers to a project-specific subdirectory: -The install destination given to the files install ``DESTINATION`` may +.. code-block:: cmake + + include(GNUInstallDirs) + install(FILES mylib.h + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) + +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -412,7 +446,8 @@ Installing Directories .. code-block:: cmake - install(DIRECTORY dirs... [DESTINATION <dir> | TYPE <type>] + install(DIRECTORY dirs... + TYPE <type> | DESTINATION <dir> [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] @@ -483,12 +518,15 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the file permissions, the scripts will be given specific permissions, and any ``CVS`` directories will be excluded. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files within the +listed directories being installed. A destination will then be set +automatically by taking the corresponding variable from +:module:`GNUInstallDirs`, or by using a built-in default if that variable +is not defined. See the table below for the supported file types and their +corresponding variables and built-in defaults. Projects can provide a +``DESTINATION`` argument instead of a file type if they wish to explicitly +define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -508,24 +546,20 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. - Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. -The list of ``dirs...`` given to ``DIRECTORY`` and the install destination -given to the directory install ``DESTINATION`` may use "generator expressions" +The list of ``dirs...`` given to ``DIRECTORY`` and an install destination +given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index d214e4a..ba44b7f 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -556,6 +556,54 @@ command is sufficient: cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS +Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures +for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` +can be used to set an iOS/tvOS/watchOS deployment target. + +Next configuration will install fat 5 architectures iOS library +and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` +flags to the compiler: + +.. code-block:: console + + $ cmake -S. -B_builds -GXcode \ + -DCMAKE_SYSTEM_NAME=iOS \ + "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \ + -DCMAKE_INSTALL_PREFIX=`pwd`/_install \ + -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \ + -DCMAKE_IOS_INSTALL_COMBINED=YES + +Example: + +.. code-block:: cmake + + # CMakeLists.txt + cmake_minimum_required(VERSION 3.14) + project(foo) + add_library(foo foo.cpp) + install(TARGETS foo DESTINATION lib) + +Install: + +.. code-block:: console + + $ cmake --build _builds --config Release --target install + +Check library: + +.. code-block:: console + + $ lipo -info _install/lib/libfoo.a + Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 + +.. code-block:: console + + $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS + cmd LC_VERSION_MIN_IPHONEOS + cmdsize 16 + version 9.3 + Code Signing ^^^^^^^^^^^^ @@ -592,4 +640,14 @@ Please note that checks made during configuration were performed against the configure-time SDK and might not hold true for other SDKs. Commands like :command:`find_package`, :command:`find_library`, etc. store and use details only for the configured SDK/platform, so they can be problematic -if wanting to switch between device and simulator builds. +if wanting to switch between device and simulator builds. You can follow +the next rules to make device + simulator configuration work: + +- Use explicit ``-l`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-lz")`` + +- Use explicit ``-framework`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-framework CoreFoundation")`` + +- Use :command:`find_package` only for libraries installed with + :variable:`CMAKE_IOS_INSTALL_COMBINED` feature diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 83c88a5..7609597 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -259,6 +259,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/GHS-MULTI + /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index f3b81ec..e9a08b5 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -276,8 +276,8 @@ following options: The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, specifies a default parallel level when this option is not given. -``--target <tgt>`` - Build ``<tgt>`` instead of default targets. May only be specified once. +``--target <tgt>...`` + Build ``<tgt>`` instead of default targets. May be specified multiple times. ``--config <cfg>`` For multi-configuration tools, choose configuration ``<cfg>``. diff --git a/Help/release/dev/cmake-build-multiply-targets.rst b/Help/release/dev/cmake-build-multiply-targets.rst new file mode 100644 index 0000000..1275ca3 --- /dev/null +++ b/Help/release/dev/cmake-build-multiply-targets.rst @@ -0,0 +1,5 @@ +cmake-build-multiply-targets +---------------------------- + +* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support for + multiple targets, e.g. ``cmake --build . --target Library1 Library2``. diff --git a/Help/variable/CMAKE_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst index 0badaf0..43ddff5 100644 --- a/Help/variable/CMAKE_MACOSX_BUNDLE.rst +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -5,3 +5,6 @@ Default value for :prop_tgt:`MACOSX_BUNDLE` of targets. This variable is used to initialize the :prop_tgt:`MACOSX_BUNDLE` property on all the targets. See that target property for additional information. + +This variable is set to ``ON`` by default if :variable:`CMAKE_SYSTEM_NAME` +equals to :ref:`iOS, tvOS or watchOS <Cross Compiling for iOS, tvOS, or watchOS>`. diff --git a/Help/variable/IOS.rst b/Help/variable/IOS.rst new file mode 100644 index 0000000..e5cc3f6 --- /dev/null +++ b/Help/variable/IOS.rst @@ -0,0 +1,4 @@ +IOS +--- + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is ``iOS``. |