Use a tools section, rather than X-tool

[dcbaker]

This is a case where I think that python with it's pyproject.toml made a really good choice, it specified that there would be a "tools" section, like so:

[tools]
  [tools.pylint]
  foo = ['a', 'b']

  [tools.black]

I think this would be a better approach for CPS than the X- fields, there specification could look like, the tools key is an object, containing key: object mappings where the key is the name of the tool, and the object may contain any tool specific data, in the form the tool likes.

This allows the spec to say "no extra keys", for the schema to enforce "no extra keys" and we don't have to worry about collisions in the future if a new key is added and someone has ignored the guidance of using X-tool

[mathstuf]

The purpose of X- fields (though I'm not familiar with their use here) is to be able to also have tools agree on things, similar to OpenGL extensions just being named after the initial implementer, but not being specific to that vendor's hardware/implementation. Note that I would expect X- fields to be completely ignoreable by a conforming implementation. I wouldn't want tools to stuff everything into these tool-specific buckets rather than collaborating on representing the information as proper top-level fields.

[dcbaker]

Tools could agree to put them in tool specific buckets just as easily as an in X-, the real advantage is that then you can say that nothing can go in the root but what's specified, and tools can put anything they want in the tool specific thing. It both simplifies validation and ensures that you never have a collision between non-specified things and specified things.

What's the difference between:

{
  "x-tool": {
    "foo": 1,
  }
}

and

{
  "tools": {
    "tool": {
       "foo": 1
    }
  }
}

except that it prevents someone from doing:

{
   "tool": {
    "foo": 1,
   }
}

[mathstuf]

I think the X- prefix "screams" extension info. tools/ doesn't really do that.

[dcbaker]

I guess my thought is that X- always become a standard anyway, even if just a defacto standard. I'm trying to remember where, but I've ready several people noting that using X- was a design mistake, because they become basically required and people rely on them..

what if instead of tools we called it "vendor-data" or "extensions"?

[mathstuf]

I think HTTP headers and CSS are the normal culprits there.

For the C++20 module dependency format, R0 had a top-level extensions object for such purposes. Instead, after discussion, there are now _VENDOR_key fields. Note that the spec for it also says that semantic information may not be stored there. Here, we may have CMake functions in an include file for use (complicated APIs), or other information, so semantic info isn't bannable here. I forget the exact reasons we decided to use vendor keys rather than an extension object. I'll try to find the minutes to refresh my memory.

[mathstuf]

OK, found the minutes. The idea there was that extra information may be useful across the object tree. Trying to annotate a component with an extension CMake companion module in a shadowing structure was deemed as messy and a loss of locality.

[dcbaker]

At the very least then, can we change the language from "strongly recommended" to "must" for "starts with "X-"?

[dcbaker]

Honestly, I'm concerned about cmake (or meson) needing to put information in an X-section, that seems like a great way to end up with cps files that only the build system that created them can consume.

[mathstuf]

I hope it mostly gets used for special-case logic for things like CMake APIs provided by a package or the like (e.g., FindPython providing a function to build a Python module by changing the extension and installation locations). Things like that are just not portable between build systems.

[dcbaker]

To be clear, my concern is that these don't become escape hatches from the purely descriptive format we have, and provide a way for meson to say "run this bit of code," which in turn makes a generated cps file unusable in cmake or autotools if they don't also implement that code.

[mathstuf]

There are some things that cannot be described with declarative code. VTK's autoinit system is one such functionality (intersectional usage requirements that end up generating a header). It's a long story, but it's the simplest thing that does what is needed for the use case. That might have CMake-only code for now, but implementations for other systems would be accepted.

VTK also provides a CMake API as part of its package. That won't have Meson support (it's just too complicated to port and maintain in parallel), but basic usage of VTK itself wouldn't require CMake to actually work with this. Interpreters could provide snippets for building (or applying properties to) libraries for use in their import systems.

[mwoehlke]

[...] end up with cps files that only the build system that created them can consume

If that happens, we're doing something wrong and have basically failed at the entire objective.

[mwoehlke]

I guess my thought is that X- always become a standard anyway, even if just a defacto standard

