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" &gt; ${.TARGET}
                     72:         @echo "line 2" &gt;&gt; ${.TARGET}
                     73:         @false
                     74: 
                     75: correct:
                     76:         @echo "line 1" &gt; ${.TARGET}.tmp
                     77:         @echo "line 2" &gt;&gt; ${.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 &lt;    &gt; * `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>