aboutsummaryrefslogtreecommitdiff
path: root/build.1
blob: 2655ce009bc4f4a68ab3c3e03770f18f798fd5b4 (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
.Dd $Mdocdate$
.Dt BUILD 1
.Os
.Sh NAME
.Nm build
.Nd follow embedded build instructions
.Sh SYNOPSIS
.Nm
.Op Fl d
.Op Fl d
.Op Fl d
.Op Fl f
.Ar file
.Op Ar ...
.Sh DESCRIPTION
.Pp
.Nm
is a program which follows simple build instructions
embedded in source files.
The number of
.Fl d
flags control the printing of debugging information.
The
.Fl f
flag disables modification time checks,
forcing the build process.
.Pp
.Nm
is decidedly not a
.Xr make 1
replacement, except in trivial cases.
In such cases, however,
it is a nice and simple solution.
The program is originally designed for generating
.Xr troff 1
documents,
but can be used with arbitrary source files.
.
.Sh SYNTAX
.Pp
The first twenty lines of each
.Ar file
are scanned for build information.
Build information is encoded in two ways:
.Bl -tag -width indent
.It command line (one or more)
[anything] <whitespace> "$ " <shell command>
.It dependency line (only one)
[anything] <whitespace> "% " <files separated by whitespace>
.El
.Pp
Within each command line,
.Nm
searches for a
.Em target :
.Bl -tag -width indent
.It target
">" <filename without whitespace>
.br
" -o " <filename without whitespace>
.El
.Pp
The last target found will be counted
as the real target for the build process.
If no target is found,
the commands will always be executed,
regardless of modification times.
.
.Sh OPERATION
.Pp
Unlike
.Xr make 1 ,
.Nm
executes all command lines,
joined by newlines,
in the same shell process.
This means that you can keep state across multiple commands.
Note that all commands are executed
regardless of the exit status of previous commands.
.Pp
If a command fails,
.Nm
exits with a positive status and aborts the build process.
.
.Sh EXAMPLES
.Pp
Assuming that the file
.Pa prg.c
starts with the following text,
.Bd -literal -offset indent
/**
  *  To build this program, use the following invocation:
  *     $ cc -O2 -o prg prg.c
  */
.Ed
.Pp
the invocation
.Bd -literal -offset indent
$ build prg.c
.Ed
.Pp
will build
.Pa prg ,
if it is older than
.Pa prg.c .
.Pp
Assuming that the file
.Pa doc.t
starts with the following text,
.Bd -literal -offset indent
\&.\\" This document is built with the following shell commands:
\&.\\"    $ export LC_ALL=en_US.UTF-8
\&.\\"    $ refer -p refs doc.t | troff -ms | dpost > doc.ps
\&.\\"    $ ps2pdf doc.ps > doc.pdf
\&.\\"    $ rm doc.ps
\&.
\&.\\" Apart from this file, it depends on the following files:
\&.\\"    % refs x.tmac
.Ed
.Pp
the invocation
.Bd -literal -offset indent
$ build doc.t
.Ed
.Pp
will build
.Pa doc.pdf ,
depending on the relative modification times of
.Pa doc.pdf ,
.Pa doc.t
and
.Pa x.tmac .
.\" .Sh DIAGNOSTICS
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
.Nm
is written by John Ankarström
.Aq Mt "john (at) ankarstrom.se" .
.\" .Sh BUGS