diff options
Diffstat (limited to 'spec.mdwn')
| -rw-r--r-- | spec.mdwn | 37 |
1 files changed, 20 insertions, 17 deletions
@@ -59,12 +59,11 @@ integer. The integer specifies the version of the definitions format that this repo uses. A tool should refuse to process a version that it doesn't support, to -avoid unpredictable errors. See the "Versioning" heading above for more detail -on versions. +avoid unpredictable errors. See also the [Versioning](#versioning) section. The top directory of the repo can also contain a file named `DEFAULTS`. This holds repo-wide 'build-system' and 'split-rules' information. See the -'Defaults' section below. +[defaults](#defaults) section below. To find all the Baserock definition files in the repo, tooling can recursively scan the contents of the repo for files matching the glob pattern "\*.morph". @@ -90,13 +89,14 @@ For all definitions, use the following fields: * `kind`: the kind of thing being built; **required** * `description`: a comment to describe what the definition is for; optional -### Build definitions: Chunks, Systems and Strata +Build definitions: Chunks, Systems and Strata +--------------------------------------------- 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. -#### Chunks +### Chunks A 'chunk' definition describes an individual component, which can be built from a Git repository by executing the given sequence of commands. @@ -130,7 +130,7 @@ chunk: - cd o && make install_root="$DESTDIR" install A chunk can optionally make use of a repo-wide build system defined in -'DEFAULTS', by using the `build-system` field. In this case, the +['DEFAULTS'](#defaults), by using the `build-system` field. In this case, the command sequences defined in DEFAULTS are used. Any predefined command sequence can be overridden by specifying a new value. @@ -154,7 +154,7 @@ For example: build-commands: - make all -If a chunk doesn't need to override anything from 'DEFAULTS', you can avoid +If a chunk doesn't need to override anything from ['DEFAULTS'](#defaults), you can avoid having a chunk .morph file altogether, and just set 'build-system' when referring to the chunk from the stratum. @@ -166,7 +166,7 @@ phases are often not safe when run in parallel; `morph` picks a default value based on the number of CPUs on the host system. Built chunks are split up into multiple artifacts. The default splitting rules -for a chunk are defined in 'DEFAULTS'. You can use the `chunks` field of a +for a chunk are defined in ['DEFAULTS'](#defaults). You can use the `chunks` field of a chunk to override these. The `chunks` field is 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 @@ -175,7 +175,7 @@ pathnames that get installed by `install-commands` (the whole path below single chunk gets created, named according to the definition, and containing all files. -#### Strata +### 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 @@ -215,7 +215,7 @@ The fields mean the following: of a workaround for the lack of distinction between build and runtime dependencies. -#### Systems +### Systems In the Baserock model, a 'system' is the top level entity that you actually build and execute. Systems contain one or more strata. @@ -231,7 +231,7 @@ The fields mean the following: - `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 stratum: +### Example stratum: name: foundation kind: stratum @@ -257,7 +257,7 @@ The fields mean the following: - fhs-dirs - linux-api-headers -#### Example system: +### Example system: name: base kind: system @@ -265,7 +265,8 @@ The fields mean the following: - morph: foundation - morph: linux-stratum -### Deployment definitions: Clusters +Deployment definitions: Clusters +-------------------------------- For 'deployment', Baserock defines an API for running 'extensions'. The 'cluster' and 'system' definitions together describe what extensions should be @@ -345,7 +346,8 @@ Example: cluster-foo-armv7-2: HOSTNAME: cluster-foo-armv7-2 -### Repo URLs +Repo URLs +--------- Git repository locations can (and should) be abbreviated using the 'repo-alias' feature of Baserock definitions. This is a kind of [Compact URI](http://www.w3.org/TR/2009/CR-curie-20090116/). It currently only affects the 'repo' fields in a stratum .morph file. @@ -372,7 +374,8 @@ There are two repo aliases that *must* be defined: Baserock tools should allow changing these values. The main benefit of this compact URI scheme is that definitions are not tied to a specific Git server, or protocol. You can build against a mirror of the original Git server, or change the protocol that is used, just by altering the repo-alias configuration. -### Defaults +Defaults +-------- A definitions repository can contain a file named DEFAULTS. This file sets up repo-wide configuration. @@ -381,7 +384,7 @@ The structure of the DEFAULTS file is described using [JSON-Schema] in the [spec.git] repo: <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/defaults.json-schema> -#### Build systems +### Build systems You can define common command sequences using the 'build-systems' key. These can then be referenced in chunk (and stratum) definitions, to avoid repeating @@ -398,7 +401,7 @@ system: install-commands: - python setup.py install --prefix "$PREFIX" --root "$DESTDIR" -#### Splitting rules +### Splitting rules One 'source' in Baserock can produce multiple binary 'artifacts'. This allows you to separate programs, libraries, documentation, debugging information, and |