Help: Update documentation to reflect support for iOS

Many of our interfaces documented for OS X also work for iOS.
This commit is contained in:
Bartosz Kosiorek 2015-11-11 05:37:15 +01:00 committed by Brad King
parent dbef2244f9
commit 5d74c870d9
21 changed files with 102 additions and 72 deletions

View File

@ -95,14 +95,17 @@ Apple Frameworks
"""""""""""""""" """"""""""""""""
A ``SHARED`` 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 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 .. code-block:: cmake
add_library(MyFramework SHARED MyFramework.cpp) add_library(MyFramework SHARED MyFramework.cpp)
set_target_properties(MyFramework PROPERTIES set_target_properties(MyFramework PROPERTIES
FRAMEWORK 1 FRAMEWORK TRUE
FRAMEWORK_VERSION A FRAMEWORK_VERSION A
MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
) )
.. _`Object Libraries`: .. _`Object Libraries`:

View File

@ -1,19 +1,23 @@
MACOSX_PACKAGE_LOCATION 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 Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are
Mac OS X application bundles on Apple platforms. Shared library built as OS X or iOS application bundles on Apple platforms. Shared
targets with the FRAMEWORK property set are built as Mac OS X library targets with the :prop_tgt:`FRAMEWORK` property set are built as
frameworks on Apple platforms. Module library targets with the BUNDLE OS X or iOS frameworks on Apple platforms. Module library targets with
property set are built as Mac OS X CFBundle bundles on Apple the :prop_tgt:`BUNDLE` property set are built as OS X ``CFBundle`` bundles
platforms. Source files listed in the target with this property set on Apple platforms. Source files listed in the target with this property
will be copied to a directory inside the bundle or framework content set will be copied to a directory inside the bundle or framework content
folder specified by the property value. For bundles the content folder specified by the property value. For OS X Application Bundles the
folder is "<name>.app/Contents". For frameworks the content folder is content folder is ``<name>.app/Contents``. For OS X Frameworks the
"<name>.framework/Versions/<version>". For cfbundles the content content folder is ``<name>.framework/Versions/<version>``. For OS X
folder is "<name>.bundle/Contents" (unless the extension is changed). CFBundles the content folder is ``<name>.bundle/Contents`` (unless the
See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target properties extension is changed). See the :prop_tgt:`PUBLIC_HEADER`,
for specifying files meant for Headers, PrivateHeaders, or Resources :prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for
directories. specifying files meant for ``Headers``, ``PrivateHeaders``, or
``Resources`` directories.

View File

@ -1,9 +1,9 @@
BUNDLE 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 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 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 structure required for a ``CFBundle`` and will be suitable to be used for
creating Browser Plugins or other application resources. creating Browser Plugins or other application resources.

View File

@ -1,7 +1,7 @@
BUNDLE_EXTENSION 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. file extension is required by the host app for your bundle.

View File

@ -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 For DLL platforms an import library will be created for the exported
symbols and then used for linking. All Windows-based systems symbols and then used for linking. All Windows-based systems
including Cygwin are DLL platforms. For non-DLL platforms that 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 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 ignored since the dynamic loader will automatically bind symbols when
the module is loaded. the module is loaded.

View File

@ -1,11 +1,31 @@
FRAMEWORK 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 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 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 directory structure required for a framework and will be suitable to
be used with the ``-framework`` option 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"
)

View File

@ -3,3 +3,6 @@ FRAMEWORK_VERSION
Version of a framework created using the :prop_tgt:`FRAMEWORK` target Version of a framework created using the :prop_tgt:`FRAMEWORK` target
property (e.g. ``A``). property (e.g. ``A``).
This property only affects OS X, as iOS doesn't have versioned
directory structure.

View File

@ -1,12 +1,12 @@
MACOSX_BUNDLE 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 When this property is set to true the executable when built on OS X
X will be created as an application bundle. This makes it a GUI or iOS will be created as an application bundle. This makes it
executable that can be launched from the Finder. See the a GUI executable that can be launched from the Finder. See the
MACOSX_BUNDLE_INFO_PLIST target property for information about :prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property for information about
creation of the Info.plist file for the application bundle. This creation of the ``Info.plist`` file for the application bundle.
property is initialized by the value of the variable This property is initialized by the value of the variable
CMAKE_MACOSX_BUNDLE if it is set when a target is created. :variable:`CMAKE_MACOSX_BUNDLE` if it is set when a target is created.

