path: root/doc/guide/files/makefile.xml

<!-- $NetBSD: makefile.xml,v 1.31 2022/11/18 19:35:03 rillig Exp $ -->

<chapter id="makefile"> <?dbhtml filename="makefile.html"?>
  <title>Programming in <filename>Makefile</filename>s</title>

  <para>Pkgsrc consists of many <filename>Makefile</filename> fragments,
  each of which forms a well-defined part of the pkgsrc system. Using
  the &man.make.1; system as a programming language for a big system
  like pkgsrc requires some discipline to keep the code correct and
  understandable.</para>

  <para>The basic ingredients for <filename>Makefile</filename>
  programming are variables and shell
  commands. Among these shell commands may even be more complex ones
  like &man.awk.1; programs. To make sure that every shell command runs
  as intended it is necessary to quote all variables correctly when they
  are used.</para>

  <para>This chapter describes some patterns that appear quite often in
  <filename>Makefile</filename>s, including the pitfalls that come along
  with them.</para>

  <sect1 id="makefile.style">
  <title>Caveats</title>

    <itemizedlist><listitem><para>When you are creating a file as a
    target of a rule, always write the data to a temporary file first
    and finally rename that file. Otherwise there might occur an error
    in the middle of generating the file, and when the user runs
    &man.make.1; for the second time, the file exists and will not be
    regenerated properly. Example:</para>

<programlisting>
wrong:
        @echo "line 1" > ${.TARGET}
        @echo "line 2" >> ${.TARGET}
        @false

correct:
        @echo "line 1" > ${.TARGET}.tmp
        @echo "line 2" >> ${.TARGET}.tmp
        @false
        @mv ${.TARGET}.tmp ${.TARGET}
</programlisting>

    <para>When you run <command>make wrong</command> twice, the file
    <filename>wrong</filename> will exist, although there was an error
    message in the first run. On the other hand, running <command>make
    correct</command> gives an error message twice, as expected.</para>

    <para>You might remember that &man.make.1; sometimes removes
    <literal>${.TARGET}</literal> in case of error, but this only
    happens when it is interrupted, for example by pressing
    <literal>Ctrl+C</literal>. This does <emphasis>not</emphasis> happen
    when one of the commands fails (like &man.false.1; above).</para>

    </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="makefile.variables">
    <title><filename>Makefile</filename> variables</title>

    <para><filename>Makefile</filename> variables contain strings that
    can be processed using the five operators <code>=</code>,
    <code>+=</code>, <code>?=</code>, <code>:=</code> and
    <code>!=</code>, which are described in the &man.make.1; man
    page.</para>

    <para>When a variable's value is parsed from a
    <filename>Makefile</filename>, the hash character <code>#</code> and
    the backslash character <code>\</code> are handled specially. If a
    backslash is the last character in a line, that backslash is removed
    from the line and the line continues with the next line of the file.</para>

    <para>The <code>#</code> character starts a comment that reaches
    until the end of the line. To get an actual <code>#</code> character,
    such as in a URL, write <code>\#</code> instead.</para>

    <para>The evaluation of variables either happens immediately or lazy.
    It happens immediately when the variable occurs on the right-hand
    side of the <code>:=</code> or the <code>!=</code> operator, in a
    <varname>.if</varname> condition or a <varname>.for</varname> loop.
    In the other cases, it is evaluated lazily.</para>

    <para>Some of the modifiers split the string into words and then
    operate on the words, others operate on the string as a whole. When a
    string is split into words, double quotes and single quotes are
    interpreted as delimiters, just like in &man.sh.1;.</para>

    <sect2 id="makefile.variables.names">
      <title>Naming conventions</title>

      <itemizedlist>

	<listitem><para>All variable names starting with an underscore
	are reserved for use by the pkgsrc infrastructure. They shall
	not be used by packages.</para></listitem>

	<listitem><para>In <command>.for</command> loops you should use
	lowercase variable names for the iteration
	variables.</para></listitem>

	<listitem><para>All list variables should have a plural name,
	such as <varname>PKG_OPTIONS</varname> or
	<varname>DISTFILES</varname>.</para></listitem>

      </itemizedlist>
    </sect2>

  </sect1>

<sect1 id="makefile.code">
<title>Code snippets</title>

<sect2 id="adding-to-list">
<title>Adding things to a list</title>

<para>When adding a string that possibly contains whitespace or quotes to
a list (example 1), it must be quoted using the <code>:Q</code>
modifier.</para>

<para>When adding another list to a list (example 2), it must not be
quoted, since its elements are already quoted.</para>

<programlisting>
STRING=         foo * bar `date`
LIST=           # empty
ANOTHER_LIST=   a=b c=d

LIST+=          ${STRING:Q}       # 1
LIST+=          ${ANOTHER_LIST}   # 2
</programlisting>

