From 00007dcc365797f71ebba2c7d31ab20abc4019e6 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 29 Jan 2014 09:00:40 -0500 Subject: [PATCH] Help: Format project command and variable documentation Also add document for CMAKE_PROJECT__INCLUDE variable. --- Help/command/project.rst | 40 ++++++++++--------- Help/manual/cmake-variables.7.rst | 1 + .../CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst | 6 +++ Help/variable/PROJECT-NAME_BINARY_DIR.rst | 6 +-- Help/variable/PROJECT-NAME_SOURCE_DIR.rst | 6 +-- Help/variable/PROJECT_BINARY_DIR.rst | 2 +- Help/variable/PROJECT_NAME.rst | 2 +- Help/variable/PROJECT_SOURCE_DIR.rst | 2 +- 8 files changed, 38 insertions(+), 27 deletions(-) create mode 100644 Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst diff --git a/Help/command/project.rst b/Help/command/project.rst index 9b9f93f5f..cb7d3fc81 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,27 +1,31 @@ project ------- -Set a name for the entire project. +Set a name and enable languages for the entire project. -:: +.. code-block:: cmake - project( [languageName1 languageName2 ... ] ) + project( [...]) -Sets the name of the project. Additionally this sets the variables -_BINARY_DIR and _SOURCE_DIR to the -respective values. +Sets the name of the project and stores the name in the +:variable:`PROJECT_NAME` variable. Additionally this sets variables + +* :variable:`PROJECT_SOURCE_DIR`, + :variable:`_SOURCE_DIR` +* :variable:`PROJECT_BINARY_DIR`, + :variable:`_BINARY_DIR` Optionally you can specify which languages your project supports. -Example languages are CXX (i.e. C++), C, Fortran, etc. By default C -and CXX are enabled. E.g. if you do not have a C++ compiler, you can -disable the check for it by explicitly listing the languages you want -to support, e.g. C. By using the special language "NONE" all checks -for any language can be disabled. If a variable exists called -CMAKE_PROJECT__INCLUDE, the file pointed to by that -variable will be included as the last step of the project command. +Example languages are ``C``, ``CXX`` (i.e. C++), ``Fortran``, etc. +By default ``C`` and ``CXX`` are enabled if no language options are +given. Specify language ``NONE`` to skip enabling any languages. -The top-level CMakeLists.txt file for a project must contain a -literal, direct call to the project() command; loading one through the -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). +If a variable exists called :variable:`CMAKE_PROJECT__INCLUDE`, +the file pointed to by that variable will be included as the last step of the +project command. + +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``). diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 832bd9994..f363f946a 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -121,6 +121,7 @@ Variables that Change Behavior /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH + /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SYSTEM_IGNORE_PATH diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst new file mode 100644 index 000000000..ba9df5a34 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_PROJECT__INCLUDE +------------------------------------ + +A CMake language file or module to be included by the :command:`project` +command. This is is intended for injecting custom code into project +builds without modifying their source. diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst index a19940f1d..49bc55878 100644 --- a/Help/variable/PROJECT-NAME_BINARY_DIR.rst +++ b/Help/variable/PROJECT-NAME_BINARY_DIR.rst @@ -3,6 +3,6 @@ Top level binary directory for the named project. -A variable is created with the name used in the PROJECT command, and -is the binary directory for the project. This can be useful when -SUBDIR is used to connect several projects. +A variable is created with the name used in the :command:`project` command, +and is the binary directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst index f2f5caf60..4df3e223c 100644 --- a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst +++ b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst @@ -3,6 +3,6 @@ Top level source directory for the named project. -A variable is created with the name used in the PROJECT command, and -is the source directory for the project. This can be useful when -add_subdirectory is used to connect several projects. +A variable is created with the name used in the :command:`project` command, +and is the source directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT_BINARY_DIR.rst b/Help/variable/PROJECT_BINARY_DIR.rst index e506bdd0d..09e9ef218 100644 --- a/Help/variable/PROJECT_BINARY_DIR.rst +++ b/Help/variable/PROJECT_BINARY_DIR.rst @@ -3,4 +3,4 @@ PROJECT_BINARY_DIR Full path to build directory for project. -This is the binary directory of the most recent PROJECT command. +This is the binary directory of the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst index 7559af6d5..61aa8bc00 100644 --- a/Help/variable/PROJECT_NAME.rst +++ b/Help/variable/PROJECT_NAME.rst @@ -3,4 +3,4 @@ PROJECT_NAME Name of the project given to the project command. -This is the name given to the most recent PROJECT command. +This is the name given to the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst index c9ba13227..27f2838ee 100644 --- a/Help/variable/PROJECT_SOURCE_DIR.rst +++ b/Help/variable/PROJECT_SOURCE_DIR.rst @@ -3,4 +3,4 @@ PROJECT_SOURCE_DIR Top level source directory for the current project. -This is the source directory of the most recent PROJECT command. +This is the source directory of the most recent :command:`project` command.