pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc regen
details: https://anonhg.NetBSD.org/pkgsrc/rev/f606c7495a94
branches: trunk
changeset: 348990:f606c7495a94
user: wiz <wiz%pkgsrc.org@localhost>
date: Tue Jun 21 21:48:02 2016 +0000
description:
regen
diffstat:
doc/pkgsrc.html | 325 ++++++++++++++++++++-----------------------------------
doc/pkgsrc.txt | 245 ++++++++++++++++++-----------------------
2 files changed, 229 insertions(+), 341 deletions(-)
diffs (truncated from 840 to 300 lines):
diff -r b5c32a796b16 -r f606c7495a94 doc/pkgsrc.html
--- a/doc/pkgsrc.html Tue Jun 21 21:47:29 2016 +0000
+++ b/doc/pkgsrc.html Tue Jun 21 21:48:02 2016 +0000
@@ -31,7 +31,7 @@
</h3>
</div></div>
<div><p class="copyright">Copyright © 1994-2016 The NetBSD Foundation, Inc</p></div>
-<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.29 2016/05/06 17:26:34 jnemeth Exp $</p></div>
+<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.30 2016/06/11 18:14:42 rillig Exp $</p></div>
<div><div class="abstract">
<p class="title"><b>Abstract</b></p>
<p>pkgsrc is a centralized package management system for
@@ -209,8 +209,9 @@
<dt><span class="sect1"><a href="#makefile.code">12.3. Code snippets</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#adding-to-list">12.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#passing-variable-to-shell">12.3.2. Passing variables to a shell command</a></span></dt>
-<dt><span class="sect2"><a href="#quoting-guideline">12.3.3. Quoting guideline</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">12.3.2. Echoing a string exacty as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">12.3.4. Handling possibly empty variables</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#plist">13. PLIST issues</a></span></dt>
@@ -301,7 +302,6 @@
<dt><span class="sect1"><a href="#pkgsrc-tools">18.1. Tools for pkgsrc builds</a></span></dt>
<dt><span class="sect1"><a href="#package-tools">18.2. Tools needed by packages</a></span></dt>
<dt><span class="sect1"><a href="#platform-tools">18.3. Tools provided by platforms</a></span></dt>
-<dt><span class="sect1"><a href="#tools.questions">18.4. Questions regarding the tools</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#fixes">19. Making your package work</a></span></dt>
<dd><dl>
@@ -3334,8 +3334,9 @@
<dt><span class="sect1"><a href="#makefile.code">12.3. Code snippets</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#adding-to-list">12.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#passing-variable-to-shell">12.3.2. Passing variables to a shell command</a></span></dt>
-<dt><span class="sect2"><a href="#quoting-guideline">12.3.3. Quoting guideline</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">12.3.2. Echoing a string exacty as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">12.3.4. Handling possibly empty variables</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#plist">13. PLIST issues</a></span></dt>
@@ -3426,7 +3427,6 @@
<dt><span class="sect1"><a href="#pkgsrc-tools">18.1. Tools for pkgsrc builds</a></span></dt>
<dt><span class="sect1"><a href="#package-tools">18.2. Tools needed by packages</a></span></dt>
<dt><span class="sect1"><a href="#platform-tools">18.3. Tools provided by platforms</a></span></dt>
-<dt><span class="sect1"><a href="#tools.questions">18.4. Questions regarding the tools</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#fixes">19. Making your package work</a></span></dt>
<dd><dl>
@@ -4537,8 +4537,9 @@
<dt><span class="sect1"><a href="#makefile.code">12.3. Code snippets</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#adding-to-list">12.3.1. Adding things to a list</a></span></dt>
-<dt><span class="sect2"><a href="#passing-variable-to-shell">12.3.2. Passing variables to a shell command</a></span></dt>
-<dt><span class="sect2"><a href="#quoting-guideline">12.3.3. Quoting guideline</a></span></dt>
+<dt><span class="sect2"><a href="#echo-literal">12.3.2. Echoing a string exacty as-is</a></span></dt>
+<dt><span class="sect2"><a href="#cflags-gnu-configure">12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</a></span></dt>
+<dt><span class="sect2"><a href="#empty-variables">12.3.4. Handling possibly empty variables</a></span></dt>
</dl></dd>
</dl>
</div>
@@ -4657,36 +4658,28 @@
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="makefile.code"></a>12.3. Code snippets</h2></div></div></div>
-<p>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.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="adding-to-list"></a>12.3.1. Adding things to a list</h3></div></div></div>
-<pre class="programlisting">
-STRING= foo * bar `date`
-INT_LIST= # empty
-ANOTHER_INT_LIST= apache-[0-9]*:../../www/apache
-EXT_LIST= # empty
-ANOTHER_EXT_LIST= a=b c=d
+<p>When adding a string that possibly contains whitespace or quotes to
+a list (example 1), it must be quoted using the <code class="code">:Q</code>
+modifier.</p>
+<p>When adding another list to a list (example 2), it must not be
+quoted, since its elements are already quoted.</p>
+<pre class="programlisting">
+STRING= foo * bar `date`
+LIST= # empty
+ANOTHER_LIST= a=b c=d
-INT_LIST+= ${STRING} # 1
-INT_LIST+= ${ANOTHER_INT_LIST} # 2
-EXT_LIST+= ${STRING:Q} # 3
-EXT_LIST+= ${ANOTHER_EXT_LIST} # 4
-</pre>
-<p>When you add a string 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.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="passing-variable-to-shell"></a>12.3.2. Passing variables to a shell command</h3></div></div></div>
-<p>Sometimes you may want to print an arbitrary string. There
- are many ways to get it wrong and only few that can handle every
- nastiness.</p>
+LIST+= ${STRING:Q} # 1
+LIST+= ${ANOTHER_LIST} # 2
+</pre>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="echo-literal"></a>12.3.2. Echoing a string exacty as-is</h3></div></div></div>
+<p>Echoing a string containing special characters needs special
+work.</p>
<pre class="programlisting">
STRING= foo bar < > * `date` $$HOME ' "
EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
@@ -4695,99 +4688,83 @@
echo ${STRING} # 1
echo ${STRING:Q} # 2
printf '%s\n' ${STRING:Q}'' # 3
- env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
-</pre>
-<p>Example 1 leads to a syntax error in the shell, as the
- characters are just copied.</p>
-<p>Example 2 can handle all strings, except those starting
- with a dash or those containing backslashes.</p>
-<p>Example 3 can handle arbitrary strings.</p>
-<p>In example 4, the <code class="varname">EXT_LIST</code> does not
- need to be quoted because the quoting has already been done
- when adding elements to the list.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="quoting-guideline"></a>12.3.3. Quoting guideline</h3></div></div></div>
-<p>There are many possible sources of wrongly quoted variables.
- This section lists some of the commonly known ones.</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
-<p>Whenever you use the value of a list, think
- about what happens to leading or trailing whitespace. If the
- list is a well-formed shell expression, you can apply the
- <code class="varname">:M*</code> modifier to strip leading and trailing
- whitespace from each word. The <code class="varname">:M</code> operator
- first splits its argument according to the rules of the shell,
- and then creates a new list consisting of all words that match
- the shell glob expression <code class="varname">*</code>, that is: all.
- One class of situations where this is needed is when adding a
- variable like <code class="varname">CPPFLAGS</code> to
- <code class="varname">CONFIGURE_ARGS</code>. If the configure script
- invokes 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) <code class="varname">CPPFLAGS</code> variable to be the same as
- the parent <code class="varname">CPPFLAGS</code>. That's why we better
- pass the <code class="varname">CPPFLAGS</code> value properly trimmed. And
- here is how we do it:</p>
+ env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
+</pre>
+<p>Example 1 leads to a syntax error in the shell, as the characters
+are just copied.</p>
+<p>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.</p>
+<p>Example 3 can handle arbitrary strings, since <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?printf+1+NetBSD-5.0.1+i386";><span class="citerefentry"><span
class="refentrytitle">printf</span>(1)</span></a> only
+interprets the format string, but not the next argument.</p>
+<p>In example 4, the <code class="varname">EXAMPLE_ENV</code> does not
+need to be quoted because the quoting has already been done
+when adding elements to the list.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="cflags-gnu-configure"></a>12.3.3. Passing <code class="varname">CFLAGS</code> to GNU configure scripts</h3></div></div></div>
+<p>When passing <code class="varname">CFLAGS</code> 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 class="code">:M</code> modifier, as in the
+following example:</p>
<pre class="programlisting">
CPPFLAGS= # empty
-CPPFLAGS+= -Wundef -DPREFIX=\"${PREFIX:Q}\"
+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}x # properly trimmed
-</pre>
-</li>
-<li class="listitem"><p>The example above contains one bug: The
- <code class="varname">${PREFIX}</code> is a properly quoted shell
- expression, but there is the C compiler after it, which also
- expects a properly quoted string (this time in C syntax). The
- version above is therefore only correct if
- <code class="varname">${PREFIX}</code> does not have embedded backslashes
- or double quotes. If you want to allow these, you have to add
- another layer of quoting to each variable that is used as a C
- string literal. You cannot use the <code class="varname">:Q</code>
- operator for it, as this operator only works for the
- shell.</p></li>
-<li class="listitem">
-<p>Whenever a variable can be empty, the
- <code class="varname">:Q</code> operator can have surprising results. Here
- are two completely different cases which can be solved with the
- same trick.</p>
-<pre class="programlisting">
-EMPTY= # empty
-empty_test:
- for i in a ${EMPTY:Q} c; do \
- echo "$$i"; \
+ echo x${CONFIGURE_ARGS:Q}x # properly trimmed
+</pre>
+<p>In this example, <code class="varname">CPPFLAGS</code> has both leading and
+trailing whitespace because the <code class="code">+=</code> operator always adds a
+space.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="empty-variables"></a>12.3.4. Handling possibly empty variables</h3></div></div></div>
+<p>When a possibly empty variable is used in a shell program, it may
+lead to a syntax error.</p>
+<pre class="programlisting">
+EGFILES= # empty
+
+install-examples: # produces a syntax error in the shell
+ for egfile in ${EGFILES}; do \
+ echo "Installing $$egfile"; \
done
+</pre>
+<p>The shell only sees the text <code class="code">for egfile in ; do</code>, since
+<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+NetBSD-5.0.1+i386";><span class="citerefentry"><span
class="refentrytitle">make</span>(1)</span></a>.
+To fix this syntax error, use one of the snippets below.</p>
+<pre class="programlisting">
+EMPTY= # empty
-for_test:
-.for i in a:\ a:\test.txt
- echo ${i:Q}
- echo "foo"
+install-examples:
+ for egfile in ${EGFILES} ""; do \
+ [ -n "$$egfile" ] || continue; \
+ echo "Installing $$egfile"; \
+ done
+</pre>
+<p>In this case, an empty string is appended to the iteration list (to
+prevent the syntax error) and filtered out later.</p>
+<pre class="programlisting">
+EGFILES= # empty
+
+install-examples:
+.for egfile in ${EGFILES}
+ echo "Installing ${egfile}"
.endfor
</pre>
-<p>The first example will only print two of the three lines
- we might have expected. This is because
- <code class="varname">${EMPTY:Q}</code> expands to the empty string, which
- the shell cannot see. The workaround is to write
- <code class="varname">${EMPTY:Q}""</code>. This pattern can be often found
- as <code class="varname">${TEST} -z ${VAR:Q}</code> or as <code class="varname">${TEST}
- -f ${FNAME:Q}</code> (both of these are wrong).</p>
-<p>The second example will only print three lines instead of
- four. The first line looks like <code class="varname">a:\ echo foo</code>.
- This is because the backslash of the value
- <code class="varname">a:\</code> is interpreted as a line-continuation by
- <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386";><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>, which makes the
second line the arguments of the
- <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-5.0.1+i386";><span class="citerefentry"><span class="refentrytitle">echo</span>(1)</span></a> command from the
first line. To avoid this, write
- <code class="varname">${i:Q}""</code>.</p>
-</li>
-</ul></div>
+<p>This variant only works when <code class="varname">EGFILES</code> does not
+contain filenames with spaces, since the <code class="code">.for</code> loop splits on
+simple whitespace.</p>
+<p>To have a shell command test whether a make variable is empty, use
+the following code: <code class="code">${TEST} -z ${POSSIBLY_EMPTY:Q}""</code>.</p>
</div>
</div>
</div>
@@ -7194,7 +7171,6 @@
<dt><span class="sect1"><a href="#pkgsrc-tools">18.1. Tools for pkgsrc builds</a></span></dt>
<dt><span class="sect1"><a href="#package-tools">18.2. Tools needed by packages</a></span></dt>
<dt><span class="sect1"><a href="#platform-tools">18.3. Tools provided by platforms</a></span></dt>
-<dt><span class="sect1"><a href="#tools.questions">18.4. Questions regarding the tools</a></span></dt>
</dl>
</div>
<p>The <code class="varname">USE_TOOLS</code> definition is used both internally
@@ -7266,65 +7242,6 @@
TOOLS_PLATFORM.true?= true # shell builtin
</pre>
</div>
-<div class="sect1">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="tools.questions"></a>18.4. Questions regarding the tools</h2></div></div></div>
-<div class="qandaset">
Home |
Main Index |
Thread Index |
Old Index