From e2f349864dea91bec1d4c07428ab94225ff589dd Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 8 Jun 2015 15:15:47 -0400 Subject: [PATCH 1/4] Help: Document CMAKE_SYSTEM_FRAMEWORK_PATH variable --- Help/manual/cmake-variables.7.rst | 1 + Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst | 8 ++++++++ 2 files changed, 9 insertions(+) create mode 100644 Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index bd02f8b8b..d62194532 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -147,6 +147,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX + /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH diff --git a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst new file mode 100644 index 000000000..1e8b0d947 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_FRAMEWORK_PATH +--------------------------- + +Search path for OS X frameworks used by the :command:`find_library`, +:command:`find_package`, :command:`find_path`, and :command:`find_file` +commands. By default it contains the standard directories for the +current system. It is *not* intended to be modified by the project, +use :variable:`CMAKE_FRAMEWORK_PATH` for this. From 25b4483ef8d6f6f074f05cf99e0282abf22d8939 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 8 Jun 2015 15:21:47 -0400 Subject: [PATCH 2/4] Help: Document CMAKE_SYSTEM_APPBUNDLE_PATH variable --- Help/manual/cmake-variables.7.rst | 1 + Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index d62194532..4c51fe120 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -147,6 +147,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX + /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH diff --git a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst new file mode 100644 index 000000000..3c6687c6e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_SYSTEM_APPBUNDLE_PATH +--------------------------- + +Search path for OS X application bundles used by the :command:`find_program`, +and :command:`find_package` commands. By default it contains the standard +directories for the current system. It is *not* intended to be modified by +the project, use :variable:`CMAKE_APPBUNDLE_PATH` for this. From 8c64c4783dde25d84b1549945b95d192c1b7fd68 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 8 Jun 2015 15:36:31 -0400 Subject: [PATCH 3/4] Help: Document CMAKE_FIND_APPBUNDLE and CMAKE_FIND_FRAMEWORK Add dedicated documents for these and link to them instead of duplicating their documentation in every find command. --- Help/command/FIND_XXX.txt | 5 ++++- Help/command/FIND_XXX_MAC.txt | 24 ------------------------ Help/command/find_package.rst | 7 +++---- Help/manual/cmake-variables.7.rst | 2 ++ Help/variable/CMAKE_FIND_APPBUNDLE.rst | 22 ++++++++++++++++++++++ Help/variable/CMAKE_FIND_FRAMEWORK.rst | 22 ++++++++++++++++++++++ 6 files changed, 53 insertions(+), 29 deletions(-) delete mode 100644 Help/command/FIND_XXX_MAC.txt create mode 100644 Help/variable/CMAKE_FIND_APPBUNDLE.rst create mode 100644 Help/variable/CMAKE_FIND_FRAMEWORK.rst diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 935832930..474127d23 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -100,6 +100,9 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows: .. |FIND_ARGS_XXX| replace:: NAMES name -.. include:: FIND_XXX_MAC.txt +On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and +:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of +preference between Apple-style and unix-style package components. + .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt diff --git a/Help/command/FIND_XXX_MAC.txt b/Help/command/FIND_XXX_MAC.txt deleted file mode 100644 index eb3900cbb..000000000 --- a/Help/command/FIND_XXX_MAC.txt +++ /dev/null @@ -1,24 +0,0 @@ -On Darwin or systems supporting OS X Frameworks, the cmake variable -CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: - -* FIRST: Try to find frameworks before standard libraries or headers. - This is the default on Darwin. - -* LAST: Try to find frameworks after standard libraries or headers. - -* ONLY: Only try to find frameworks. - -* NEVER: Never try to find frameworks. - -On Darwin or systems supporting OS X Application Bundles, the cmake -variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the -following: - -* FIRST: Try to find application bundles before standard programs. - This is the default on Darwin. - -* LAST: Try to find application bundles after standard programs. - -* ONLY: Only try to find application bundles. - -* NEVER: Never try to find application bundles. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index a5efba6d0..58dff9d39 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -228,9 +228,9 @@ installation directory. Those marked with (U) are intended for installations on UNIX platforms where the prefix is shared by multiple packages. This is merely a convention, so all (W) and (U) directories are still searched on all platforms. Directories marked with (A) are -intended for installations on Apple platforms. The cmake variables -``CMAKE_FIND_FRAMEWORK`` and ``CMAKE_FIND_APPBUNDLE`` -determine the order of preference as specified below. +intended for installations on Apple platforms. The +:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` +variables determine the order of preference. The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are @@ -295,7 +295,6 @@ enabled. .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` -.. include:: FIND_XXX_MAC.txt .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4c51fe120..f010d28b1 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -117,6 +117,8 @@ Variables that Change Behavior /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_SYSROOT + /variable/CMAKE_FIND_APPBUNDLE + /variable/CMAKE_FIND_FRAMEWORK /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX diff --git a/Help/variable/CMAKE_FIND_APPBUNDLE.rst b/Help/variable/CMAKE_FIND_APPBUNDLE.rst new file mode 100644 index 000000000..e0727b547 --- /dev/null +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_APPBUNDLE +-------------------- + +This variable affects how ``find_*`` commands choose between +OS X Application Bundles and unix-style package components. + +On Darwin or systems supporting OS X Application Bundles, the +``CMAKE_FIND_APPBUNDLE`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find application bundles before standard programs. + This is the default on Darwin. + +``LAST`` + Try to find application bundles after standard programs. + +``ONLY`` + Only try to find application bundles. + +``NEVER`` + Never try to find application bundles. diff --git a/Help/variable/CMAKE_FIND_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst new file mode 100644 index 000000000..790694ac5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_FRAMEWORK +-------------------- + +This variable affects how ``find_*`` commands choose between +OS X Frameworks and unix-style package components. + +On Darwin or systems supporting OS X Frameworks, the +``CMAKE_FIND_FRAMEWORK`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find frameworks before standard libraries or headers. + This is the default on Darwin. + +``LAST`` + Try to find frameworks after standard libraries or headers. + +``ONLY`` + Only try to find frameworks. + +``NEVER`` + Never try to find frameworks. From 3de3544fcd38680652d5bbe0790b78477ffa26f1 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 8 Jun 2015 15:52:21 -0400 Subject: [PATCH 4/4] Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places. --- Help/command/FIND_XXX.txt | 56 +++++++++++++++++++--------------- Help/command/FIND_XXX_ROOT.txt | 16 +++++++--- Help/command/find_file.rst | 29 ++++++++++-------- Help/command/find_library.rst | 51 ++++++++++++++++--------------- Help/command/find_path.rst | 35 +++++++++++---------- Help/command/find_program.rst | 15 +++++---- 6 files changed, 113 insertions(+), 89 deletions(-) diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 474127d23..966db06c2 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -33,36 +33,42 @@ and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be ``-NOTFOUND``, and the search will be attempted again the next time |FIND_XXX| is invoked with the same variable. -The name of the |SEARCH_XXX| that -is searched for is specified by the names listed -after the NAMES argument. Additional search locations -can be specified after the PATHS argument. If ENV var is -found in the HINTS or PATHS section the environment variable var -will be read and converted from a system environment variable to -a cmake style list of paths. For example ENV PATH would be a way -to list the system path variable. The argument -after DOC will be used for the documentation string in -the cache. -PATH_SUFFIXES specifies additional subdirectories to check below -each search path. -If NO_DEFAULT_PATH is specified, then no additional paths are +Options include: + +``NAMES`` + Specify one or more possible names for the |SEARCH_XXX|. + +``HINTS``, ``PATHS`` + Specify directories to search in addition to the default locations. + The ``ENV var`` sub-option reads paths from a system environment + variable. + +``PATH_SUFFIXES`` + Specify additional subdirectories to check below each directory + location otherwise considered. + +``DOC`` + Specify the documentation string for the ```` cache entry. + +If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. -If NO_DEFAULT_PATH is not specified, the search process is as follows: +If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: - /|XXX_SUBDIR| for each in CMAKE_PREFIX_PATH + |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_PREFIX_PATH` .. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace:: - /|XXX_SUBDIR| for each /[s]bin in PATH, and - /|XXX_SUBDIR| for other entries in PATH + |prefix_XXX_SUBDIR| for each ``/[s]bin`` in ``PATH``, and + |entry_XXX_SUBDIR| for other entries in ``PATH`` .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: - /|XXX_SUBDIR| for each in CMAKE_SYSTEM_PREFIX_PATH + |prefix_XXX_SUBDIR| for each ```` in + :variable:`CMAKE_SYSTEM_PREFIX_PATH` 1. Search paths specified in cmake-specific cache variables. - These are intended to be used on the command line with a -DVAR=value. - This can be skipped if NO_CMAKE_PATH is passed. + These are intended to be used on the command line with a ``-DVAR=value``. + This can be skipped if ``NO_CMAKE_PATH`` is passed. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -70,24 +76,24 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows: 2. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration. - This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -3. Search the paths specified by the HINTS option. +3. Search the paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. - Hard-coded guesses should be specified with the PATHS option. + Hard-coded guesses should be specified with the ``PATHS`` option. 4. Search the standard system environment variables. - This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. * |SYSTEM_ENVIRONMENT_PATH_XXX| 5. Search cmake variables defined in the Platform files - for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH + for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt index b5cab68b8..fab23037c 100644 --- a/Help/command/FIND_XXX_ROOT.txt +++ b/Help/command/FIND_XXX_ROOT.txt @@ -16,8 +16,14 @@ search there too. By default at first the directories listed in directory is searched, and then the non-rooted directories will be searched. The default behavior can be adjusted by setting |CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually -overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH -the search order will be as described above. If -NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be -used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted -directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched. +overridden on a per-call basis using options: + +``CMAKE_FIND_ROOT_PATH_BOTH`` + Search in the order described above. + +``NO_CMAKE_FIND_ROOT_PATH`` + Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable. + +``ONLY_CMAKE_FIND_ROOT_PATH`` + Search only the re-rooted directories and directories below + :variable:`CMAKE_STAGING_PREFIX`. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index be309a530..bf7a91993 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -5,24 +5,27 @@ find_file .. |NAMES| replace:: NAMES name1 [name2 ...] .. |SEARCH_XXX| replace:: full path to a file .. |SEARCH_XXX_DESC| replace:: full path to named file -.. |XXX_SUBDIR| replace:: include +.. |prefix_XXX_SUBDIR| replace:: ``/include`` +.. |entry_XXX_SUBDIR| replace:: ``/include`` .. |CMAKE_PREFIX_PATH_XXX| replace:: - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH -.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` +.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE, - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in PATH itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``, + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the + directories in ``PATH`` itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH -.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index e3dcd2ba0..5d07574ad 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -5,33 +5,36 @@ find_library .. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] .. |SEARCH_XXX| replace:: library .. |SEARCH_XXX_DESC| replace:: library -.. |XXX_SUBDIR| replace:: lib +.. |prefix_XXX_SUBDIR| replace:: ``/lib`` +.. |entry_XXX_SUBDIR| replace:: ``/lib`` .. |CMAKE_PREFIX_PATH_XXX| replace:: - /lib/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH -.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + ``/lib/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH` +.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB, - /lib/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in PATH itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``, + ``/lib/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, + and the directories in ``PATH`` itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: - /lib/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_LIBRARY_PATH -.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH + ``/lib/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY` .. include:: FIND_XXX.txt -When more than one value is given to the NAMES option this command by +When more than one value is given to the ``NAMES`` option this command by default will consider one name at a time and search every directory -for it. The NAMES_PER_DIR option tells this command to consider one +for it. The ``NAMES_PER_DIR`` option tells this command to consider one directory at a time and search for all names in it. Each library name given to the ``NAMES`` option is first considered @@ -40,14 +43,14 @@ prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one may specify library file names such as ``libfoo.a`` directly. This can be used to locate static libraries on UNIX-like systems. -If the library found is a framework, then VAR will be set to the full -path to the framework /A.framework. When a full path to a -framework is used as a library, CMake will use a -framework A, and a --F to link the framework to the target. +If the library found is a framework, then ```` will be set to the full +path to the framework ``/A.framework``. When a full path to a +framework is used as a library, CMake will use a ``-framework A``, and a +``-F`` to link the framework to the target. -If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all search -paths will be tested as normal, with "64/" appended, and with all -matches of "lib/" replaced with "lib64/". This property is +If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set +all search paths will be tested as normal, with ``64/`` appended, and +with all matches of ``lib/`` replaced with ``lib64/``. This property is automatically set for the platforms that are known to need it if at -least one of the languages supported by the PROJECT command is -enabled. +least one of the languages supported by the :command:`project` command +is enabled. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index b5a6e373f..4403cb5bc 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -5,31 +5,34 @@ find_path .. |NAMES| replace:: NAMES name1 [name2 ...] .. |SEARCH_XXX| replace:: file in a directory .. |SEARCH_XXX_DESC| replace:: directory containing the named file -.. |XXX_SUBDIR| replace:: include +.. |prefix_XXX_SUBDIR| replace:: ``/include`` +.. |entry_XXX_SUBDIR| replace:: ``/include`` .. |CMAKE_PREFIX_PATH_XXX| replace:: - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH -.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` +.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE, - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in PATH itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``, + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the + directories in ``PATH`` itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: - /include/ if CMAKE_LIBRARY_ARCHITECTURE is set, and - |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH -.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` .. include:: FIND_XXX.txt -When searching for frameworks, if the file is specified as A/b.h, then -the framework search will look for A.framework/Headers/b.h. If that +When searching for frameworks, if the file is specified as ``A/b.h``, then +the framework search will look for ``A.framework/Headers/b.h``. If that is found the path will be set to the path to the framework. CMake -will convert this to the correct -F option to include the file. +will convert this to the correct ``-F`` option to include the file. diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index c62a8a5d2..2a5ce9a8d 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -5,19 +5,22 @@ find_program .. |NAMES| replace:: NAMES name1 [name2 ...] .. |SEARCH_XXX| replace:: program .. |SEARCH_XXX_DESC| replace:: program -.. |XXX_SUBDIR| replace:: [s]bin +.. |prefix_XXX_SUBDIR| replace:: ``/[s]bin`` +.. |entry_XXX_SUBDIR| replace:: ``/[s]bin`` .. |CMAKE_PREFIX_PATH_XXX| replace:: |CMAKE_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_XXX_PATH| replace:: CMAKE_PROGRAM_PATH -.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_APPBUNDLE_PATH +.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` +.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH`` .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| -.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_PROGRAM_PATH -.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_PROGRAM_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH` .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`