diff options
| -rw-r--r-- | Help/command/if.rst | 90 | ||||
| -rw-r--r-- | Help/command/project.rst | 147 | ||||
| -rw-r--r-- | Help/release/dev/0-sample-topic.rst | 7 | ||||
| -rw-r--r-- | Help/release/index.rst | 2 | ||||
| -rw-r--r-- | README.rst | 9 | ||||
| -rw-r--r-- | Source/CMakeVersion.cmake | 4 | ||||
| -rw-r--r-- | Utilities/Release/linux64_release.cmake | 6 |
7 files changed, 159 insertions, 106 deletions
diff --git a/Help/command/if.rst b/Help/command/if.rst index 5294ce8..8abe9ba 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -3,41 +3,46 @@ if Conditionally execute a group of commands. -.. code-block:: cmake - - if(expression) - # then section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - elseif(expression2) - # elseif section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - else(expression) - # else section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - endif(expression) - -Evaluates the given expression. If the result is true, the commands -in the THEN section are invoked. Otherwise, the commands in the else -section are invoked. The elseif and else sections are optional. You -may have multiple elseif clauses. Note that the expression in the -else and endif clause is optional. Long expressions can be used and -there is a traditional order of precedence. Parenthetical expressions -are evaluated first followed by unary tests such as ``EXISTS``, -``COMMAND``, and ``DEFINED``. Then any binary tests such as +Synopsis +^^^^^^^^ + +:: + + if(<condition>) + <commands> + elseif(<condition>) # optional block, can be repeated + <commands> + else() # optional block + <commands> + endif() + +Evaluates the ``condition`` argument of the ``if`` clause according to the +`Condition syntax`_ described below. If the result is true, then the +``commands`` in the ``if`` block are executed. +Otherwise, optional ``elseif`` blocks are processed in the same way. +Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` +block are executed. + +Per legacy, the ``else`` and ``endif`` clause may also have a ``condition`` argument, +which then must be a verbatim repeat of the argument of the opening ``if`` clause. + +Condition Syntax +^^^^^^^^^^^^^^^^ + +The following syntax applies to the ``condition`` argument of +the ``if``, ``elseif`` and :command:`while` clauses. + +Compound conditions are evaluated in the following order of precedence: +Innermost parentheses are evaluated first. Next come unary tests such +as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then binary tests such as ``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, -and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and -finally boolean ``AND`` and then ``OR`` operators will be evaluated. +and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``, +and finally ``OR``. -Possible expressions are: +Possible conditions are: ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, @@ -52,14 +57,14 @@ Possible expressions are: True if given a variable that is defined to a value that is not a false constant. False otherwise. (Note macro arguments are not variables.) -``if(NOT <expression>)`` - True if the expression is not true. +``if(NOT <condition>)`` + True if the condition is not true. -``if(<expr1> AND <expr2>)`` - True if both expressions would be considered true individually. +``if(<cond1> AND <cond2>)`` + True if both conditions would be considered true individually. -``if(<expr1> OR <expr2>)`` - True if either expression would be considered true individually. +``if(<cond1> OR <cond2>)`` + True if either condition would be considered true individually. ``if(COMMAND command-name)`` True if the given name is a command, macro or function that can be @@ -103,7 +108,7 @@ Possible expressions are: ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. + condition. See :ref:`Regex Specification` for regex format. ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. ``if(<variable|string> LESS <variable|string>)`` @@ -184,11 +189,14 @@ Possible expressions are: variable is true or false just if it has been set. (Note macro arguments are not variables.) -``if((expression) AND (expression OR (expression)))`` - The expressions inside the parenthesis are evaluated first and then - the remaining expression is evaluated as in the previous examples. +``if((condition) AND (condition OR (condition)))`` + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the previous examples. Where there are nested parenthesis the innermost are evaluated as part - of evaluating the expression that contains them. + of evaluating the condition that contains them. + +Variable Expansion +^^^^^^^^^^^^^^^^^^ The if command was written very early in CMake's history, predating the ``${}`` variable evaluation syntax, and for convenience evaluates diff --git a/Help/command/project.rst b/Help/command/project.rst index bd8b4ef..688e56c 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,90 +1,119 @@ project ------- -Sets project details such as name, version, etc. and enables languages. +Set the name of the project. + +Synopsis +^^^^^^^^ .. code-block:: cmake - project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> [<language-name>...]) project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [DESCRIPTION <project-description-string>] [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) -Sets the name of the project and stores the name in the -:variable:`PROJECT_NAME` variable. Additionally this sets variables +Sets the name of the project, and stores it in the variable +:variable:`PROJECT_NAME`. When called from the top-level +``CMakeLists.txt`` also stores the project name in the +variable :variable:`CMAKE_PROJECT_NAME`. + +Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` * :variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` -If ``VERSION`` is specified, given components must be non-negative integers. -If ``VERSION`` is not specified, the default version is the empty string. -The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is -set to ``NEW``. - -The :command:`project()` command stores the version number and its components -in variables - -* :variable:`PROJECT_VERSION`, - :variable:`<PROJECT-NAME>_VERSION` -* :variable:`PROJECT_VERSION_MAJOR`, - :variable:`<PROJECT-NAME>_VERSION_MAJOR` -* :variable:`PROJECT_VERSION_MINOR`, - :variable:`<PROJECT-NAME>_VERSION_MINOR` -* :variable:`PROJECT_VERSION_PATCH`, - :variable:`<PROJECT-NAME>_VERSION_PATCH` -* :variable:`PROJECT_VERSION_TWEAK`, - :variable:`<PROJECT-NAME>_VERSION_TWEAK` - -Variables corresponding to unspecified versions are set to the empty string -(if policy :policy:`CMP0048` is set to ``NEW``). - -If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` -and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. -These variables will be cleared if ``DESCRIPTION`` is not given. -The description is expected to be a relatively short string, usually no more -than a few words. - -The optional ``HOMEPAGE_URL`` sets the analogous variables -:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. -When this option is given, the URL provided should be the canonical home for -the project. -These variables will be cleared if ``HOMEPAGE_URL`` is not given. - -Note that the description and homepage URL may be used as defaults for -things like packaging meta-data, documentation, etc. - -Optionally you can specify which languages your project supports. -Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, -``Fortran``, and ``ASM``. -By default ``C`` and ``CXX`` are enabled if no language options are -given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword -and list no languages, to skip enabling any languages. - -If enabling ``ASM``, list it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. - -If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +Further variables are set by the optional arguments described in the following. +If any of these arguments is not used, then the corresponding variables are +set to the empty string. + +If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` exists, the file pointed to by that variable will be included as the last step of the project command. +Options +^^^^^^^ + +The options are: + +``VERSION <version>`` + Optional; may not be used unless policy :policy:`CMP0048` is + set to ``NEW``. + + Takes a ``<version>`` argument composed of non-negative integer components, + i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``, + and sets the variables + + * :variable:`PROJECT_VERSION`, + :variable:`<PROJECT-NAME>_VERSION` + * :variable:`PROJECT_VERSION_MAJOR`, + :variable:`<PROJECT-NAME>_VERSION_MAJOR` + * :variable:`PROJECT_VERSION_MINOR`, + :variable:`<PROJECT-NAME>_VERSION_MINOR` + * :variable:`PROJECT_VERSION_PATCH`, + :variable:`<PROJECT-NAME>_VERSION_PATCH` + * :variable:`PROJECT_VERSION_TWEAK`, + :variable:`<PROJECT-NAME>_VERSION_TWEAK`. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. + +``DESCRIPTION <project-description-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION` + + to ``<project-description-string>``. + It is recommended that this description is a relatively short string, + usually no more than a few words. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. + +``HOMEPAGE_URL <url-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + + to ``<url-string>``, which should be the canonical home URL for the project. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +``LANGUAGES <language-name>...`` + Optional. + Can also be specified without ``LANGUAGES`` keyword per the first, short signature. + + Selects which programming languages are needed to build the project. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + By default ``C`` and ``CXX`` are enabled if no language options are given. + Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, + to skip enabling any languages. + + If enabling ``ASM``, list it last so that CMake can check whether + compilers for other languages like ``C`` work for assembly too. + +The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` +options are intended for use as default values in package metadata and documentation. + +Usage +^^^^^ + The top-level ``CMakeLists.txt`` file for a project must contain a literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). The name of the project set in -the top level ``CMakeLists.txt`` file is available from the -:variable:`CMAKE_PROJECT_NAME` variable, its description from -:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from -:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from -:variable:`CMAKE_PROJECT_VERSION`. +default languages (``C`` and ``CXX``). .. note:: Call the :command:`cmake_minimum_required` command at the beginning of the top-level ``CMakeLists.txt`` file even before calling the - ``project()`` command. It is important to establish version and + :command:`project()` command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy :policy:`CMP0000`. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/index.rst b/Help/release/index.rst index fbe4cf6..7ef3a8e 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== @@ -68,7 +68,7 @@ Windows ^^^^^^^ You need to download and install a binary release of CMake in order to build -CMake. You can get these releases from the `CMake Download Page`_ . Then +CMake. You can get these releases from the `CMake Download Page`_. Then proceed with the instructions below. .. _`CMake Download Page`: https://cmake.org/cmake/resources/software.html @@ -83,6 +83,13 @@ For instructions how to do this, see documentation on `Running CMake`_. .. _`Running CMake`: https://cmake.org/cmake/help/runningcmake.html +To build the documentation, install `Sphinx`_ and configure CMake with +``-DSPHINX_HTML=ON`` and/or ``-DSPHINX_MAN=ON`` to enable the "html" or +"man" builder. Add ``-DSPHINX_EXECUTABLE=/path/to/sphinx-build`` if the +tool is not found automatically. + +.. _`Sphinx`: http://sphinx-doc.org + Reporting Bugs ============== diff --git a/Source/CMakeVersion.cmake b/Source/CMakeVersion.cmake index 626dbb8..6a2cb16 100644 --- a/Source/CMakeVersion.cmake +++ b/Source/CMakeVersion.cmake @@ -1,5 +1,5 @@ # CMake version number components. set(CMake_VERSION_MAJOR 3) set(CMake_VERSION_MINOR 13) -set(CMake_VERSION_PATCH 0) -set(CMake_VERSION_RC 1) +set(CMake_VERSION_PATCH 20181010) +#set(CMake_VERSION_RC 1) diff --git a/Utilities/Release/linux64_release.cmake b/Utilities/Release/linux64_release.cmake index dc34120..fa585d7 100644 --- a/Utilities/Release/linux64_release.cmake +++ b/Utilities/Release/linux64_release.cmake @@ -29,9 +29,9 @@ CURSES_LIBRARY:FILEPATH=/home/kitware/ncurses-5.9/lib/libncurses.a CURSES_INCLUDE_PATH:PATH=/home/kitware/ncurses-5.9/include FORM_LIBRARY:FILEPATH=/home/kitware/ncurses-5.9/lib/libform.a CMAKE_USE_OPENSSL:BOOL=ON -OPENSSL_CRYPTO_LIBRARY:STRING=/home/kitware/openssl-1.1.0h/lib/libcrypto.a;-pthread -OPENSSL_INCLUDE_DIR:PATH=/home/kitware/openssl-1.1.0h/include -OPENSSL_SSL_LIBRARY:FILEPATH=/home/kitware/openssl-1.1.0h/lib/libssl.a +OPENSSL_CRYPTO_LIBRARY:STRING=/home/kitware/openssl-1.1.1/lib/libcrypto.a;-pthread +OPENSSL_INCLUDE_DIR:PATH=/home/kitware/openssl-1.1.1/include +OPENSSL_SSL_LIBRARY:FILEPATH=/home/kitware/openssl-1.1.1/lib/libssl.a PYTHON_EXECUTABLE:FILEPATH=/usr/bin/python3 CPACK_SYSTEM_NAME:STRING=Linux-x86_64 BUILD_CursesDialog:BOOL=ON |