cmake: explain BUILD_VERSION and KERNEL_VERSION_* #15950
Conversation
cmake/version.cmake
Outdated
| # | ||
| # Outputs with examples:: | ||
| # | ||
| # PROJECT_VERSION 1.14.99.42 |
There was a problem hiding this comment.
If the idea was "to explain everything", then I'd like to point that the list below doesn't explain what is "42" at the end.
There was a problem hiding this comment.
Good catch thank you, will put the PATCHLEVEL example below back in sync.
There was a problem hiding this comment.
Despite the "42" example (changed, thx) the goal is to explain but not "everything". This is more about not having to read the whole cmake file or git grep the entire source code to filter out the many temporary variables and find the names that matters. The added comment points at the VERSION file where TWEAK is defined so this is hopefully enough. I considered mentioning TWEAK here but @SebastianBoe just helped me trim this down significantly (thx) so I'm reluctant to add stuff again.
cmake/git.cmake
Outdated
| # everything fails and leave BUILD_VERSION undefined. | ||
| # | ||
| # Inputs: | ||
| # ``BUILD_VERSION`` or the output of ``git describe`` |
There was a problem hiding this comment.
How is
the output of git describe
an input to git.cmake ?
There was a problem hiding this comment.
Because git.cmake execute_process( git describe) and reads its output? I don't understand the question.
There was a problem hiding this comment.
The output of git describe is not an input to git.cmake, it is an internal process of git.cmake.
If we had run git describe before git.cmake, then you could say it was an input.
There was a problem hiding this comment.
I don't see why who runs git describe and when matters. The terms "input" and "output" are standard for internal calls too:
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/out-parameter-modifier
https://docs.swift.org/swift-book/LanguageGuide/Functions.html
https://www.learncpp.com/cpp-tutorial/73-passing-arguments-by-reference/
etc.
In fact CMake's documentation for execute_process() uses the terms "input" and "output" too:
https://cmake.org/cmake/help/v3.14/command/execute_process.html?highlight=output
There was a problem hiding this comment.
I find the documentation causes more confusion than than it clarifies, but perhaps this is subjective.
Perhaps "the output of 'git describe'" will clarify things for some users.
This is OK.
There was a problem hiding this comment.
I wrote the "inputs" and "outputs" section in git.cmake for consistency with version.cmake but now I see they've become mostly redundant with the plain English sentence just before. I'll drop them; less is more. I assume the first sentence is OK.
The last sentence with the reference to the (independent!) KERNEL_VERSION_* is the most important IMHO
- Add examples for the latter. - Point at each other and highlight how independent they are from each other. - State their inputs and outputs in plain English. - Fix "git describe" error message giving the wrong impression that everyone cares about BUILD_VERSION. Only the boot banner cares now. Signed-off-by: Marc Herbert <marc.herbert@intel.com>
marc-hb
force-pushed
the
cmake-explain-versions
branch
from
4ba10bf to
b2a199b
Compare
other.
everyone cares about BUILD_VERSION. Only the boot banner cares now.
Signed-off-by: Marc Herbert marc.herbert@intel.com