</sect2>

<sect2 id="echo-literal">
<title>Echoing a string exactly as-is</title>

<para>Echoing a string containing special characters needs special
work.</para>

<programlisting>
STRING=         foo bar &lt;    &gt; * `date` $$HOME ' "
EXAMPLE_ENV=    string=${STRING:Q} x=multiple\ quoted\ words

all:
        echo ${STRING}                  # 1
        echo ${STRING:Q}                # 2
        printf '%s\n' ${STRING:Q}''     # 3
        env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"'   # 4
</programlisting>

<para>Example 1 leads to a syntax error in the shell, as the characters
are just copied.</para>

<para>Example 2 quotes the string so that the shell interprets it
correctly. But the echo command may additionally interpret strings with a
leading dash or those containing backslashes.</para>

<para>Example 3 can handle arbitrary strings, since &man.printf.1; only
interprets the format string, but not the next argument. The trailing
single quotes handle the case when the string is empty. In that case, the
:Q modifier would result in an empty string too, which would then be
skipped by the shell. For &man.printf.1; this doesn't make a difference,
but other programs may care.</para>

<para>In example 4, the <varname>EXAMPLE_ENV</varname> does not
need to be quoted because the quoting has already been done
when adding elements to the list.</para>

</sect2>

<sect2 id="cflags-gnu-configure">
<title>Passing <varname>CFLAGS</varname> to GNU configure scripts</title>

<para>When passing <varname>CFLAGS</varname> or similar variables to a
GNU-style configure script (especially those that call other configure
scripts), it must not have leading or trailing whitespace, since
otherwise the configure script gets confused. To trim leading and
trailing whitespace, use the <code>:M</code> modifier, as in the
following example:</para>

<!--
Additional details, intentionally left out of the guide to keep the text
short:

If the configure script calls other configure scripts, it strips the
leading and trailing whitespace from the variable and then passes it to
the other configure scripts. But these configure scripts expect the
(child) <varname>CPPFLAGS</varname> variable to be the same as the parent
<varname>CPPFLAGS</varname>.
-->

<programlisting>
CPPFLAGS=               # empty
CPPFLAGS+=              -Wundef -DPREFIX=\"${PREFIX}\"
CPPFLAGS+=              ${MY_CPPFLAGS}

CONFIGURE_ARGS+=        CPPFLAGS=${CPPFLAGS:M*:Q}

all:
        echo x${CPPFLAGS:Q}x            # leading and trailing whitespace
        echo x${CONFIGURE_ARGS:Q}x      # properly trimmed
</programlisting>

<para>In this example, <varname>CPPFLAGS</varname> has both leading and
trailing whitespace because the <code>+=</code> operator always adds a
space.</para>

</sect2>
<sect2 id="empty-variables">
<title>Handling possibly empty variables</title>

<para>When a possibly empty variable is used in a shell program, it may
lead to a syntax error.</para>

<programlisting>
EGFILES=        # empty

install-examples:   # produces a syntax error in the shell
        for egfile in ${EGFILES}; do            \
                echo "Installing $$egfile";     \
        done
</programlisting>

<para>The shell only sees the text <code>for egfile in ; do</code>, since
<code>${EGFILES}</code> is replaced with an empty string by &man.make.1;.
To fix this syntax error, use one of the snippets below.</para>

<programlisting>
EGFILES=        # empty

install-examples:
        for egfile in ${EGFILES} ""; do         \
                [ -n "$$egfile" ] || continue;  \
                echo "Installing $$egfile";     \
        done
</programlisting>

<para>In this case, an empty string is appended to the iteration list (to
prevent the syntax error) and filtered out later.</para>

<programlisting>
EGFILES=        # empty

install-examples:
.for egfile in ${EGFILES}
        echo "Installing ${egfile}"
.endfor
</programlisting>

<para>If one of the filenames contains special characters, it should be
enclosed in single or double quotes.</para>

<para>To have a shell command test whether a make variable is empty, use
the following code: <code>${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</para>

</sect2>

<sect2 id="makefile.yesno">
<title>Testing yes/no variables in conditions</title>

<para>When a variable can have the values <literal>yes</literal> or
<literal>no</literal>, use the following pattern to test the variable:</para>

<programlisting>
.if ${VAR:U:tl} == "yes"
# do something
.endif
</programlisting>

<para>The <literal>:U</literal> modifier is only necessary if the variable
can be undefined. If the variable is guaranteed to be defined, the
<literal>:U</literal> can be omitted.</para>

<para>The <literal>:tl</literal> modifier converts the variable value to
lowercase, allowing for the values <literal>yes</literal>,
<literal>Yes</literal>, <literal>YES</literal>.</para>

</sect2>
</sect1>
</chapter>