pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Removed unnecessary complexity and sup...
details: https://anonhg.NetBSD.org/pkgsrc/rev/d661bbc031ba
branches: trunk
changeset: 348284:d661bbc031ba
user: rillig <rillig%pkgsrc.org@localhost>
date: Sat Jun 11 14:58:26 2016 +0000
description:
Removed unnecessary complexity and super-special corner cases from the
documentation.
diffstat:
doc/guide/files/components.xml | 25 +++-----
doc/guide/files/configuring.xml | 4 +-
doc/guide/files/faq.xml | 27 +++------
doc/guide/files/introduction.xml | 4 +-
doc/guide/files/makefile.xml | 108 ++++++--------------------------------
doc/guide/files/platforms.xml | 4 +-
doc/guide/files/porting.xml | 9 +--
7 files changed, 43 insertions(+), 138 deletions(-)
diffs (truncated from 338 to 300 lines):
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/components.xml
--- a/doc/guide/files/components.xml Sat Jun 11 14:56:28 2016 +0000
+++ b/doc/guide/files/components.xml Sat Jun 11 14:58:26 2016 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.51 2015/07/04 16:12:54 joerg Exp $ -->
+<!-- $NetBSD: components.xml,v 1.52 2016/06/11 14:58:26 rillig Exp $ -->
<chapter id="components"> <?dbhtml filename="components.html"?>
<title>Package components - files, directories and contents</title>
@@ -190,9 +190,9 @@
digest, or checksum, of each distfile needed for the package. This
ensures that the distfiles retrieved from the Internet have not been
corrupted during transfer or altered by a malign force to introduce
- a security hole. Due to recent rumor about weaknesses of digest
- algorithms, all distfiles are protected using both SHA1 and RMD160
- message digests, as well as the file size.</para>
+ a security hole. To provide maximum security, all distfiles are
+ protected using three different message digest algorithms (SHA1,
+ RMD160, SHA512), as well as the file size.</para>
<para>The <filename>distinfo</filename> file also contains the
checksums for all the patches found in the
@@ -200,8 +200,7 @@
linkend="components.patches"/>).</para>
<para>To regenerate the <filename>distinfo</filename> file, use the
- <command>make makedistinfo</command> or <command>make mdi</command>
- command.</para>
+ <command>make distinfo</command> command.</para>
<para>Some packages have different sets of distfiles depending on
the platform, for example <filename
@@ -213,18 +212,16 @@
</sect1>
<sect1 id="components.patches">
- <title>patches/*</title>
+ <title><filename>patches/*</filename></title>
- <para>Many packages still don't work out-of-the box on the various
- platforms that are supported by pkgsrc. Therefore, a number of custom
- patch files are needed to make the package work. These patch files are
+ <para>Some packages don't work out-of-the box on the various
+ platforms that are supported by pkgsrc. These packages need
+ to be patched to make them work. The patch files can be
found in the <filename>patches/</filename> directory.</para>
<para>In the <emphasis>patch</emphasis> phase, these patches are
applied to the files in <varname>WRKSRC</varname> directory after
- extracting them, in <ulink
- url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03";>alphabetic
- order</ulink>.</para>
+ extracting them, in alphabetic order.</para>
<sect2 id="components.patch.structure">
<title>Structure of a single patch file</title>
@@ -254,7 +251,7 @@
</itemizedlist>
- <para>In all, the patch should be commented so that any
+ <para>The patch should be commented so that any
developer who knows the code of the application can make some use of
the patch. Special care should be taken for the upstream developers,
since we generally want that they accept our patches, so we have less
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/configuring.xml
--- a/doc/guide/files/configuring.xml Sat Jun 11 14:56:28 2016 +0000
+++ b/doc/guide/files/configuring.xml Sat Jun 11 14:58:26 2016 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: configuring.xml,v 1.48 2016/04/10 16:02:02 joerg Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.49 2016/06/11 14:58:26 rillig Exp $ -->
<chapter id="configuring">
<title>Configuring pkgsrc</title>
@@ -90,7 +90,7 @@
<sect1 id="variables-affecting-build">
<title>Variables affecting the build process</title>
- <para>XXX
+ <para>
<itemizedlist>
<listitem><para><varname>PACKAGES</varname>: The top level
directory for the binary packages. The default is
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/faq.xml
--- a/doc/guide/files/faq.xml Sat Jun 11 14:56:28 2016 +0000
+++ b/doc/guide/files/faq.xml Sat Jun 11 14:58:26 2016 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: faq.xml,v 1.52 2016/06/11 13:19:54 rillig Exp $ -->
+<!-- $NetBSD: faq.xml,v 1.53 2016/06/11 14:58:26 rillig Exp $ -->
<chapter id="faq"> <?dbhtml filename="faq.html"?>
<title>Frequently Asked Questions</title>
@@ -222,25 +222,16 @@
<sect1 id="non-root-pkgsrc">
<title>How to use pkgsrc as non-root</title>
-<para>If you want to use pkgsrc as non-root user, you can set some
-variables to make pkgsrc work under these conditions. At the very least,
-you need to set <varname>UNPRIVILEGED</varname> to <quote>yes</quote>; this
-will turn on unprivileged mode and set multiple related variables to allow
-installation of packages as non-root.</para>
+<para>To install packages from source as a non-root user, download
+pkgsrc as described in <xref linkend="getting"/>, cd into that
+directory and run the command <command>./bootstrap/bootstrap
+--unprivileged</command>.</para>
-<para>In case the defaults are not enough, you may want to tune some other
-variables used. For example, if the automatic user/group detection leads
-to incorrect values (or not the ones you would like to use), you can change
-them by setting <varname>UNPRIVILEGED_USER</varname> and
-<varname>UNPRIVILEGED_GROUP</varname> respectively.</para>
+<para>This will install the binary part of pkgsrc to
+<filename>~/pkg</filename> and put the pkgsrc configuration &mk.conf;
+into <filename>~/pkg/etc</filename>.</para>
-<para>As regards bootstrapping, please note that the
-<command>bootstrap</command> script will ease non-root configuration when
-given the <quote>--ignore-user-check</quote> flag, as it will choose and
-use multiple default directories under <filename>~/pkg</filename> as the
-installation targets. These directories can be overridden by the
-<quote>--prefix</quote> flag provided by the script, as well as some others
-that allow finer tuning of the tree layout.</para>
+<para>For more details, see <filename>mk/unprivileged.mk</filename>.</para>
</sect1>
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/introduction.xml
--- a/doc/guide/files/introduction.xml Sat Jun 11 14:56:28 2016 +0000
+++ b/doc/guide/files/introduction.xml Sat Jun 11 14:58:26 2016 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: introduction.xml,v 1.37 2016/01/17 22:06:16 sevan Exp $ -->
+<!-- $NetBSD: introduction.xml,v 1.38 2016/06/11 14:58:26 rillig Exp $ -->
<chapter id="introduction">
<title>What is pkgsrc?</title>
@@ -39,7 +39,7 @@
</listitem>
</itemizedlist>
- <para>...just to name a few.</para>
+ <para>… just to name a few.</para>
<para>pkgsrc has built-in support for handling varying dependencies,
such as pthreads and X11, and extended features such as IPv6 support on
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/makefile.xml
--- a/doc/guide/files/makefile.xml Sat Jun 11 14:56:28 2016 +0000
+++ b/doc/guide/files/makefile.xml Sat Jun 11 14:58:26 2016 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: makefile.xml,v 1.24 2014/12/03 07:05:05 ryoon Exp $ -->
+<!-- $NetBSD: makefile.xml,v 1.25 2016/06/11 14:58:26 rillig Exp $ -->
<chapter id="makefile"> <?dbhtml filename="makefile.html"?>
<title>Programming in <filename>Makefile</filename>s</title>
@@ -78,28 +78,15 @@
not preceded by a backslash starts a comment that continues upto the
end of the logical line.</para>
- <para><emphasis>Note:</emphasis> Because of this parsing algorithm
- the only way to create a variable consisting of a single backslash
- is using the ``!='' operator, for example: <!-- FIXME
- --><varname>BACKSLASH!=echo "\\"</varname>.</para>
-
- <para>So far for defining variables. The other thing you can do with
- variables is evaluating them. A variable is evaluated when it is
- part of the right side of the ``:='' or the ``!='' operator, or
- directly before executing a shell command which the variable is part
- of. In all other cases, &man.make.1; performs lazy evaluation, that
- is, variables are not evaluated until there's no other way. The
- ``modifiers'' mentioned in the man page also evaluate the
- variable.</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 ``:='' or the ``!='' 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, it is split as you would expect
- it from &man.sh.1;.</para>
-
- <para>No rule without exception—the <command>.for</command>
- loop does not follow the shell quoting rules but splits at sequences
- of whitespace.</para>
+ a string is split into words, it is split like in &man.sh.1;.</para>
<para>There are several types of variables that should be handled
differently. Strings and two types of lists.</para>
@@ -183,24 +170,6 @@
</sect2>
- <sect2 id="converting-internal-to-external">
- <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. The reason for appending
- <varname>""</varname> is explained below.</para>
-
- </sect2>
-
<sect2 id="passing-variable-to-shell">
<title>Passing variables to a shell command</title>
@@ -210,50 +179,26 @@
<programlisting>
STRING= foo bar < > * `date` $$HOME ' "
-EXT_LIST= string=${STRING:Q} x=second\ item
+EXAMPLE_ENV= string=${STRING:Q} x=multiple\ quoted\ words
all:
echo ${STRING} # 1
- echo "${STRING}" # 2
- echo "${STRING:Q}" # 3
- echo ${STRING:Q} # 4
- echo x${STRING:Q} | sed 1s,.,, # 5
- printf "%s\\n" ${STRING:Q}"" # 6
- env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
+ 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 leads to a syntax error too, and if you leave out
- the last " character from <varname>${STRING}</varname>,
- &man.date.1; will be executed. The <varname>$HOME</varname> shell
- variable would be evaluated, too.</para>
-
- <para>Example 3 outputs each space character preceded by 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 2 can handle all strings, except those starting
+ with a dash or those containing backslashes.</para>
- <para>Example 5 handles even the case of a leading dash
- correctly.</para>
-
- <para>Example 6 also works with every string and is the
- light-weight solution, since it does not involve a pipe, which has
- its own problems.</para>
+ <para>Example 3 can handle arbitrary strings.</para>
- <para>The <varname>EXT_LIST</varname> does not need to be quoted
- because the quoting has already been 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>
-
+ <para>In example 4, the <varname>EXT_LIST</varname> does not
+ need to be quoted because the quoting has already been done
+ when adding elements to the list.</para>
</sect2>
<sect2 id="quoting-guideline">
@@ -344,24 +289,5 @@
</itemizedlist>
</sect2>
-
- <sect2 id="bsd-make-bug-workaround">
- <title>Workaround for a bug in BSD Make</title>
-
- <para>The pkgsrc bmake program does not handle the following
- assignment correctly. In case <varname>_othervar_</varname>
- contains a ``-'' character, one of the closing braces is included
- in <varname>${VAR}</varname> after this code executes.</para>
-
-<programlisting>
-VAR:= ${VAR:N${_othervar_:C/-//}}
-</programlisting>
-
- <para>For a more complex code snippet and a workaround, see the
- package <filename role="pkg">regress/make-quoting</filename>, testcase
- <varname>bug1</varname>.</para>
-
- </sect2>
-
</sect1>
</chapter>
diff -r a7083eb7bfab -r d661bbc031ba doc/guide/files/platforms.xml
Home |
Main Index |
Thread Index |
Old Index