Annotation of htdocs/docs/pkgsrc/makefile.html, revision 1.41
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>
1.41 ! wiz 4: <meta charset="UTF-8">
1.40 martin 5: <title>Chapter 15. 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.40 martin 9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
10: <link rel="prev" href="creating.html" title="Chapter 14. Creating a new pkgsrc package from scratch">
11: <link rel="next" href="options.html" title="Chapter 16. Options handling">
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.40 martin 16: <tr><th colspan="3" align="center">Chapter 15. Programming in <code class="filename">Makefile</code>s</th></tr>
1.1 dsieger 17: <tr>
18: <td width="20%" align="left">
1.40 martin 19: <a accesskey="p" href="creating.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="options.html">Next</a>
1.1 dsieger 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.40 martin 29: <a name="makefile"></a>Chapter 15. 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.33 rillig 33: <dt><span class="sect1"><a href="makefile.html#makefile.style">15.1. Caveats</a></span></dt>
34: <dt><span class="sect1"><a href="makefile.html#makefile.variables">15.2. <code class="filename">Makefile</code> variables</a></span></dt>
35: <dd><dl><dt><span class="sect2"><a href="makefile.html#makefile.variables.names">15.2.1. Naming conventions</a></span></dt></dl></dd>
36: <dt><span class="sect1"><a href="makefile.html#makefile.code">15.3. Code snippets</a></span></dt>
1.1 dsieger 37: <dd><dl>
1.33 rillig 38: <dt><span class="sect2"><a href="makefile.html#adding-to-list">15.3.1. Adding things to a list</a></span></dt>
39: <dt><span class="sect2"><a href="makefile.html#echo-literal">15.3.2. Echoing a string exactly as-is</a></span></dt>
40: <dt><span class="sect2"><a href="makefile.html#cflags-gnu-configure">15.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">15.3.4. Handling possibly empty variables</a></span></dt>
1.37 gutterid 42: <dt><span class="sect2"><a href="makefile.html#makefile.yesno">15.3.5. Testing yes/no variables in conditions</a></span></dt>
1.1 dsieger 43: </dl></dd>
44: </dl>
45: </div>
46: <p>Pkgsrc consists of many <code class="filename">Makefile</code> fragments,
47: each of which forms a well-defined part of the pkgsrc system. Using
1.39 leot 48: the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/make.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> system as a programming language for a big system
1.1 dsieger 49: like pkgsrc requires some discipline to keep the code correct and
50: understandable.</p>
51: <p>The basic ingredients for <code class="filename">Makefile</code>
1.29 rillig 52: programming are variables and shell
1.1 dsieger 53: commands. Among these shell commands may even be more complex ones
1.39 leot 54: like <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/awk.1"><span class="citerefentry"><span class="refentrytitle">awk</span>(1)</span></a> programs. To make sure that every shell command runs
1.1 dsieger 55: as intended it is necessary to quote all variables correctly when they
56: are used.</p>
1.29 rillig 57: <p>This chapter describes some patterns that appear quite often in
1.1 dsieger 58: <code class="filename">Makefile</code>s, including the pitfalls that come along
59: with them.</p>
1.13 asau 60: <div class="sect1">
1.1 dsieger 61: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.40 martin 62: <a name="makefile.style"></a>15.1. Caveats</h2></div></div></div>
1.13 asau 63: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
1.1 dsieger 64: <p>When you are creating a file as a
65: target of a rule, always write the data to a temporary file first
66: and finally rename that file. Otherwise there might occur an error
67: in the middle of generating the file, and when the user runs
1.39 leot 68: <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/make.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 69: regenerated properly. Example:</p>
70: <pre class="programlisting">
71: wrong:
72: @echo "line 1" > ${.TARGET}
73: @echo "line 2" >> ${.TARGET}
74: @false
75:
76: correct:
77: @echo "line 1" > ${.TARGET}.tmp
78: @echo "line 2" >> ${.TARGET}.tmp
79: @false
80: @mv ${.TARGET}.tmp ${.TARGET}
81: </pre>
1.5 hubertf 82: <p>When you run <span class="command"><strong>make wrong</strong></span> twice, the file
1.1 dsieger 83: <code class="filename">wrong</code> will exist, although there was an error
1.5 hubertf 84: message in the first run. On the other hand, running <span class="command"><strong>make
1.1 dsieger 85: correct</strong></span> gives an error message twice, as expected.</p>
1.39 leot 86: <p>You might remember that <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/make.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> sometimes removes
1.1 dsieger 87: <code class="literal">${.TARGET}</code> in case of error, but this only
88: happens when it is interrupted, for example by pressing
1.29 rillig 89: <code class="literal">Ctrl+C</code>. This does <span class="emphasis"><em>not</em></span> happen
1.39 leot 90: when one of the commands fails (like <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/false.1"><span class="citerefentry"><span class="refentrytitle">false</span>(1)</span></a> above).</p>
1.1 dsieger 91: </li></ul></div>
92: </div>
1.13 asau 93: <div class="sect1">
1.1 dsieger 94: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.40 martin 95: <a name="makefile.variables"></a>15.2. <code class="filename">Makefile</code> variables</h2></div></div></div>
1.1 dsieger 96: <p><code class="filename">Makefile</code> variables contain strings that
1.29 rillig 97: can be processed using the five operators <code class="code">=</code>,
98: <code class="code">+=</code>, <code class="code">?=</code>, <code class="code">:=</code> and
1.39 leot 99: <code class="code">!=</code>, which are described in the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/make.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man
1.1 dsieger 100: page.</p>
101: <p>When a variable's value is parsed from a
1.29 rillig 102: <code class="filename">Makefile</code>, the hash character <code class="code">#</code> and
103: the backslash character <code class="code">\</code> are handled specially. If a
104: backslash is the last character in a line, that backslash is removed
105: from the line and the line continues with the next line of the file.</p>
106: <p>The <code class="code">#</code> character starts a comment that reaches
107: until the end of the line. To get an actual <code class="code">#</code> character,
108: such as in a URL, write <code class="code">\#</code> instead.</p>
1.21 rillig 109: <p>The evaluation of variables either happens immediately or lazy.
1.29 rillig 110: It happens immediately when the variable occurs on the right-hand
111: side of the <code class="code">:=</code> or the <code class="code">!=</code> operator, in a
1.21 rillig 112: <code class="varname">.if</code> condition or a <code class="varname">.for</code> loop.
113: In the other cases, it is evaluated lazily.</p>
1.1 dsieger 114: <p>Some of the modifiers split the string into words and then
1.29 rillig 115: operate on the words, others operate on the string as a whole. When a
116: string is split into words, double quotes and single quotes are
1.39 leot 117: interpreted as delimiters, just like in <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/sh.1"><span class="citerefentry"><span class="refentrytitle">sh</span>(1)</span></a>.</p>
1.13 asau 118: <div class="sect2">
1.1 dsieger 119: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 120: <a name="makefile.variables.names"></a>15.2.1. Naming conventions</h3></div></div></div>
1.13 asau 121: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.10 wiz 122: <li class="listitem"><p>All variable names starting with an underscore
1.1 dsieger 123: are reserved for use by the pkgsrc infrastructure. They shall
1.29 rillig 124: not be used by packages.</p></li>
1.10 wiz 125: <li class="listitem"><p>In <span class="command"><strong>.for</strong></span> loops you should use
1.1 dsieger 126: lowercase variable names for the iteration
127: variables.</p></li>
1.29 rillig 128: <li class="listitem"><p>All list variables should have a plural name,
129: such as <code class="varname">PKG_OPTIONS</code> or
1.1 dsieger 130: <code class="varname">DISTFILES</code>.</p></li>
131: </ul></div>
132: </div>
133: </div>
1.13 asau 134: <div class="sect1">
1.1 dsieger 135: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.40 martin 136: <a name="makefile.code"></a>15.3. Code snippets</h2></div></div></div>
1.13 asau 137: <div class="sect2">
1.1 dsieger 138: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 139: <a name="adding-to-list"></a>15.3.1. Adding things to a list</h3></div></div></div>
1.21 rillig 140: <p>When adding a string that possibly contains whitespace or quotes to
141: a list (example 1), it must be quoted using the <code class="code">:Q</code>
142: modifier.</p>
143: <p>When adding another list to a list (example 2), it must not be
144: quoted, since its elements are already quoted.</p>
1.1 dsieger 145: <pre class="programlisting">
1.21 rillig 146: STRING= foo * bar `date`
147: LIST= # empty
148: ANOTHER_LIST= a=b c=d
1.1 dsieger 149:
1.21 rillig 150: LIST+= ${STRING:Q} # 1
151: LIST+= ${ANOTHER_LIST} # 2
1.1 dsieger 152: </pre>
153: </div>
1.13 asau 154: <div class="sect2">
1.1 dsieger 155: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 156: <a name="echo-literal"></a>15.3.2. Echoing a string exactly as-is</h3></div></div></div>
1.21 rillig 157: <p>Echoing a string containing special characters needs special
158: work.</p>
1.1 dsieger 159: <pre class="programlisting">
160: STRING= foo bar < > * `date` $$HOME ' "
1.21 rillig 161: EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
1.1 dsieger 162:
163: all:
164: echo ${STRING} # 1
1.21 rillig 165: echo ${STRING:Q} # 2
166: printf '%s\n' ${STRING:Q}'' # 3
167: env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
168: </pre>
169: <p>Example 1 leads to a syntax error in the shell, as the characters
170: are just copied.</p>
171: <p>Example 2 quotes the string so that the shell interprets it
172: correctly. But the echo command may additionally interpret strings with a
173: leading dash or those containing backslashes.</p>
1.39 leot 174: <p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/printf.1"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> only
1.27 leot 175: interprets the format string, but not the next argument. The trailing
176: single quotes handle the case when the string is empty. In that case, the
177: :Q modifier would result in an empty string too, which would then be
1.39 leot 178: skipped by the shell. For <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/printf.1"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> this doesn't make a difference,
1.27 leot 179: but other programs may care.</p>
1.21 rillig 180: <p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
181: need to be quoted because the quoting has already been done
182: when adding elements to the list.</p>
1.1 dsieger 183: </div>
1.13 asau 184: <div class="sect2">
1.1 dsieger 185: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 186: <a name="cflags-gnu-configure"></a>15.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
1.21 rillig 187: <p>When passing <code class="varname">CFLAGS</code> or similar variables to a
188: GNU-style configure script (especially those that call other configure
189: scripts), it must not have leading or trailing whitespace, since
190: otherwise the configure script gets confused. To trim leading and
191: trailing whitespace, use the <code class="code">:M</code> modifier, as in the
192: following example:</p>
1.1 dsieger 193: <pre class="programlisting">
194: CPPFLAGS= # empty
1.21 rillig 195: CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX}\"
1.1 dsieger 196: CPPFLAGS+= ${MY_CPPFLAGS}
197:
198: CONFIGURE_ARGS+= CPPFLAGS=${CPPFLAGS:M*:Q}
199:
200: all:
201: echo x${CPPFLAGS:Q}x # leading and trailing whitespace
1.21 rillig 202: echo x${CONFIGURE_ARGS:Q}x # properly trimmed
1.1 dsieger 203: </pre>
1.21 rillig 204: <p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
205: trailing whitespace because the <code class="code">+=</code> operator always adds a
206: space.</p>
207: </div>
208: <div class="sect2">
209: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 210: <a name="empty-variables"></a>15.3.4. Handling possibly empty variables</h3></div></div></div>
1.21 rillig 211: <p>When a possibly empty variable is used in a shell program, it may
212: lead to a syntax error.</p>
1.1 dsieger 213: <pre class="programlisting">
1.21 rillig 214: EGFILES= # empty
215:
216: install-examples: # produces a syntax error in the shell
217: for egfile in ${EGFILES}; do \
218: echo "Installing $$egfile"; \
219: done
220: </pre>
221: <p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
1.39 leot 222: <code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/make.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>.
1.21 rillig 223: To fix this syntax error, use one of the snippets below.</p>
224: <pre class="programlisting">
1.37 gutterid 225: EGFILES= # empty
1.21 rillig 226:
227: install-examples:
228: for egfile in ${EGFILES} ""; do \
229: [ -n "$$egfile" ] || continue; \
230: echo "Installing $$egfile"; \
1.1 dsieger 231: done
1.21 rillig 232: </pre>
233: <p>In this case, an empty string is appended to the iteration list (to
234: prevent the syntax error) and filtered out later.</p>
235: <pre class="programlisting">
236: EGFILES= # empty
1.1 dsieger 237:
1.21 rillig 238: install-examples:
239: .for egfile in ${EGFILES}
240: echo "Installing ${egfile}"
1.1 dsieger 241: .endfor
242: </pre>
1.29 rillig 243: <p>If one of the filenames contains special characters, it should be
244: enclosed in single or double quotes.</p>
1.21 rillig 245: <p>To have a shell command test whether a make variable is empty, use
246: the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
1.1 dsieger 247: </div>
1.37 gutterid 248: <div class="sect2">
249: <div class="titlepage"><div><div><h3 class="title">
1.40 martin 250: <a name="makefile.yesno"></a>15.3.5. Testing yes/no variables in conditions</h3></div></div></div>
1.37 gutterid 251: <p>When a variable can have the values <code class="literal">yes</code> or
252: <code class="literal">no</code>, use the following pattern to test the variable:</p>
253: <pre class="programlisting">
254: .if ${VAR:U:tl} == "yes"
255: # do something
256: .endif
257: </pre>
258: <p>The <code class="literal">:U</code> modifier is only necessary if the variable
259: can be undefined. If the variable is guaranteed to be defined, the
260: <code class="literal">:U</code> can be omitted.</p>
261: <p>The <code class="literal">:tl</code> modifier converts the variable value to
262: lowercase, allowing for the values <code class="literal">yes</code>,
263: <code class="literal">Yes</code>, <code class="literal">YES</code>.</p>
264: </div>
1.1 dsieger 265: </div>
266: </div>
267: <div class="navfooter">
268: <hr>
269: <table width="100%" summary="Navigation footer">
270: <tr>
271: <td width="40%" align="left">
1.40 martin 272: <a accesskey="p" href="creating.html">Prev</a> </td>
1.1 dsieger 273: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1.40 martin 274: <td width="40%" align="right"> <a accesskey="n" href="options.html">Next</a>
1.1 dsieger 275: </td>
276: </tr>
277: <tr>
1.40 martin 278: <td width="40%" align="left" valign="top">Chapter 14. Creating a new pkgsrc package from scratch </td>
1.1 dsieger 279: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.40 martin 280: <td width="40%" align="right" valign="top"> Chapter 16. Options handling</td>
1.1 dsieger 281: </tr>
282: </table>
283: </div>
284: </body>
285: </html>
CVSweb <webmaster@jp.NetBSD.org>