mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-02-26 02:38:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'docs-CMAKE_CURRENT_FUNCTION' into release-3.17

Browse Source 
10ee9611f0 Help: Improve wording of CMAKE_CURRENT_FUNCTION_LIST_DIR docs
22fbc404a7 Help: Add cross-references for CMAKE_CURRENT_FUNCTION* docs
d2b139687a Help: Minor grammar cleanups of CMAKE_CURRENT_FUNCTION* docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Brad King <brad.king@kitware.com>
Acked-by: Alex Turbov <i.zaufi@gmail.com>
Merge-request: !4595
This commit is contained in:
Craig Scott
2020-04-11 13:12:19 +00:00
committed by Kitware Robot
parent f0b213e291 10ee9611f0
commit baff868b41
5 changed files with 45 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/macro.rst
View File

@@ -95,7 +95,7 @@ Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
set for macro.
set for a macro.
.. _`Argument Caveats`:

6
Help/variable/CMAKE_CURRENT_FUNCTION.rst
View File

@@ -2,5 +2,9 @@ CMAKE_CURRENT_FUNCTION
----------------------
When executing code inside a :command:`function`, this variable
contains the name of the current function. It can be used for
contains the name of the current function. It can be useful for
diagnostic or debug messages.
See also :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.

48
Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst
View File

@@ -2,32 +2,40 @@ CMAKE_CURRENT_FUNCTION_LIST_DIR
-------------------------------
When executing code inside a :command:`function`, this variable
contains the full directory of the listfile defining the current function.
contains the full directory of the listfile that defined the current function.
It is quite common practice in CMake that modules use some additional files
(e.g., templates to render). And the code typically did the following:
It is quite common practice in CMake for modules to use some additional files,
such as templates to be copied in after substituting CMake variables.
In such cases, a function needs to know where to locate those files in a way
that doesn't depend on where the function is called. Without
``CMAKE_CURRENT_FUNCTION_LIST_DIR``, the code to do that would typically use
the following pattern:
.. code-block:: cmake
:caption: Bad
set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
function(foo)
configure_file(
"${_THIS_MODULE_BASE_DIR}/some.template.in"
some.output
)
endfunction()
function(foo)
configure_file(
"${_THIS_MODULE_BASE_DIR}/some.template.in"
some.output
)
endfunction()
Using this variable inside a function eliminates the neccessity of the
additional one with "global" scope:
Using ``CMAKE_CURRENT_FUNCTION_LIST_DIR`` inside the function instead
eliminates the need for the extra variable which would otherwise be visible
outside the function's scope.
The above example can be written in the more concise and more robust form:
.. code-block:: cmake
:caption: Good
function(foo)
configure_file(
"${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
some.output
)
endfunction()
function(foo)
configure_file(
"${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
some.output
)
endfunction()
See also :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.

6
Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst
View File

@@ -2,4 +2,8 @@ CMAKE_CURRENT_FUNCTION_LIST_FILE
--------------------------------
When executing code inside a :command:`function`, this variable
contains the full path to the listfile declaring a current function.
contains the full path to the listfile that defined the current function.
See also :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.

7
Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst
View File

@@ -2,4 +2,9 @@ CMAKE_CURRENT_FUNCTION_LIST_LINE
--------------------------------
When executing code inside a :command:`function`, this variable
contains the line number in the listfile where a current function has defined.
contains the line number in the listfile where the current function
was defined.
See also :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`.