Future YAML support for CMake presets?

Development
1

Is there possibly any scope for adding YAML support for CMake presets? (Using e.g. https://github.com/jbeder/yaml-cpp.) The reason I ask is:

  1. it can make presets files cleaner as you don’t always require enclosing braces or quotes, and
  2. it can allow users to add comments to their code (allowed in YAML Spec 1.2; YAML Ain’t Markup Language (YAML™) revision 1.2.2)

I think it goes without saying that the latter is incredibly helpful and is sorely missed by many with the current JSON support (but I understand why it is not supported).

2

I believe you can add “comments” with custom, unrecognized keys though?

IMO, YAML is way too complicated for its own good (and that’s before the sadness of things like "true", "1", and "no" being necessary). Nevermind the implementation differences and YAML supplement support differences (e.g., merge keys >>: being default in some and unsupported in others).

Cc: @kyle.edwards

3

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 :slight_smile:

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 type and 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

"warnings": {
  "unusedCli": true
}

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 "true" , "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.

4

It’s not so simple:

{ "key": "this is a single string
// without a comment
but a preprocessor might not know that" }
5

Presets files are read by more than just CMake. We cannot put things in presets files that do not conform to the JSON spec because that could break other tools that also read them. See the following issues which cover this topic on more detail:

6

It’s not so simple:

{ "key": "this is a single string
// without a comment
but a preprocessor might not know that" }

That’s true. I guess it’s not a simple task (but still possible). However, as Craig alludes, that could break other tools which makes my proposal void.

Presets files are read by more than just CMake. We cannot put things in presets files that do not conform to the JSON spec because that could break other tools that also read them.
…

Ah, thank you for those links. I can see that Brad K proposed adding a “comment” field (that can possibly be duplicated multiple times?) about a year ago but that doesn’t appear to have had any traction or matching PRs; do you know if there are any plans to add this in? If a “comment” field won’t be addd, and you want to avoid breaking backward compatibility, it sounds like a new additional/alternative syntax has to be allowed. Are there any alternative configuration formats that you could use? E.g. TOML or some sort of custom .cmake config file?

It’s clear that people need/want a way to comment their preset files. I’m almost grasping at straws for a possible solution and I think you both, as developers/contributors to the CMake library, would know the best approach for adding such a feature, so I pose the question: how would you propose users add/allow comments to their preset files?

7

I don’t know if it is on anyone’s radar to work on. I don’t see switching to another format like YAML or TOML as feasible, I think Brad’s suggestion of adding support for a comment field is the most likely avenue to be successful.

For now, users can (ab)use the description field as one way to add comments. That field has questionable value anyway, since there’s also a displayName field. Some IDEs may still show the description as well for non-hidden presets, but it’s the third level down in terms of detail about the preset (name → displayName → description) and there’s a good chance the IDE will only show the first one or two. I’ve used the description field for adding a comment to hidden presets.

Another option might be to (ab)use the vendor object support. I won’t suggest any further details about that other than to say it would be possible to add your own fictitious vendor and put whatever comment details you want within that, but I wouldn’t recommend it.

8

Some formats based on JSON (e.g. JSON Schema) offer the “$comment” field for these purposes

9

This is not a valid JSON. JSON does not allow line breaks within string literals.

10

Indeed it is not. However, if we’re talking about // support, we’re also outside of JSON (no idea how most parsers handle it in practice…which is also a far worse problem for YAML IME).

1 Like
11

I’d like to second the spirit of this request. While JSON is marginally better than XML, it’s still noisy to read and not easily edited, not to mention the lack of comments. There are several other formats that I would have preferred, YAML topping the list. I have never heard of any complaints from users of YAML when used in practice - most arguments against seem to be mostly theoretical. But at any rate, there is also TOML, INI and HCL as only three examples of human-editable text-based configuration file formats that would fit the bill.

I realize this topic is over two years old, but some folks are slow to update to the latest version of anything (cmake included) and others won’t embrace new features like this when they see it still uses a machine-to-machine data format as a user-editable file.

Finally, I’d be happy to work up a merge request for this if there’s enough interest in the community at large.