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

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.33      rillig      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.1       dsieger     9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.33      rillig     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.33      rillig     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.33      rillig     19: <a accesskey="p" href="creating.html">Prev</a> </td>
1.1       dsieger    20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
1.33      rillig     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.33      rillig     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.38    ! leot       48:   the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.38    ! leot       54:   like <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.33      rillig     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.38    ! leot       68:     <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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" &gt; ${.TARGET}
                     73:         @echo "line 2" &gt;&gt; ${.TARGET}
                     74:         @false
                     75: 
                     76: correct:
                     77:         @echo "line 1" &gt; ${.TARGET}.tmp
                     78:         @echo "line 2" &gt;&gt; ${.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.38    ! leot       86: <p>You might remember that <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.38    ! leot       90:     when one of the commands fails (like <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.33      rillig     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.38    ! leot       99:     <code class="code">!=</code>, which are described in the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.38    ! leot      117:     interpreted as delimiters, just like in <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.33      rillig    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.33      rillig    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.33      rillig    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.33      rillig    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 &lt;    &gt; * `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.38    ! leot      174: <p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.38    ! leot      178: skipped by the shell. For <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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.33      rillig    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.33      rillig    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.38    ! leot      222: <code class="code">${EGFILES}</code> is replaced with an empty string by <a class="citerefentry" href="//man.NetBSD.org/NetBSD-9.3/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">
                    250: <a name="makefile.yesno"></a>15.3.5. Testing yes/no variables in conditions</h3></div></div></div>
                    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.33      rillig    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.33      rillig    274: <td width="40%" align="right"> <a accesskey="n" href="options.html">Next</a>
1.1       dsieger   275: </td>
                    276: </tr>
                    277: <tr>
1.33      rillig    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.33      rillig    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>