1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
README for morph
================
> **NOTA BENE:** This document is very much work-in-progress, and anything
> and everything may and will change at little or no notice. If you see
> problems, mail baserock-dev@baserock.org.
`morph` builds binaries for [Baserock](http://www.baserock.org/),
an embedded Linux solution. Please see the website for overall information.
Usage
-----
The Baserock builds are controlled by **morphology** files,
which are build recipes. See below for their syntax. Everything
in Baserock is built from git commits, and also the morphologies
must be committed in git before building. The `morph` tool is
used to actually run the build. The usual workflow is this:
* put the morphology for an upstream project with its source code
* put other morphologies in the `morphs` (note plural) repository
* run `morph` to build stuff
Eventually, `morph` will get a manual page. Meanwhile, a short usage:
morph --keep-path -v build morphs master base-system.morph
Run `morph --help` to get a list of all options and short descriptions.
You can write a configuration file to avoid having to write options on
the command line every time. Put it in `~/.morph.conf` and make it look
something like this:
[config]
cachedir = /home/username/baserock/cache
log = /home/username/baserock/morph.log
log-max = 200M
git-base-url = file:///home/username/baserock/gits/
You should set at least the above settings.
Morphology file syntax
----------------------
JSON is used for the morphology syntax. For example, to build a chunk:
{
"name": "foo",
"kind": "chunk",
"configure-commands": [
"./configure --prefix=$PREFIX"
],
"build-commands": [
"make"
],
"test-commands": [
"make check"
],
"install-commands": [
"make DESTDIR=$DESTDIR install"
]
}
For all morphologies, use the following fields:
* `name`: the name of the morphology; it must currently match the filename
(without the `.morph` suffix); **required**
* `kind`: the kind of thing being built; **required**
For chunks, use the following fields:
* `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 and that
requires the `configure` script to have been committed into git;
optional
* `configure-commands`: a list of shell commands to run at the configuraiton
phase of a build; optional
* `build-commands`: a list of shell commands to run to build (compile) the
project; optional
* `test-commands`: a list of shell commands to run unit tests and other
non-interactive tests on the built but un-installed project; optional
* `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; optional
* `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 to run
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;
optional
* `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;
optional
For strata, use the following fields:
* `sources`: 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 chunk's name (may be different from the
morphology name), `repo` is the repository in which to find (defaults to
chunk name), `ref` identifies the commit to use (typically a branch
name, but any tree-ish git accepts is ok), and `morph` is the name
of the morphology to use; optional
For systems, use the following fields:
* `disk-size`: size of the disk image to be created; may use suffixes like
`M` and `G`; **required**
* `strata`: a list of stratum names to include in the system image;
**required**
Example chunk (simplified commands):
{
"name": "eglibc",
"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",
"sources": [
{
"name": "fhs-dirs",
"ref": "baserock/bootstrap"
},
{
"name": "linux-api-headers",
"repo": "linux",
"ref": "baserock/morph"
},
{
"name": "eglibc",
"ref": "baserock/bootstrap"
},
{
"name": "busybox",
"ref": "baserock/bootstrap"
}
]
}
Example system:
{
"name": "base",
"kind": "system",
"disk-size": "1G",
"strata": [
"foundation",
"linux-stratum"
]
}
Note that unknown keys in morphologies are silently ignored.
Build environment
-----------------
When `morph` runs build commands, it clears the environment of all
variables and creates new ones. This is so that the build will run
more consistently across machines and developers.
See the `morphlib/builder.py` file, method `setup_env` for details.
Until Baserock is properly bootstrapped, it's awkward that the `PATH`
variable gets reset. To avoid that, use the `--keep-path` option.
Hacking morph
-------------
Run the test suite with this command:
./check
Install CoverageTestRunner (from <http://liw.fi/coverage-test-runner/>),
and check out the `cmdtest` utility (from <http://liw.fi/cmdtest/>).
Run the checks before submitting a patch, please.
Legalese
--------
Copyright (C) 2011 Codethink Limited
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
