-
Notifications
You must be signed in to change notification settings - Fork 4
/
part3-2-1.xml
185 lines (185 loc) · 6.34 KB
/
part3-2-1.xml
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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Build System</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Build System
</h3>
<p>
On modern <a class="term" href="glossary.xml#unix">UNIX</a> systems, the method for build management is overwhelmingly
the <a class="cmd" href="commands.xml#cmd_make">make</a> utility. Although there are two disjoint <a
href="commands.xml#cmd_make" class="cmd">make</a> implementations in use (namely by for <a
href="glossary.xml#gnu" class="term">GNU</a> and <a href="glossary.xml#bsd_unix" class="term">BSD UNIX</a>
systems), I examine the syntax common to both.
</p>
<p>
In this section, I'll assume the file <span class="file">Makefile</span> already exists, and is used to build a system
where one wishes to incorporate <span class="lang">mdoc</span> files.
</p>
<div class="screen">
all: foo
<br />
<br />
clean:
<br />
rm -f foo foo.o
<br />
<br />
install: all
<br />
install -m 0755 foo /usr/local/bin
<br />
<br />
foo: foo.o
<br />
cc -o foo foo.o
</div>
<p>
A rigorous analysis of this syntax is beyond the scope of this book (do consult your system's documentation for the <a
href="commands.xml#cmd_make" class="cmd">make</a> command with <span class="cmdline">man make</span>). It
defines the targets <span class="screen">all</span>, <span class="screen">clean</span>, and <span
class="screen">install</span>: build, clean up, and install the utility, respectively.
</p>
<h4>
File Extension
</h4>
<p>
First, it's important to settle upon an input and output file extension, as <a href="commands.xml#cmd_make"
class="cmd">make</a> tracks file status by way of comparing the time-stamp of a file's input (which may be
multiple files) and output (called the target). In short, if the target is older than any of the input files, it is
rebuilt. The input files are created and maintained by the developer; the output files are built by <a
href="commands.xml#cmd_make" class="cmd">make</a>.
</p>
<p>
For simplicity, I use the standard <span class="file">.1</span>, <span class="file">.2</span>, and so on convention for
the target (the output). I then use <span class="file">.in.1</span> and so on for input. Thus, it is necessary to
notify the <a href="commands.xml#cmd_make" class="cmd">make</a> utility of these new extensions before all other rules;
</p>
<div class="screen">
.SUFFIXES: .in.1 .1
</div>
<p>
If more categories are built, these would need to be added (e.g., <span class="screen">.in.3 .3</span>, etc.).
</p>
<h4>
Build Rules
</h4>
<p>
A build rule is required to translate input to output. Let's begin with a general rule to establish that the <span
class="lang">mdoc</span> syntax is correct. We'll add this to the target building the main system: this way,
all changes to the <span class="lang">mdoc</span> input file will be syntax-checked when <span
class="cmdline">make</span> is invoked. We'll use <a href="commands.xml#cmd_mandoc" class="cmd">mandoc</a> to
syntax-check the document.
</p>
<div class="screen">
.in.1.1:
<br />
mandoc -Tlint $<
<br />
#nroff -mandoc $< >/dev/null
<br />
cp -f $< $@
</div>
<p>
We also need to build the target and clean it. Assume that <span class="file">foo.1</span> is the output file and <span
class="file">foo.in.1</span>, the input.
</p>
<div class="screen">
all: foo foo.1
<br />
<br />
clean:
<br />
rm -f foo foo.o foo.1
</div>
<h4>
Result
</h4>
<p>
Putting these together, the new <span class="file">Makefile</span> is as follows:
</p>
<div class="screen">
.SUFFIXES: .in.1 .1
<br />
<br />
all: foo foo.1
<br />
<br />
clean:
<br />
rm -f foo foo.o foo.1
<br />
<br />
install: all
<br />
install -m 0755 foo /usr/local/bin
<br />
install -m 0644 foo.1 /usr/local/share/man/man1
<br />
<br />
foo: foo.o
<br />
cc -o foo foo.o
<br />
<br />
.in.1.1:
<br />
mandoc -Tlint $<
<br />
#nroff -mandoc $< >/dev/null
<br />
cp -f $< $@
</div>
<h4>
Formatted Output
</h4>
<p>
Let's build an <a class="term" href="glossary.xml#html">HTML</a> manual with the <span class="cmdline">make www</span>
rule. For simplicity, we won't install this file; it's merely for instruction. This rule will translate the built
manual <span class="file">foo.1</span> into an HTML file <span class="file">foo.1.html</span>.
</p>
<div class="screen">
.SUFFIXES: .in.1 .1 .1.html
</div>
<p>
Let's let our rule include a <a class="term" href="glossary.xml#css">CSS</a> file. Note that the traditional <a
class="term cmd" href="commands.xml#cmd_nroff">nroff</a> utility doesn't include HTML output.
</p>
<div class="screen">
foo.1.html: style.css
<br />
<br />
.1.1.html:
<br />
mandoc -Thtml -Ostyle=style.css $< >$@
</div>
<p>
The target rule is simply as follows:
</p>
<div class="screen">
www: foo.1.html
</div>
<p>
The reason for building from <span class="file">foo.1</span> instead of <span class="file">foo.in.1</span> is that we
may wish to postprocess the <span class="file">foo.1</span> file after it has been created. However, this is entirely
decision of the programmer.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part3-2-2.xml">Next</a></td>
<td class="nav-home"><a href="http://manpages.bsd.lv/index.html">Home</a></td>
<td class="nav-history"><a href="http://manpages.bsd.lv/cgi-bin/cvsweb/part3-2-1.xml?cvsroot=manpages">History</a></td>
</tr>
</tbody>
</table>
<p class="edits">
Last edited by $Author$ on $Date$. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.
</p>
</body>
</html>