Annotation of htdocs/docs/pkgsrc/makefile.html, revision 1.22
1.1 dsieger 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html>
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.4 rillig 5: <title>Chapter 12. Programming in Makefiles</title>
1.11 spz 6: <link rel="stylesheet" type="text/css" href="/global.css">
1.1 dsieger 7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
1.9 rillig 8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.1 dsieger 9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.4 rillig 10: <link rel="prev" href="components.html" title="Chapter 11. Package components - files, directories and contents">
11: <link rel="next" href="plist.html" title="Chapter 13. PLIST issues">
1.1 dsieger 12: </head>
13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
14: <div class="navheader">
15: <table width="100%" summary="Navigation header">
1.10 wiz 16: <tr><th colspan="3" align="center">Chapter 12. Programming in <code class="filename">Makefile</code>s</th></tr>
1.1 dsieger 17: <tr>
18: <td width="20%" align="left">
19: <a accesskey="p" href="components.html">Prev</a> </td>
20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
21: <td width="20%" align="right"> <a accesskey="n" href="plist.html">Next</a>
22: </td>
23: </tr>
24: </table>
25: <hr>
26: </div>
1.13 asau 27: <div class="chapter">
1.1 dsieger 28: <div class="titlepage"><div><div><h2 class="title">
1.4 rillig 29: <a name="makefile"></a>Chapter 12. Programming in <code class="filename">Makefile</code>s</h2></div></div></div>
1.1 dsieger 30: <div class="toc">
31: <p><b>Table of Contents</b></p>
1.20 leot 32: <dl class="toc">
1.4 rillig 33: <dt><span class="sect1"><a href="makefile.html#makefile.style">12.1. Caveats</a></span></dt>
1.10 wiz 34: <dt><span class="sect1"><a href="makefile.html#makefile.variables">12.2. <code class="filename">Makefile</code> variables</a></span></dt>
1.4 rillig 35: <dd><dl><dt><span class="sect2"><a href="makefile.html#makefile.variables.names">12.2.1. Naming conventions</a></span></dt></dl></dd>
36: <dt><span class="sect1"><a href="makefile.html#makefile.code">12.3. Code snippets</a></span></dt>
1.1 dsieger 37: <dd><dl>
1.4 rillig 38: <dt><span class="sect2"><a href="makefile.html#adding-to-list">12.3.1. Adding things to a list</a></span></dt>
1.22 ! sevan 39: <dt><span class="sect2"><a href="makefile.html#echo-literal">12.3.2. Echoing a string exactly as-is</a></span></dt>
1.21 rillig 40: <dt><span class="sect2"><a href="makefile.html#cflags-gnu-configure">12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
41: <dt><span class="sect2"><a href="makefile.html#empty-variables">12.3.4. Handling possibly empty variables</a></span></dt>
1.1 dsieger 42: </dl></dd>
43: </dl>
44: </div>
45: <p>Pkgsrc consists of many <code class="filename">Makefile</code> fragments,
46: each of which forms a well-defined part of the pkgsrc system. Using
1.12 dholland 47: the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> system as a programming language for a big system
1.1 dsieger 48: like pkgsrc requires some discipline to keep the code correct and
49: understandable.</p>
50: <p>The basic ingredients for <code class="filename">Makefile</code>
51: programming are variables (which are actually macros) and shell
52: commands. Among these shell commands may even be more complex ones
1.12 dholland 53: like <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?awk+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">awk</span>(1)</span></a> programs. To make sure that every shell command runs
1.1 dsieger 54: as intended it is necessary to quote all variables correctly when they
55: are used.</p>
56: <p>This chapter describes some patterns, that appear quite often in
57: <code class="filename">Makefile</code>s, including the pitfalls that come along
58: with them.</p>
1.13 asau 59: <div class="sect1">
1.1 dsieger 60: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 61: <a name="makefile.style"></a>12.1. Caveats</h2></div></div></div>
1.13 asau 62: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
1.1 dsieger 63: <p>When you are creating a file as a
64: target of a rule, always write the data to a temporary file first
65: and finally rename that file. Otherwise there might occur an error
66: in the middle of generating the file, and when the user runs
1.12 dholland 67: <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> for the second time, the file exists and will not be
1.1 dsieger 68: regenerated properly. Example:</p>
69: <pre class="programlisting">
70: wrong:
71: @echo "line 1" > ${.TARGET}
72: @echo "line 2" >> ${.TARGET}
73: @false
74:
75: correct:
76: @echo "line 1" > ${.TARGET}.tmp
77: @echo "line 2" >> ${.TARGET}.tmp
78: @false
79: @mv ${.TARGET}.tmp ${.TARGET}
80: </pre>
1.5 hubertf 81: <p>When you run <span class="command"><strong>make wrong</strong></span> twice, the file
1.1 dsieger 82: <code class="filename">wrong</code> will exist, although there was an error
1.5 hubertf 83: message in the first run. On the other hand, running <span class="command"><strong>make
1.1 dsieger 84: correct</strong></span> gives an error message twice, as expected.</p>
1.12 dholland 85: <p>You might remember that <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> sometimes removes
1.1 dsieger 86: <code class="literal">${.TARGET}</code> in case of error, but this only
87: happens when it is interrupted, for example by pressing
88: <code class="literal">^C</code>. This does <span class="emphasis"><em>not</em></span> happen
1.12 dholland 89: when one of the commands fails (like <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?false+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">false</span>(1)</span></a> above).</p>
1.1 dsieger 90: </li></ul></div>
91: </div>
1.13 asau 92: <div class="sect1">
1.1 dsieger 93: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 94: <a name="makefile.variables"></a>12.2. <code class="filename">Makefile</code> variables</h2></div></div></div>
1.1 dsieger 95: <p><code class="filename">Makefile</code> variables contain strings that
96: can be processed using the five operators ``='', ``+='', ``?='',
1.12 dholland 97: ``:='', and ``!='', which are described in the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man
1.1 dsieger 98: page.</p>
99: <p>When a variable's value is parsed from a
100: <code class="filename">Makefile</code>, the hash character ``#'' and the
101: backslash character ``\'' are handled specially. If a backslash is
102: followed by a newline, any whitespace immediately in front of the
103: backslash, the backslash, the newline, and any whitespace
104: immediately behind the newline are replaced with a single space. A
105: backslash character and an immediately following hash character are
106: replaced with a single hash character. Otherwise, the backslash is
107: passed as is. In a variable assignment, any hash character that is
108: not preceded by a backslash starts a comment that continues upto the
109: end of the logical line.</p>
1.21 rillig 110: <p>The evaluation of variables either happens immediately or lazy.
111: It happens immediately when the variable occurs
112: on the right-hand side of the ``:='' or the ``!='' operator, in a
113: <code class="varname">.if</code> condition or a <code class="varname">.for</code> loop.
114: In the other cases, it is evaluated lazily.</p>
1.1 dsieger 115: <p>Some of the modifiers split the string into words and then
116: operate on the words, others operate on the string as a whole. When
1.21 rillig 117: a string is split into words, it is split like in <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">sh</span>(1)</span></a>.</p>
1.1 dsieger 118: <p>There are several types of variables that should be handled
119: differently. Strings and two types of lists.</p>
1.13 asau 120: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.10 wiz 121: <li class="listitem"><p><span class="emphasis"><em>Strings</em></span> can contain arbitrary
1.1 dsieger 122: characters. Nevertheless, you should restrict yourself to only
123: using printable characters. Examples are
124: <code class="varname">PREFIX</code> and
125: <code class="varname">COMMENT</code>.</p></li>
1.10 wiz 126: <li class="listitem"><p><span class="emphasis"><em>Internal lists</em></span> are lists that
1.1 dsieger 127: are never exported to any shell command. Their elements are
128: separated by whitespace. Therefore, the elements themselves cannot
129: have embedded whitespace. Any other characters are allowed.
1.5 hubertf 130: Internal lists can be used in <span class="command"><strong>.for</strong></span> loops.
1.1 dsieger 131: Examples are <code class="varname">DEPENDS</code> and
132: <code class="varname">BUILD_DEPENDS</code>.</p></li>
1.10 wiz 133: <li class="listitem"><p><span class="emphasis"><em>External lists</em></span> are lists that
1.1 dsieger 134: may be exported to a shell command. Their elements can contain any
135: characters, including whitespace. That's why they cannot be used
1.5 hubertf 136: in <span class="command"><strong>.for</strong></span> loops. Examples are
1.1 dsieger 137: <code class="varname">DISTFILES</code> and
138: <code class="varname">MASTER_SITES</code>.</p></li>
139: </ul></div>
1.13 asau 140: <div class="sect2">
1.1 dsieger 141: <div class="titlepage"><div><div><h3 class="title">
1.4 rillig 142: <a name="makefile.variables.names"></a>12.2.1. Naming conventions</h3></div></div></div>
1.13 asau 143: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.10 wiz 144: <li class="listitem"><p>All variable names starting with an underscore
1.1 dsieger 145: are reserved for use by the pkgsrc infrastructure. They shall
146: not be used by package
147: <code class="filename">Makefile</code>s.</p></li>
1.10 wiz 148: <li class="listitem"><p>In <span class="command"><strong>.for</strong></span> loops you should use
1.1 dsieger 149: lowercase variable names for the iteration
150: variables.</p></li>
1.10 wiz 151: <li class="listitem"><p>All list variables should have a ``plural''
1.1 dsieger 152: name, e.g. <code class="varname">PKG_OPTIONS</code> or
153: <code class="varname">DISTFILES</code>.</p></li>
154: </ul></div>
155: </div>
156: </div>
1.13 asau 157: <div class="sect1">
1.1 dsieger 158: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 159: <a name="makefile.code"></a>12.3. Code snippets</h2></div></div></div>
1.13 asau 160: <div class="sect2">
1.1 dsieger 161: <div class="titlepage"><div><div><h3 class="title">
1.4 rillig 162: <a name="adding-to-list"></a>12.3.1. Adding things to a list</h3></div></div></div>
1.21 rillig 163: <p>When adding a string that possibly contains whitespace or quotes to
164: a list (example 1), it must be quoted using the <code class="code">:Q</code>
165: modifier.</p>
166: <p>When adding another list to a list (example 2), it must not be
167: quoted, since its elements are already quoted.</p>
1.1 dsieger 168: <pre class="programlisting">
1.21 rillig 169: STRING= foo * bar `date`
170: LIST= # empty
171: ANOTHER_LIST= a=b c=d
1.1 dsieger 172:
1.21 rillig 173: LIST+= ${STRING:Q} # 1
174: LIST+= ${ANOTHER_LIST} # 2
1.1 dsieger 175: </pre>
176: </div>
1.13 asau 177: <div class="sect2">
1.1 dsieger 178: <div class="titlepage"><div><div><h3 class="title">
1.22 ! sevan 179: <a name="echo-literal"></a>12.3.2. Echoing a string exactly as-is</h3></div></div></div>
1.21 rillig 180: <p>Echoing a string containing special characters needs special
181: work.</p>
1.1 dsieger 182: <pre class="programlisting">
183: STRING= foo bar < > * `date` $$HOME ' "
1.21 rillig 184: EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
1.1 dsieger 185:
186: all:
187: echo ${STRING} # 1
1.21 rillig 188: echo ${STRING:Q} # 2
189: printf '%s\n' ${STRING:Q}'' # 3
190: env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
191: </pre>
192: <p>Example 1 leads to a syntax error in the shell, as the characters
193: are just copied.</p>
194: <p>Example 2 quotes the string so that the shell interprets it
195: correctly. But the echo command may additionally interpret strings with a
196: leading dash or those containing backslashes.</p>
197: <p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?printf+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> only
198: interprets the format string, but not the next argument.</p>
199: <p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
200: need to be quoted because the quoting has already been done
201: when adding elements to the list.</p>
1.1 dsieger 202: </div>
1.13 asau 203: <div class="sect2">
1.1 dsieger 204: <div class="titlepage"><div><div><h3 class="title">
1.21 rillig 205: <a name="cflags-gnu-configure"></a>12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
206: <p>When passing <code class="varname">CFLAGS</code> or similar variables to a
207: GNU-style configure script (especially those that call other configure
208: scripts), it must not have leading or trailing whitespace, since
209: otherwise the configure script gets confused. To trim leading and
210: trailing whitespace, use the <code class="code">:M</code> modifier, as in the
211: following example:</p>
1.1 dsieger 212: <pre class="programlisting">
213: CPPFLAGS= # empty
1.21 rillig 214: CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
1.1 dsieger 215: CPPFLAGS+= ${MY_CPPFLAGS}
216:
217: CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
218:
219: all:
220: echo x${CPPFLAGS:Q}x # leading and trailing whitespace
1.21 rillig 221: echo x${CONFIGURE_ARGS:Q}x # properly trimmed
1.1 dsieger 222: </pre>
1.21 rillig 223: <p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
224: trailing whitespace because the <code class="code">+=</code> operator always adds a
225: space.</p>
226: </div>
227: <div class="sect2">
228: <div class="titlepage"><div><div><h3 class="title">
229: <a name="empty-variables"></a>12.3.4. Handling possibly empty variables</h3></div></div></div>
230: <p>When a possibly empty variable is used in a shell program, it may
231: lead to a syntax error.</p>
1.1 dsieger 232: <pre class="programlisting">
1.21 rillig 233: EGFILES= # empty
234:
235: install-examples: # produces a syntax error in the shell
236: for egfile in ${EGFILES}; do \
237: echo "Installing $$egfile"; \
238: done
239: </pre>
240: <p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
241: <code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>.
242: To fix this syntax error, use one of the snippets below.</p>
243: <pre class="programlisting">
244: EMPTY= # empty
245:
246: install-examples:
247: for egfile in ${EGFILES} ""; do \
248: [ -n "$$egfile" ] || continue; \
249: echo "Installing $$egfile"; \
1.1 dsieger 250: done
1.21 rillig 251: </pre>
252: <p>In this case, an empty string is appended to the iteration list (to
253: prevent the syntax error) and filtered out later.</p>
254: <pre class="programlisting">
255: EGFILES= # empty
1.1 dsieger 256:
1.21 rillig 257: install-examples:
258: .for egfile in ${EGFILES}
259: echo "Installing ${egfile}"
1.1 dsieger 260: .endfor
261: </pre>
1.21 rillig 262: <p>This variant only works when <code class="varname">EGFILES</code> does not
263: contain filenames with spaces, since the <code class="code">.for</code> loop splits on
264: simple whitespace.</p>
265: <p>To have a shell command test whether a make variable is empty, use
266: the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
1.1 dsieger 267: </div>
268: </div>
269: </div>
270: <div class="navfooter">
271: <hr>
272: <table width="100%" summary="Navigation footer">
273: <tr>
274: <td width="40%" align="left">
275: <a accesskey="p" href="components.html">Prev</a> </td>
276: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
277: <td width="40%" align="right"> <a accesskey="n" href="plist.html">Next</a>
278: </td>
279: </tr>
280: <tr>
1.4 rillig 281: <td width="40%" align="left" valign="top">Chapter 11. Package components - files, directories and contents </td>
1.1 dsieger 282: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.4 rillig 283: <td width="40%" align="right" valign="top"> Chapter 13. PLIST issues</td>
1.1 dsieger 284: </tr>
285: </table>
286: </div>
287: </body>
288: </html>
CVSweb <webmaster@jp.NetBSD.org>