From 74b3eacdc755bc056aac65bf5c0b45aa02d097d4 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Wed, 10 Oct 2018 23:03:31 +0200 Subject: Help: Use appropriate list types in FindPkgConfig --- Modules/FindPkgConfig.cmake | 69 +++++++++++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 27 deletions(-) diff --git a/Modules/FindPkgConfig.cmake b/Modules/FindPkgConfig.cmake index 06beb7d..a451ba5 100644 --- a/Modules/FindPkgConfig.cmake +++ b/Modules/FindPkgConfig.cmake @@ -9,12 +9,14 @@ A ``pkg-config`` module for CMake. Finds the ``pkg-config`` executable and adds the :command:`pkg_get_variable`, :command:`pkg_check_modules` and :command:`pkg_search_module` commands. The -following variables will also be set:: +following variables will also be set: - PKG_CONFIG_FOUND ... if pkg-config executable was found - PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program - PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found - (since CMake 2.8.8) +``PKG_CONFIG_FOUND`` + if pkg-config executable was found +``PKG_CONFIG_EXECUTABLE`` + pathname of the pkg-config program +``PKG_CONFIG_VERSION_STRING`` + version of pkg-config (since CMake 2.8.8) #]========================================] @@ -543,27 +545,36 @@ endmacro() Each ```` can be either a bare module name or it can be a module name with a version constraint (operators ``=``, ``<``, ``>``, ``<=`` and ``>=`` are supported). The following are examples for a module - named ``foo`` with various constraints:: + named ``foo`` with various constraints: - foo # Any version matches - foo<2 # Only match versions before 2 - foo>=3.1 # Match any version from 3.1 or later - foo=1.2.3 # Foo must be exactly version 1.2.3 + - ``foo`` matches any version. + - ``foo<2`` only matches versions before 2. + - ``foo>=3.1`` matches any version from 3.1 or later. + - ``foo=1.2.3`` requires that foo must be exactly version 1.2.3. The following variables may be set upon return. Two sets of values exist, one for the common case (`` = ``) and another for the information ``pkg-config`` provides when it is called with the ``--static`` - option (`` = _STATIC``):: - - _FOUND ... set to 1 if module(s) exist - _LIBRARIES ... only the libraries (without the '-l') - _LINK_LIBRARIES ... the libraries and their absolute paths - _LIBRARY_DIRS ... the paths of the libraries (without the '-L') - _LDFLAGS ... all required linker flags - _LDFLAGS_OTHER ... all other linker flags - _INCLUDE_DIRS ... the '-I' preprocessor flags (without the '-I') - _CFLAGS ... all required cflags - _CFLAGS_OTHER ... the other compiler flags + option (`` = _STATIC``) + + ``_FOUND`` + set to 1 if module(s) exist + ``_LIBRARIES`` + only the libraries (without the '-l') + ``_LINK_LIBRARIES`` + the libraries and their absolute paths + ``_LIBRARY_DIRS`` + the paths of the libraries (without the '-L') + ``_LDFLAGS`` + all required linker flags + ``_LDFLAGS_OTHER`` + all other linker flags + ``_INCLUDE_DIRS`` + the '-I' preprocessor flags (without the '-I') + ``_CFLAGS`` + all required cflags + ``_CFLAGS_OTHER`` + the other compiler flags All but ``_FOUND`` may be a :ref:`;-list ` if the associated variable returned from ``pkg-config`` has multiple values. @@ -571,12 +582,16 @@ endmacro() There are some special variables whose prefix depends on the number of ```` given. When there is only one ````, ```` will simply be ````, but if two or more ```` - items are given, ```` will be ``_``:: - - _VERSION ... version of the module - _PREFIX ... prefix directory of the module - _INCLUDEDIR ... include directory of the module - _LIBDIR ... lib directory of the module + items are given, ```` will be ``_`` + + ``_VERSION`` + version of the module + ``_PREFIX`` + prefix directory of the module + ``_INCLUDEDIR`` + include directory of the module + ``_LIBDIR`` + lib directory of the module Examples -- cgit v0.12 From fc7ee1ca459c3b231aa1fb64aeeaee590c019513 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Wed, 10 Oct 2018 09:39:17 +0200 Subject: Help: Override pygments CMakeLexer to support <..> and [..] * The code snippets in the docs consist of CMake code mixed with syntax definition punctuation like < > [ ] ... Therefore a pure CMake lexer is inadequate. Here it is replaced by a CMake syntax definition parser. * Fixed syntax definition snippets in FindPkgConfig.cmake to make best use of syntax highlighting. This source file is the hardest to support because it contains comparison operators <= = >=, which need special attention to avoid confusion with the placeholder indicators <...>. * Fixed syntax in execute_process.rst (there were unbalanced brackets). * Disabled syntax highlighting for long string examples in cmake-language.7.rst. * No highlighting of removed syntax in CMP0049 * To inspect the outcome of this patch, see e.g. the pages * manual/cmake-buildsystem.7.html * module/ExternalProject.html * module/FindPkgConfig.html which are particularly rich in complex code snippets. --- Help/command/execute_process.rst | 4 +-- Help/manual/cmake-language.7.rst | 17 +++++++------ Help/policy/CMP0049.rst | 8 +++--- Modules/ExternalProject.cmake | 24 +++++++++++++----- Modules/FindPkgConfig.cmake | 26 ++++++++++++-------- Utilities/Sphinx/cmake.py | 53 +++++++++++++++++++++++++++++++++++----- Utilities/Sphinx/colors.py | 29 ++++++++++++++++++++++ Utilities/Sphinx/conf.py.in | 1 + 8 files changed, 127 insertions(+), 35 deletions(-) create mode 100644 Utilities/Sphinx/colors.py diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 716f457..fc7d177 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -5,8 +5,8 @@ Execute one or more child processes. .. code-block:: cmake - execute_process(COMMAND [args1...]] - [COMMAND [args2...] [...]] + execute_process(COMMAND [] + [COMMAND []]... [WORKING_DIRECTORY ] [TIMEOUT ] [RESULT_VARIABLE ] diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 71649ba..8740d97 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_, is performed. A bracket argument is always given to the command invocation as exactly one argument. -For example: +.. No code-block syntax highlighting in the following example + (long string literal not supported by our cmake.py) -.. code-block:: cmake +For example:: message([=[ This is the first line in a bracket argument with bracket length 1. @@ -253,9 +254,10 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. -For example: +.. No code-block syntax highlighting in the following example + (escape \" not supported by our cmake.py) -:: +For example:: message("This is a quoted argument containing multiple lines. This is always one argument even though it contains a ; character. @@ -264,11 +266,12 @@ For example: It does end in an unescaped double quote. ") +.. No code-block syntax highlighting in the following example + (for conformity with the two above examples) + The final ``\`` on any line ending in an odd number of backslashes is treated as a line continuation and ignored along with the -immediately following newline character. For example: - -.. code-block:: cmake +immediately following newline character. For example:: message("\ This is the first line of a quoted argument. \ diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index a3ce4b1..291bf57 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -3,14 +3,14 @@ CMP0049 Do not expand variables in target source entries. -CMake 2.8.12 and lower performed and extra layer of variable expansion -when evaluating source file names: - -.. code-block:: cmake +CMake 2.8.12 and lower performed an extra layer of variable expansion +when evaluating source file names:: set(a_source foo.c) add_executable(foo \${a_source}) +.. note: no cmake highlighting since this syntax is deprecated + This was undocumented behavior. The OLD behavior for this policy is to expand such variables when processing diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index f987d2d..eb4f9fa 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -16,7 +16,9 @@ External Project Definition The ``ExternalProject_Add()`` function creates a custom target to drive download, update/patch, configure, build, install and test steps of an - external project:: + external project: + + .. code-block:: cmake ExternalProject_Add( [