summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJoel Dillon <joel.dillon@codethink.co.uk>2012-09-05 14:08:23 +0100
committerJoel Dillon <joel.dillon@codethink.co.uk>2012-09-05 14:08:23 +0100
commit7f4355fd6dd4976e5b7d5421992718ab7763a682 (patch)
treecd9dbce48e0fb54d4c027565fba09b3e5c64ab5f
parent6ee84608f0179226c38ffb88408afbc2336fe560 (diff)
downloaddocumentation-7f4355fd6dd4976e5b7d5421992718ab7763a682.tar.gz
Add initial documentation of morphology file format
-rw-r--r--morphology.txt45
-rw-r--r--morphology_examples.txt59
2 files changed, 104 insertions, 0 deletions
diff --git a/morphology.txt b/morphology.txt
new file mode 100644
index 0000000..336f88a
--- /dev/null
+++ b/morphology.txt
@@ -0,0 +1,45 @@
+Morphology files define how Baserock builds artifacts of different types. There are three types - identified by the `kind` field (see below) - corresponding to the three types of Baserock artifact:; `systems`, `strata`, and `chunks`.
+
+`system` and `strata` morphology files live in the 'morphs' git repository
+
+`chunks` morphology files live in a branch of the user's choice (as specified in the strata morphology file), in a chunk, at the top level. They are optional for chunks that Baserock natively knows how to build.
+
+The following **required** field common to all morphologies:
+
+* `kind`: the type of thing being built (system, stratum, chunk).
+* `name`: the name of the thing; for strata this is the same as the morphology file, for chunks it is the same as the base name of the repository.
+
+The following **optional** field is common to all morphologies:
+
+* `description`: a human-readable string describing the morphology.
+
+The following **optional** fields, are specific to `chunk` morphologies:
+
+* `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 `*-commands` fields; only `autotools` is currently known; the commands that the build system specifies can be overridden.
+* `configure-commands`: a list of shell commands to run at the configuration phase of a build.
+* `build-commands`: a list of shell commands to run to build (compile) the project.
+* `test-commands`: a list of shell commands to run unit tests and other non-interactive tests on the built but un-installed project.
+* `install-commands`: a list of shell commands to install the built project; the install should go into the directory named in the `DESTDIR` environment variable, not the actual system.
+* `max-jobs`: a string to be given to `make` as the argument to the `-j` option to specify the maximum number of parallel jobs; the only sensible value is `"1"` (including the quotes), to prevent parallel jobs running at all; parallel jobs are only used during the `build-commands` phase, since the other phases are often not safe when run in parallel; `morph` picks a default value based on the number of CPUs on the host system.
+* `chunks`: a key/value map of lists of regular expressions;
+ the key is the name of a binary chunk, the regexps match the pathnames that will be included in that chunk; the patterns match the pathnames that get installed by `install-commands` (the whole path below `DESTDIR`); every file must be matched by at least one pattern; by default, a single chunk gets created, named according to the morphology, and containing all files.
+
+The following **optional** fields, are specific to `strata` morphologies:
+
+* `build-depends`: a list of strings, each of which refers to another stratum that the current stratum depends on. This list may be omitted or empty if the stratum does not depend on anything else.
+* `chunks`: a list of key/value mappings, where each mapping corresponds to a chunk to be included in the stratum; the mappings may use the following keys:
+ + `name` is the name of the chunk.
+ + `repo` is the repository in which to find it (defaults to chunk name).
+ + `ref` identifies the commit to use (typically a branch name, but any tree-ish git accepts is ok).
+ + `morphology` is the name of the morphology to use and is optional.
+ In addition to these keys, each of the sources MUST specify a list of build dependencies using the `build-depends` field. This field may be omitted to make the source depend on all other chunks that are listed earlier in the `chunks` list. The field may be an empty list to indicate that the chunk does not depend on anything else in the same stratum. To specify one or more chunk dependencies, `build-depends` needs to be set to a list that contains the names of chunks that the source depends on in the same stratum. These names correspond to the values of the `name` fields of the other chunks.
+
+The following **required** fields are specific to `system` morphologies:
+
+* `disk-size`: size of the disk image to be created. The size may be suffixed with 'G', 'M' or 'K' for gigabytes, megabytes and kilobytes respectively.
+* `strata`: a list of stratum names to include in the system image; these are specified similarly to the `chunks` section of the `strata` morphology.
+* `arch`: a description of the target architecture, e.g. 'arm' or 'x86_64'.
+* `system-kind`: either 'rootfs-tarball' for a tarball or 'syslinux-disk' to produce a bootable image.
+
+Fields with keys unknown to Morph are silently ignored.
+
diff --git a/morphology_examples.txt b/morphology_examples.txt
new file mode 100644
index 0000000..5cabeec
--- /dev/null
+++ b/morphology_examples.txt
@@ -0,0 +1,59 @@
+Example chunk (simplified commands):
+
+ {
+ "kind": "chunk",
+ "configure-commands": [
+ "mkdir o",
+ "cd o && ../libc/configure --prefix=/usr"
+ ],
+ "build-commands": [
+ "cd o && make"
+ ],
+ "install-commands": [
+ "cd o && make install_root=\"$DESTDIR\" install"
+ ]
+ }
+
+Example stratum:
+
+ {
+ "name": "foundation",
+ "kind": "stratum",
+ "chunks": [
+ {
+ "ref": "baserock/bootstrap",
+ "build-depends": [],
+ },
+ {
+ "repo": "linux",
+ "ref": "baserock/morph",
+ "build-depends": ["fhs-dirs"]
+ },
+ {
+ "ref": "baserock/bootstrap",
+ "build-depends": [
+ "linux-api-headers"
+ ]
+ },
+ {
+ "ref": "baserock/bootstrap",
+ "build-depends": [
+ "fhs-dirs",
+ "linux-api-headers"
+ ]
+ }
+ ]
+ }
+
+Example system:
+
+ {
+ "kind": "system",
+ "arch": "arm",
+ "system-kind": "syslinux-disk",
+ "disk-size": "1G",
+ "strata": [
+ "foundation",
+ "linux-stratum"
+ ]
+ }