From d2b139687adbe91afa1d198176c7ca4e6a488c18 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 10 Apr 2020 21:55:38 +1000 Subject: Help: Minor grammar cleanups of CMAKE_CURRENT_FUNCTION* docs --- Help/command/macro.rst | 2 +- Help/variable/CMAKE_CURRENT_FUNCTION.rst | 2 +- Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst | 2 +- Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst | 2 +- Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst | 3 ++- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 3f6f2f9..008d049 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -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`: diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst index aa2936c..b11a62a 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -2,5 +2,5 @@ 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. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst index 0119381..8e861e0 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -2,7 +2,7 @@ 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: diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst index d2c846a..88d8423 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -2,4 +2,4 @@ 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. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst index 5a7cd13..8b18d2e 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -2,4 +2,5 @@ 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. -- cgit v0.12 From 22fbc404a7f8cf4439f2caefb34e90fe1b32bf8f Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 10 Apr 2020 21:56:07 +1000 Subject: Help: Add cross-references for CMAKE_CURRENT_FUNCTION* docs --- Help/variable/CMAKE_CURRENT_FUNCTION.rst | 4 ++++ Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst | 4 ++++ Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst index b11a62a..fb7f610 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -4,3 +4,7 @@ CMAKE_CURRENT_FUNCTION When executing code inside a :command:`function`, this variable 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`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst index 88d8423..c737af9 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -3,3 +3,7 @@ CMAKE_CURRENT_FUNCTION_LIST_FILE When executing code inside a :command:`function`, this variable 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`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst index 8b18d2e..ad6282e 100644 --- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -4,3 +4,7 @@ CMAKE_CURRENT_FUNCTION_LIST_LINE When executing code inside a :command:`function`, this variable 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`. -- cgit v0.12 From 10ee9611f0d3d2a8ad8e3423dde1f60ed43dd946 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 10 Apr 2020 22:02:11 +1000 Subject: Help: Improve wording of CMAKE_CURRENT_FUNCTION_LIST_DIR docs 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. --- Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst | 48 +++++++++++++---------- 1 file 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`. -- cgit v0.12