diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 8801a9fdfe..707568cf79 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands. Calling Commands ^^^^^^^^^^^^^^^^ -.. _CALL: - -.. code-block:: cmake - +.. signature:: cmake_language(CALL [...]) -Calls the named ```` with the given arguments (if any). -For example, the code: + Calls the named ```` with the given arguments (if any). + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(message_command "message") - cmake_language(CALL ${message_command} STATUS "Hello World!") + set(message_command "message") + cmake_language(CALL ${message_command} STATUS "Hello World!") -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - message(STATUS "Hello World!") + message(STATUS "Hello World!") -.. note:: - To ensure consistency of the code, the following commands are not allowed: + .. note:: + To ensure consistency of the code, the following commands are not allowed: - * ``if`` / ``elseif`` / ``else`` / ``endif`` - * ``block`` / ``endblock`` - * ``while`` / ``endwhile`` - * ``foreach`` / ``endforeach`` - * ``function`` / ``endfunction`` - * ``macro`` / ``endmacro`` + * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``block`` / ``endblock`` + * ``while`` / ``endwhile`` + * ``foreach`` / ``endforeach`` + * ``function`` / ``endfunction`` + * ``macro`` / ``endmacro`` Evaluating Code ^^^^^^^^^^^^^^^ -.. _EVAL: - -.. code-block:: cmake - +.. signature:: cmake_language(EVAL CODE ...) + :target: EVAL -Evaluates the ``...`` as CMake code. + Evaluates the ``...`` as CMake code. -For example, the code: + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - cmake_language(EVAL CODE " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + cmake_language(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) - include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) Deferring Calls ^^^^^^^^^^^^^^^ .. versionadded:: 3.19 -.. _DEFER: - -.. code-block:: cmake - +.. signature:: cmake_language(DEFER ... CALL [...]) -Schedules a call to the named ```` with the given arguments (if any) -to occur at a later time. By default, deferred calls are executed as if -written at the end of the current directory's ``CMakeLists.txt`` file, -except that they run even after a :command:`return` call. Variable -references in arguments are evaluated at the time the deferred call is -executed. + Schedules a call to the named ```` with the given arguments (if any) + to occur at a later time. By default, deferred calls are executed as if + written at the end of the current directory's ``CMakeLists.txt`` file, + except that they run even after a :command:`return` call. Variable + references in arguments are evaluated at the time the deferred call is + executed. -The options are: + The options are: -``DIRECTORY `` - Schedule the call for the end of the given directory instead of the - current directory. The ```` may reference either a source - directory or its corresponding binary directory. Relative paths are - treated as relative to the current source directory. + ``DIRECTORY `` + Schedule the call for the end of the given directory instead of the + current directory. The ```` may reference either a source + directory or its corresponding binary directory. Relative paths are + treated as relative to the current source directory. - The given directory must be known to CMake, being either the top-level - directory or one added by :command:`add_subdirectory`. Furthermore, - the given directory must not yet be finished processing. This means - it can be the current directory or one of its ancestors. + The given directory must be known to CMake, being either the top-level + directory or one added by :command:`add_subdirectory`. Furthermore, + the given directory must not yet be finished processing. This means + it can be the current directory or one of its ancestors. -``ID `` - Specify an identification for the deferred call. - The ```` may not be empty and may not begin with a capital letter ``A-Z``. - The ```` may begin with an underscore (``_``) only if it was generated - automatically by an earlier call that used ``ID_VAR`` to get the id. + ``ID `` + Specify an identification for the deferred call. + The ```` may not be empty and may not begin with a capital letter ``A-Z``. + The ```` may begin with an underscore (``_``) only if it was generated + automatically by an earlier call that used ``ID_VAR`` to get the id. -``ID_VAR `` - Specify a variable in which to store the identification for the - deferred call. If ``ID `` is not given, a new identification - will be generated and the generated id will start with an underscore (``_``). + ``ID_VAR `` + Specify a variable in which to store the identification for the + deferred call. If ``ID `` is not given, a new identification + will be generated and the generated id will start with an underscore (``_``). -The currently scheduled list of deferred calls may be retrieved: + The currently scheduled list of deferred calls may be retrieved: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS ) + cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS ) -This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids. The ids are for the directory scope in which -the calls have been deferred to (i.e. where they will be executed), which can -be different to the scope in which they were created. The ``DIRECTORY`` -option can be used to specify the scope for which to retrieve the call ids. -If that option is not given, the call ids for the current directory scope will -be returned. + This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids. The ids are for the directory scope in which + the calls have been deferred to (i.e. where they will be executed), which can + be different to the scope in which they were created. The ``DIRECTORY`` + option can be used to specify the scope for which to retrieve the call ids. + If that option is not given, the call ids for the current directory scope + will be returned. -Details of a specific call may be retrieved from its id: + Details of a specific call may be retrieved from its id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] GET_CALL ) + cmake_language(DEFER [DIRECTORY ] GET_CALL ) -This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be -called, and the remaining elements are its unevaluated arguments (any -contained ``;`` characters are included literally and cannot be distinguished -from multiple arguments). If multiple calls are scheduled with the same id, -this retrieves the first one. If no call is scheduled with the given id in -the specified ``DIRECTORY`` scope (or the current directory scope if no -``DIRECTORY`` option is given), this stores an empty string in the variable. + This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be + called, and the remaining elements are its unevaluated arguments (any + contained ``;`` characters are included literally and cannot be distinguished + from multiple arguments). If multiple calls are scheduled with the same id, + this retrieves the first one. If no call is scheduled with the given id in + the specified ``DIRECTORY`` scope (or the current directory scope if no + ``DIRECTORY`` option is given), this stores an empty string in the variable. -Deferred calls may be canceled by their id: + Deferred calls may be canceled by their id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) + cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) -This cancels all deferred calls matching any of the given ids in the specified -``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option -is given). Unknown ids are silently ignored. + This cancels all deferred calls matching any of the given ids in the specified + ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option + is given). Unknown ids are silently ignored. Deferred Call Examples """""""""""""""""""""" @@ -229,8 +221,6 @@ also prints:: Deferred Message 1 Deferred Message 2 - -.. _SET_DEPENDENCY_PROVIDER: .. _dependency_providers: Dependency Providers @@ -241,51 +231,50 @@ Dependency Providers .. note:: A high-level introduction to this feature can be found in the :ref:`Using Dependencies Guide `. -.. code-block:: cmake - +.. signature:: cmake_language(SET_DEPENDENCY_PROVIDER SUPPORTED_METHODS ...) -When a call is made to :command:`find_package` or -:command:`FetchContent_MakeAvailable`, the call may be forwarded to a -dependency provider which then has the opportunity to fulfill the request. -If the request is for one of the ```` specified when the provider -was set, CMake calls the provider's ```` with a set of -method-specific arguments. If the provider does not fulfill the request, -or if the provider doesn't support the request's method, or no provider -is set, the built-in :command:`find_package` or -:command:`FetchContent_MakeAvailable` implementation is used to fulfill -the request in the usual way. + When a call is made to :command:`find_package` or + :command:`FetchContent_MakeAvailable`, the call may be forwarded to a + dependency provider which then has the opportunity to fulfill the request. + If the request is for one of the ```` specified when the provider + was set, CMake calls the provider's ```` with a set of + method-specific arguments. If the provider does not fulfill the request, + or if the provider doesn't support the request's method, or no provider + is set, the built-in :command:`find_package` or + :command:`FetchContent_MakeAvailable` implementation is used to fulfill + the request in the usual way. -One or more of the following values can be specified for the ```` -when setting the provider: + One or more of the following values can be specified for the ```` + when setting the provider: -``FIND_PACKAGE`` - The provider command accepts :command:`find_package` requests. + ``FIND_PACKAGE`` + The provider command accepts :command:`find_package` requests. -``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` - The provider command accepts :command:`FetchContent_MakeAvailable` - requests. It expects each dependency to be fed to the provider command - one at a time, not the whole list in one go. + ``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` + The provider command accepts :command:`FetchContent_MakeAvailable` + requests. It expects each dependency to be fed to the provider command + one at a time, not the whole list in one go. -Only one provider can be set at any point in time. If a provider is already -set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new -provider replaces the previously set one. The specified ```` must -already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. -As a special case, providing an empty string for the ```` and no -```` will discard any previously set provider. + Only one provider can be set at any point in time. If a provider is already + set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new + provider replaces the previously set one. The specified ```` must + already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. + As a special case, providing an empty string for the ```` and no + ```` will discard any previously set provider. -The dependency provider can only be set while processing one of the files -specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. -Thus, dependency providers can only be set as part of the first call to -:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` -outside of that context will result in an error. + The dependency provider can only be set while processing one of the files + specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. + Thus, dependency providers can only be set as part of the first call to + :command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` + outside of that context will result in an error. -.. note:: - The choice of dependency provider should always be under the user's control. - As a convenience, a project may choose to provide a file that users can - list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but - the use of such a file should always be the user's choice. + .. note:: + The choice of dependency provider should always be under the user's control. + As a convenience, a project may choose to provide a file that users can + list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but + the use of such a file should always be the user's choice. Provider commands """"""""""""""""" @@ -499,23 +488,21 @@ Getting current message log level .. versionadded:: 3.25 -.. _GET_MESSAGE_LOG_LEVEL: .. _query_message_log_level: -.. code-block:: cmake - +.. signature:: cmake_language(GET_MESSAGE_LOG_LEVEL ) -Writes the current :command:`message` logging level -into the given ````. + Writes the current :command:`message` logging level + into the given ````. -See :command:`message` for the possible logging levels. + See :command:`message` for the possible logging levels. -The current message logging level can be set either using the -:option:`--log-level ` -command line option of the :manual:`cmake(1)` program or using -the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. + The current message logging level can be set either using the + :option:`--log-level ` + command line option of the :manual:`cmake(1)` program or using + the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. -If both the command line option and the variable are set, the command line -option takes precedence. If neither are set, the default logging level -is returned. + If both the command line option and the variable are set, the command line + option takes precedence. If neither are set, the default logging level + is returned. diff --git a/Help/command/string.rst b/Help/command/string.rst index c24b9bc16a..b47fa098d2 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -45,16 +45,16 @@ Synopsis `JSON`_ string(JSON [ERROR_VARIABLE ] - {:ref:`GET ` | :ref:`TYPE ` | :ref:`LENGTH ` | :ref:`REMOVE `} + {`GET `_ | `TYPE `_ | `LENGTH `_ | `REMOVE `_} [ ...]) string(JSON [ERROR_VARIABLE ] - :ref:`MEMBER ` + `MEMBER `_ [ ...] ) string(JSON [ERROR_VARIABLE ] - :ref:`SET ` + `SET `_ [ ...] ) string(JSON [ERROR_VARIABLE ] - :ref:`EQUAL ` ) + `EQUAL `_ ) Search and Replace ^^^^^^^^^^^^^^^^^^ @@ -62,75 +62,60 @@ Search and Replace Search and Replace With Plain Strings """"""""""""""""""""""""""""""""""""" -.. _FIND: - -.. code-block:: cmake - +.. signature:: string(FIND [REVERSE]) -Return the position where the given ```` was found in -the supplied ````. If the ``REVERSE`` flag was used, the command will -search for the position of the last occurrence of the specified -````. If the ```` is not found, a position of -1 is -returned. + Return the position where the given ```` was found in + the supplied ````. If the ``REVERSE`` flag was used, the command + will search for the position of the last occurrence of the specified + ````. If the ```` is not found, a position of -1 is + returned. -The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. -The index stored in ```` will also be counted in bytes, -so strings containing multi-byte characters may lead to unexpected results. - -.. _REPLACE: - -.. code-block:: cmake + The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. + The index stored in ```` will also be counted in bytes, + so strings containing multi-byte characters may lead to unexpected results. +.. signature:: string(REPLACE [...]) -Replace all occurrences of ```` in the ```` -with ```` and store the result in the ````. + Replace all occurrences of ```` in the ```` + with ```` and store the result in the ````. Search and Replace With Regular Expressions """"""""""""""""""""""""""""""""""""""""""" -.. _`REGEX MATCH`: - -.. code-block:: cmake - +.. signature:: string(REGEX MATCH [...]) -Match the ```` once and store the match in the -````. -All ```` arguments are concatenated before matching. -Regular expressions are specified in the subsection just below. - -.. _`REGEX MATCHALL`: - -.. code-block:: cmake + Match the ```` once and store the match in the + ````. + All ```` arguments are concatenated before matching. + Regular expressions are specified in the subsection just below. +.. signature:: string(REGEX MATCHALL [...]) -Match the ```` as many times as possible and store the -matches in the ```` as a list. -All ```` arguments are concatenated before matching. - -.. _`REGEX REPLACE`: - -.. code-block:: cmake + Match the ```` as many times as possible and store the + matches in the ```` as a list. + All ```` arguments are concatenated before matching. +.. signature:: string(REGEX REPLACE [...]) -Match the ```` as many times as possible and substitute -the ```` for the match in the output. -All ```` arguments are concatenated before matching. + Match the ```` as many times as possible and substitute + the ```` for the match in the output. + All ```` arguments are concatenated before matching. -The ```` may refer to parenthesis-delimited -subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that -two backslashes (``\\1``) are required in CMake code to get a backslash -through argument parsing. + The ```` may refer to parenthesis-delimited + subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that + two backslashes (``\\1``) are required in CMake code to get a backslash + through argument parsing. .. _`Regex Specification`: @@ -201,130 +186,100 @@ newlines, and backslashes (respectively) to pass in a regex. For example: Manipulation ^^^^^^^^^^^^ -.. _APPEND: - -.. code-block:: cmake - +.. signature:: string(APPEND [...]) -.. versionadded:: 3.4 + .. versionadded:: 3.4 -Append all the ```` arguments to the string. - -.. _PREPEND: - -.. code-block:: cmake + Append all the ```` arguments to the string. +.. signature:: string(PREPEND [...]) -.. versionadded:: 3.10 + .. versionadded:: 3.10 -Prepend all the ```` arguments to the string. - -.. _CONCAT: - -.. code-block:: cmake + Prepend all the ```` arguments to the string. +.. signature:: string(CONCAT [...]) -Concatenate all the ```` arguments together and store -the result in the named ````. - -.. _JOIN: - -.. code-block:: cmake + Concatenate all the ```` arguments together and store + the result in the named ````. +.. signature:: string(JOIN [...]) -.. versionadded:: 3.12 + .. versionadded:: 3.12 -Join all the ```` arguments together using the ```` -string and store the result in the named ````. + Join all the ```` arguments together using the ```` + string and store the result in the named ````. -To join a list's elements, prefer to use the ``JOIN`` operator -from the :command:`list` command. This allows for the elements to have -special characters like ``;`` in them. - -.. _TOLOWER: - -.. code-block:: cmake + To join a list's elements, prefer to use the ``JOIN`` operator + from the :command:`list` command. This allows for the elements to have + special characters like ``;`` in them. +.. signature:: string(TOLOWER ) -Convert ```` to lower characters. - -.. _TOUPPER: - -.. code-block:: cmake + Convert ```` to lower characters. +.. signature:: string(TOUPPER ) -Convert ```` to upper characters. - -.. _LENGTH: - -.. code-block:: cmake + Convert ```` to upper characters. +.. signature:: string(LENGTH ) -Store in an ```` a given string's length in bytes. -Note that this means if ```` contains multi-byte characters, the -result stored in ```` will *not* be the number of characters. - -.. _SUBSTRING: - -.. code-block:: cmake + Store in an ```` a given string's length in bytes. + Note that this means if ```` contains multi-byte characters, + the result stored in ```` will *not* be + the number of characters. +.. signature:: string(SUBSTRING ) -Store in an ```` a substring of a given ````. If -```` is ``-1`` the remainder of the string starting at ```` -will be returned. + Store in an ```` a substring of a given ````. If + ```` is ``-1`` the remainder of the string starting at ```` + will be returned. -.. versionchanged:: 3.2 - If ```` is shorter than ```` then the end of the string - is used instead. Previous versions of CMake reported an error in this case. + .. versionchanged:: 3.2 + If ```` is shorter than ```` + then the end of the string is used instead. + Previous versions of CMake reported an error in this case. -Both ```` and ```` are counted in bytes, so care must -be exercised if ```` could contain multi-byte characters. - -.. _STRIP: - -.. code-block:: cmake + Both ```` and ```` are counted in bytes, so care must + be exercised if ```` could contain multi-byte characters. +.. signature:: string(STRIP ) -Store in an ```` a substring of a given ```` with -leading and trailing spaces removed. - -.. _GENEX_STRIP: - -.. code-block:: cmake + Store in an ```` a substring of a given ```` + with leading and trailing spaces removed. +.. signature:: string(GENEX_STRIP ) -.. versionadded:: 3.1 + .. versionadded:: 3.1 -Strip any :manual:`generator expressions ` -from the input ```` and store the result in the ````. - -.. _REPEAT: - -.. code-block:: cmake + Strip any :manual:`generator expressions ` + from the input ```` and store the result + in the ````. +.. signature:: string(REPEAT ) -.. versionadded:: 3.15 + .. versionadded:: 3.15 -Produce the output string as the input ```` repeated ```` times. + Produce the output string as the input ```` + repeated ```` times. Comparison ^^^^^^^^^^ .. _COMPARE: -.. code-block:: cmake - +.. signature:: string(COMPARE LESS ) string(COMPARE GREATER ) string(COMPARE EQUAL ) @@ -332,240 +287,217 @@ Comparison string(COMPARE LESS_EQUAL ) string(COMPARE GREATER_EQUAL ) -Compare the strings and store true or false in the ````. + Compare the strings and store true or false in the ````. -.. versionadded:: 3.7 - Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. + .. versionadded:: 3.7 + Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. .. _`Supported Hash Algorithms`: Hashing ^^^^^^^ -.. _`HASH`: - -.. code-block:: cmake - +.. signature:: string( ) + :target: HASH -Compute a cryptographic hash of the ```` string. -The supported ```` algorithm names are: + Compute a cryptographic hash of the ```` string. + The supported ```` algorithm names are: -``MD5`` - Message-Digest Algorithm 5, RFC 1321. -``SHA1`` - US Secure Hash Algorithm 1, RFC 3174. -``SHA224`` - US Secure Hash Algorithms, RFC 4634. -``SHA256`` - US Secure Hash Algorithms, RFC 4634. -``SHA384`` - US Secure Hash Algorithms, RFC 4634. -``SHA512`` - US Secure Hash Algorithms, RFC 4634. -``SHA3_224`` - Keccak SHA-3. -``SHA3_256`` - Keccak SHA-3. -``SHA3_384`` - Keccak SHA-3. -``SHA3_512`` - Keccak SHA-3. + ``MD5`` + Message-Digest Algorithm 5, RFC 1321. + ``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. + ``SHA224`` + US Secure Hash Algorithms, RFC 4634. + ``SHA256`` + US Secure Hash Algorithms, RFC 4634. + ``SHA384`` + US Secure Hash Algorithms, RFC 4634. + ``SHA512`` + US Secure Hash Algorithms, RFC 4634. + ``SHA3_224`` + Keccak SHA-3. + ``SHA3_256`` + Keccak SHA-3. + ``SHA3_384`` + Keccak SHA-3. + ``SHA3_512`` + Keccak SHA-3. -.. versionadded:: 3.8 - Added the ``SHA3_*`` hash algorithms. + .. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. Generation ^^^^^^^^^^ -.. _ASCII: - -.. code-block:: cmake - +.. signature:: string(ASCII [ ...] ) -Convert all numbers into corresponding ASCII characters. - -.. _HEX: - -.. code-block:: cmake + Convert all numbers into corresponding ASCII characters. +.. signature:: string(HEX ) -.. versionadded:: 3.18 + .. versionadded:: 3.18 -Convert each byte in the input ```` to its hexadecimal representation -and store the concatenated hex digits in the ````. Letters in -the output (``a`` through ``f``) are in lowercase. - -.. _CONFIGURE: - -.. code-block:: cmake + Convert each byte in the input ```` to its hexadecimal representation + and store the concatenated hex digits in the ````. + Letters in the output (``a`` through ``f``) are in lowercase. +.. signature:: string(CONFIGURE [@ONLY] [ESCAPE_QUOTES]) -Transform a ```` like :command:`configure_file` transforms a file. - -.. _MAKE_C_IDENTIFIER: - -.. code-block:: cmake + Transform a ```` like :command:`configure_file` transforms a file. +.. signature:: string(MAKE_C_IDENTIFIER ) -Convert each non-alphanumeric character in the input ```` to an -underscore and store the result in the ````. If the first -character of the ```` is a digit, an underscore will also be prepended -to the result. - -.. _RANDOM: - -.. code-block:: cmake + Convert each non-alphanumeric character in the input ```` to an + underscore and store the result in the ````. If the first + character of the ```` is a digit, an underscore will also be + prepended to the result. +.. signature:: string(RANDOM [LENGTH ] [ALPHABET ] [RANDOM_SEED ] ) -Return a random string of given ```` consisting of -characters from the given ````. Default length is 5 characters -and default alphabet is all numbers and upper and lower case letters. -If an integer ``RANDOM_SEED`` is given, its value will be used to seed the -random number generator. - -.. _TIMESTAMP: - -.. code-block:: cmake + Return a random string of given ```` consisting of + characters from the given ````. Default length is 5 characters + and default alphabet is all numbers and upper and lower case letters. + If an integer ``RANDOM_SEED`` is given, its value will be used to seed the + random number generator. +.. signature:: string(TIMESTAMP [] [UTC]) -Write a string representation of the current date -and/or time to the ````. + Write a string representation of the current date + and/or time to the ````. -If the command is unable to obtain a timestamp, the ```` -will be set to the empty string ``""``. + If the command is unable to obtain a timestamp, the ```` + will be set to the empty string ``""``. -The optional ``UTC`` flag requests the current date/time representation to -be in Coordinated Universal Time (UTC) rather than local time. + The optional ``UTC`` flag requests the current date/time representation to + be in Coordinated Universal Time (UTC) rather than local time. -The optional ```` may contain the following format -specifiers: + The optional ```` may contain the following format + specifiers: + + ``%%`` + .. versionadded:: 3.8 + + A literal percent sign (%). + + ``%d`` + The day of the current month (01-31). + + ``%H`` + The hour on a 24-hour clock (00-23). + + ``%I`` + The hour on a 12-hour clock (01-12). + + ``%j`` + The day of the current year (001-366). + + ``%m`` + The month of the current year (01-12). + + ``%b`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + + ``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + + ``%M`` + The minute of the current hour (00-59). + + ``%s`` + .. versionadded:: 3.6 + + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + + ``%S`` + The second of the current minute. 60 represents a leap second. (00-60) + + ``%f`` + .. versionadded:: 3.23 + + The microsecond of the current second (000000-999999). + + ``%U`` + The week number of the current year (00-53). + + ``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + + ``%w`` + The day of the current week. 0 is Sunday. (0-6) + + ``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + + ``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + + ``%y`` + The last two digits of the current year (00-99). + + ``%Y`` + The current year. + + ``%z`` + .. versionadded:: 3.26 + + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. + + ``%Z`` + .. versionadded:: 3.26 + + The time zone name. + + Unknown format specifiers will be ignored and copied to the output + as-is. + + If no explicit ```` is given, it will default to: + + :: + + %Y-%m-%dT%H:%M:%S for local time. + %Y-%m-%dT%H:%M:%SZ for UTC. -``%%`` .. versionadded:: 3.8 + If the ``SOURCE_DATE_EPOCH`` environment variable is set, + its value will be used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. - A literal percent sign (%). - -``%d`` - The day of the current month (01-31). - -``%H`` - The hour on a 24-hour clock (00-23). - -``%I`` - The hour on a 12-hour clock (01-12). - -``%j`` - The day of the current year (001-366). - -``%m`` - The month of the current year (01-12). - -``%b`` - .. versionadded:: 3.7 - - Abbreviated month name (e.g. Oct). - -``%B`` - .. versionadded:: 3.10 - - Full month name (e.g. October). - -``%M`` - The minute of the current hour (00-59). - -``%s`` - .. versionadded:: 3.6 - - Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - -``%S`` - The second of the current minute. 60 represents a leap second. (00-60) - -``%f`` - .. versionadded:: 3.23 - - The microsecond of the current second (000000-999999). - -``%U`` - The week number of the current year (00-53). - -``%V`` - .. versionadded:: 3.22 - - The ISO 8601 week number of the current year (01-53). - -``%w`` - The day of the current week. 0 is Sunday. (0-6) - -``%a`` - .. versionadded:: 3.7 - - Abbreviated weekday name (e.g. Fri). - -``%A`` - .. versionadded:: 3.10 - - Full weekday name (e.g. Friday). - -``%y`` - The last two digits of the current year (00-99). - -``%Y`` - The current year. - -``%z`` - .. versionadded:: 3.26 - - The offset of the time zone from UTC, in hours and minutes, - with format ``+hhmm`` or ``-hhmm``. - -``%Z`` - .. versionadded:: 3.26 - - The time zone name. - -Unknown format specifiers will be ignored and copied to the output -as-is. - -If no explicit ```` is given, it will default to: - -:: - - %Y-%m-%dT%H:%M:%S for local time. - %Y-%m-%dT%H:%M:%SZ for UTC. - -.. versionadded:: 3.8 - If the ``SOURCE_DATE_EPOCH`` environment variable is set, - its value will be used instead of the current time. - See https://reproducible-builds.org/specs/source-date-epoch/ for details. - -.. _UUID: - -.. code-block:: cmake - +.. signature:: string(UUID NAMESPACE NAME TYPE [UPPER]) -.. versionadded:: 3.1 + .. versionadded:: 3.1 -Create a universally unique identifier (aka GUID) as per RFC4122 -based on the hash of the combined values of ```` -(which itself has to be a valid UUID) and ````. -The hash algorithm can be either ``MD5`` (Version 3 UUID) or -``SHA1`` (Version 5 UUID). -A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each ``x`` represents a lower case hexadecimal character. -Where required, an uppercase representation can be requested -with the optional ``UPPER`` flag. + Create a universally unique identifier (aka GUID) as per RFC4122 + based on the hash of the combined values of ```` + (which itself has to be a valid UUID) and ````. + The hash algorithm can be either ``MD5`` (Version 3 UUID) or + ``SHA1`` (Version 5 UUID). + A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` + where each ``x`` represents a lower case hexadecimal character. + Where required, an uppercase representation can be requested + with the optional ``UPPER`` flag. .. _JSON: @@ -586,78 +518,72 @@ Functionality for querying a JSON string. option is not present, a fatal error message is generated. If no error occurs, the ```` will be set to ``NOTFOUND``. -.. _JSON_GET: -.. code-block:: cmake - +.. signature:: string(JSON [ERROR_VARIABLE ] GET [ ...]) + :target: JSON GET -Get an element from ```` at the location given -by the list of ```` arguments. -Array and object elements will be returned as a JSON string. -Boolean elements will be returned as ``ON`` or ``OFF``. -Null elements will be returned as an empty string. -Number and string types will be returned as strings. - -.. _JSON_TYPE: -.. code-block:: cmake + Get an element from ```` at the location given + by the list of ```` arguments. + Array and object elements will be returned as a JSON string. + Boolean elements will be returned as ``ON`` or ``OFF``. + Null elements will be returned as an empty string. + Number and string types will be returned as strings. +.. signature:: string(JSON [ERROR_VARIABLE ] TYPE [ ...]) + :target: JSON TYPE -Get the type of an element in ```` at the location -given by the list of ```` arguments. The ```` -will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, -``ARRAY``, or ``OBJECT``. - -.. _JSON_MEMBER: -.. code-block:: cmake + Get the type of an element in ```` at the location + given by the list of ```` arguments. The ```` + will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, + ``ARRAY``, or ``OBJECT``. +.. signature:: string(JSON [ERROR_VARIABLE ] MEMBER [ ...] ) + :target: JSON MEMBER -Get the name of the ````-th member in ```` at the location -given by the list of ```` arguments. -Requires an element of object type. - -.. _JSON_LENGTH: -.. code-block:: cmake + Get the name of the ````-th member in ```` + at the location given by the list of ```` arguments. + Requires an element of object type. +.. signature:: string(JSON [ERROR_VARIABLE ] LENGTH [ ...]) + :target: JSON LENGTH -Get the length of an element in ```` at the location -given by the list of ```` arguments. -Requires an element of array or object type. - -.. _JSON_REMOVE: -.. code-block:: cmake + Get the length of an element in ```` at the location + given by the list of ```` arguments. + Requires an element of array or object type. +.. signature:: string(JSON [ERROR_VARIABLE ] REMOVE [ ...]) + :target: JSON REMOVE -Remove an element from ```` at the location -given by the list of ```` arguments. The JSON string -without the removed element will be stored in ````. - -.. _JSON_SET: -.. code-block:: cmake + Remove an element from ```` at the location + given by the list of ```` arguments. The JSON string + without the removed element will be stored in ````. +.. signature:: string(JSON [ERROR_VARIABLE ] SET [ ...] ) + :target: JSON SET -Set an element in ```` at the location -given by the list of ```` arguments to ````. -The contents of ```` should be valid JSON. - -.. _JSON_EQUAL: -.. code-block:: cmake + Set an element in ```` at the location + given by the list of ```` arguments to ````. + The contents of ```` should be valid JSON. +.. signature:: string(JSON [ERROR_VARIABLE ] EQUAL ) + :target: JSON EQUAL -Compare the two JSON objects given by ```` and ```` -for equality. The contents of ```` and ```` -should be valid JSON. The ```` will be set to a true value if the -JSON objects are considered equal, or a false value otherwise. + Compare the two JSON objects given by ```` + and ```` for equality. The contents of ```` + and ```` should be valid JSON. The ```` + will be set to a true value if the JSON objects are considered equal, + or a false value otherwise. diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index db92022089..a340739c1b 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -168,46 +168,154 @@ documentation: See the `cmake-variables(7)`_ manual and the `set()`_ command. -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help//.rst`` to a domain object with -type ````. The object name is extracted from the document title, -which is expected to be of the form:: +Documentation objects in the CMake Domain come from two sources: - - ------------- +1. The CMake extension to Sphinx transforms every document named + with the form ``Help//.rst`` to a domain object with + type ````. The object name is extracted from the document title, + which is expected to be of the form:: -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, ``<``, or ``$``. If no such title appears -literally in the ``.rst`` file, the object name is the ````. -If a title does appear, it is expected that ```` is equal -to ```` with any ``<`` and ``>`` characters removed, -or in the case of a ``$`` or ``$``, the -``genex-name``. + + ------------- -Second, the CMake Domain provides directives to define objects inside -other documents: + and to appear at or near the top of the ``.rst`` file before any other lines + starting in a letter, digit, ``<``, or ``$``. If no such title appears + literally in the ``.rst`` file, the object name is the ````. + If a title does appear, it is expected that ```` is equal + to ```` with any ``<`` and ``>`` characters removed, + or in the case of a ``$`` or ``$``, the + ``genex-name``. + +2. `CMake Domain directives`_ may be used in documents to explicitly define + some object types: + + * `command directive`_ + * `envvar directive`_ + * `genex directive`_ + * `variable directive`_ + + Object types for which no directive is available must be defined using + the document transform above. + +CMake Domain Directives +----------------------- + +The CMake Domain provides the following directives. + +``command`` directive +^^^^^^^^^^^^^^^^^^^^^ + +Document a "command" object: .. code-block:: rst - .. command:: + .. command:: - This indented block documents . + This indented block documents . - .. envvar:: +The directive requires a single argument, the command name. - This indented block documents . +``envvar`` directive +^^^^^^^^^^^^^^^^^^^^ + +Document an "envvar" object: + +.. code-block:: rst + + .. envvar:: + + This indented block documents . + +The directive requires a single argument, the environment variable name. + +``genex`` directive +^^^^^^^^^^^^^^^^^^^ + +Document a "genex" object: + +.. code-block:: rst .. genex:: This indented block documents . +The directive requires a single argument, the generator expression name. + +``signature`` directive +^^^^^^^^^^^^^^^^^^^^^^^ + +Document `CMake Command Signatures `_ +within a ``Help/command/.rst`` document. + +.. code-block:: rst + + .. signature:: () + + This indented block documents one or more signatures of a CMake command. + +The ``signature`` directive requires one argument, the signature summary: + +* One or more signatures must immediately follow the ``::``. + The first signature may optionally be placed on the same line. + A blank line following the ``signature`` directive will result in a + documentation generation error: ``1 argument(s) required, 0 supplied``. + +* Signatures may be split across multiple lines, but the final ``)`` of each + signature must be the last character on its line. + +* Blank lines between signatures are not allowed. (Content after a blank line + is treated as part of the description.) + +* Whitespace in signatures is not preserved. To document a complex signature, + abbreviate it in the ``signature`` directive argument and specify the full + signature in a ``code-block`` in the description. + +The ``signature`` directive generates a document-local hyperlink target +for each signature: + +* Default target names are automatically extracted from leading "keyword" + arguments in the signatures, where a keyword is any sequence of + non-space starting with a letter. For example, the signature + ``string(REGEX REPLACE ...)`` generates the target + ``REGEX REPLACE``, similar to ``.. _`REGEX REPLACE`:``. + +* Custom target names may be specified using a ``:target:`` option. + For example: + + .. code-block:: rst + + .. signature:: + cmake_path(GET ROOT_NAME ) + cmake_path(GET ROOT_PATH ) + :target: + GET ROOT_NAME + GET ROOT_PATH + + Provide a custom target name for each signature, one per line. + The first target may optionally be placed on the same line as ``:target:``. + +* If a target name is already in use earlier in the document, no hyperlink + target will be generated. + +* The targets may be referenced from within the same document using + ```REF`_`` or ```TEXT `_`` syntax. Like reStructuredText section + headers, the targets do not work with Sphinx ``:ref:`` syntax. + +The directive treats its content as the documentation of the signature(s). +Indent the signature documentation accordingly. + +``variable`` directive +^^^^^^^^^^^^^^^^^^^^^^ + +Document a "variable" object: + +.. code-block:: rst + .. variable:: This indented block documents . -Object types for which no directive is available must be defined using -the first approach above. +The directive requires a single argument, the variable name. .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html @@ -329,11 +437,11 @@ paragraph. Style: CMake Command Signatures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: +A ``Help/command/.rst`` document defines one ``command`` +object in the `CMake Domain`_, but some commands have multiple signatures. +Use the CMake Domain's `signature directive`_ to document each signature. +Separate signatures from preceding content by a section header. +For example: .. code-block:: rst @@ -342,17 +450,23 @@ That is, use: Normal Libraries ^^^^^^^^^^^^^^^^ - :: - + .. signature:: add_library( ...) - This signature is used for ... + This signature is used for ... -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. +Use the following conventions in command signature documentation: + +* Use an angle-bracket ```` for arguments to be specified + by the caller. Refer to them in prose using + `inline literal `_ syntax. + +* Wrap optional parts with square brackets. + +* Mark repeatable parts with a trailing ellipsis (``...``). + +The ``signature`` directive may be used multiple times for different +signatures of the same command. Style: Boolean Constants ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index fa9d4cc25a..71b77e091c 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -20,7 +20,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) : OS(os) , DocRoot(std::move(docroot)) , CMakeDirective("^.. (cmake:)?(" - "command|envvar|genex|variable" + "command|envvar|genex|signature|variable" ")::[ \t]+([^ \t\n]+)$") , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$") , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$") diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 5e3cdb1045..076562aa5e 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -70,6 +70,14 @@ Bracket Comment Content Generator expression $ description. +.. cmake:signature:: some_command(SOME_SIGNATURE) + + Command some_command SOME_SIGNATURE description. + +.. signature:: other_command(OTHER_SIGNATURE) + + Command other_command OTHER_SIGNATURE description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 4139801833..43b08dacd3 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -73,6 +73,14 @@ Inline literal ``__`` followed by inline link `Link Text `_. Generator expression $ description. +.. cmake:signature:: some_command(SOME_SIGNATURE) + + Command some_command SOME_SIGNATURE description. + +.. signature:: other_command(OTHER_SIGNATURE) + + Command other_command OTHER_SIGNATURE description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index 47e4909ba0..9043709f9f 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -16,6 +16,9 @@ from pygments.lexers import CMakeLexer from pygments.token import Name, Operator, Punctuation, String, Text, Comment, Generic, Whitespace, Number from pygments.lexer import bygroups +# RE to split multiple command signatures +sig_end_re = re.compile(r'(?<=[)])\n') + # Notes on regular expressions below: # - [\.\+-] are needed for string constants like gtk+-2.0 # - Unix paths are recognized by '/'; support for Windows paths may be added if needed @@ -57,14 +60,16 @@ CMakeLexer.tokens["root"] = [ # (r'[^<>\])\}\|$"# \t\n]+', Name.Exception), # fallback, for debugging only ] +from docutils.utils.code_analyzer import Lexer, LexerError from docutils.parsers.rst import Directive, directives from docutils.transforms import Transform from docutils import io, nodes -from sphinx.directives import ObjectDescription +from sphinx.directives import ObjectDescription, nl_escape_re from sphinx.domains import Domain, ObjType from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode +from sphinx.util import ws_re from sphinx import addnodes sphinx_before_1_4 = False @@ -286,9 +291,9 @@ class CMakeObject(ObjectDescription): def add_target_and_index(self, name, sig, signode): if self.objtype == 'command': - targetname = name.lower() + targetname = name.lower() else: - targetname = name + targetname = name targetid = '%s:%s' % (self.objtype, targetname) if targetid not in self.state.document.ids: signode['names'].append(targetid) @@ -302,6 +307,79 @@ class CMakeObject(ObjectDescription): if make_index_entry: self.indexnode['entries'].append(make_index_entry(name, targetid)) +class CMakeSignatureObject(CMakeObject): + object_type = 'signature' + + option_spec = { + 'target': directives.unchanged, + } + + def get_signatures(self): + content = nl_escape_re.sub('', self.arguments[0]) + lines = sig_end_re.split(content) + return [ws_re.sub(' ', line.strip()) for line in lines] + + def handle_signature(self, sig, signode): + language = 'cmake' + classes = ['code', 'cmake', 'highlight'] + + node = addnodes.desc_name(sig, '', classes=classes) + + try: + tokens = Lexer(sig, language, 'short') + except LexerError as error: + if self.state.document.settings.report_level > 2: + # Silently insert without syntax highlighting. + tokens = Lexer(sig, language, 'none') + else: + raise self.warning(error) + + for classes, value in tokens: + if classes: + node += nodes.inline(value, value, classes=classes) + else: + node += nodes.Text(value) + + signode.clear() + signode += node + + return sig + + def __init__(self, *args, **kwargs): + self.targetnames = {} + super().__init__(*args, **kwargs) + + def add_target_and_index(self, name, sig, signode): + if name in self.targetnames: + targetname = self.targetnames[name].lower() + else: + def extract_keywords(params): + for p in params: + if p[0].isalpha(): + yield p + else: + return + + keywords = extract_keywords(name.split('(')[1].split()) + targetname = ' '.join(keywords).lower() + targetid = nodes.make_id(targetname) + + if targetid not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetid) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + + def run(self): + targets = self.options.get('target') + if targets is not None: + signatures = self.get_signatures() + targets = [t.strip() for t in targets.split('\n')] + for signature, target in zip(signatures, targets): + self.targetnames[signature] = target + + return super().run() + class CMakeXRefRole(XRefRole): # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. @@ -411,19 +489,9 @@ class CMakeDomain(Domain): 'command': CMakeObject, 'envvar': CMakeObject, 'genex': CMakeObject, + 'signature': CMakeSignatureObject, 'variable': CMakeObject, - # Other object types cannot be created except by the CMakeTransform - # 'generator': CMakeObject, - # 'module': CMakeObject, - # 'policy': CMakeObject, - # 'prop_cache': CMakeObject, - # 'prop_dir': CMakeObject, - # 'prop_gbl': CMakeObject, - # 'prop_inst': CMakeObject, - # 'prop_sf': CMakeObject, - # 'prop_test': CMakeObject, - # 'prop_tgt': CMakeObject, - # 'manual': CMakeObject, + # Other `object_types` cannot be created except by the `CMakeTransform` } roles = { 'command': CMakeXRefRole(fix_parens = True, lowercase = True), diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css index 324cd92eb1..dd0dd0272d 100644 --- a/Utilities/Sphinx/static/cmake.css +++ b/Utilities/Sphinx/static/cmake.css @@ -17,6 +17,29 @@ div.sphinxsidebarwrapper { background-color: #dfdfdf; } +/* Apply 
 style (from classic.css) to signature directive argument. */
+.signature .sig {
+  padding: 5px;
+  background-color: #eeeeee;
+  color: #333333;
+  line-height: 120%;
+  border: 1px solid #ac9;
+  border-left: none;
+  border-right: none;
+}
+
+/* Add additional styling to signature directive argument. */
+.signature .sig {
+  margin-bottom: 5px;
+  padding-left: calc(5px + 3em);
+  text-indent: -3em;
+  font-family: monospace;
+}
+
+.signature .sig .code.sig-name {
+  font-weight: normal;
+}
+
 /* Remove unwanted margin in case list item contains a div-wrapping
    directive like `.. versionadded` or `.. deprecated`. */
 dd > :first-child > p {