diff options
| -rw-r--r-- | Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst | 48 |
1 files changed, 28 insertions, 20 deletions
diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst index 8e861e0..44ae1e5 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -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`. |