From 3de3544fcd38680652d5bbe0790b78477ffa26f1 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 8 Jun 2015 15:52:21 -0400 Subject: [PATCH] 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`