Annotation of htdocs/docs/pkgsrc/makefile.html, revision 1.23

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.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.23    ! sevan      47:   the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-7.0.2"><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.23    ! sevan      53:   like <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?awk+1.i386+NetBSD-7.0.2"><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.23    ! sevan      67:     <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-7.0.2"><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.23    ! sevan      85: <p>You might remember that <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-7.0.2"><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.23    ! sevan      89:     when one of the commands fails (like <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?false+1.i386+NetBSD-7.0.2"><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.23    ! sevan      97:     ``:='', and ``!='', which are described in the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-7.0.2"><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.23    ! sevan     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.i386+NetBSD-7.0.2"><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 &lt;    &gt; * `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>
1.23    ! sevan     197: <p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?printf+1.i386+NetBSD-7.0.2"><span class="citerefentry"><span class="refentrytitle">printf</span>(1)</span></a> only
1.21      rillig    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
1.23    ! sevan     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.i386+NetBSD-7.0.2"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>.
1.21      rillig    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>