From 3a27dea7161f8b1e0c4e386b104caed93ddcfafb Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Tue, 1 Mar 2016 12:17:47 +0000 Subject: Describe what chunks, systems & strata actually are, and link to schemas The spec was trying to be technically precise about describing the structure of the .morph files. The JSON-Schema format is much better than prose for precisely describing structure of JSON/YAML documents, so we should link to the schemas. The text of the spec can then be rewritten a bit so it describes the intention and meaning of the different .morph files a bit more clearly. More rewriting would be useful. It's also unfortunate that we have go as far as 4th-level headings (####), reorganising a bit could fix that. Change-Id: Ic502db0b5723a46f72d9cf375df623ad89b4686d --- spec.mdwn | 50 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/spec.mdwn b/spec.mdwn index 8e43b13..c7574d7 100644 --- a/spec.mdwn +++ b/spec.mdwn @@ -92,7 +92,16 @@ Within this document, consider 'building' to be the act of running a series of commands in a given 'environment', where the commands and how to build the environment are completely specified by the definitions and the build tool. -For chunks, use the following fields: +#### Chunks + +A 'chunk' definition describes an individual component, which can be built from +a Git repository by executing the given sequence of commands. + +The structure of a 'chunk' definition is described using [JSON-Schema] in the +[spec.git] repo: + + +The fields mean the following: * `build-system`: if the program is built using a build system known to `morph`, you can set this field and avoid having to set the various @@ -169,7 +178,17 @@ For chunks, use the following fields: created, named according to the definition, and containing all files; optional -For strata, use the following fields: +#### Strata + +A 'stratum' is a group of related chunks. A stratum can contain only chunks. +Certain information about how to build a chunk is defined in the containing +stratum, rather than in the chunk definition. + +The structure of a 'stratum' definition is described using [JSON-Schema] in the +[spec.git] repo: + + +The fields mean the following: * `build-depends`: a list of strings, each of which refers to another stratum that the current stratum depends on. This list may be omitted @@ -199,14 +218,23 @@ For strata, use the following fields: of a workaround for the lack of distinction between build and runtime dependencies. -For systems, use the following fields: +#### Systems + +In the Baserock model, a 'system' is the top level entity that you actually +build and execute. Systems contain one or more strata. + +The structure of a 'system' definition is described using [JSON-Schema] in the +[spec.git] repo: + + +The fields mean the following: * `strata`: a list of key/value mappings, similar to the 'chunks' field of a stratum. Two fields are allowed (are both required?): - `name`: name of the artifact when the stratum is build - `morph`: path to a stratum .morph file relative to the top of the containing repo -Example chunk (simplified commands): +#### Example chunk (simplified commands): name: eglibc kind: chunk @@ -218,7 +246,7 @@ Example chunk (simplified commands): install-commands: - cd o && make install_root="$DESTDIR" install -Example stratum: +#### Example stratum: name: foundation kind: stratum @@ -244,7 +272,7 @@ Example stratum: - fhs-dirs - linux-api-headers -Example system: +#### Example system: name: base kind: system @@ -265,8 +293,12 @@ post-processing a filesystem tree with one or more 'configure extensions', then performing an operation to convert and/or transfer the filesystem tree using a 'write extension'. +The structure of the 'cluster' definitions is described using [JSON-Schema] in +the [spec.git] repo: + + A cluster morphology defines a list of systems to deploy, and for each system a -list of ways to deploy them. Use the following field: +list of ways to deploy them. The fields are used as follows: * **systems**: a list of systems to deploy; the value is a list of mappings, where each mapping has the @@ -377,7 +409,9 @@ The following environment variables can be used in chunk configure/build/install FIXME: The `TARGET` and `TARGET_STAGE1` fields are specific to building GNU/Linux based systems, they shouldn't be mandated in the spec. +[JSON-Schema]: https://www.json-schema.org/ [Morph]: http://wiki.baserock.org/Morph/ [YBD]: http://wiki.baserock.org/ybd/ -[morph.git]: git://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/morph +[morph.git]: git://git.baserock.org/cgit/baserock/baserock/morph.git/ +[spec.git]: git://git.baserock.org/cgit/baserock/baserock/spec.git/ [YAML]: http://yaml.org/ -- cgit v1.2.1