Before continuing, I feel I should preface my reply with a description of my use case: I am overhauling an open-source C++ library to switch from old-school Autotools to CMake. The library is primarily used by people of a math/physics background who are not necessarily build-system experts, so it helps to provide comments wherever possible to ease their transition to using CMake, as well as future new users of the library. The only area where I have had difficulty doing this is in the presets files. However, these files are incredibly useful, so I do not want to just avoid using them, which is why I’d likely to identify or reach a nice compromise
I believe you can add “comments” with custom, unrecognized keys though?
You’re absolutely right, but unfortunately, that workaround (which admittedly feels like a hack) is very restrictive. I cannot place these keys wherever I want. For example, I can’t
- place them at the root level of the presets level
- next to each configuration/build/test preset
- in the warnings field
- create several “comment” fields of the same name, or
- create a “multiline comment” field as an array of strings
At the moment, users can set cache variables to a dictionary containing a
value field. Even adding a
desc field that would form the comment for the variable in the
CMakeCache.txt would be helpful. Is there any chance that would be possible?
One other pain point is that if I use custom variables that are just used as comments then I can’t enable
otherwise, I’ll get a warning about these auxiliary variables not being used. It then makes it harder to spot variables that contain typos or actually aren’t used as they’ll be mixed up in that list.
IMO, YAML is way too complicated for its own good (and that’s before the sadness of things like
"1" , and
"no" being necessary).
That I certainly do not dispute. It would require some investment to get right however it would be a possible solution to the inability to use comments (with the added benefit that it is also slightly cleaner – visually – than JSON).
As an alternative, would it be reasonable to add a pre-processing phase to the
cmCMakePresetsGraph::ReadJSONFile(...) function in the CMake codebase wherein comments indicated by, e.g. a
//, are stripped from the file contents?
To simplify matters, I imagine you would want to restrict comments to lines starting with an
// otherwise it might get tedious to distinguish between a cache variable containing a
// in its argument and a trailing comment.