pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Added first (still incomplete) version...
details: https://anonhg.NetBSD.org/pkgsrc/rev/fe47c21f9574
branches: trunk
changeset: 493589:fe47c21f9574
user: rillig <rillig%pkgsrc.org@localhost>
date: Tue May 10 00:27:43 2005 +0000
description:
Added first (still incomplete) version of the guide for programming with
Makefiles.
diffstat:
doc/guide/files/chapters.ent | 3 +-
doc/guide/files/makefile.xml | 156 +++++++++++++++++++++++++++++++++++++++++++
doc/guide/files/pkgsrc.xml | 5 +-
3 files changed, 161 insertions(+), 3 deletions(-)
diffs (203 lines):
diff -r 3e3f8622d7e6 -r fe47c21f9574 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent Tue May 10 00:18:03 2005 +0000
+++ b/doc/guide/files/chapters.ent Tue May 10 00:27:43 2005 +0000
@@ -1,7 +1,7 @@
<!--
Creates entities for each chapter in the pkgsrc book.
- $NetBSD: chapters.ent,v 1.2 2004/10/22 00:24:48 hubertf Exp $
+ $NetBSD: chapters.ent,v 1.3 2005/05/10 00:27:43 rillig Exp $
-->
<!-- users-guide -->
@@ -23,3 +23,4 @@
<!ENTITY chap.ftp-layout SYSTEM "ftp-layout.xml">
<!ENTITY chap.editing SYSTEM "editing.xml">
<!ENTITY chap.platform SYSTEM "platforms.xml">
+<!ENTITY chap.makefile SYSTEM "makefile.xml">
diff -r 3e3f8622d7e6 -r fe47c21f9574 doc/guide/files/makefile.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/makefile.xml Tue May 10 00:27:43 2005 +0000
@@ -0,0 +1,156 @@
+<!-- $NetBSD: makefile.xml,v 1.1 2005/05/10 00:27:43 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 (which are actually macros) 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.variables">
+ <title><filename>Makefile</filename> variables</title>
+
+ <para>A restriction common to all types of variables is that they
+ can neither contain a newline character nor the '\0' character nor
+ the '#' character. The effects of the backslash character is not
+ documented, so you should not use it at the moment. As the $ is used
+ to get values of a <filename>Makefile</filename> variable, it must
+ be quoted as $$.</para>
+
+ <para>There are several types of variables that must be handled
+ differently.</para>
+
+ <itemizedlist>
+
+ <listitem><para><emphasis>Simple values</emphasis> (which I will
+ call atoms) can contain any string, which does not have to be
+ quoted in any way. All other types are somewhat restricted in
+ their possible values.</para></listitem>
+
+ <listitem><para><emphasis>Internal lists</emphasis> are lists that
+ are never exported to any shell command. Their elements are
+ separated by whitespace. Therefore the elements themselves cannot
+ have embedded whitespace. Any other characters are allowed.
+ Internal lists can be used in <!-- FIXME
+ --><varname>.for</varname> loops. Examples are
+ <varname>DEPENDS</varname>,
+ <varname>BUILD_DEPENDS</varname>.</para></listitem>
+
+ <listitem><para><emphasis>External lists</emphasis> are lists that
+ may be exported to a shell command. Their elements can contain any
+ characters, including whitespace. That's why they cannot be used
+ in <!-- FIXME --><varname>.for</varname> loops. Examples are
+ <varname>DISTFILES</varname>,
+ <varname>MASTER_SITES</varname>.</para></listitem>
+
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="makefile.code">
+ <title>Code snippets</title>
+
+ <para>This section presents you with some code snippets you should
+ use in your own code. If you don't find anything appropriate here,
+ you should test your code and add it here.</para>
+
+ <sect2>
+ <title>Adding things to a list</title>
+
+ <programlisting>
+ATOM= foo * bar `date`
+INT_LIST= # empty
+ANOTHER_INT_LIST= apache-[0-9]*:../../www/apache
+EXT_LIST= # empty
+ANOTHER_EXT_LIST= a=b c=d
+
+INT_LIST+= ${ATOM} # 1
+INT_LIST+= ${ANOTHER_INT_LIST} # 2
+EXT_LIST+= ${ATOM:Q} # 3
+EXT_LIST+= ${ANOTHER_EXT_LIST} # 4
+ </programlisting>
+
+ <para>When you add an atom to an external list (example 3), it
+ must be quoted. In all other cases, you must not add a quoting
+ level. You must not merge internal and external lists, unless you
+ are sure that all entries are correctly interpreted in both
+ lists.</para>
+
+ </sect2>
+
+ <sect2>
+ <title>Converting an internal list into an external list</title>
+
+ <programlisting>
+EXT_LIST= # empty
+.for i in ${INT_LIST}
+EXT_LIST+= ${i:Q}
+.endfor
+ </programlisting>
+
+ <para>This code converts the internal list
+ <varname>INT_LIST</varname> into the external list
+ <varname>EXT_LIST</varname>. As the elements of an internal list
+ are unquoted they must be quoted here.</para>
+
+ </sect2>
+
+ <sect2>
+ <title>Passing variables to a shell command</title>
+
+ <programlisting>
+ATOM= foo bar < > * `date` $$HOME ' "
+EXT_LIST= atom=${ATOM:Q} x=second\ item
+
+all:
+ echo ${ATOM} # 1
+ echo "${ATOM}" # 2
+ echo "${ATOM:Q}" # 3
+ echo ${ATOM:Q} # 4
+ echo x${ATOM:Q} | sed 1s,.,, # 5
+ env ${EXT_LIST} /bin/sh -c 'echo "$$atom"; echo "$$x"'
+ </programlisting>
+
+ <para>Example 1 leads to a syntax error in the shell, as the
+ characters are just copied.</para>
+
+ <para>Example 2 leads to a syntax error too, and when you leave
+ out the last " character from <varname>${ATOM}</varname> the
+ &man.date.1; would be executed. The <varname>$HOME</varname> shell
+ variable would be evaluated, too.</para>
+
+ <para>Example 3 would output precede each space character with a
+ backslash (or not), depending on the implementation of the
+ &man.echo.1; command.</para>
+
+ <para>Example 4 handles correctly every string that does not start
+ with a dash. In that case, the result depends on the
+ implementation of the &man.echo.1; command. As long as you can
+ guarantee that your input does not start with a dash this form is
+ appropriate.</para>
+
+ <para>Example 5 handles even the case of a leading dash
+ correctly.</para>
+
+ <para>The <varname>EXT_LIST</varname> does not need to be quoted
+ because the quoting has already be done when adding elements to
+ the list.</para>
+
+ <para>As internal lists shall not be passed to the shell, there is
+ no example for it.</para>
+
+ </sect2>
+ </sect1>
+</chapter>
diff -r 3e3f8622d7e6 -r fe47c21f9574 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml Tue May 10 00:18:03 2005 +0000
+++ b/doc/guide/files/pkgsrc.xml Tue May 10 00:27:43 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.4 2005/05/07 22:28:47 wiz Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.5 2005/05/10 00:27:43 rillig Exp $ -->
<?xml version="1.0"?>
@@ -45,7 +45,7 @@
<holder role="mailto:www%NetBSD.org@localhost";>The NetBSD Foundation, Inc</holder>
</copyright>
- <pubdate>$NetBSD: pkgsrc.xml,v 1.4 2005/05/07 22:28:47 wiz Exp $</pubdate>
+ <pubdate>$NetBSD: pkgsrc.xml,v 1.5 2005/05/10 00:27:43 rillig Exp $</pubdate>
<abstract>
<para>Information about using the NetBSD package system (pkgsrc)
@@ -70,6 +70,7 @@
<part id="developers-guide"> <?dbhtml filename="developers-guide.html"?>
<title id="developers-guide.title">The pkgsrc developer's guide</title>
+ &chap.makefile;
&chap.components;
&chap.plist;
&chap.buildlink;
Home |
Main Index |
Thread Index |
Old Index