summaryrefslogtreecommitdiff
path: root/mbld/mbld.1
blob: c92c580c8adeaa2dd2e72fcc4a41176bf4527f2e (plain)
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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
.TH MBLD 1
.SH NAME
mbld
.SH SYNOPSIS
.B mbld
[
.B -?hcfrSs
]
[
.B -b
.I bin
]
[
.B -l
.I lib
]
[
.B -R
.I src
]
[
.B -I
.I inc
]
[
.B -B
.I base
]
[
.B -r
.I runtime
]
[
.I all
|
.I clean
|
.I install
|
.I uninstall
|
.I test
|
.I file ...
|
.I target ...
]
.br
.SH DESCRIPTION
.PP
The
.I mbld
tool takes as input a list of Myrddin or assembly sources,
and compiles them in the correct dependency order into either a library,
or an executable.
.PP
By default, it reads from an input file called
.IR bld.proj ,
but if given the option
.B -b
or
.BR -l ,
it will build a binary or library, respectively, from
the arguments specified on the command lines.
.PP
.I Mbld
will default to building for the current architecture and operating
system.
.SH OPTIONS
.TP
.BR -h\  |\ -?
Print a summary of the available options.
.TP
.BI -b\  binname
Compile source into a binary named
.IR name .
If neither this option nor the
.B -l
option are given, mbld will create a binary called
.IR a.out .
.TP
.BI -I\  path
Add
.I path
to the search path for unquoted use statments. This option
does not affect the search path for local usefiles, which are always
searched relative to the compiler's current working directory. Without
any options, the search path defaults to
.IR /usr/include/myr .
.TP
.BI -l\  libname
Compile source given into a library called
.I libname.a
(or the equivalent
for the target platform), and a matching usefile called
.IR name .
Only static
libraries are currently supported. Ignores the contents of
.I bld.proj
and
.I bld.sub
if they exist.
.TP
.BI -R\  src
Compile source given into a binary in temporary storage, and then execute it
with the command line arguments passed in.
.TP
.B -S
Tell the toolchain to generate assembly for the code being compiled as well
as the .o files, as though
.B -S
was passed to
.IR 6m .
.TP
.BI -r\  runtime
Compile a binary using the given runtime.
If the runtime name given is
.IR none ,
then no runtime will be linked. If this option is not provided,
then the default runtime in
.B $INSTALL_ROOT/myr/lib/_myrrt.o
will be used.
.SH ACTIONS
.I Mbld
already knows how to do most of the common commands. Given a file
describing your project, it can build, test, clean, install, uninstall,
and benchmark your code.
.TP
.B all
The
.I all
action will build all the non-test targets specified in the build file.
If there are generated files included in the build, then their generation
commands will be run.
.TP
.B clean
The
.I clean
action will remove all compiled files and non-durable generated inputs
from the build directories.
.TP
.B install
The
.I install
action will copy the generated sources, manpages, data files, and anything
else installable into the appropriate directories for the current system.
If the
.B $DESTDIR
environment variable is set, then its contexts will be prepended to the
install path.
.TP
.B uninstall
The
.I uninstall
action will remove the files installed by the
.I install
action.
.TP
.B test
The
.I test
action will build the test cases, and run them. If the test case
exits with a non-zero status, that is counted as a failure. If a
test outputs subtest data, then this target will show the output
in a pretty format.
.TP
.B bench
The
.I bench
action will build the benchmarks and run them. At the end of the
run, the run statistics are shown. Benchmarks must generate output
in the subtest format.
.TP
.B list
The
.I list
action lists all available targets for the build.
.SH BUILD FILES
Build files contain lists of targets. Targets generally
consist of a target type. This is usually followed by
target name, an attribute list, and the list of inputs.
Each Myrddin source file may have a corresponding implicit
test. If a source file
.I foo.myr
is built, then the corresponding
.I test/foo.myr
is used as the testcase for
.I foo.myr
if it exists.
.PP
A typical build file may look something like:
.IP
.EX
bin foo = main.myr gen-foo.myr ;;
man = foo.1 ;;
gen gen-foo.myr = sh -c "echo $FOO > gen-foo.myr" ;;
lib foothing = lib.myr ;;
.EE
.LP
The full grammar is listed below:
.IP
.EX
bldfile : bldent+
bldent  : "bin" target
        | "lib" target
        | "test" target
        | "bench" target
        | "gen" target
        | "cmd" target
        | "data" flist
        | "man" flist
        | "sub" flist
        | option
option  : "incpath" "=" list
        | "libdeps" "=" list
        | "testdeps" "=" list
        | "runtime" word
        | "noinst"
