svn commit: r44363 - in head/en_US.ISO8859-1/books/porters-handbook: pkg-files plist upgrading
Mathieu Arnold
mat at FreeBSD.org
Thu Mar 27 16:50:33 UTC 2014
Author: mat (ports committer)
Date: Thu Mar 27 16:50:32 2014
New Revision: 44363
URL: http://svnweb.freebsd.org/changeset/doc/44363
Log:
Update plist, pkg-files and upgrading chapters.
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:13:55 2014 (r44362)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:50:32 2014 (r44363)
@@ -54,25 +54,15 @@
<command>pkg install</command> you can do this via the
<filename>pkg-install</filename> script. This script will
automatically be added to the package, and will be run twice by
- <command>pkg</command> the first time as
-
- <literal>${SH} pkg-install ${PKGNAME}
- PRE-INSTALL</literal> and the second time as
+ <command>pkg</command> the first time as <literal>${SH}
+ pkg-install ${PKGNAME} PRE-INSTALL</literal> before the
+ package is installed and the second time as
<literal>${SH} pkg-install ${PKGNAME}
- POST-INSTALL</literal>. <literal>$2</literal> can be
- tested to determine which mode the script is being run in.
- The <envar>PKG_PREFIX</envar> environmental variable will be
- set to the package installation directory.</para>
-
- <note>
- <para>This script is not run automatically if you install the
- port with <command>make install</command>. If you are
- depending on it being run, you will have to explicitly call
- it from your port's <filename>Makefile</filename>, with a
- line like <literal>PKG_PREFIX=${PREFIX} ${SH}
- ${PKGINSTALL} ${PKGNAME}
- PRE-INSTALL</literal>.</para>
- </note>
+ POST-INSTALL</literal> after it has been installed.
+ <literal>$2</literal> can be tested to determine which
+ mode the script is being run in. The <envar>PKG_PREFIX</envar>
+ environmental variable will be set to the package installation
+ directory.</para>
</sect1>
<sect1 xml:id="pkg-deinstall">
@@ -80,12 +70,16 @@
<para>This script executes when a package is removed.</para>
- <para>This script will be run twice by
- <command>pkg delete</command> The first time as
+ <para>This script will be run twice by <command>pkg
+ delete</command> The first time as <literal>${SH}
+ pkg-deinstall ${PKGNAME} DEINSTALL</literal> before the
+ port is de-installed and the second time as
<literal>${SH} pkg-deinstall ${PKGNAME}
- DEINSTALL</literal> and the second time as
- <literal>${SH} pkg-deinstall
- ${PKGNAME} POST-DEINSTALL</literal>.</para>
+ POST-DEINSTALL</literal> after the port has been de-installed.
+ <literal>$2</literal> can be tested to determine which
+ mode the script is being run in. The <envar>PKG_PREFIX</envar>
+ environmental variable will be set to the package installation
+ directory</para>
</sect1>
<sect1 xml:id="pkg-names">
@@ -143,12 +137,6 @@
</tbody>
</tgroup>
</informaltable>
-
- <para>Please change these variables rather than overriding
- <varname>PKG_ARGS</varname>. If you change
- <varname>PKG_ARGS</varname>, those files will not correctly be
- installed in <filename>/var/db/pkg</filename> upon install
- from a port.</para>
</sect1>
<sect1 xml:id="using-sub-files">
@@ -163,14 +151,15 @@
<para>The <varname>SUB_FILES</varname> variable specifies a list
of files to be automatically modified. Each
- <replaceable>file</replaceable> in the
+ <filename><replaceable>file</replaceable></filename> in the
<varname>SUB_FILES</varname> list must have a corresponding
- <filename>file.in</filename> present in
- <varname>FILESDIR</varname>. A modified version will be created
- in <varname>WRKDIR</varname>. Files defined as a value of
- <varname>USE_RC_SUBR</varname> (or the deprecated
- <varname>USE_RCORDER</varname>) are automatically added to the
- <varname>SUB_FILES</varname>. For the files
+ <filename><replaceable>file</replaceable>.in</filename> present
+ in <varname>FILESDIR</varname>. A modified version will be
+ created as
+ <filename>${WRKDIR}/<replaceable>file</replaceable></filename>.
+ Files defined as a value of <varname>USE_RC_SUBR</varname> (or
+ the deprecated <varname>USE_RCORDER</varname>) are automatically
+ added to the <varname>SUB_FILES</varname>. For the files
<filename>pkg-message</filename>,
<filename>pkg-install</filename>, and
<filename>pkg-deinstall</filename>, the corresponding Makefile
@@ -186,7 +175,7 @@
<varname>LOCALBASE</varname>, <varname>DATADIR</varname>,
<varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>,
<varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. Any
- line beginning with <literal>@comment</literal> will be deleted
+ line beginning with <literal>@comment </literal> will be deleted
from resulting files after a variable substitution.</para>
<para>The following example will replace
Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:13:55 2014 (r44362)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:50:32 2014 (r44363)
@@ -57,19 +57,22 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSI
<para>If your port installs files conditionally on the options
set in the port, the usual way of handling it is prefixing the
<filename>pkg-plist</filename> lines with a
- <literal>%%TAG%%</literal> and adding that
- <literal>TAG</literal> to the <varname>PLIST_SUB</varname>
- variable inside the <filename>Makefile</filename> with a special
- value of <literal>@comment</literal>, which makes package tools
- to ignore the line:</para>
-
- <programlisting>.if defined(WITH_X11)
-PLIST_SUB+= X11=""
-.else
-PLIST_SUB+= X11="@comment "
-.endif</programlisting>
-
- <para>and in the <filename>pkg-plist</filename>:</para>
+ <literal>%%OPT%%</literal> for lines needed when the option is
+ enabled, or <literal>%%NO_OPT%%</literal> when the option is
+ disabled, and adding <literal>OPTIONS_SUB=yes</literal> to the
+ <filename>Makefile</filename>. See <xref
+ linkend="options_sub"/> for more information.</para>
+
+ <para>For instance, if there are files that are only installed
+ when the <literal>X11</literal> option is enabled, and the
+ <filename>Makefile</filename> has:</para>
+
+ <programlisting>OPTIONS_DEFINE= X11
+OPTIONS_SUB= yes</programlisting>
+
+ <para>In the <filename>pkg-plist</filename> file, put
+ <literal>%%X11%%</literal> in front of the lines only being
+ installed when the option is enabled, like this :</para>
<programlisting>%%X11%%bin/foo-gui</programlisting>
@@ -104,6 +107,24 @@ PLIST_SUB+= X11="@comment "
and <varname>PLIST_DIRSTRY</varname> must be set before
<filename>TMPPLIST</filename> is written, i.e., in
<buildtarget>pre-install</buildtarget> or earlier.</para>
+
+ <para>From time to time, the <varname>OPTIONS_SUB</varname>
+ construct is not enough, in those cases, adding a specific
+ <literal>TAG</literal> to the <varname>PLIST_SUB</varname>
+ variable inside the <filename>Makefile</filename> with a special
+ value of <literal>@comment</literal>, makes package tools to
+ ignore the line. For instance, if some files are only installed
+ when the <literal>X11</literal> option is on and the
+ architecture is <literal>i386</literal>:</para>
+
+ <programlisting>.include <bsd.port.pre.mk>
+
+.if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386"
+PLIST_SUB+= X11I386=""
+.else
+PLIST_SUB+= X11I386="@comment "
+.endif</programlisting>
+
</sect1>
<sect1 xml:id="plist-cleaning">
@@ -112,10 +133,10 @@ PLIST_SUB+= X11="@comment "
<sect2 xml:id="plist-dir-cleaning">
<title>Cleaning Up Empty Directories</title>
- <para>Do make your ports remove empty directories when they are
- de-installed. This is usually accomplished by adding
- <literal>@dirrm</literal> lines for all directories that are
- specifically created by the port. You need to delete
+ <para>When being de-installed, A port has to remove empty
+ directories it created. This is usually accomplished by
+ adding <literal>@dirrm</literal> lines for all directories
+ that are specifically created by the port. You need to delete
subdirectories before you can delete parent
directories.</para>
@@ -209,6 +230,17 @@ etc/orbit.conf.sample
<link linkend="porting-message">message</link> pointing out that
the user must copy and edit the file before the software will
work.</para>
+
+ <tip>
+ <para>When a port installs its configuration in a subdirectory
+ of <filename>${PREFIX}/etc</filename>, it should be in
+ <varname>ETCDIR</varname>, which defaults to
+ <literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be
+ overrided in the ports <filename>Makefile</filename> if there
+ is a convention for the port to use some other directory. The
+ <literal>%%ETCDIR%%</literal> macro should be used in its
+ stead in the <filename>pkg-plist</filename> file.</para>
+ </tip>
</sect1>
<sect1 xml:id="plist-dynamic">
@@ -223,9 +255,10 @@ etc/orbit.conf.sample
and <varname>PLIST_DIRSTRY</varname>. Even if the contents are
auto-generated by a tool or a target in the Makefile
<emphasis>before</emphasis> the inclusion into the Ports
- Collection by a committer, this is still considered a static
- list, since it is possible to examine it without having to
- download or compile the distfile.</para>
+ Collection by a committer (e.g., using <command>make
+ makeplist></command>), this is still considered a static list,
+ since it is possible to examine it without having to download or
+ compile the distfile.</para>
<para>A <emphasis>dynamic package list</emphasis> is a package
list which is generated at the time the port is compiled based
@@ -249,14 +282,17 @@ etc/orbit.conf.sample
<sect1 xml:id="plist-autoplist">
<title>Automated Package List Creation</title>
- <para>First, make sure your port is almost complete, with only
- <filename>pkg-plist</filename> missing. You may then run
- <command>make makeplist</command> to generate a
- <filename>pkg-plist</filename> automatically. This file must be
- double checked for correctness.</para>
-
- <para>User configuration files should be removed, or installed as
- <filename>filename.sample</filename>. The
+ <para>First, make sure the port is almost complete, with only
+ <filename>pkg-plist</filename> missing. Running <command>make
+ makeplist</command> will show what should be put in
+ <filename>pkg-plist</filename>. The output of
+ <buildtarget>makeplist</buildtarget> must be double checked for
+ correctness as it tries to automatically guess a few things, and
+ can get it wrong.</para>
+
+ <para>User configuration files should be installed as
+ <filename>filename.sample</filename>, as it is described in
+ <xref linkend="plist-config"/>. The
<filename>info/dir</filename> file should not be listed and
appropriate <filename>install-info</filename> lines should be
added as noted in the
Modified: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:13:55 2014 (r44362)
+++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:50:32 2014 (r44363)
@@ -147,7 +147,10 @@
to see what has changed, and to update the diff if
something was modified in the Ports Collection since you
began work on it, or if the
- committer asks for something to be fixed.</para>
+ committer asks for something to be fixed. Also, a patch
+ generated with <command>svn diff</command> can be easily applied
+ with <command>svn patch</command> and will save some time to the
+ committer.</para>
<screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/>
&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd</userinput> <co xml:id="svn-FreeBSD-org"/>
@@ -173,10 +176,11 @@
</calloutlist>
<para>While in the working directory, make any changes that you
- would usually make to the port. If you add or remove a file,
- use <command>svn</command> to track these changes:</para>
+ would usually make to the port. If you add, move or remove a
+ file, use <command>svn</command> to track these changes:</para>
<screen>&prompt.user; <userinput>svn add new_file</userinput>
+&prompt.user; <userinput>svn move old_name new_name</userinput>
&prompt.user; <userinput>svn remove deleted_file</userinput></screen>
<para>Make sure that you check the port using the checklist in
@@ -251,6 +255,14 @@
<para>Send your patch following the guidelines in
<xref linkend="port-upgrading"/>.</para>
+
+ <tip>
+ <para>You can have patch automatically generated and the PR
+ pre-filled with your contact information by using
+ the <application>Port Tools</application> <command>port
+ submit</command> command. See <xref
+ linkend="testing-porttools"/> for more details.</para>
+ </tip>
</sect1>
<sect1 xml:id="moved-and-updating-files">
@@ -273,6 +285,17 @@
instructions, please make sure to get the shell escaping
right.</para>
+ <note>
+ <para>It is recommended that the AFFECTS line contains a glob
+ matching all the ports affected by the entry so that automated
+ tools can parse it as easily as possible. If an update
+ concerns all the existing <application>BIND 9</application>
+ versions the <literal>AFFECTS</literal> content should be
+ <literal>users of dns/bind9*</literal>, it should
+ <emphasis>not</emphasis> be <literal>users of BIND
+ 9</literal></para>
+ </note>
+
<para>The <filename>/usr/ports/MOVED</filename> file is used to
list moved or removed ports. Each line in the file is made
up of the name of the port, where the port was moved to, when,
@@ -285,12 +308,18 @@
<para>The date should be entered in the form
<literal>YYYY-MM-DD</literal>. New entries should be added to
- the end of the file to keep it in chronological order.</para>
+ the top of the file to keep it in reverse chronological order
+ (the latest entries first).</para>
<para>If a port was removed but has since been restored,
delete the line in this file that states that it was
removed.</para>
+ <para>If a port was renamed and then renamed back to its original
+ name, you should add a new one with the intermediate name to the
+ old name, and remove the old entry as to not create a
+ loop.</para>
+
<para>The changes can be validated with
<command>Tools/scripts/MOVEDlint.awk</command>.</para>
</sect1>
More information about the svn-doc-head
mailing list