View File

@ -1,10 +1,10 @@
MACOSX_BUNDLE_INFO_PLIST 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 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 by configuring a template called ``MacOSXBundleInfo.plist.in`` located in the
:variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template
file name which may be a full path. file name which may be a full path.

View File

@ -1,10 +1,10 @@
MACOSX_FRAMEWORK_INFO_PLIST 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 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 configuring a template called ``MacOSXFrameworkInfo.plist.in`` located in the
:variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template
file name which may be a full path. file name which may be a full path.

View File

@ -1,7 +1,7 @@
MACOSX_RPATH 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 When this property is set to true, the directory portion of
the "install_name" field of this shared library will be ``@rpath`` 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 can be controlled by the :prop_tgt:`INSTALL_RPATH` target property on
the target linking to this target. the target linking to this target.
Policy CMP0042 was introduced to change the default value of Policy :policy:`CMP0042` was introduced to change the default value of
MACOSX_RPATH to ON. This is because use of ``@rpath`` is a ``MACOSX_RPATH`` to ``TRUE. This is because use of ``@rpath`` is a
more flexible and powerful alternative to ``@executable_path`` and more flexible and powerful alternative to ``@executable_path`` and
``@loader_path``. ``@loader_path``.

View File

@ -1,7 +1,7 @@
OSX_ARCHITECTURES_<CONFIG> OSX_ARCHITECTURES_<CONFIG>
-------------------------- --------------------------
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 This property is the configuration-specific version of
:prop_tgt:`OSX_ARCHITECTURES`. :prop_tgt:`OSX_ARCHITECTURES`.

View File

@ -1,11 +1,11 @@
PRIVATE_HEADER 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 Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate
frameworks on OS X and normal shared libraries on other platforms. 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 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 PrivateHeaders directory inside the framework folder. On non-Apple
platforms these headers may be installed using the PRIVATE_HEADER platforms these headers may be installed using the ``PRIVATE_HEADER``
option to the install(TARGETS) command. option to the ``install(TARGETS)`` command.

View File

@ -1,11 +1,11 @@
PUBLIC_HEADER 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 Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate
frameworks on OS X and normal shared libraries on other platforms. 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 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 ``Headers`` directory inside the framework folder. On non-Apple platforms
these headers may be installed using the PUBLIC_HEADER option to the these headers may be installed using the ``PUBLIC_HEADER`` option to the
install(TARGETS) command. ``install(TARGETS)`` command.

View File

@ -1,11 +1,11 @@
RESOURCE 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 Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate
frameworks on OS X and normal shared libraries on other platforms. 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 This property may be set to a list of files to be placed in the
Resources directory inside the framework folder. On non-Apple ``Resources`` directory inside the framework folder. On non-Apple
platforms these files may be installed using the RESOURCE option to platforms these files may be installed using the ``RESOURCE`` option to
the install(TARGETS) command. the ``install(TARGETS)`` command.

View File

@ -1,6 +1,6 @@
APPLE 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.

View File

@ -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 Normally an executable does not export any symbols because it is the
final program. It is possible for an executable to export symbols to 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 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 :command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level
dependency on the executable is created for targets that link to it. dependency on the executable is created for targets that link to it.
For DLL platforms an import library will be created for the exported For DLL platforms an import library will be created for the exported
symbols and then used for linking. All Windows-based systems symbols and then used for linking. All Windows-based systems
including Cygwin are DLL platforms. For non-DLL platforms that 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 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 ignored since the dynamic loader will automatically bind symbols when
the module is loaded. the module is loaded.

View File

@ -4,5 +4,5 @@ CMAKE_HOST_SYSTEM_NAME
Name of the OS CMake is running on. Name of the OS CMake is running on.
On systems that have the uname command, this variable is set to the 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. are the values found on the big three operating systems.

View File

@ -1,7 +1,7 @@
CMAKE_INSTALL_NAME_DIR 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 ``CMAKE_INSTALL_NAME_DIR`` is used to initialize the
:prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target :prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target

View File

@ -1,7 +1,7 @@
CMAKE_MACOSX_RPATH 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 This variable is used to initialize the :prop_tgt:`MACOSX_RPATH` property on
all targets. all targets.

View File

@ -1,7 +1,7 @@
CMAKE_OSX_ARCHITECTURES 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` This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES`
property on each target as it is creaed. See that target property property on each target as it is creaed. See that target property