diff options
| -rw-r--r-- | manifest-reference.md | 23 | ||||
| -rw-r--r-- | src/fpm/manifest/package.f90 | 3 |
2 files changed, 25 insertions, 1 deletions
diff --git a/manifest-reference.md b/manifest-reference.md index 0a68c6a..2c79a02 100644 --- a/manifest-reference.md +++ b/manifest-reference.md @@ -49,6 +49,8 @@ Every manifest file consists of the following sections: Dependencies only needed for tests - [*install*](#installation-configuration): Installation configuration +- [*extra*](#additional-free-data-field): + Additional free data field [TOML]: https://toml.io/ @@ -479,3 +481,24 @@ By default only executables are installed, library projects can set the *library [install] library = true ``` + + +## Additional free data field + +Third-party tools can store their configuration inside the *extra* section. +This section will never be evaluated by fpm itself, the only constraint imposed it that is has to be valid TOML. + +Since the format of this section is free, only recommendations are provided here for adding data to the *extra* section. + +1. Only use subtables, never add configuration data to the toplevel of the *extra* section. + Reasoning: different tools can avoid collisions of keynames by placing their data in separate subtables +2. Use the concrete name of the tool rather than a generic name for the subtable. + Reasoning: different formatter or linter might use conflicting keywords in a *format* or *lint* subtable. + Also, users can tell from the table name which tool is preferred for usage with the project. +3. Fpm plugins should use a subtable with their plugin name in the *extra.fpm* section to store their data. + Reasoning: following this convention provides the user of fpm plugins with one section to configure their used plugins. +4. Use the fpm preferred style for keywords which is lowercase with dashes. + Reasoning: while there is no style check in this section, a consistent style in the whole manifest will make it easier for the user to understand the whole package manifest. + +Feedback for the recommendations above is very much welcome. +If you have a tool that uses the *extra* section in the package manifest, feel free to post it in at the [fpm discussion board](https://github.com/fortran-lang/fpm/discussions). diff --git a/src/fpm/manifest/package.f90 b/src/fpm/manifest/package.f90 index dba4d21..5cd8765 100644 --- a/src/fpm/manifest/package.f90 +++ b/src/fpm/manifest/package.f90 @@ -29,6 +29,7 @@ !>[[ executable ]] !>[[ example ]] !>[[ test ]] +!>[extra] !>``` module fpm_manifest_package use fpm_manifest_build, only: build_config_t, new_build_config @@ -303,7 +304,7 @@ contains case("version", "license", "author", "maintainer", "copyright", & & "description", "keywords", "categories", "homepage", "build", & & "dependencies", "dev-dependencies", "test", "executable", & - & "example", "library", "install") + & "example", "library", "install", "extra") continue end select |