From 5d74c870d907eed9afc9c544e7e6786fd1ea53c8 Mon Sep 17 00:00:00 2001 From: Bartosz Kosiorek Date: Wed, 11 Nov 2015 05:37:15 +0100 Subject: Help: Update documentation to reflect support for iOS Many of our interfaces documented for OS X also work for iOS. --- Help/manual/cmake-buildsystem.7.rst | 9 ++++--- Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst | 34 +++++++++++++++------------ Help/prop_tgt/BUNDLE.rst | 6 ++--- Help/prop_tgt/BUNDLE_EXTENSION.rst | 4 ++-- Help/prop_tgt/ENABLE_EXPORTS.rst | 4 ++-- Help/prop_tgt/FRAMEWORK.rst | 28 ++++++++++++++++++---- Help/prop_tgt/FRAMEWORK_VERSION.rst | 3 +++ Help/prop_tgt/MACOSX_BUNDLE.rst | 16 ++++++------- Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst | 4 ++-- Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst | 4 ++-- Help/prop_tgt/MACOSX_RPATH.rst | 6 ++--- Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst | 2 +- Help/prop_tgt/PRIVATE_HEADER.rst | 10 ++++---- Help/prop_tgt/PUBLIC_HEADER.rst | 12 +++++----- Help/prop_tgt/RESOURCE.rst | 12 +++++----- Help/variable/APPLE.rst | 4 ++-- Help/variable/CMAKE_ENABLE_EXPORTS.rst | 8 +++---- Help/variable/CMAKE_HOST_SYSTEM_NAME.rst | 2 +- Help/variable/CMAKE_INSTALL_NAME_DIR.rst | 2 +- Help/variable/CMAKE_MACOSX_RPATH.rst | 2 +- Help/variable/CMAKE_OSX_ARCHITECTURES.rst | 2 +- 21 files changed, 102 insertions(+), 72 deletions(-) diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index bc633e6..4a04f31 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -95,15 +95,18 @@ Apple Frameworks """""""""""""""" A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` -target property to create an OS X Framework: +target property to create an OS X or iOS Framework Bundle. +The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key +and it uniquely identifies the bundle. .. code-block:: cmake add_library(MyFramework SHARED MyFramework.cpp) set_target_properties(MyFramework PROPERTIES - FRAMEWORK 1 + FRAMEWORK TRUE FRAMEWORK_VERSION A - ) + MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework + ) .. _`Object Libraries`: diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst index 27f2929..69cdcb7 100644 --- a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -1,19 +1,23 @@ MACOSX_PACKAGE_LOCATION ----------------------- -Place a source file inside a Mac OS X bundle, CFBundle, or framework. +Place a source file inside a Application Bundle +(:prop_tgt:`MACOSX_BUNDLE`), Core Foundation Bundle (:prop_tgt:`BUNDLE`), +or Framework Bundle (:prop_tgt:`FRAMEWORK`). It is applicable for OS X +and iOS. -Executable targets with the MACOSX_BUNDLE property set are built as -Mac OS X application bundles on Apple platforms. Shared library -targets with the FRAMEWORK property set are built as Mac OS X -frameworks on Apple platforms. Module library targets with the BUNDLE -property set are built as Mac OS X CFBundle bundles on Apple -platforms. Source files listed in the target with this property set -will be copied to a directory inside the bundle or framework content -folder specified by the property value. For bundles the content -folder is ".app/Contents". For frameworks the content folder is -".framework/Versions/". For cfbundles the content -folder is ".bundle/Contents" (unless the extension is changed). -See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target properties -for specifying files meant for Headers, PrivateHeaders, or Resources -directories. +Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are +built as OS X or iOS application bundles on Apple platforms. Shared +library targets with the :prop_tgt:`FRAMEWORK` property set are built as +OS X or iOS frameworks on Apple platforms. Module library targets with +the :prop_tgt:`BUNDLE` property set are built as OS X ``CFBundle`` bundles +on Apple platforms. Source files listed in the target with this property +set will be copied to a directory inside the bundle or framework content +folder specified by the property value. For OS X Application Bundles the +content folder is ``.app/Contents``. For OS X Frameworks the +content folder is ``.framework/Versions/``. For OS X +CFBundles the content folder is ``.bundle/Contents`` (unless the +extension is changed). See the :prop_tgt:`PUBLIC_HEADER`, +:prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for +specifying files meant for ``Headers``, ``PrivateHeaders``, or +``Resources`` directories. diff --git a/Help/prop_tgt/BUNDLE.rst b/Help/prop_tgt/BUNDLE.rst index 166659f..075f017 100644 --- a/Help/prop_tgt/BUNDLE.rst +++ b/Help/prop_tgt/BUNDLE.rst @@ -1,9 +1,9 @@ BUNDLE ------ -This target is a CFBundle on the Mac. +This target is a ``CFBundle`` on the OS X. If a module library target has this property set to true it will be -built as a CFBundle when built on the mac. It will have the directory -structure required for a CFBundle and will be suitable to be used for +built as a ``CFBundle`` when built on the mac. It will have the directory +structure required for a ``CFBundle`` and will be suitable to be used for creating Browser Plugins or other application resources. diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst index 94ac935..ea265b3 100644 --- a/Help/prop_tgt/BUNDLE_EXTENSION.rst +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -1,7 +1,7 @@ BUNDLE_EXTENSION ---------------- -The file extension used to name a BUNDLE target on the Mac. +The file extension used to name a :prop_tgt:`BUNDLE` target on the OS X and iOS. -The default value is "bundle" - you can also use "plugin" or whatever +The default value is ``bundle`` - you can also use ``plugin`` or whatever file extension is required by the host app for your bundle. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index dfd4af7..9e22309 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -12,9 +12,9 @@ dependency on the executable is created for targets that link to it. For DLL platforms an import library will be created for the exported symbols and then used for linking. All Windows-based systems including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as Mac OS X, the +require all symbols to be resolved at link time, such as OS X, the module will "link" to the executable using a flag like -"-bundle_loader". For other non-DLL platforms the link rule is simply +``-bundle_loader``. For other non-DLL platforms the link rule is simply ignored since the dynamic loader will automatically bind symbols when the module is loaded. diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index dcb6d3b..6c212c3 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -1,11 +1,31 @@ FRAMEWORK --------- -This target is a framework on the Mac. +Build ``SHARED`` library as Framework Bundle on the OS X and iOS. -If a shared library target has this property set to true it will be -built as a framework when built on the mac. It will have the +If a ``SHARED`` library target has this property set to ``TRUE`` it will be +built as a framework when built on the OS X and iOS. It will have the directory structure required for a framework and will be suitable to be used with the ``-framework`` option -See also the :prop_tgt:`FRAMEWORK_VERSION` target property. +To customize ``Info.plist`` file in the framework, use +:prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property. + +For OS X see also the :prop_tgt:`FRAMEWORK_VERSION` target property. + +Example of creation ``dynamicFramework``: + +.. code-block:: cmake + + add_library(dynamicFramework SHARED + dynamicFramework.c + dynamicFramework.h + ) + set_target_properties(dynamicFramework PROPERTIES + FRAMEWORK TRUE + FRAMEWORK_VERSION C + MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework + MACOSX_FRAMEWORK_INFO_PLIST Info.plist + PUBLIC_HEADER dynamicFramework.h + XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer" + ) diff --git a/Help/prop_tgt/FRAMEWORK_VERSION.rst b/Help/prop_tgt/FRAMEWORK_VERSION.rst index bf650a7..6aa3026 100644 --- a/Help/prop_tgt/FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/FRAMEWORK_VERSION.rst @@ -3,3 +3,6 @@ FRAMEWORK_VERSION Version of a framework created using the :prop_tgt:`FRAMEWORK` target property (e.g. ``A``). + +This property only affects OS X, as iOS doesn't have versioned +directory structure. diff --git a/Help/prop_tgt/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst index ff21e61..8d7d914 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -1,12 +1,12 @@ MACOSX_BUNDLE ------------- -Build an executable as an application bundle on Mac OS X. +Build an executable as an Application Bundle on OS X or iOS. -When this property is set to true the executable when built on Mac OS -X will be created as an application bundle. This makes it a GUI -executable that can be launched from the Finder. See the -MACOSX_BUNDLE_INFO_PLIST target property for information about -creation of the Info.plist file for the application bundle. This -property is initialized by the value of the variable -CMAKE_MACOSX_BUNDLE if it is set when a target is created. +When this property is set to true the executable when built on OS X +or iOS will be created as an application bundle. This makes it +a GUI executable that can be launched from the Finder. See the +:prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property for information about +creation of the ``Info.plist`` file for the application bundle. +This property is initialized by the value of the variable +:variable:`CMAKE_MACOSX_BUNDLE` if it is set when a target is created. diff --git a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst index 07a933f..8515acc 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_BUNDLE_INFO_PLIST ------------------------ -Specify a custom ``Info.plist`` template for a Mac OS X App Bundle. +Specify a custom ``Info.plist`` template for a OS X and iOS Application Bundle. An executable target with :prop_tgt:`MACOSX_BUNDLE` enabled will be built as an -application bundle on Mac OS X. By default its ``Info.plist`` file is created +application bundle on OS X. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXBundleInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst index 548c3ac..58f31d4 100644 --- a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_FRAMEWORK_INFO_PLIST --------------------------- -Specify a custom ``Info.plist`` template for a Mac OS X Framework. +Specify a custom ``Info.plist`` template for a OS X and iOS Framework. A library target with :prop_tgt:`FRAMEWORK` enabled will be built as a -framework on Mac OS X. By default its ``Info.plist`` file is created by +framework on OS X. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXFrameworkInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_RPATH.rst b/Help/prop_tgt/MACOSX_RPATH.rst index 1c503d1..41bb8cc 100644 --- a/Help/prop_tgt/MACOSX_RPATH.rst +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -1,7 +1,7 @@ MACOSX_RPATH ------------ -Whether this target on Mac OS X is located at runtime using rpaths. +Whether this target on OS X or iOS is located at runtime using rpaths. When this property is set to true, the directory portion of the "install_name" field of this shared library will be ``@rpath`` @@ -17,7 +17,7 @@ Runtime paths will also be embedded in binaries using this target and can be controlled by the :prop_tgt:`INSTALL_RPATH` target property on the target linking to this target. -Policy CMP0042 was introduced to change the default value of -MACOSX_RPATH to ON. This is because use of ``@rpath`` is a +Policy :policy:`CMP0042` was introduced to change the default value of +``MACOSX_RPATH`` to ``TRUE. This is because use of ``@rpath`` is a more flexible and powerful alternative to ``@executable_path`` and ``@loader_path``. diff --git a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst index f8fdcff..fb78177 100644 --- a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -1,7 +1,7 @@ OSX_ARCHITECTURES_ -------------------------- -Per-configuration OS X binary architectures for a target. +Per-configuration OS X and iOS binary architectures for a target. This property is the configuration-specific version of :prop_tgt:`OSX_ARCHITECTURES`. diff --git a/Help/prop_tgt/PRIVATE_HEADER.rst b/Help/prop_tgt/PRIVATE_HEADER.rst index da2127b..c4412ed 100644 --- a/Help/prop_tgt/PRIVATE_HEADER.rst +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -1,11 +1,11 @@ PRIVATE_HEADER -------------- -Specify private header files in a FRAMEWORK shared library target. +Specify private header files in a :prop_tgt:`FRAMEWORK` shared library target. -Shared library targets marked with the FRAMEWORK property generate -frameworks on OS X and normal shared libraries on other platforms. +Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate +frameworks on OS X, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the PrivateHeaders directory inside the framework folder. On non-Apple -platforms these headers may be installed using the PRIVATE_HEADER -option to the install(TARGETS) command. +platforms these headers may be installed using the ``PRIVATE_HEADER`` +option to the ``install(TARGETS)`` command. diff --git a/Help/prop_tgt/PUBLIC_HEADER.rst b/Help/prop_tgt/PUBLIC_HEADER.rst index 6e25d94..d4a636c 100644 --- a/Help/prop_tgt/PUBLIC_HEADER.rst +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -1,11 +1,11 @@ PUBLIC_HEADER ------------- -Specify public header files in a FRAMEWORK shared library target. +Specify public header files in a :prop_tgt:`FRAMEWORK` shared library target. -Shared library targets marked with the FRAMEWORK property generate -frameworks on OS X and normal shared libraries on other platforms. +Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate +frameworks on OS X, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the -Headers directory inside the framework folder. On non-Apple platforms -these headers may be installed using the PUBLIC_HEADER option to the -install(TARGETS) command. +``Headers`` directory inside the framework folder. On non-Apple platforms +these headers may be installed using the ``PUBLIC_HEADER`` option to the +``install(TARGETS)`` command. diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst index 1e9921d..5dad3ea 100644 --- a/Help/prop_tgt/RESOURCE.rst +++ b/Help/prop_tgt/RESOURCE.rst @@ -1,11 +1,11 @@ RESOURCE -------- -Specify resource files in a FRAMEWORK shared library target. +Specify resource files in a :prop_tgt:`FRAMEWORK` shared library target. -Shared library targets marked with the FRAMEWORK property generate -frameworks on OS X and normal shared libraries on other platforms. +Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate +frameworks on OS X, iOS and normal shared libraries on other platforms. This property may be set to a list of files to be placed in the -Resources directory inside the framework folder. On non-Apple -platforms these files may be installed using the RESOURCE option to -the install(TARGETS) command. +``Resources`` directory inside the framework folder. On non-Apple +platforms these files may be installed using the ``RESOURCE`` option to +the ``install(TARGETS)`` command. diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst index a8d2429..75eecf1 100644 --- a/Help/variable/APPLE.rst +++ b/Help/variable/APPLE.rst @@ -1,6 +1,6 @@ APPLE ----- -``True`` if running on Mac OS X. +``True`` if running on OS X. -Set to ``true`` on Mac OS X. +Set to ``true`` on OS X. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 1f9ba6f..9a877e7 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -6,15 +6,15 @@ Specify whether an executable exports symbols for loadable modules. Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to be used by loadable modules. When this property is set to true CMake -will allow other targets to "link" to the executable with the +will allow other targets to ``link`` to the executable with the :command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level dependency on the executable is created for targets that link to it. For DLL platforms an import library will be created for the exported symbols and then used for linking. All Windows-based systems including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as Mac OS X, the -module will "link" to the executable using a flag like -"-bundle_loader". For other non-DLL platforms the link rule is simply +require all symbols to be resolved at link time, such as OS X, the +module will ``link`` to the executable using a flag like +``-bundle_loader``. For other non-DLL platforms the link rule is simply ignored since the dynamic loader will automatically bind symbols when the module is loaded. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst index e5e6f67..c673592 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -4,5 +4,5 @@ CMAKE_HOST_SYSTEM_NAME Name of the OS CMake is running on. On systems that have the uname command, this variable is set to the -output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for Mac OS X +output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for OS X are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst index 961d712..1f2d62b 100644 --- a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -1,7 +1,7 @@ CMAKE_INSTALL_NAME_DIR ---------------------- -Mac OS X directory name for installed targets. +OS X directory name for installed targets. ``CMAKE_INSTALL_NAME_DIR`` is used to initialize the :prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target diff --git a/Help/variable/CMAKE_MACOSX_RPATH.rst b/Help/variable/CMAKE_MACOSX_RPATH.rst index ac897c0..042e807 100644 --- a/Help/variable/CMAKE_MACOSX_RPATH.rst +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -1,7 +1,7 @@ CMAKE_MACOSX_RPATH ------------------- -Whether to use rpaths on Mac OS X. +Whether to use rpaths on OS X and iOS. This variable is used to initialize the :prop_tgt:`MACOSX_RPATH` property on all targets. diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst index b9de518..93916dd 100644 --- a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -1,7 +1,7 @@ CMAKE_OSX_ARCHITECTURES ----------------------- -Target specific architectures for OS X. +Target specific architectures for OS X and iOS. This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` property on each target as it is creaed. See that target property -- cgit v0.12