I think the goal would be that if an extension is widely used and seen as useful, it should be officially incorporated, losing the X- in the process. This might necessitate a major version bump, however, so I suspect what would happen is that tools would be encouraged to read both with and without the X- (preferring the without-X- key if both are present), but write with X- for backwards compatibility until the next major version.

For example, say X-foo is in wide use and CPS 1.5 standardizes it as foo. Tools supporting CPS ≥ 1.5 should support both foo and X-foo, but should write X-foo (or both, though that violates DRY) until CPS 2.x, at which point X-foo goes away. (Or unless/until they just don't care about being compatible with tools that don't support CPS < 1.5, which might also happen.)

[dcbaker]

That makes my point though. If they go in a tools section, then there's no need for either a major version bump or reading/writing two fields, tools/pkg-config-compat (whatever that does), is valid forever.

[mwoehlke]

Is the objection (#39 also) mostly about schema validation?

Perhaps I can be convinced. I'd prefer ext over tool[s], though.

[bretbrownjr]

For me an analog would be XDG or /opt in LFH documenting the way to keep possibly messy nonstandard things in a specific namespace.

I guess XDG could have documented using X-config-git/ instead of .config/git. And LFH could have documented /X-rh instead of /opt/rh, but I like the choices they made. I think it's easier to tool, cleaner, and easier to understand.

I'm flexible on the bikeshedding of the field name. LFH uses opt. pyproject.toml uses tool. Maven has plugins and plugin. Cargo supports a package.metadata section. There's a justification for that last example:

Cargo by default will warn about unused keys in Cargo.toml to assist in detecting typos and such. The package.metadata table, however, is completely ignored by Cargo and will not be warned about.

I expect a cps-config tool could ship with a validation feature without much work. Package maintainers and package management systems could use that to avoid silly spelling mistakes or possibly premature adoption of new features.

[mwoehlke]

At the most recent Ecosystem Evolution meeting, we agreed that we want to reserve a single name that can apply to root object types. Leading contenders are extension and shed (and possibly bikeshed).

[bruxisma]

For the record I personally vote for bikeshed because of the following reasons:

1. teehee :)

[autoantwort]

We could create a Poll in the Discussions tab for the name

[mwoehlke]

We could create a Poll in the Discussions tab

Unfortunately, polls seem to only allow one question and one vote. I'd prefer something more WG21-like.

So... let's do that. Voting is open to anyone. For each option, you may vote "SF" (strongly in favor), "F" (in favor), "N" (neutral), "A" (against), "SA" (strongly against). You may also add your own suggestions. Voters are encouraged to check for new suggestions and update their votes accordingly. Please keep voting to a single comment per person (comments are editable).

Here's mine:

bikeshed        A
ext             SF
extension       N
extensions      N
extra           F
srb             N
sc              N
sep             F
shed            F
supplement      A
supplemental    A
tool            A
vendor          A

("SRB" = "Specification Review Board", a nod to "ARB" from the Khronos Group. "SC" = "Specification Committee". "SEP" = "Specification Extension Proposal" or, pertinently, "Somebody Else's Problem". I hereby veto "toolymctoolface".)

Some of the options just seem unwieldy. In general, I'd prefer to avoid anything that implies this is only for tool-specific extensions. I think "bikeshed" just seems unprofessional. ("SEP" can be 'cute' also, but at least can be claimed to officially stand for something serious.)

[bruxisma]

I'm using a markdown table for my vote. I've also added vendor as a field. I'm against shed because it is also a verb. bikeshed less so. Also it's funny. Without an actual board in place or a authorized committee I'm against those names. SEP is an acronym used by the IRS, I'd prefer to stay away from any confusion on that.

Field	Vote
bikeshed	SF
ext	A
extension	A
extensions	F
extra	N
srb	SA
sc	SA
sep	SA
shed	A
supplement	A
supplemental	A
tool	A
vendor	F

[bretbrownjr]

I'm A on sc, srb, and sep, but only because I don't know what those are supposed to mean.

I'm happy with anything else. So far everyone at least somewhat likes ext.