os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update plist, pkg-files and upgrading chapters.

Browse source 
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-03-27 16:50:32 +00:00
parent 4a255253b7
commit c43ffaa928
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44363
3 changed files with 120 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
View file

@ -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
<command>pkg</command> the first time as <literal>&dollar;{SH}
pkg-install &dollar;{PKGNAME} PRE-INSTALL</literal> before the
package is installed and the second time as
<literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
PRE-INSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
POST-INSTALL</literal>. <literal>&dollar;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=&dollar;{PREFIX} &dollar;{SH}
&dollar;{PKGINSTALL} &dollar;{PKGNAME}
PRE-INSTALL</literal>.</para>
</note>
POST-INSTALL</literal> after it has been installed.
<literal>&dollar;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>&dollar;{SH}
pkg-deinstall &dollar;{PKGNAME} DEINSTALL</literal> before the
port is de-installed and the second time as
<literal>&dollar;{SH} pkg-deinstall &dollar;{PKGNAME}
DEINSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-deinstall
&dollar;{PKGNAME} POST-DEINSTALL</literal>.</para>
POST-DEINSTALL</literal> after the port has been de-installed.
<literal>&dollar;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

86
en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
View file

@ -57,19 +57,22 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<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>
<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>
<programlisting>.if defined(WITH_X11)
PLIST_SUB+= X11=""
.else
PLIST_SUB+= X11="@comment "
.endif</programlisting>
<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>
<para>and in the <filename>pkg-plist</filename>:</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 &lt;bsd.port.pre.mk&gt;
.if ${PORT_OPTIONS:MX11} &amp;&amp; ${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>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 removed, or installed as
<filename>filename.sample</filename>. The
<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

37
en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml
View file

@ -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>