diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/install.rst | 136 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 22 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 60 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 17 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MACOSX_BUNDLE.rst | 3 | ||||
| -rw-r--r-- | Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst | 25 | ||||
| -rw-r--r-- | Help/variable/IOS.rst | 4 |
7 files changed, 181 insertions, 86 deletions
diff --git a/Help/command/install.rst b/Help/command/install.rst index a0e8c37..6910d6d 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 ^^^^^^^^^^^^ @@ -172,11 +172,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 @@ -188,12 +197,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: @@ -218,11 +243,9 @@ the following additional arguments: install(TARGETS mylib LIBRARY - DESTINATION lib COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER - DESTINATION include COMPONENT Development ) @@ -318,7 +341,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. @@ -330,7 +353,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>] @@ -354,12 +378,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 @@ -379,7 +405,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 @@ -387,15 +415,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. @@ -406,7 +440,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] @@ -477,12 +512,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 @@ -502,24 +540,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-properties.7.rst b/Help/manual/cmake-properties.7.rst index 4366c0d..ef86412 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -351,22 +351,22 @@ Properties on Targets /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_ENVIRONMENT + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_STACK /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER - /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP - /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE - /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES - /prop_tgt/XCODE_SCHEME_GUARD_MALLOC /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS - /prop_tgt/XCODE_SCHEME_MALLOC_STACK - /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE - /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS - /prop_tgt/XCODE_SCHEME_EXECUTABLE - /prop_tgt/XCODE_SCHEME_ARGUMENTS - /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCTEST .. _`Test Properties`: 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..6bb30cb 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -216,19 +216,19 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER - /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP - /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE - /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES - /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS - /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK - /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE - /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/PackageName_ROOT Variables that Describe the System @@ -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/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/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst index ed20bbe..7466784 100644 --- a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -1,15 +1,10 @@ CMAKE_XCODE_GENERATE_SCHEME --------------------------- -If enabled, the Xcode generator will generate schema files. Those are +If enabled, the Xcode generator will generate schema files. These are useful to invoke analyze, archive, build-for-testing and test actions from the command line. -.. note:: - - The Xcode Schema Generator is still experimental and subject to - change. - The following target properties overwrite the default of the corresponding settings on the "Diagnostic" tab for each schema file. Each of those is initialized by the respective ``CMAKE_`` variable @@ -17,23 +12,23 @@ at target creation time. - :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` - :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +- :prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +- :prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +- :prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +- :prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +- :prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +- :prop_tgt:`XCODE_SCHEME_MALLOC_STACK` - :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` - :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` - :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` - :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` -- :prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` -- :prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` -- :prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` -- :prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` -- :prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` - :prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` -- :prop_tgt:`XCODE_SCHEME_MALLOC_STACK` -- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` -- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` The following target properties will be applied on the "Info" and "Arguments" tab: -- :prop_tgt:`XCODE_SCHEME_EXECUTABLE` - :prop_tgt:`XCODE_SCHEME_ARGUMENTS` - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +- :prop_tgt:`XCODE_SCHEME_EXECUTABLE` 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``. |