RFC: Module Metadata Format #3
Conversation
bretbrownjr
left a comment
bretbrownjr
left a comment
There was a problem hiding this comment.
I don't want to hold up this PR on this concern, but I expect a typical reader would go through this RFC and request other kinds of related documents, like how-tos, realistic examples, tutorials, and things of that nature. That being said, I think it's reasonable to keep this document a technical reference. But maybe the repo itself has ways to help users contribute other kinds of docs and eventually discover them? That might be something @grafikrobot wants to weigh in on.
Overall, I'm in favor of adding module metadata to the EcoStd, so I'm supportive of this PR. I'm mainly requesting changes to clear up the typographical errors.
Note: I haven't done a thorough review to compare this specification to the actual implementations in toolchains.
| ---- | ||
| { | ||
| "$schema": "", | ||
| "$id": "http://example.com/root.json", |
There was a problem hiding this comment.
| "$id": "http://example.com/root.json", | |
| "$id": "http://example.com/root.json", |
Will this get replaced with a real URI, perhaps published by this repo?
FYI @grafikrobot since you might have thoughts on how schemas are published when required.
There was a problem hiding this comment.
Will this get replaced with a real URI, perhaps published by this repo?
I did research this when creating the initial rfcs. What I concluded is that the most portable is to use a std_<name>-<version>.json. As having a full URI is not sufficiently transportable. Hence just using a unique tag+version is better. For this rfc maybe use std_modmeta-1.0.0.json?
|
|
||
| This RFC specifies the format for pre-built libraries to advertise the | ||
| metadata about the C++ Modules being provided, with the information required to | ||
| perform the translation of the Importable Units into Built Module Interface |
There was a problem hiding this comment.
| perform the translation of the Importable Units into Built Module Interface | |
| perform the translation of the Importable Units into Built Module Interface |
It's a pain, but I'm not aware of a standard document anywhere that actually defines some of these terms. Such as "Build Module Interface". That probably means it goes in the EcoStd and this RFC.
I believe P0947 has initial definitions for a lot of terms. P1687 is mainly published minutes, but it discusses a bikeshedding poll to select BMI as a term.
I also found some definitions in the clang docs on C++ modules:
https://clang.llvm.org/docs/StandardCPlusPlusModules.html#built-module-interface
I'm assuming @Bigcheese reviewed those docs at some point.
There was a problem hiding this comment.
I wrote this while watching game 1, and that's what I'm going to use as my excuse for all the mistakes. I think the more correct term for what this RFC describes are "module interface units", but the existing wording from P3286 uses "importable unit" so I did as well.
AFAIK "Built Module Interface" comes from P2581, which is where the meaning on the "B" was originally legislated.
I'm down to RFC a terms glossary separately. I don't think it's a blocker for this.
There was a problem hiding this comment.
It's a pain, but I'm not aware of a standard document anywhere that actually defines some of these terms. Such as "Build Module Interface". That probably means it goes in the EcoStd and this RFC.
Yes, we will need to add definitions to EcoStd for these. We can probably steal the ones from wg21. But we could adjust the definitions to our current understanding.
| In practice, the extension `.modules.json` has seen widespread use. | ||
| Standardizing the exact extension seems excessive. The module metadata file | ||
| is typically located via packaging mechanisms and thus the exact names and | ||
| file extensions should not be semantically relevant. |
There was a problem hiding this comment.
Is it too early to link to CPS and how it wires up this info?
There was a problem hiding this comment.
I'll update with it when it merges CPS-side (cps-org/cps#95). Should be in a day or two if not today.
Adds a parser and serializer for the EcoStd Module Metadata format RFC: ecostd/rfcs#3 This adapts the existing experimental support for import std; to use the new parser. The CMAKE_CXX_STDLIB_MODULES_JSON is now the canonical variable for controlling how CMake discovers the stdlib module metadata, and is used directly by compiler detection. Toolchains can still override the __CMAKE::CXX## targets if they wish, either in conjunction with CMAKE_CXX_STDLIB_MODULE_JSON or not. It is possible to disable automatic detection of CMAKE_CXX_STDLIB_MODULE_JSON by setting it to the empty string. When available, the CMAKE_CXX_STDLIB_MODULE_JSON will be used to create all requested C++ stdlibs which do not already have targets.
| [source,javascript] | ||
| ---- | ||
| { | ||
| "$schema": "", |
There was a problem hiding this comment.
Needs to be "$schema": "https://json-schema.org/draft/2020-12/schema",
| "version": 1, | ||
| "revision": 1, |
There was a problem hiding this comment.
Is it possible to use regular semver on this? As that's what ecostd is trying to coalesce to?
| Any file or directory referenced by the metadata file in relative form should be | ||
| considered relative to the path provided. Any relative path in the metadata file | ||
| will be resolved based on the path provided by the toolchain or package manager. |
There was a problem hiding this comment.
Not clear on this.. Are things relative to the directory of the metadata file? What happens if the given path is itself relative? Is that possible?
3 participants
This RFC specifies the format for pre-built libraries to advertise the metadata about the C++ Modules being provided, with the information required to perform the translation of the Importable Units into Built Module Interface files. It is effectively identical to the P3286, "Module Metadata Format for Distribution with Pre-Built Libraries", as originally presented to SG15, seeking only to standardize existing practice.
I finally learned enough AsciiDoc to make this PR.
This is effectively a port of P3286. I've asked for and received the original author's blessing to do so. I intend to the same with P1689 in the near future.
This RFC is motivated by the upcoming inclusion of module metadata in the Common Package Spec. It is desirable that we have some central repository and website for describing these formats instead of pointing at unratified WG21 papers.
As discussed in the RFC, there's little to debate here. This format exists and is in use. Hopefully this and P1689 will be useful jump-starts to the ecostd process as they should be relatively straightforward to move through the pipeline.