diff options
Diffstat (limited to 'Help')
69 files changed, 811 insertions, 153 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ecbf9dd..8726b70 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -178,7 +178,7 @@ target is already built, the command will not execute. :: - add_custom_command(TARGET target + add_custom_command(TARGET <target> PRE_BUILD | PRE_LINK | POST_BUILD COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] @@ -188,7 +188,10 @@ target is already built, the command will not execute. [VERBATIM] [USES_TERMINAL]) This defines a new command that will be associated with building the -specified target. When the command will happen is determined by which +specified ``<target>``. The ``<target>`` must be defined in the current +directory; targets defined in other directories may not be specified. + +When the command will happen is determined by which of the following is specified: ``PRE_BUILD`` diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 8573218..dc65a9e 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -5,7 +5,7 @@ Set the minimum required version of cmake for a project. :: - cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]] + cmake_minimum_required(VERSION major.minor[.patch[.tweak]] [FATAL_ERROR]) If the current version of CMake is lower than that required it will diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst new file mode 100644 index 0000000..6206611 --- /dev/null +++ b/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,85 @@ +cmake_parse_arguments +--------------------- + +``cmake_parse_arguments`` is intended to be used in macros or functions for +parsing the arguments given to that macro or function. It processes the +arguments and defines a set of variables which hold the values of the +respective options. + +:: + + cmake_parse_arguments(<prefix> <options> <one_value_keywords> + <multi_value_keywords> args...) + + +The ``<options>`` argument contains all options for the respective macro, +i.e. keywords which can be used when calling the macro without any value +following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` +command. + +The ``<one_value_keywords>`` argument contains all keywords for this macro +which are followed by one value, like e.g. ``DESTINATION`` keyword of the +:command:`install` command. + +The ``<multi_value_keywords>`` argument contains all keywords for this +macro which can be followed by more than one value, like e.g. the +``TARGETS`` or ``FILES`` keywords of the :command:`install` command. + +.. note:: + + All keywords shall be unique. I.e. every keyword shall only be specified + once in either ``<options>``, ``<one_value_keywords>`` or + ``<multi_value_keywords>``. A warning will be emitted if uniqueness is + violated. + +When done, ``cmake_parse_arguments`` will have defined for each of the +keywords listed in ``<options>``, ``<one_value_keywords>`` and +``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` +followed by ``"_"`` and the name of the respective keyword. These +variables will then hold the respective value from the argument list. +For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. + +All remaining arguments are collected in a variable +``<prefix>_UNPARSED_ARGUMENTS``, this can be checked afterwards to see +whether your macro was called with unrecognized parameters. + +As an example here a ``my_install()`` macro, which takes similar arguments +as the real :command:`install` command: + +.. code-block:: cmake + + function(MY_INSTALL) + set(options OPTIONAL FAST) + set(oneValueArgs DESTINATION RENAME) + set(multiValueArgs TARGETS CONFIGURATIONS) + cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" + "${multiValueArgs}" ${ARGN} ) + + # ... + +Assume ``my_install()`` has been called like this: + +.. code-block:: cmake + + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + +After the ``cmake_parse_arguments`` call the macro will have set the +following variables:: + + MY_INSTALL_OPTIONAL = TRUE + MY_INSTALL_FAST = FALSE (was not used in call to my_install) + MY_INSTALL_DESTINATION = "bin" + MY_INSTALL_RENAME = "" (was not used) + MY_INSTALL_TARGETS = "foo;bar" + MY_INSTALL_CONFIGURATIONS = "" (was not used) + MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL") + +You can then continue and process these variables. + +Keywords terminate lists of values, e.g. if directly after a +one_value_keyword another recognized keyword follows, this is +interpreted as the beginning of the new option. E.g. +``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in +``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and +``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 7798252..2a72c3a 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -13,6 +13,6 @@ the variable ``VAR``. If the property is not found, ``VAR`` will be set to Properties are usually used to control how a target is built, but some query the target instead. This command can get properties for any target so far created. The targets do not need to be in the current -CMakeLists.txt file. +``CMakeLists.txt`` file. See also the more general :command:`get_property` command. diff --git a/Help/command/if.rst b/Help/command/if.rst index 2465bde..56e618c 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -67,9 +67,10 @@ Possible expressions are: True if the given name is an existing policy (of the form ``CMP<NNNN>``). ``if(TARGET target-name)`` - True if the given name is an existing logical target name such as those - created by the :command:`add_executable`, :command:`add_library`, or - :command:`add_custom_target` commands. + True if the given name is an existing logical target name created + by a call to the :command:`add_executable`, :command:`add_library`, + or :command:`add_custom_target` command that has already been invoked + (in any directory). ``if(TEST test-name)`` True if the given name is an existing test name created by the @@ -80,7 +81,7 @@ Possible expressions are: only for full paths. ``if(file1 IS_NEWER_THAN file2)`` - True if file1 is newer than file2 or if one of the two files doesn't + True if ``file1`` is newer than ``file2`` or if one of the two files doesn't exist. Behavior is well-defined only for full paths. If the file time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns true, so that any dependent build operations will occur in the event diff --git a/Help/command/install.rst b/Help/command/install.rst index 423899e..aaf12cc 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -45,11 +45,15 @@ signatures that specify them. The common options are: is associated, such as "runtime" or "development". During component-specific installation only install rules associated with the given component name will be executed. During a full installation - all components are installed. If ``COMPONENT`` is not provided a - default component "Unspecified" is created. The default component - name may be controlled with the + all components are installed unless marked with ``EXCLUDE_FROM_ALL``. + If ``COMPONENT`` is not provided a default component "Unspecified" is + created. The default component name may be controlled with the :variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable. +``EXCLUDE_FROM_ALL`` + Specify that the file is excluded from a full installation and only + installed as part of a component-specific installation + ``RENAME`` Specify a name for an installed file that may be different from the original file. Renaming is allowed only when a single file is @@ -72,12 +76,14 @@ Installing Targets [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION <dir>] - [INCLUDES DESTINATION [<dir> ...]] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] - [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP] - ] [...]) + [OPTIONAL] [EXCLUDE_FROM_ALL] + [NAMELINK_ONLY|NAMELINK_SKIP] + ] [...] + [INCLUDES DESTINATION [<dir> ...]] + ) The ``TARGETS`` form specifies rules for installing targets from a project. There are five kinds of target files that may be installed: @@ -97,11 +103,7 @@ change the type of target to which the subsequent properties apply. If none is given the 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). The ``INCLUDES DESTINATION`` specifies a list of directories -which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -target property of the ``<targets>`` when exported by the -:command:`install(EXPORT)` command. If a relative path is -specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. +library). The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments cause subsequent properties to be applied to installing a ``FRAMEWORK`` @@ -131,6 +133,14 @@ option installs nothing. See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for details on creating versioned shared libraries. +The ``INCLUDES DESTINATION`` specifies a list of directories +which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +target property of the ``<targets>`` when exported by the +:command:`install(EXPORT)` command. If a relative path is +specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. +This is independent of the rest of the argument groups and does +not actually install anything. + One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than once to different locations. Consider hypothetical targets ``myExe``, @@ -172,7 +182,7 @@ Installing Files [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] - [RENAME <name>] [OPTIONAL]) + [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) The ``FILES`` form specifies rules for installing files for a project. File names given as relative paths are interpreted with respect to the @@ -206,7 +216,8 @@ Installing Directories [DIRECTORY_PERMISSIONS permissions...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] [CONFIGURATIONS [Debug|Release|...]] - [COMPONENT <component>] [FILES_MATCHING] + [COMPONENT <component>] [EXCLUDE_FROM_ALL] + [FILES_MATCHING] [[PATTERN <pattern> | REGEX <regex>] [EXCLUDE] [PERMISSIONS permissions...]] [...]) @@ -271,9 +282,10 @@ 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. -The install destination given to the directory install ``DESTINATION`` may -use "generator expressions" with the syntax ``$<...>``. See the -:manual:`cmake-generator-expressions(7)` manual for available expressions. +The list of ``dirs...`` given to ``DIRECTORY`` and the install destination +given to the directory install ``DESTINATION`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -281,7 +293,7 @@ Custom Installation Logic :: install([[SCRIPT <file>] [CODE <code>]] - [COMPONENT <component>] [...]) + [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) The ``SCRIPT`` form will invoke the given CMake script files during installation. If the script file name is a relative path it will be @@ -306,7 +318,8 @@ Installing Exports [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [EXPORT_LINK_INTERFACE_LIBRARIES] - [COMPONENT <component>]) + [COMPONENT <component>] + [EXCLUDE_FROM_ALL]) The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. diff --git a/Help/command/list.rst b/Help/command/list.rst index a7a05c7..f6b75bc 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -9,6 +9,7 @@ List operations. list(GET <list> <element index> [<element index> ...] <output variable>) list(APPEND <list> [<element> ...]) + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) list(FIND <list> <value> <output variable>) list(INSERT <list> <element_index> <element> [<element> ...]) list(REMOVE_ITEM <list> <value> [<value> ...]) @@ -23,6 +24,12 @@ List operations. ``APPEND`` will append elements to the list. +``FILTER`` will include or remove items from the list that match the +mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. +For more information on regular expressions see also the :command:`string` +command. + ``FIND`` will return the index of the element specified in the list or -1 if it wasn't found. @@ -38,9 +45,9 @@ difference is that ``REMOVE_ITEM`` will remove the given items, while ``SORT`` sorts the list in-place alphabetically. -The list subcommands ``APPEND``, ``INSERT``, ``REMOVE_AT``, ``REMOVE_ITEM``, -``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new values for -the list within the current CMake variable scope. Similar to the +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, +``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new +values for the list within the current CMake variable scope. Similar to the :command:`set` command, the LIST command creates new variable values in the current scope, even if the list itself is actually defined in a parent scope. To propagate the results of these operations upwards, use diff --git a/Help/command/string.rst b/Help/command/string.rst index 0361c74..3f4050e 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -277,6 +277,7 @@ specifiers: %j The day of the current year (001-366). %m The month of the current year (01-12). %M The minute of the current hour (00-59). + %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). %S The second of the current minute. 60 represents a leap second. (00-60) %U The week number of the current year (00-53). diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 28dae80..78b1bc7 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -112,3 +112,6 @@ The current setting of :policy:`CMP0065` is set in the generated project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. + +Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify +the type of target used for the source file signature. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 4207db4..b428a74 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -77,10 +77,47 @@ Suppress developer warnings. Suppress warnings that are meant for the author of the - CMakeLists.txt files. + CMakeLists.txt files. By default this will also turn off + deprecation warnings. ``-Wdev`` Enable developer warnings. Enable warnings that are meant for the author of the CMakeLists.txt - files. + files. By default this will also turn on deprecation warnings. + +``-Werror=dev`` + Make developer warnings errors. + + Make warnings that are meant for the author of the CMakeLists.txt files + errors. By default this will also turn on deprecated warnings as errors. + +``-Wno-error=dev`` + Make developer warnings not errors. + + Make warnings that are meant for the author of the CMakeLists.txt files not + errors. By default this will also turn off deprecated warnings as errors. + +``-Wdeprecated`` + Enable deprecated functionality warnings. + + Enable warnings for usage of deprecated functionality, that are meant + for the author of the CMakeLists.txt files. + +``-Wno-deprecated`` + Suppress deprecated functionality warnings. + + Suppress warnings for usage of deprecated functionality, that are meant + for the author of the CMakeLists.txt files. + +``-Werror=deprecated`` + Make deprecated macro and function warnings errors. + + Make warnings for usage of deprecated macros and functions, that are meant + for the author of the CMakeLists.txt files, errors. + +``-Wno-error=deprecated`` + Make deprecated macro and function warnings not errors. + + Make warnings for usage of deprecated macros and functions, that are meant + for the author of the CMakeLists.txt files, not errors. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index bc633e6..9004bb2 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`: @@ -424,7 +427,7 @@ specified will be calculated: ) add_library(lib1Version3 SHARED lib1_v3.cpp) - set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000) + set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000) add_executable(exe1 exe1.cpp) # CONTAINER_SIZE_REQUIRED will be "200" diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 5b92b51..d0c2986 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -29,6 +29,7 @@ These commands may be used freely in CMake projects. /command/build_command /command/cmake_host_system_information /command/cmake_minimum_required + /command/cmake_parse_arguments /command/cmake_policy /command/configure_file /command/continue diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index a335384..7bfdcad 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -718,7 +718,7 @@ same consideration applies to macros, functions and imported targets. If False, do not try to use the relevant CMake wrapping command. ``Xxx_Yy_FOUND`` - If False, optional Yy part of Xxx sytem is not available. + If False, optional Yy part of Xxx system is not available. ``Xxx_FOUND`` Set to false, or undefined, if we haven't found, or don't want to use diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index c9219d5..10f05df 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -213,6 +213,7 @@ All Modules /module/FindwxWidgets /module/FindwxWindows /module/FindXCTest + /module/FindXalanC /module/FindXercesC /module/FindX11 /module/FindXMLRPC diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index b9073a5..aebc5d9 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -89,7 +89,7 @@ a package is to set the ``CMAKE_PREFIX_PATH`` cache variable. Config-file packages are provided by upstream vendors as part of development packages, that is, they belong with the header files and any other files -provided to assist downsteams in using the package. +provided to assist downstreams in using the package. A set of variables which provide package status information are also set automatically when using a config-file package. The ``<Package>_FOUND`` @@ -352,7 +352,7 @@ version-specific variables ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``, used to export the targets in the ``ClimbingStatsTargets`` export-set, defined previously by the :command:`install(TARGETS)` command. This command generates the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED` -targets, suitable for use by downsteams and arranges to install it to +targets, suitable for use by downstreams and arranges to install it to ``lib/cmake/ClimbingStats``. The generated ``ClimbingStatsConfigVersion.cmake`` and a ``cmake/ClimbingStatsConfig.cmake`` are installed to the same location, completing the package. @@ -383,7 +383,7 @@ In this case, when using :command:`install(TARGETS)` the ``INCLUDES DESTINATION` was specified. This causes the ``IMPORTED`` targets to have their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated with the ``include`` directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` -target is used by downsteam, it automatically consumes the entries from +target is used by downstream, it automatically consumes the entries from that property. Creating a Package Configuration File @@ -412,7 +412,7 @@ This can also be extended to cover dependencies: target_link_libraries(ClimbingStats PUBLIC Stats::Types) As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``ClimbingStats``, -downsteams must also find the ``Stats`` package and link to the ``Stats::Types`` +downstreams must also find the ``Stats`` package and link to the ``Stats::Types`` library. The ``Stats`` package should be found in the ``ClimbingStatsConfig.cmake`` file to ensure this. The ``find_dependency`` macro from the :module:`CMakeFindDependencyMacro` helps with this by propagating @@ -464,7 +464,7 @@ Creating a Package Configuration File for the Build Tree The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets definition file which is specific to the build-tree, and is not relocatable. -This can similiarly be used with a suitable package configuration file and +This can similarly be used with a suitable package configuration file and package version file to define a package for the build tree which may be used without installation. Consumers of the build tree can simply ensure that the :variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 931363c..d6618fe 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -191,6 +191,7 @@ Properties on Targets /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION + /prop_tgt/IOS_INSTALL_COMBINED /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK /prop_tgt/LABELS @@ -254,6 +255,7 @@ Properties on Targets /prop_tgt/TYPE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN + /prop_tgt/VS_CONFIGURATION_TYPE /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 492fcac..7b294a8 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -151,6 +151,36 @@ target system prefixes, whereas executables which must be run as part of the bui should be found only on the host and not on the target. This is the purpose of the ``CMAKE_FIND_ROOT_PATH_MODE_*`` variables. +.. _`Cray Cross-Compile`: + +Cross Compiling for the Cray Linux Environment +---------------------------------------------- + +Cross compiling for compute nodes in the Cray Linux Environment can be done +without needing a separate toolchain file. Specifying +``-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment`` on the CMake command line will +ensure that the appropriate build settings and search paths are configured. +The platform will pull its configuration from the current environment +variables and will configure a project to use the compiler wrappers from the +Cray Programming Environment's ``PrgEnv-*`` modules if present and loaded. + +The default configuration of the Cray Programming Environment is to only +support static libraries. This can be overridden and shared libraries +enabled by setting the ``CRAYPE_LINK_TYPE`` environment variable to +``dynamic``. + +Running CMake without specifying :variable:`CMAKE_SYSTEM_NAME` will +run the configure step in host mode assuming a standard Linux environment. +If not overridden, the ``PrgEnv-*`` compiler wrappers will end up getting used, +which if targeting the either the login node or compute node, is likely not the +desired behavior. The exception to this would be if you are building directly +on a NID instead of cross-compiling from a login node. If trying to build +software for a login node, you will need to either first unload the +currently loaded ``PrgEnv-*`` module or explicitly tell CMake to use the +system compilers in ``/usr/bin`` instead of the Cray wrappers. If instead +targeting a compute node is desired, just specify the +:variable:`CMAKE_SYSTEM_NAME` as mentioned above. + Cross Compiling using Clang --------------------------- diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 2116900..444a706 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -118,6 +118,7 @@ Variables that Change Behavior /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXPORT_COMPILE_COMMANDS /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_APPBUNDLE @@ -257,6 +258,7 @@ Variables that Control the Build /variable/CMAKE_INSTALL_NAME_DIR /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH + /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_COMPILER_LAUNCHER /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE /variable/CMAKE_LANG_VISIBILITY_PRESET @@ -290,6 +292,7 @@ Variables that Control the Build /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS /variable/CMAKE_TRY_COMPILE_CONFIGURATION + /variable/CMAKE_TRY_COMPILE_TARGET_TYPE /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index dac16bf..5295a48c 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -58,13 +58,14 @@ Options <dir> = Project binary directory to be built. --target <tgt> = Build <tgt> instead of default targets. + May only be specified once. --config <cfg> = For multi-configuration tools, choose <cfg>. --clean-first = Build target 'clean' first, then build. (To clean only, use --target 'clean'.) --use-stderr = Ignored. Behavior is default in CMake >= 3.0. -- = Pass remaining options to the native tool. - Run cmake --build with no options for quick help. + Run ``cmake --build`` with no options for quick help. ``-N`` View mode only. @@ -167,16 +168,23 @@ Available commands are: Change the current working directory and run a command. ``compare_files <file1> <file2>`` - Check if file1 is same as file2. + Check if ``<file1>`` is same as ``<file2>``. If files are the same, + then returns 0, if not itreturns 1. -``copy <file> <destination>`` - Copy file to destination (either file or directory). +``copy <file>... <destination>`` + Copy files to ``<destination>`` (either file or directory). + If multiple files are specified, the ``<destination>`` must be + directory and it must exist. -``copy_directory <source> <destination>`` - Copy directory 'source' content to directory 'destination'. +``copy_directory <dir>... <destination>`` + Copy directories to ``<destination>`` directory. + If ``<destination>`` directory does not exist it will be created. -``copy_if_different <in-file> <out-file>`` - Copy file if input has changed. +``copy_if_different <file>... <destination>`` + Copy files to ``<destination>`` (either file or directory) if + they have changed. + If multiple files are specified, the ``<destination>`` must be + directory and it must exist. ``echo [<string>...]`` Displays arguments as text. @@ -188,19 +196,23 @@ Available commands are: Run command in a modified environment. ``environment`` - Display the current environment. + Display the current environment variables. -``make_directory <dir>`` - Create a directory. +``make_directory <dir>...`` + Create ``<dir>`` directories. If necessary, create parent + directories too. If a directory already exists it will be + silently ignored. -``md5sum [<file>...]`` +``md5sum <file>...`` Compute md5sum of files. -``remove [-f] [<file>...]`` - Remove the file(s), use ``-f`` to force it. +``remove [-f] <file>...`` + Remove the file(s), use ``-f`` to force it. If a file does + not exist it will be silently ignored. ``remove_directory <dir>`` - Remove a directory and its contents. + Remove a directory and its contents. If a directory does + not exist it will be silently ignored. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). @@ -233,7 +245,8 @@ Available commands are: Touch a file. ``touch_nocreate <file>`` - Touch a file if it exists but do not create it. + Touch a file if it exists but do not create it. If a file does + not exist it will be silently ignored. UNIX-specific Command-Line Tools -------------------------------- diff --git a/Help/module/FindXalanC.rst b/Help/module/FindXalanC.rst new file mode 100644 index 0000000..b99d212 --- /dev/null +++ b/Help/module/FindXalanC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXalanC.cmake diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst index e746c03..d46baf6 100644 --- a/Help/policy/CMP0040.rst +++ b/Help/policy/CMP0040.rst @@ -1,18 +1,21 @@ CMP0040 ------- -The target in the TARGET signature of add_custom_command() must exist. +The target in the ``TARGET`` signature of :command:`add_custom_command` +must exist and must be defined in current directory. CMake 2.8.12 and lower silently ignored a custom command created with -the TARGET signature of :command:`add_custom_command` -if the target is unknown. +the ``TARGET`` signature of :command:`add_custom_command` +if the target is unknown or was defined outside the current directory. -The OLD behavior for this policy is to ignore custom commands -for unknown targets. The NEW behavior for this policy is to report an error -if the target referenced in :command:`add_custom_command` is unknown. +The ``OLD`` behavior for this policy is to ignore custom commands +for unknown targets. The ``NEW`` behavior for this policy is to report +an error if the target referenced in :command:`add_custom_command` is +unknown or was defined outside the current directory. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/prop_dir/CLEAN_NO_CUSTOM.rst b/Help/prop_dir/CLEAN_NO_CUSTOM.rst index 9a4173e..5ae78bf 100644 --- a/Help/prop_dir/CLEAN_NO_CUSTOM.rst +++ b/Help/prop_dir/CLEAN_NO_CUSTOM.rst @@ -1,7 +1,6 @@ CLEAN_NO_CUSTOM --------------- -Should the output of custom commands be left. - -If this is true then the outputs of custom commands for this directory -will not be removed during the "make clean" stage. +Set to true to tell :ref:`Makefile Generators` not to remove the outputs of +custom commands for this directory during the ``make clean`` operation. +This is ignored on other generators because it is not possible to implement. 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 "<name>.app/Contents". For frameworks the content folder is -"<name>.framework/Versions/<version>". For cfbundles the content -folder is "<name>.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 ``<name>.app/Contents``. For OS X Frameworks the +content folder is ``<name>.framework/Versions/<version>``. For OS X +CFBundles the content folder is ``<name>.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/IOS_INSTALL_COMBINED.rst b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst new file mode 100644 index 0000000..59f67a7 --- /dev/null +++ b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst @@ -0,0 +1,11 @@ +IOS_INSTALL_COMBINED +-------------------- + +Build a combined (device and simulator) target when installing. + +When this property is set to set to false (which is the default) then it will +either be built with the device SDK or the simulator SDK depending on the SDK +set. But if this property is set to true then the target will at install time +also be built for the corresponding SDK and combined into one library. + +This feature requires at least Xcode version 6. diff --git a/Help/prop_tgt/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst index ff21e61..7cd8046 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 d3934ba..1f9a036 100644 --- a/Help/prop_tgt/MACOSX_RPATH.rst +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -1,18 +1,23 @@ MACOSX_RPATH ------------ -Whether to use rpaths on Mac OS X. +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`` +unless overridden by :prop_tgt:`INSTALL_NAME_DIR`. This indicates +the shared library is to be found at runtime using runtime +paths (rpaths). -When this property is set to true, the directory portion of -the "install_name" field of shared libraries will be ``@rpath`` -unless overridden by :prop_tgt:`INSTALL_NAME_DIR`. Runtime -paths will also be embedded in binaries using this target and -can be controlled by the :prop_tgt:`INSTALL_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_MACOSX_RPATH` if it is set when a target is created. -Policy CMP0042 was introduced to change the default value of -MACOSX_RPATH to ON. This is because use of ``@rpath`` is a +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 :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_<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 :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..d837f7b 100644 --- a/Help/prop_tgt/RESOURCE.rst +++ b/Help/prop_tgt/RESOURCE.rst @@ -1,11 +1,61 @@ RESOURCE -------- -Specify resource files in a FRAMEWORK shared library target. - -Shared library targets marked with the FRAMEWORK property generate -frameworks on OS X 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. +Specify resource files in a :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE`. + +Target marked with the :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE` property +generate framework or application bundle (both OS X and iOS is supported) +or normal shared libraries on other platforms. +This property may be set to a list of files to be placed in the corresponding +directory (eg. ``Resources`` directory for OS X) inside the bundle. +On non-Apple platforms these files may be installed using the ``RESOURCE`` +option to the ``install(TARGETS)`` command. + +Following example of Application Bundle: + +.. code-block:: cmake + + add_executable(ExecutableTarget + addDemo.c + resourcefile.txt + appresourcedir/appres.txt + ) + + target_link_libraries(ExecutableTarget heymath mul) + + set(RESOURCE_FILES + resourcefile.txt + appresourcedir/appres.txt + ) + + set_target_properties(ExecutableTarget PROPERTIES + MACOSX_BUNDLE TRUE + MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget + RESOURCE "${RESOURCE_FILES}" + ) + +will produce flat structure for iOS systems:: + + ExecutableTarget.app + appres.txt + ExecutableTarget + Info.plist + resourcefile.txt + +For OS X systems it will produce following directory structure:: + + ExecutableTarget.app/ + Contents + Info.plist + MacOS + ExecutableTarget + Resources + appres.txt + resourcefile.txt + +For Linux, such cmake script produce following files:: + + ExecutableTarget + Resources + appres.txt + resourcefile.txt diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst new file mode 100644 index 0000000..ff987ff --- /dev/null +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -0,0 +1,10 @@ +VS_CONFIGURATION_TYPE +--------------------- + +Visual Studio project configuration type. + +Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +If this property is set, it overrides the default setting that is based on the +target type (e.g. ``StaticLibrary``, ``Application``, ...). + +Supported on :ref:`Visual Studio Generators` for VS 2010 and higher. diff --git a/Help/release/3.5.rst b/Help/release/3.5.rst new file mode 100644 index 0000000..009eb3c --- /dev/null +++ b/Help/release/3.5.rst @@ -0,0 +1,185 @@ +CMake 3.5 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.4 include the following. + +New Features +============ + +GUI +--- + +* The :manual:`cmake-gui(1)` gained options to control warnings about + deprecated functionality. + +* The :manual:`cmake-gui(1)` learned an option to set the toolset + to be used with VS IDE and Xcode generators, much like the + existing ``-T`` option to :manual:`cmake(1)`. + +* The :manual:`cmake-gui(1)` gained a Regular Expression Explorer which + may be used to create and evaluate regular expressions in real-time. + The explorer window is available via the ``Tools`` menu. + +Command-Line +------------ + +* The ``-Wdev`` and ``-Wno-dev`` :manual:`cmake(1)` options now also enable + and suppress the deprecated warnings output by default. + +* The suppression of developer warnings as errors can now be controlled with + the new ``-Werror=dev`` and ``-Wno-error=dev`` :manual:`cmake(1)` options. + +* The :manual:`cmake(1)` ``-E`` command-line tools ``copy``, + ``copy_if_different``, ``copy_directory``, and ``make_directory`` + learned to support multiple input files or directories. + +Commands +-------- + +* The :command:`cmake_parse_arguments` command is now implemented natively. + The :module:`CMakeParseArguments` module remains as an empty placeholder + for compatibility. + +* The :command:`install(DIRECTORY)` command learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>` + in the list of directories. + +Variables +--------- + +* The :variable:`CMAKE_ERROR_DEPRECATED` variable can now be set using the + ``-Werror=deprecated`` and ``-Wno-error=deprecated`` :manual:`cmake(1)` + options. + +* The :variable:`CMAKE_WARN_DEPRECATED` variable can now be set using the + ``-Wdeprecated`` and ``-Wno-deprecated`` :manual:`cmake(1)` options. + +Properties +---------- + +* The :prop_tgt:`VS_GLOBAL_<variable>` target property is now implemented + for VS 2010 and above. Previously it worked only in VS 2008 and below. + +Modules +------- + +* The :module:`ExternalProject` module learned a new ``GIT_REMOTE_NAME`` + option to control the ``git clone --origin`` value. + +* The :module:`FindBoost` module now provides imported targets + such as ``Boost::boost`` and ``Boost::filesystem``. + +* The :module:`FindFLEX` module ``FLEX_TARGET`` macro learned a + new ``DEFINES_FILE`` option to specify a custom output header + to be generated. + +* The :module:`FindGTest` module now provides imported targets. + +* The :module:`FindGTK2` module, when ``GTK2_USE_IMPORTED_TARGETS`` is + enabled, now sets ``GTK2_LIBRARIES`` to contain the list of imported + targets instead of the paths to the libraries. Moreover it now sets + a new ``GTK2_TARGETS`` variable containing all the targets imported. + +* The :module:`FindOpenMP` module learned to support Clang. + +* The :module:`FindOpenSSL` module gained a new + ``OPENSSL_MSVC_STATIC_RT`` option to search for libraries using + the MSVC static runtime. + +* The :module:`FindPNG` module now provides imported targets. + +* The :module:`FindTIFF` module now provides imported targets. + +* A :module:`FindXalanC` module was introduced to find the + Apache Xalan-C++ XSL transform processing library. + +* The :module:`FindXercesC` module now provides imported targets. + +Platforms +--------- + +* Support was added for the ARM Compiler (arm.com) with compiler id ``ARMCC``. + +* A new platform file for cross-compiling in the Cray Linux Environment to + target compute nodes was added. See + :ref:`Cross Compiling for the Cray Linux Environment <Cray Cross-Compile>` + for usage details. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Clang compilers on Windows (MinGW). + +* When building for embedded Apple platforms like iOS CMake learned to build and + install combined targets which contain both a device and a simulator build. + This behavior can be enabled by setting the :prop_tgt:`IOS_INSTALL_COMBINED` + target property. + +CPack +----- + +* The :module:`CPackDMG` module learned new variable to specify AppleScript + file run to customize appearance of ``DragNDrop`` installer folder, + including background image setting using supplied PNG or multi-resolution + TIFF file. See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and + :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables. + +* The :module:`CPackDeb` module learned to set the optional config + file ``Source`` field using a monolithic or per-component variable. + See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`. + +* The :module:`CPackDeb` module learned to set Package, Section + and Priority control fields per-component. + See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`. + +* The :module:`CPack DragNDrop generator <CPackDMG>` learned to add + multi-lingual SLAs to a DMG which is presented to the user when they try to + mount the DMG. See the :variable:`CPACK_DMG_SLA_LANGUAGES` and + :variable:`CPACK_DMG_SLA_DIR` variables for details. + +* The :module:`CPackNSIS` module learned new variables to add bitmaps to the + installer. See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` + and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables. + +* The :module:`CPackRPM` module learned to set Name and Group + control fields per-component. + See :variable:`CPACK_RPM_<component>_PACKAGE_NAME` + and :variable:`CPACK_RPM_<component>_PACKAGE_GROUP`. + +Other +----- + +* Warnings about deprecated functionality are now enabled by default. + They may be suppressed with ``-Wno-deprecated`` or by setting the + :variable:`CMAKE_WARN_DEPRECATED` variable to false. + +Deprecated and Removed Features +=============================== + +* The :manual:`cmake(1)` ``-E time`` command now properly passes arguments + with spaces or special characters through to the child process. This + may break scripts that worked around the bug with their own extra + quoting or escaping. + +* The :generator:`Xcode` generator was fixed to escape backslashes in + strings consistently with other generators. Projects that previously + worked around the inconsistecy with an extra level of backslashes + conditioned on the Xcode generator must be updated to remove the + workaround for CMake 3.5 and greater. + +Other Changes +============= + +* The :generator:`Visual Studio 14 2015` generator learned to map the + ``/debug:fastlink`` linker flag to the ``.vcxproj`` file property. + +* The :module:`FindGTK2` module now configures the ``GTK2::sigc++`` imported + target to enable c++11 on its dependents when using sigc++ 2.5.1 or higher. + +* The precompiled Windows binary provided on ``cmake.org`` is now a + ``.msi`` package instead of an installer executable. One may need + to manually uninstall CMake versions lower than 3.5 before installing + the new package. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/FindProtobuf-version.rst b/Help/release/dev/FindProtobuf-version.rst new file mode 100644 index 0000000..2bfd9f4 --- /dev/null +++ b/Help/release/dev/FindProtobuf-version.rst @@ -0,0 +1,6 @@ +FindProtobuf-version +-------------------- + +* The :module:`FindProtobuf` module learned to provide a ``PROTOBUF_VERSION`` + variable and check the version number requested in a :command:`find_package` + call. diff --git a/Help/release/dev/cpack-deb-autodep-ORIGIN-RPATH.rst b/Help/release/dev/cpack-deb-autodep-ORIGIN-RPATH.rst new file mode 100644 index 0000000..b0d6196 --- /dev/null +++ b/Help/release/dev/cpack-deb-autodep-ORIGIN-RPATH.rst @@ -0,0 +1,6 @@ +cpack-deb-autodep-ORIGIN-RPATH +-------------------------------- + +* The "CPackDeb" module learned how to handle ``$ORIGIN`` + in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` + is used for dependency auto detection. diff --git a/Help/release/dev/cpack-rpm-upper-cased-components.rst b/Help/release/dev/cpack-rpm-upper-cased-components.rst new file mode 100644 index 0000000..a5fb233 --- /dev/null +++ b/Help/release/dev/cpack-rpm-upper-cased-components.rst @@ -0,0 +1,15 @@ +cpack-rpm-upper-cased-components +-------------------------------- + +* The "CPackRPM" module now supports upper cased component name + in per component CPackRPM specific variables. + E.g. component named ``foo`` now expects component specific + variable to be ``CPACK_RPM_FOO_PACKAGE_NAME`` while before + it expected ``CPACK_RPM_foo_PACKAGE_NAME``. + Upper cased component name part in variables is compatible + with convention used for other CPack variables. + For back compatibility old format of variables is still valid + and prefered if both versions of variable are set, but the + preferred future use is upper cased component names in variables. + New variables that will be added to CPackRPM in later versions + will only support upper cased component variable format. diff --git a/Help/release/dev/enable-ssl-automatically.rst b/Help/release/dev/enable-ssl-automatically.rst new file mode 100644 index 0000000..8ded656 --- /dev/null +++ b/Help/release/dev/enable-ssl-automatically.rst @@ -0,0 +1,8 @@ +enable-ssl-automatically +------------------------ + +* On Linux and FreeBSD platforms, when building CMake itself from source and + not using a system-provided libcurl, OpenSSL is now used by default if it is + found on the system. This enables SSL/TLS support for commands supporting + network communication via ``https``, such as :command:`file(DOWNLOAD)`, + :command:`file(UPLOAD)`, and :command:`ctest_submit`. diff --git a/Help/release/dev/error-multiple-targets.rst b/Help/release/dev/error-multiple-targets.rst new file mode 100644 index 0000000..060b26b --- /dev/null +++ b/Help/release/dev/error-multiple-targets.rst @@ -0,0 +1,6 @@ +error-multiple-targets +---------------------- + +* The :manual:`cmake(1)` ``--build`` command-line tool now rejects multiple + ``--target`` options with an error instead of silently ignoring all but the + last one. diff --git a/Help/release/dev/install-EXCLUDE_FROM_ALL.rst b/Help/release/dev/install-EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000..a611eae --- /dev/null +++ b/Help/release/dev/install-EXCLUDE_FROM_ALL.rst @@ -0,0 +1,5 @@ +install-EXCLUDE_FROM_ALL +------------------------ + +* The :command:`install` command learned a new ``EXCLUDE_FROM_ALL`` option + to leave installation rules out of the default installation. diff --git a/Help/release/dev/list-FILTER-command.rst b/Help/release/dev/list-FILTER-command.rst new file mode 100644 index 0000000..3fee4f0 --- /dev/null +++ b/Help/release/dev/list-FILTER-command.rst @@ -0,0 +1,5 @@ +list-FILTER-command +------------------- + +* The :command:`list` command gained a ``FILTER`` sub-command to filter + list elements by regular expression. diff --git a/Help/release/dev/try_compile-target-type.rst b/Help/release/dev/try_compile-target-type.rst new file mode 100644 index 0000000..cc41bf3 --- /dev/null +++ b/Help/release/dev/try_compile-target-type.rst @@ -0,0 +1,8 @@ +try_compile-target-type +----------------------- + +* The :command:`try_compile` command learned to check a new + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to optionally + build a static library instead of an executable. This is useful + for cross-compiling toolchains that cannot link binaries without + custom flags or scripts. diff --git a/Help/release/dev/unix-timestamps.rst b/Help/release/dev/unix-timestamps.rst new file mode 100644 index 0000000..cdb0e5b --- /dev/null +++ b/Help/release/dev/unix-timestamps.rst @@ -0,0 +1,6 @@ +unix-timestamps +--------------- + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` + commands gained support for the ``%s`` placeholder. This is + the number of seconds since the UNIX Epoch. diff --git a/Help/release/dev/vs-vcxproj-ConfigurationType.rst b/Help/release/dev/vs-vcxproj-ConfigurationType.rst new file mode 100644 index 0000000..46d05b4 --- /dev/null +++ b/Help/release/dev/vs-vcxproj-ConfigurationType.rst @@ -0,0 +1,6 @@ +vs-vcxproj-ConfigurationType +---------------------------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned a new + :prop_tgt:`VS_CONFIGURATION_TYPE` target property to specify a custom + project file type. diff --git a/Help/release/index.rst b/Help/release/index.rst index 5d1a3f7..7ecf910 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,12 +5,15 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. toctree:: :maxdepth: 1 + 3.5 <3.5> 3.4 <3.4> 3.3 <3.3> 3.2 <3.2> 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_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst index f8dd8ab..3b323b7 100644 --- a/Help/variable/CMAKE_BINARY_DIR.rst +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -6,3 +6,8 @@ The path to the top level of the build tree. This is the full path to the top level of the current CMake build tree. For an in-source build, this would be the same as :variable:`CMAKE_SOURCE_DIR`. + +When run in -P script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index cc3b639..40496b5 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -8,3 +8,8 @@ processed by cmake. Each directory added by :command:`add_subdirectory` will create a binary directory in the build tree, and as it is being processed this variable will be set. For in-source builds this is the current source directory being processed. + +When run in -P script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index db063a4..c1b755a 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -5,3 +5,8 @@ The path to the source directory currently being processed. This the full path to the source directory that is currently being processed by cmake. + +When run in -P script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. 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_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst index 277a4cc..f3a6738 100644 --- a/Help/variable/CMAKE_ERROR_DEPRECATED.rst +++ b/Help/variable/CMAKE_ERROR_DEPRECATED.rst @@ -1,8 +1,7 @@ CMAKE_ERROR_DEPRECATED ---------------------- -Whether to issue deprecation errors for macros and functions. +Whether to issue errors for deprecated functionality. -If ``TRUE``, this can be used by macros and functions to issue fatal -errors when deprecated macros or functions are used. This variable is -``FALSE`` by default. +If ``TRUE``, use of deprecated functionality will issue fatal errors. +If this variable is not set, CMake behaves as if it were set to ``FALSE``. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..8776279 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,30 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +Enable/Disable output of compile commands during generation. + +If enabled, generates a ``compile_commands.json`` file containing the exact +compiler calls for all translation units of the project in machine-readable +form. The format of the JSON file looks like: + +.. code-block:: javascript + + [ + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/foo.cc", + "file": "../foo/foo.cc" + }, + + ... + + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/bar.cc", + "file": "../foo/bar.cc" + } + ] + +.. note:: + This option is implemented only by :ref:`Makefile Generators` + and the :generator:`Ninja`. It is ignored on other generators. 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_IOS_INSTALL_COMBINED.rst b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst new file mode 100644 index 0000000..c5cb9b6 --- /dev/null +++ b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst @@ -0,0 +1,8 @@ +CMAKE_IOS_INSTALL_COMBINED +-------------------------- + +Default value for :prop_tgt:`IOS_INSTALL_COMBINED` of targets. + +This variable is used to initialize the :prop_tgt:`IOS_INSTALL_COMBINED` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 1c3b134..81976a9 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -11,6 +11,7 @@ include: Absoft = Absoft Fortran (absoft.com) ADSP = Analog VisualDSP++ (analog.com) AppleClang = Apple Clang (apple.com) + ARMCC = ARM Compiler (arm.com) CCur = Concurrent Fortran (ccur.com) Clang = LLVM Clang (clang.llvm.org) Cray = Cray Compiler (cray.com) 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 diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index 3df0226..416fbe1 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -6,3 +6,8 @@ The path to the top level of the source tree. This is the full path to the top level of the current CMake source tree. For an in-source build, this would be the same as :variable:`CMAKE_BINARY_DIR`. + +When run in -P script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst new file mode 100644 index 0000000..5fa8dfc --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst @@ -0,0 +1,15 @@ +CMAKE_TRY_COMPILE_TARGET_TYPE +----------------------------- + +Type of target generated for :command:`try_compile` calls using the +source file signature. Valid values are: + +``EXECUTABLE`` + Use :command:`add_executable` to name the source file in the + generated project. This is the default if no value is given. + +``STATIC_LIBRARY`` + Use :command:`add_library` with the ``STATIC`` option to name the + source file in the generated project. This avoids running the + linker and is intended for use with cross-compiling toolchains + that cannot link without custom flags or linker scripts. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst index 6392849..e0be3a4 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -8,4 +8,5 @@ specification of a target Windows version to select a corresponding SDK. The :variable:`CMAKE_SYSTEM_VERSION` variable may be set to specify a version. Otherwise CMake computes a default version based on the Windows SDK versions available. The chosen Windows target version number is provided -in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``. +in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``. If no Windows 10 SDK +is available this value will be empty. diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst index 662cbd8..4a224fa 100644 --- a/Help/variable/CMAKE_WARN_DEPRECATED.rst +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst @@ -1,7 +1,10 @@ CMAKE_WARN_DEPRECATED --------------------- -Whether to issue deprecation warnings for macros and functions. +Whether to issue warnings for deprecated functionality. -If ``TRUE``, this can be used by macros and functions to issue deprecation -warnings. This variable is ``FALSE`` by default. +If not ``FALSE``, use of deprecated functionality will issue warnings. +If this variable is not set, CMake behaves as if it were set to ``TRUE``. + +When running :manual:`cmake(1)`, this option can be enabled with the +``-Wdeprecated`` option, or disabled with the ``-Wno-deprecated`` option. diff --git a/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst index 122b9f6..be683d6 100644 --- a/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst +++ b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst @@ -8,3 +8,9 @@ in the generated Xcode project. Ignored on other generators. See the :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property to set attributes on a specific target. + +Contents of ``CMAKE_XCODE_ATTRIBUTE_<an-attribute>`` 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. |