target  : name [attrs] "=" list
flist   : [attrs] "=" list
list    : name+ ";;"
attrs   : "{" (key [ "=" value])* "}"
name    : <nonspace> | <quoted word>
.EE
.LP
.PP
.IR Bin ,
.IR test ,
and
.I bench
targets all behave in a
very similar way. They all produce a single binary
from a list of Myrddin sources, scraping the appropriate
library dependencies and building any libraries from
the local source directories.
.I Bin
targets are installed to
.B $BASEDIR/bin
when invoking
.IR mbld\ install .
.I Test
and
.I bench
targets built and run
when invoking
.I mbld
.IR bench .
Tests are run with the working directory set to the directory
that contains the test source
.PP
.I Lib
targets also resemble
.I bin
targets, but instead of producing a binary, they produce a
.I .use
and
.I .a
file pair. These files are installed to
.B $BASEDIR/lib/myr
when invoking
.IR mbld\ install .
.PP
.I Gen
and
.I cmd
targets are also similar to each other,
varying largely in when and how they are invoked.
.I Gen
targets specify an output file, and are run in
response to a target requiring their output.
.PP
On the other targets are not invoked implicitly at all,
unless they have an attribute such as
.I test
or
.IR bench .
Instead, they are invoked explicitly by the user, bundling
up some useful command or another, possibly providing system
specific variants.
.PP
Data targets allow the specification of bundled static data.
This data may be generated from a
.I gen
target, or may simply be shipped as a file. The data is
installed to the system specific share directory. For example,
on Unix, this may be
.BR $BASEDIR/share .
.PP
Man targets are installed to the system-appropriate manual
directory. The section is determined by the manpage suffix.
For example
.I foo.1
would be installed into section 1 of the manual.
.PP
.I Sub
targets include a
.I bld.sub
or
.I bld.proj
from a subdirectory. If the file in the subdirectory is
.I bld.proj
then the root of the project is changed for that subbuild.
.SH ATTRIBUTES
Many targets support attributes. These are the valid
attributes allowed in the targets.
.TP
.B ldscript
Link the target using an ldscript. This is a system
dependent option, and should be avoided. Valid on binary
targets.
.TP
.B runtime
Link the target using a custom runtime. Valid on binary
targets
.TP
.B inc=path
Add a path to the include
.IR path .
Valid on binary targets.
.TP
.B tag=tagname
Build this target only when the build tag
.I tagname
is specified.
.TP
.B inst
Install this target. This is the default for all non-test
targets.
.TP
.B noinst
Do not install this target when running
.IR mbld\ install .
.TP
.B test
This target should run as a test. This is how command targets
are turned into test runners.
.TP
.B bench
This target is run as a benchmark. This is how command targets
are turned into benchmark runners.
.TP
.B notest
This target is not to be run as a benchmark. It's particularly
fun to use in conjunction with test targets, in spite of being
spectacularly useless.
.TP
.B durable
The file generated by this
.I gen
or
.I cmd
target should not be removed with
.IR mbld\ clean .
This is useful for keeping around files where the user may not
have or want to run the generation code.
.TP
.B dep=path
Specifies that a
.I gen
or
.I cmd
target should be re-run when the argument changes.
.TP
.B path=path
When specified on a data target, provides the desired
installation directory. Defaults to
.BR $BASEDIR/share .
.SH FILES
.TP
.I bld.proj
The root project file. All paths in bldfiles are relative
to the most recent one in the directory heirarchy.
.TP
.I bld.sub
A sub build. This contains targets, and may specify dependencies
on other targets within the same project.
.SH EXAMPLE
.EX
mbld
.EE
.PP
The command above will load bld.proj and all associated sub builds,
and run the commands to incrementally rebuild the code.
.EX
mbld -l foo bar.myr baz.myr
.EE
.PP
The command above will ignore bld.proj and produce a library named
.IR libfoo.a ,
consisting of the files
.I bar.myr
and
.IR baz.myr .
.SH ENVIRONMENT VARIABLES
.TP
.B DESTDIR
Prepends
.B $DESTDIR
to the installation path. For example, if the installation prefix is
/amd64 and the binary path is /bin, the resulting binaries will be
copied to
.B $DESTDIR/amd64/bin
on
.IR mbld\ install .
.TP
.B MYR_MC
Compiles the binaries with
.B $MYR_MC
instead of the default value,
.IR 6m .
.TP
.B MYR_MUSE
Merges usefiles with
.B $MYR_MUSE
instead of the default value
.IR muse .
.TP
.B MYR_RT
Links with the runtime $MYR_RT instead of the default
.BR $BASEDIR/lib/myr/_myrrt.o .
.SH SOURCES
The source for mbld is available from
.B git://git.eigenstate.org/git/ori/mc.git
and lives in the
.I mbld
directory within the source tree.
.SH SEE ALSO
.IR 6m (1),
.IR muse (1),
.IR make (1),
.IR mk (1)
.SH BUGS
.PP
None known.