diff options
author | Will Woods <wwoods@redhat.com> | 2016-01-21 18:21:24 -0500 |
---|---|---|
committer | Will Woods <wwoods@redhat.com> | 2016-01-21 18:21:24 -0500 |
commit | 323d5763593156b66ba5c355d4b44c83168fa420 (patch) | |
tree | ef6f3369fe415fea3776441d11e6ef10878dd30d | |
parent | c47a48f14ccc72f829f5a03b58903250604df9cc (diff) | |
download | weld-docs-master.tar.gz weld-docs-master.tar.xz weld-docs-master.zip |
Starting to try to specify what the metadata should look like.
-rw-r--r-- | warp/0002-weld-metadata.md | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/warp/0002-weld-metadata.md b/warp/0002-weld-metadata.md new file mode 100644 index 0000000..d4c988a --- /dev/null +++ b/warp/0002-weld-metadata.md @@ -0,0 +1,145 @@ +# weld-pkg-metadata + +| WARP | 2 +|----------|-------------------------------------------------------- +| Title | Weld Package Metadata +| Author | Will Woods +| Type | Standards +| Proposed | 21 Jan 2016 +| Status | Draft + +---- + +# Summary +[summary]: #summary + +This document describes the package metadata used by the Weld project. + +# Motivation +[motivation]: #motivation + +The heart of a Linux distribution is its package metadata. [RPM]-based +distributions have [spec files], [dpkg]-based distributions +have the [`debian/` directory], [Gentoo] has [ebuild] files, and so on. + +Since everything produced by a Linux distribution is derived from this metadata, +it's crucial to the health of the project. Weld's metadata is designed with +the following goals in mind: + +1. **Simple**: the files should be short and (mostly) human-readable. +2. **Flexible**: we should be able to add new fields when needed. +3. **Powerful**: the metadata should be able to express everything currently + handled by [spec files] in Fedora. +4. **Customizable**: it should be easy for a Weld user to fork and build their + own variant, with different build flags, alternative implementations, etc. + +[RPM]: http://rpm.org/ +[spec files]: http://www.rpm.org/max-rpm/ch-rpm-inside.html +[dpkg]: https://en.wikipedia.org/wiki/Dpkg +[`debian/` directory]: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html +[Gentoo]: https://www.gentoo.org/ +[ebuild]: https://devmanual.gentoo.org/ebuild-writing/index.html + +[YUM metadata]: https://en.opensuse.org/openSUSE:Standards_Rpm_Metadata +[Fedora RPM Guide]: https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-specfiles.html + +# Specification +[spec]: #spec + +## File format + +Weld's metadata files are in [TOML] format, with sections, keys, and values +to be described below. + +[TOML]: https://github.com/toml-lang/toml + +## File names and repo layout + +The files are named `<package>.weld`, and they are kept in a git repo named +`weld-dist`. Related packages may grouped into subdirectories - for example, +`gfx/wayland.weld` or `dev/gcc.weld`. + +## File sections + +### `[upstream]` + +The `[upstream]` section describes where the upstream code can be found, what +format it's in, and other metadata pertaining to finding and fetching code +from the upstream developers. + +#### `homepage = <http-url>` + +_Optional._ Gives a `http` or `https` URL to the upstream project's homepage. + +#### `vcs = <url>` + +Gives the URL of the upstream's version control system. + +#### `tarball = <url>` + +Gives the URL to a tarball of released sources. + +The escape sequence `{version}` can be used as a placeholder for the version +string. + +### `[build]` + +The `[build]` section describes how to build the software + +# Rationale +[rationale]: #rationale + +## Considerations +[considerations]: #considerations + +One of the major goals for Weld is that package metadata and build instructions +should be encoded as _data_, not _code_ - in other words: no shell scripts +unless absolutely necessary. + +[TOML] was chosen because of its clean, simple syntax and unambiguous parsing +rules. This allows `.weld` files to be read and written easily in nearly any +popular programming language. + +## Alternatives +[alternatives]: #alternatives + +### `spec` + +* Under-documented - where's the specification for spec files? +* Inflexible - no `TestRequires`, and no easy way to add it +* Opaque - impossible to tell what scriptlets will do, how long they will take, + how much disk they might use, etc. + +### `debian/*` + +TODO + +### `ebuild` + +Also TODO + +### `Cargo.toml` and `Cargo.lock` + +TODO. A lot of what's going on here is inspired by (or coincidentally +similar to) [Cargo] and [Cargo manifest]s; look closer at it. + +[Cargo]: http://doc.crates.io/guide.html +[Cargo manifest]: http://doc.crates.io/manifest.html + +## Unresolved Questions +[questions]: #questions + +* How are we gonna create the initial set of `.weld` files? +* What escape sequences do we want/need? + * And what form should those take? `{name}`, `%n`, ..? +* If we're gonna talk about dependencies we need a spec for package / binary + match expressions + * like RPM version expressions (`xz >= 5.2.0`) + * or Cargo version expressions () + +# Copyright +[copyright]: #copyright + +This work is licensed under the Creative Commons Attribution 4.0 International +License. To view a copy of this license, visit +http://creativecommons.org/licenses/by/4.0/. |