Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-17 07:11:52 +08:00
Code Issues Projects Releases Wiki Activity

Help: Improve wording of CMAKE_CURRENT_FUNCTION_LIST_DIR docs

Browse Source 
The original wording was somewhat confusing in talking about rendering of
templates. While technically correct, a less experienced user may not know
that terminology. The wording has been updated to more clearly describe the
example usage.

The old way of implementing the example is not "bad", it was the only way to do
things before the CMAKE_CURRENT_FUNCTION_LIST_DIR variable was added.
The example has been updated to remove the Bad/Good captions to reflect this.
Indentation of the examples was also fixed to make them conform to the guidelines.
This commit is contained in:
Craig Scott
2020-04-10 22:02:11 +10:00
parent 22fbc404a7
commit 10ee9611f0
1 changed files with 27 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst
View File

@@ -4,30 +4,38 @@ CMAKE_CURRENT_FUNCTION_LIST_DIR
When executing code inside a :command:`function`, this variable
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`.