Annotation of htdocs/docs/pkgsrc/makefile.html, revision 1.31
1.23 sevan 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1 dsieger 2: <html>
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.29 rillig 5: <title>Chapter 14. 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.29 rillig 10: <link rel="prev" href="components.html" title="Chapter 13. Package components - files, directories and contents">
11: <link rel="next" href="plist.html" title="Chapter 15. 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.29 rillig 16: <tr><th colspan="3" align="center">Chapter 14. 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.29 rillig 29: <a name="makefile"></a>Chapter 14. 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.29 rillig 33: <dt><span class="sect1"><a href="makefile.html#makefile.style">14.1. Caveats</a></span></dt>
34: <dt><span class="sect1"><a href="makefile.html#makefile.variables">14.2. <code class="filename">Makefile</code> variables</a></span></dt>
35: <dd><dl><dt><span class="sect2"><a href="makefile.html#makefile.variables.names">14.2.1. Naming conventions</a></span></dt></dl></dd>
36: <dt><span class="sect1"><a href="makefile.html#makefile.code">14.3. Code snippets</a></span></dt>
1.1 dsieger 37: <dd><dl>
1.29 rillig 38: <dt><span class="sect2"><a href="makefile.html#adding-to-list">14.3.1. Adding things to a list</a></span></dt>
39: <dt><span class="sect2"><a href="makefile.html#echo-literal">14.3.2. Echoing a string exactly as-is</a></span></dt>
40: <dt><span class="sect2"><a href="makefile.html#cflags-gnu-configure">14.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">14.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.31 ! leot 47: the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><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>
1.29 rillig 51: programming are variables and shell
1.1 dsieger 52: commands. Among these shell commands may even be more complex ones
1.31 ! leot 53: like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?awk+1.i386+NetBSD-8.1"><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>
1.29 rillig 56: <p>This chapter describes some patterns that appear quite often in
1.1 dsieger 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.29 rillig 61: <a name="makefile.style"></a>14.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.31 ! leot 67: <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><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.31 ! leot 85: <p>You might remember that <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><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
1.29 rillig 88: <code class="literal">Ctrl+C</code>. This does <span class="emphasis"><em>not</em></span> happen
1.31 ! leot 89: when one of the commands fails (like <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?false+1.i386+NetBSD-8.1"><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.29 rillig 94: <a name="makefile.variables"></a>14.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
1.29 rillig 96: can be processed using the five operators <code class="code">=</code>,
97: <code class="code">+=</code>, <code class="code">?=</code>, <code class="code">:=</code> and
1.31 ! leot 98: <code class="code">!=</code>, which are described in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man
1.1 dsieger 99: page.</p>
100: <p>When a variable's value is parsed from a
1.29 rillig 101: <code class="filename">Makefile</code>, the hash character <code class="code">#</code> and
102: the backslash character <code class="code">\</code> are handled specially. If a
103: backslash is the last character in a line, that backslash is removed
104: from the line and the line continues with the next line of the file.</p>
105: <p>The <code class="code">#</code> character starts a comment that reaches
106: until the end of the line. To get an actual <code class="code">#</code> character,
107: such as in a URL, write <code class="code">\#</code> instead.</p>
1.21 rillig 108: <p>The evaluation of variables either happens immediately or lazy.
1.29 rillig 109: It happens immediately when the variable occurs on the right-hand
110: side of the <code class="code">:=</code> or the <code class="code">!=</code> operator, in a
1.21 rillig 111: <code class="varname">.if</code> condition or a <code class="varname">.for</code> loop.
112: In the other cases, it is evaluated lazily.</p>
1.1 dsieger 113: <p>Some of the modifiers split the string into words and then
1.29 rillig 114: operate on the words, others operate on the string as a whole. When a
115: string is split into words, double quotes and single quotes are
1.31 ! leot 116: interpreted as delimiters, just like in <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sh+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">sh</span>(1)</span></a>.</p>
1.13 asau 117: <div class="sect2">
1.1 dsieger 118: <div class="titlepage"><div><div><h3 class="title">
1.29 rillig 119: <a name="makefile.variables.names"></a>14.2.1. Naming conventions</h3></div></div></div>
1.13 asau 120: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.10 wiz 121: <li class="listitem"><p>All variable names starting with an underscore
1.1 dsieger 122: are reserved for use by the pkgsrc infrastructure. They shall
1.29 rillig 123: not be used by packages.</p></li>
1.10 wiz 124: <li class="listitem"><p>In <span class="command"><strong>.for</strong></span> loops you should use
1.1 dsieger 125: lowercase variable names for the iteration
126: variables.</p></li>
1.29 rillig 127: <li class="listitem"><p>All list variables should have a plural name,
128: such as <code class="varname">PKG_OPTIONS</code> or
1.1 dsieger 129: <code class="varname">DISTFILES</code>.</p></li>
130: </ul></div>
131: </div>
132: </div>
1.13 asau 133: <div class="sect1">
1.1 dsieger 134: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.29 rillig 135: <a name="makefile.code"></a>14.3. Code snippets</h2></div></div></div>
1.13 asau 136: <div class="sect2">
1.1 dsieger 137: <div class="titlepage"><div><div><h3 class="title">
1.29 rillig 138: <a name="adding-to-list"></a>14.3.1. Adding things to a list</h3></div></div></div>
1.21 rillig 139: <p>When adding a string that possibly contains whitespace or quotes to
140: a list (example 1), it must be quoted using the <code class="code">:Q</code>
141: modifier.</p>
142: <p>When adding another list to a list (example 2), it must not be
143: quoted, since its elements are already quoted.</p>
1.1 dsieger 144: <pre class="programlisting">
1.21 rillig 145: STRING= foo * bar `date`
146: LIST= # empty
147: ANOTHER_LIST= a=b c=d
1.1 dsieger 148:
1.21 rillig 149: LIST+= ${STRING:Q} # 1
150: LIST+= ${ANOTHER_LIST} # 2
1.1 dsieger 151: </pre>
152: </div>
1.13 asau 153: <div class="sect2">
1.1 dsieger 154: <div class="titlepage"><div><div><h3 class="title">
1.29 rillig 155: <a name="echo-literal"></a>14.3.2. Echoing a string exactly as-is</h3></div></div></div>
1.21 rillig 156: <p>Echoing a string containing special characters needs special
157: work.</p>
1.1 dsieger 158: <pre class="programlisting">
159: STRING= foo bar < > * `date` $$HOME ' "
1.21 rillig 160: EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
1.1 dsieger 161:
162: all:
163: echo ${STRING} # 1
1.21 rillig 164: echo ${STRING:Q} # 2
165: printf '%s\n' ${STRING:Q}'' # 3
166: env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
167: </pre>
168: <p>Example 1 leads to a syntax error in the shell, as the characters
169: are just copied.</p>
170: <p>Example 2 quotes the string so that the shell interprets it
171: correctly. But the echo command may additionally interpret strings with a
172: leading dash or those containing backslashes.</p>
1.31 ! leot 173: <p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> only
1.27 leot 174: interprets the format string, but not the next argument. The trailing
175: single quotes handle the case when the string is empty. In that case, the
176: :Q modifier would result in an empty string too, which would then be
1.31 ! leot 177: skipped by the shell. For <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> this doesn't make a difference,
1.27 leot 178: but other programs may care.</p>
1.21 rillig 179: <p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
180: need to be quoted because the quoting has already been done
181: when adding elements to the list.</p>
1.1 dsieger 182: </div>
1.13 asau 183: <div class="sect2">
1.1 dsieger 184: <div class="titlepage"><div><div><h3 class="title">
1.29 rillig 185: <a name="cflags-gnu-configure"></a>14.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
1.21 rillig 186: <p>When passing <code class="varname">CFLAGS</code> or similar variables to a
187: GNU-style configure script (especially those that call other configure
188: scripts), it must not have leading or trailing whitespace, since
189: otherwise the configure script gets confused. To trim leading and
190: trailing whitespace, use the <code class="code">:M</code> modifier, as in the
191: following example:</p>
1.1 dsieger 192: <pre class="programlisting">
193: CPPFLAGS= # empty
1.21 rillig 194: CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
1.1 dsieger 195: CPPFLAGS+= ${MY_CPPFLAGS}
196:
197: CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
198:
199: all:
200: echo x${CPPFLAGS:Q}x # leading and trailing whitespace
1.21 rillig 201: echo x${CONFIGURE_ARGS:Q}x # properly trimmed
1.1 dsieger 202: </pre>
1.21 rillig 203: <p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
204: trailing whitespace because the <code class="code">+=</code> operator always adds a
205: space.</p>
206: </div>
207: <div class="sect2">
208: <div class="titlepage"><div><div><h3 class="title">
1.29 rillig 209: <a name="empty-variables"></a>14.3.4. Handling possibly empty variables</h3></div></div></div>
1.21 rillig 210: <p>When a possibly empty variable is used in a shell program, it may
211: lead to a syntax error.</p>
1.1 dsieger 212: <pre class="programlisting">
1.21 rillig 213: EGFILES= # empty
214:
215: install-examples: # produces a syntax error in the shell
216: for egfile in ${EGFILES}; do \
217: echo "Installing $$egfile"; \
218: done
219: </pre>
220: <p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
1.31 ! leot 221: <code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>.
1.21 rillig 222: To fix this syntax error, use one of the snippets below.</p>
223: <pre class="programlisting">
224: EMPTY= # empty
225:
226: install-examples:
227: for egfile in ${EGFILES} ""; do \
228: [ -n "$$egfile" ] || continue; \
229: echo "Installing $$egfile"; \
1.1 dsieger 230: done
1.21 rillig 231: </pre>
232: <p>In this case, an empty string is appended to the iteration list (to
233: prevent the syntax error) and filtered out later.</p>
234: <pre class="programlisting">
235: EGFILES= # empty
1.1 dsieger 236:
1.21 rillig 237: install-examples:
238: .for egfile in ${EGFILES}
239: echo "Installing ${egfile}"
1.1 dsieger 240: .endfor
241: </pre>
1.29 rillig 242: <p>If one of the filenames contains special characters, it should be
243: enclosed in single or double quotes.</p>
1.21 rillig 244: <p>To have a shell command test whether a make variable is empty, use
245: the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
1.1 dsieger 246: </div>
247: </div>
248: </div>
249: <div class="navfooter">
250: <hr>
251: <table width="100%" summary="Navigation footer">
252: <tr>
253: <td width="40%" align="left">
254: <a accesskey="p" href="components.html">Prev</a> </td>
255: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
256: <td width="40%" align="right"> <a accesskey="n" href="plist.html">Next</a>
257: </td>
258: </tr>
259: <tr>
1.29 rillig 260: <td width="40%" align="left" valign="top">Chapter 13. Package components - files, directories and contents </td>
1.1 dsieger 261: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.29 rillig 262: <td width="40%" align="right" valign="top"> Chapter 15. PLIST issues</td>
1.1 dsieger 263: </tr>
264: </table>
265: </div>
266: </body>
267: </html>
CVSweb <webmaster@jp.NetBSD.org>