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

Catch up with several recent events.

Browse source 
(1) Describe the change in ports skeleton layout.  I think I caught
    everything, but please let me know if I missed something.

(2) Explicitly allow using things other than the "split" sequence (aa,
    ab, ac...) in patchfile names, in particular those that represent
    the names of the files being patched.

(3) Add a little note recommending the use of DISTFILES over
    DISTNAME/WRKSRC/EXTRACT_SUFX when the source extracts into
    ${WRKDIR}/${PORTNAME}-${PORTVERSION} but the archive filename is
    not ${PORTNAME}-${PORTVERSION}.tar.gz.

(4) There is error checking in category names now.

(5) There are more MASTER_SITE_* variables now, so just list a couple
    and refer the readers to bsd.sites.mk.

(6) Explain EXTRACT_PATCHES.  In particular, note that you shouldn't
    copy patches into ${PATCHDIR}.

(7) Mention that pkg-install is called with sh.

(8) The first letter of the package name should be lowercase.  (We'll
    rename existing ports soon.)

While I'm here, fix a couple of minor indenting problems in the
paragraphs I was editing.  It seems emacs some times messes up
auto-indentation, causing stuff like

===
            <para>This is <emphasis>not</emphasis> a manual or an in-depth
              description on how to use or compile the port! <emphasis>Please
                be careful if you are copying from the
===

(the "be careful" should be in the same level as "description")

Also, convert a couple of "Note that" to real <note>'s.
This commit is contained in:
Satoshi Asami 2000-10-06 09:02:30 +00:00
parent de336df357
commit d55719b34b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=8099
2 changed files with 320 additions and 286 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

303
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -1,7 +1,7 @@
<!-- <!--
The FreeBSD Documentation Project The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.130 2000/09/29 01:02:30 marko Exp $ $FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.131 2000/10/03 22:29:31 bmah Exp $
--> -->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
@ -123,14 +123,16 @@ USE_IMAKE= yes
<sect1> <sect1>
<title>Writing the description files</title> <title>Writing the description files</title>
<para>There are three description files that are required for any <para>There are three description files that are required for
port, whether they actually package or not. They are any port, whether they actually package or not. They are
<filename>COMMENT</filename>, <filename>DESCR</filename>, and <filename>pkg-comment</filename>,
<filename>PLIST</filename>, and reside in the <filename>pkg-descr</filename>, and
<filename>pkg</filename> subdirectory.</para> <filename>pkg-plist</filename>, and their
<filename>pkg-</filename> prefix distinguishes them from
other files.</para>
<sect2> <sect2>
<title><filename>COMMENT</filename></title> <title><filename>pkg-comment</filename></title>
<para>This is the one-line description of the port. <para>This is the one-line description of the port.
<emphasis>Please</emphasis> do not include the package name (or <emphasis>Please</emphasis> do not include the package name (or
@ -143,7 +145,7 @@ A cat chasing a mouse all over the screen</programlisting>
</sect2> </sect2>
<sect2> <sect2>
<title><filename>DESCR</filename></title> <title><filename>pkg-descr</filename></title>
<para>This is a longer description of the port. One to a few <para>This is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is paragraphs concisely explaining what the port does is
@ -152,8 +154,8 @@ A cat chasing a mouse all over the screen</programlisting>
<note> <note>
<para>This is <emphasis>not</emphasis> a manual or an in-depth <para>This is <emphasis>not</emphasis> a manual or an in-depth
description on how to use or compile the port! <emphasis>Please description on how to use or compile the port! <emphasis>Please
be careful if you are copying from the be careful if you are copying from the
<filename>README</filename> or manpage</emphasis>; too often <filename>README</filename> or manpage</emphasis>; too often
they are not a concise description of the port or are in an they are not a concise description of the port or are in an
awkward format (e.g., manpages have justified spacing). If the awkward format (e.g., manpages have justified spacing). If the
ported software has an official WWW homepage, you should list it ported software has an official WWW homepage, you should list it
@ -178,7 +180,7 @@ asami@cs.berkeley.edu</programlisting>
</sect2> </sect2>
<sect2> <sect2>
<title><filename>PLIST</filename></title> <title><filename>pkg-plist</filename></title>
<para>This file lists all the files installed by the port. It is <para>This file lists all the files installed by the port. It is
also called the &ldquo;packing list&rdquo; because the package is also called the &ldquo;packing list&rdquo; because the package is
@ -226,7 +228,7 @@ lib/X11/oneko/mouse.xpm
<para>Just type <command>make makesum</command>. The ports make rules <para>Just type <command>make makesum</command>. The ports make rules
will automatically generate the file will automatically generate the file
<filename>files/md5</filename>.</para> <filename>distinfo</filename>.</para>
</sect1> </sect1>
<sect1 id="porting-testing"> <sect1 id="porting-testing">
@ -238,12 +240,12 @@ lib/X11/oneko/mouse.xpm
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><filename>PLIST</filename> does not contain anything not <para><filename>pkg-plist</filename> does not contain anything not
installed by your port</para> installed by your port</para>
</listitem> </listitem>
<listitem> <listitem>
<para><filename>PLIST</filename> contains everything that is <para><filename>pkg-plist</filename> contains everything that is
installed by your port</para> installed by your port</para>
</listitem> </listitem>
@ -421,9 +423,10 @@ lib/X11/oneko/mouse.xpm
<step> <step>
<para>The <maketarget>patch</maketarget> target is run. First, <para>The <maketarget>patch</maketarget> target is run. First,
any patches defined in <makevar>PATCHFILES</makevar> are any patches defined in <makevar>PATCHFILES</makevar> are
applied. Second, if any patches are found in applied. Second, if any patch files named
<filename>patch-<replaceable>*</replaceable></filename> are found in
<makevar>PATCHDIR</makevar> (defaults to the <makevar>PATCHDIR</makevar> (defaults to the
<filename>patches</filename> subdirectory), they are applied at <filename>files</filename> subdirectory), they are applied at
this time in alphabetical order.</para> this time in alphabetical order.</para>
</step> </step>
@ -585,11 +588,14 @@ lib/X11/oneko/mouse.xpm
changed can be picked up with a recursive diff for later feeding to changed can be picked up with a recursive diff for later feeding to
patch. Each set of patches you wish to apply should be collected patch. Each set of patches you wish to apply should be collected
into a file named into a file named
<filename>patch-<replaceable>xx</replaceable></filename> where <filename>patch-<replaceable>*</replaceable></filename> where
<replaceable>xx</replaceable> denotes the sequence in which the <replaceable>*</replaceable> denotes the sequence in which the
patches will be applied &mdash; these are done in patches will be applied &mdash; these are done in
<emphasis>alphabetical order</emphasis>, thus <literal>aa</literal> <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal>
first, <literal>ab</literal> second and so on. These files should first, <literal>ab</literal> second and so on. If you wish,
you can use names that indicate the pathnames of the files that
are patched, such as <filename>patch-Imakefile</filename> or
<filename>patch-src-config.h</filename>. These files should
be stored in <makevar>PATCHDIR</makevar>, from where they will be be stored in <makevar>PATCHDIR</makevar>, from where they will be
automatically applied. All patches should be relative to automatically applied. All patches should be relative to
<makevar>WRKSRC</makevar> (generally the directory your port's <makevar>WRKSRC</makevar> (generally the directory your port's
@ -723,10 +729,10 @@ lib/X11/oneko/mouse.xpm
<listitem> <listitem>
<para>Silent changes to the port distfile which have <para>Silent changes to the port distfile which have
significant functional differences, i.e. changes to significant functional differences, i.e. changes to
the distfile requiring a correction to files/md5 with the distfile requiring a correction to
no corresponding change to <filename>distinfo</filename> with no corresponding change to
<makevar>PORTVERSION</makevar>, where a <command>diff <makevar>PORTVERSION</makevar>, where a <command>diff
-ru</command> of the old and new versions shows -ru</command> of the old and new versions shows
non-trivial changes to the code.</para> non-trivial changes to the code.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -882,13 +888,15 @@ PORTEPOCH= 1</programlisting>
<para><makevar>PKGNAME</makevar> becomes <para><makevar>PKGNAME</makevar> becomes
<literal>gtkmumble-0.3,1</literal></para> <literal>gtkmumble-0.3,1</literal></para>
<para>Note that if <makevar>PORTEPOCH</makevar> were reset <note>
to <literal>0</literal> with this upgrade, someone who had <para>If <makevar>PORTEPOCH</makevar> were reset
installed the gtkmumble-0.10_1 package would not detect to <literal>0</literal> with this upgrade, someone who had
the gtkmumble-0.3 package as newer, since installed the gtkmumble-0.10_1 package would not detect
<literal>3</literal> is still numerically less than the gtkmumble-0.3 package as newer, since
<literal>10</literal>.</para> <literal>3</literal> is still numerically less than
</sect2> <literal>10</literal>.</para>
</note>
</sect2>
</sect1> </sect1>
<sect1> <sect1>
@ -927,9 +935,20 @@ PORTEPOCH= 1</programlisting>
subdirectory named <makevar>WRKSRC</makevar>, which defaults subdirectory named <makevar>WRKSRC</makevar>, which defaults
to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para> to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
<para>Note that <makevar>PKGNAMEPREFIX</makevar> and <note>
<makevar>PKGNAMESUFFIX</makevar> do not affect <para><makevar>PKGNAMEPREFIX</makevar> and
<makevar>DISTNAME</makevar>.</para> <makevar>PKGNAMESUFFIX</makevar> do not affect
<makevar>DISTNAME</makevar>. Also note that when
<makevar>WRKSRC</makevar> is equal to
<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
while the original source archive is named something other than
<makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>,
you should probably leave <makevar>DISTNAME</makevar>
alone&mdash; you are better off defining
<makevar>DISTFILES</makevar> than having to set both
<makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
(and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
</note>
</sect1> </sect1>
<sect1> <sect1>
@ -957,12 +976,6 @@ PORTEPOCH= 1</programlisting>
all the existing ones, you can even create a new category name. In all the existing ones, you can even create a new category name. In
that case, please send mail to the &a.ports; to propose a new that case, please send mail to the &a.ports; to propose a new
category.</para> category.</para>
<note>
<para>There is no error checking for category names. <command>make
package</command> will happily create a new directory if you
mistype the category name, so be careful!</para>
</note>
</sect1> </sect1>
<sect1> <sect1>
@ -983,14 +996,13 @@ PORTEPOCH= 1</programlisting>
for automatically determining the closest master site and fetching for automatically determining the closest master site and fetching
from there!</para> from there!</para>
<para>If the original tarball is part of one of the following popular <para>If the original tarball is part of one of the popular
archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you archives such as X-contrib, GNU, or Perl CPAN, you may be able
refer to those sites in an easy compact form using refer to those sites in an easy compact form using
<makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
<makevar>MASTER_SITE_GNU</makevar>, (e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and
<makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set
<makevar>MASTER_SITE_TEX_CTAN</makevar>, and <makevar>MASTER_SITES</makevar> to one of these variables and
<makevar>MASTER_SITE_SUNSITE</makevar>. Simply set
<makevar>MASTER_SITE_SUBDIR</makevar> to the path within the <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the
archive. Here is an example:</para> archive. Here is an example:</para>
@ -998,6 +1010,11 @@ PORTEPOCH= 1</programlisting>
MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications</programlisting> MASTER_SITE_SUBDIR= applications</programlisting>
<para>These variables are defined in
<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
new archives added all the time, so make sure to check the
latest version of this file before submitting a port.</para>
<para>The user can also set the <makevar>MASTER_SITE_*</makevar> <para>The user can also set the <makevar>MASTER_SITE_*</makevar>
variables in <filename>/etc/make.conf</filename> to override our variables in <filename>/etc/make.conf</filename> to override our
choices, and use their favorite mirrors of these popular archives choices, and use their favorite mirrors of these popular archives
@ -1029,11 +1046,12 @@ MASTER_SITE_SUBDIR= applications</programlisting>
<makevar>PATCHFILES</makevar>. If that is the case, add the name <makevar>PATCHFILES</makevar>. If that is the case, add the name
and the location of the patch tarball to and the location of the patch tarball to
<makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>. <makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>.
Then, from the <maketarget>pre-patch</maketarget> target, apply the Then, use the <makevar>EXTRA_PATCHES</makevar> variable to
patch either by running the patch command from there, or copying the point to those files and <filename>bsd.port.mk</filename>
patch file into the <makevar>PATCHDIR</makevar> directory and will automatically apply them for you. In particular, do
calling it <emphasis>not</emphasis> copy patch files into the
<filename>patch-<replaceable>xx</replaceable></filename>.</para> <makevar>PATCHDIR</makevar> directory&mdash;that directory may
not be writable.</para>
<note> <note>
<para>Note that the tarball will have been extracted alongside the <para>Note that the tarball will have been extracted alongside the
@ -1234,8 +1252,8 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
define the variable <makevar>NOCLEANDEPENDS</makevar> in your define the variable <makevar>NOCLEANDEPENDS</makevar> in your
environment.</para> environment.</para>
<para>To depend on another port unconditionally, it is customary to <para>To depend on another port unconditionally, use the
use the string <literal>nonexistent</literal> as the first field variable <makevar>${NONEXISTENT}</makevar> as the first field
of <makevar>BUILD_DEPENDS</makevar> or of <makevar>BUILD_DEPENDS</makevar> or
<makevar>RUN_DEPENDS</makevar>. Use this only when you need to <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
the to get to the source of the other port. You can often save the to get to the source of the other port. You can often save
@ -1243,7 +1261,7 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
instance instance
<programlisting> <programlisting>
BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting> BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
will always descend to the JPEG port and extract it.</para> will always descend to the JPEG port and extract it.</para>
@ -1320,7 +1338,7 @@ BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
facilitate addition of an appropriate facilitate addition of an appropriate
<literal>@exec /sbin/ldconfig -m</literal> and <literal>@exec /sbin/ldconfig -m</literal> and
<literal>@unexec /sbin/ldconfig -R</literal> pair into your <literal>@unexec /sbin/ldconfig -R</literal> pair into your
<filename>pkg/PLIST</filename> file, so that a user who installed <filename>pkg-plist</filename> file, so that a user who installed
the package can start using the shared library immediately and the package can start using the shared library immediately and
deinstallation will not cause the system to still believe the deinstallation will not cause the system to still believe the
library is there.</para> library is there.</para>
@ -1340,7 +1358,7 @@ INSTALLS_SHLIB= yes
LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting> LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
<para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed <para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed
through &man.sed.1; just like the rest of <filename>pkg/PLIST</filename>, through &man.sed.1; just like the rest of <filename>pkg-plist</filename>,
so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is
recommended that you use <literal>%%PREFIX%%</literal> for recommended that you use <literal>%%PREFIX%%</literal> for
<makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for
@ -1463,7 +1481,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<filename>libfoo.so</filename> to <filename>libfoo.so</filename> to
<filename>libfoo.so.<replaceable>N</replaceable></filename> to make <filename>libfoo.so.<replaceable>N</replaceable></filename> to make
ELF linkers happy. Since it should be listed in ELF linkers happy. Since it should be listed in
<filename>PLIST</filename> too, and it won't hurt in the a.out case <filename>pkg-plist</filename> too, and it won't hurt in the a.out case
(some ports even require the link for dynamic loading), you should (some ports even require the link for dynamic loading), you should
just make this link regardless of the setting of just make this link regardless of the setting of
<makevar>PORTOBJFORMAT</makevar>.</para> <makevar>PORTOBJFORMAT</makevar>.</para>
@ -1480,9 +1498,9 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
</sect1> </sect1>
<sect1> <sect1>
<title><filename>PLIST</filename></title> <title><filename>pkg-plist</filename></title>
<para><filename>PLIST</filename> should contain the short (ELF) shlib <para><filename>pkg-plist</filename> should contain the short (ELF) shlib
names if the a.out minor number is zero, and the long (a.out) names names if the a.out minor number is zero, and the long (a.out) names
otherwise. <filename>bsd.port.mk</filename> will automatically add otherwise. <filename>bsd.port.mk</filename> will automatically add
<literal>.0</literal> to the end of short shlib lines if <literal>.0</literal> to the end of short shlib lines if
@ -1496,7 +1514,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
system (for instance, ports that install compatibility libraries for system (for instance, ports that install compatibility libraries for
other operating systems), define the variable other operating systems), define the variable
<makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing
of <filename>PLIST</filename> mentioned in the previous of <filename>pkg-plist</filename> mentioned in the previous
paragraph.</para> paragraph.</para>
</sect1> </sect1>
@ -1509,7 +1527,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<programlisting> <programlisting>
${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> ${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
<para>In <filename>PLIST</filename> it should read;</para> <para>In <filename>pkg-plist</filename> it should read;</para>
<programlisting> <programlisting>
@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... @exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ...
@ -1574,8 +1592,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<filename>xdvi400/Makefile</filename> are similar). The <filename>xdvi400/Makefile</filename> are similar). The
<makevar>MASTERDIR</makevar> definition tells <makevar>MASTERDIR</makevar> definition tells
<filename>bsd.port.mk</filename> that the regular set of <filename>bsd.port.mk</filename> that the regular set of
subdirectories like <makevar>PATCHDIR</makevar> and subdirectories like <makevar>FILESDIR</makevar> and
<makevar>PKGDIR</makevar> are to be found under <makevar>SCRIPTDIR</makevar> are to be found under
<filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal>
line will override the <literal>RESOLUTION=300</literal> line in line will override the <literal>RESOLUTION=300</literal> line in
<filename>xdvi300/Makefile</filename> and the port will be built with <filename>xdvi300/Makefile</filename> and the port will be built with
@ -1622,9 +1640,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<title>Manpages</title> <title>Manpages</title>
<para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add
any manpages to <filename>pkg/PLIST</filename> (this means you must any manpages to <filename>pkg-plist</filename> (this means you must
<emphasis>not</emphasis> list manpages in the <emphasis>not</emphasis> list manpages in the
<filename>PLIST</filename>&mdash;see <link <filename>pkg-plist</filename>&mdash;see <link
linkend="porting-plist">generating PLIST</link> for more). It also linkend="porting-plist">generating PLIST</link> for more). It also
makes the install stage automatically compress or uncompress manpages makes the install stage automatically compress or uncompress manpages
depending on the setting of <makevar>NOMANCOMPRESS</makevar> in depending on the setting of <makevar>NOMANCOMPRESS</makevar> in
@ -1636,7 +1654,7 @@ MASTERDIR= ${.CURDIR}/../xdvi300
be destroyed and recreated by <filename>bsd.port.mk</filename> be destroyed and recreated by <filename>bsd.port.mk</filename>
to make sure it points to the correct file. Any manpages to make sure it points to the correct file. Any manpages
listed in MLINKS must not be listed in the listed in MLINKS must not be listed in the
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<para>To specify whether the manpages are compressed upon installation, <para>To specify whether the manpages are compressed upon installation,
use the <makevar>MANCOMPRESSED</makevar> variable. This variable can use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
@ -1845,12 +1863,12 @@ Options:
in <emphasis>three</emphasis> places in <emphasis>three</emphasis> places
(<filename>Makefile</filename> and (<filename>Makefile</filename> and
<literal>@exec</literal>/<literal>@unexec</literal> of <literal>@exec</literal>/<literal>@unexec</literal> of
<filename>PLIST</filename>; see below). However, if you have <filename>pkg-plist</filename>; see below). However, if you have
Japanese (or other multibyte encoding) info files, you will have Japanese (or other multibyte encoding) info files, you will have
to use the extra arguments to <command>install-info</command> to use the extra arguments to <command>install-info</command>
because <command>makeinfo</command> cannot handle those texinfo because <command>makeinfo</command> cannot handle those texinfo
sources. (See <filename>Makefile</filename> and sources. (See <filename>Makefile</filename> and
<filename>PLIST</filename> of <filename>japanese/skk</filename> <filename>pkg-plist</filename> of <filename>japanese/skk</filename>
for examples on how to do this).</para> for examples on how to do this).</para>
</step> </step>
@ -1930,19 +1948,19 @@ Options:
<step> <step>
<para>(This step is only necessary if you are modifying an existing <para>(This step is only necessary if you are modifying an existing
port.) Take a look at <filename>pkg/PLIST</filename> and delete port.) Take a look at <filename>pkg-plist</filename> and delete
anything that is trying to patch up <filename>info/dir</filename>. anything that is trying to patch up <filename>info/dir</filename>.
They may be in <filename>pkg/INSTALL</filename> or some other They may be in <filename>pkg-install</filename> or some other
file, so search extensively.</para> file, so search extensively.</para>
<programlisting> <programlisting>
Index: pkg/PLIST Index: pkg-plist
=================================================================== ===================================================================
RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
retrieving revision 1.15 retrieving revision 1.15
diff -u -r1.15 PLIST diff -u -r1.15 pkg-plist
--- PLIST 1997/03/04 08:04:00 1.15 --- pkg-plist 1997/03/04 08:04:00 1.15
+++ PLIST 1997/04/15 06:32:12 +++ pkg-plist 1997/04/15 06:32:12
@@ -15,9 +15,6 @@ @@ -15,9 +15,6 @@
man/man1/emacs.1.gz man/man1/emacs.1.gz
man/man1/etags.1.gz man/man1/etags.1.gz
@ -1985,19 +2003,19 @@ diff -u -r1.26 Makefile
</step> </step>
<step> <step>
<para>Edit <filename>PLIST</filename> and add equivalent <para>Edit <filename>pkg-plist</filename> and add equivalent
<literal>@exec</literal> statements and also <literal>@exec</literal> statements and also
<literal>@unexec</literal> for <literal>@unexec</literal> for
<command>pkg_delete</command>.</para> <command>pkg_delete</command>.</para>
<programlisting> <programlisting>
Index: pkg/PLIST Index: pkg-plist
=================================================================== ===================================================================
RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
retrieving revision 1.15 retrieving revision 1.15
diff -u -r1.15 PLIST diff -u -r1.15 pkg-plist
--- PLIST 1997/03/04 08:04:00 1.15 --- pkg-plist 1997/03/04 08:04:00 1.15
+++ PLIST 1997/05/20 10:25:12 1.17 +++ pkg-plist 1997/05/20 10:25:12 1.17
@@ -16,7 +14,14 @@ @@ -16,7 +14,14 @@
man/man1/etags.1.gz man/man1/etags.1.gz
man/man1/ctags.1.gz man/man1/ctags.1.gz
@ -2034,24 +2052,24 @@ diff -u -r1.15 PLIST
</chapter> </chapter>
<chapter> <chapter>
<title>The <filename>pkg/</filename> subdirectory</title> <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title>
<para>There are some tricks we have not mentioned yet about the <para>There are some tricks we have not mentioned yet about the
<filename>pkg/</filename> subdirectory that come in handy <filename>pkg-<replaceable>*</replaceable></filename> files
sometimes.</para> that come in handy sometimes.</para>
<sect1 id="porting-message"> <sect1 id="porting-message">
<title><filename>MESSAGE</filename></title> <title><filename>pkg-message</filename></title>
<para>If you need to display a message to the installer, you may place <para>If you need to display a message to the installer, you may place
the message in <filename>pkg/MESSAGE</filename>. This capability is the message in <filename>pkg-message</filename>. This capability is
often useful to display additional installation steps to be taken often useful to display additional installation steps to be taken
after a <command>pkg_add</command> or to display licensing after a <command>pkg_add</command> or to display licensing
information.</para> information.</para>
<note> <note>
<para>The <filename>pkg/MESSAGE</filename> file does not need to be <para>The <filename>pkg-message</filename> file does not need to be
added to <filename>pkg/PLIST</filename>. Also, it will not get added to <filename>pkg-plist</filename>. Also, it will not get
automatically printed if the user is using the port, not the automatically printed if the user is using the port, not the
package, so you should probably display it from the package, so you should probably display it from the
<maketarget>post-install</maketarget> target yourself.</para> <maketarget>post-install</maketarget> target yourself.</para>
@ -2059,15 +2077,16 @@ diff -u -r1.15 PLIST
</sect1> </sect1>
<sect1> <sect1>
<title><filename>INSTALL</filename></title> <title><filename>pkg-install</filename></title>
<para>If your port needs to execute commands when the binary package <para>If your port needs to execute commands when the binary package
is installed with <command>pkg_add</command> you can do this via the is installed with <command>pkg_add</command> you can do this via the
<filename>pkg/INSTALL</filename> script. This script will <filename>pkg-install</filename> script. This script will
automatically be added to the package, and will be run twice by automatically be added to the package, and will be run twice by
<command>pkg_add</command>. The first time will as <literal>INSTALL <command>pkg_add</command>. The first time as
&dollar;{PKGNAME} PRE-INSTALL</literal> and the second time as <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
<literal>INSTALL &dollar;{PKGNAME} POST-INSTALL</literal>. 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 <literal>&dollar;2</literal> can be tested to determine which mode
the script is being run in. The <envar>PKG_PREFIX</envar> the script is being run in. The <envar>PKG_PREFIX</envar>
environmental variable will be set to the package installation environmental variable will be set to the package installation
@ -2083,23 +2102,23 @@ diff -u -r1.15 PLIST
</sect1> </sect1>
<sect1> <sect1>
<title><filename>REQ</filename></title> <title><filename>pkg-req</filename></title>
<para>If your port needs to determine if it should install or not, you <para>If your port needs to determine if it should install or not, you
can create a <filename>pkg/REQ</filename> &ldquo;requirements&rdquo; can create a <filename>pkg-req</filename> &ldquo;requirements&rdquo;
script. It will be invoked automatically at script. It will be invoked automatically at
installation/deinstallation time to determine whether or not installation/deinstallation time to determine whether or not
installation/deinstallation should proceed.</para> installation/deinstallation should proceed.</para>
</sect1> </sect1>
<sect1 id="porting-plist"> <sect1 id="porting-plist">
<title>Changing <filename>PLIST</filename> based on make <title>Changing <filename>pkg-plist</filename> based on make
variables</title> variables</title>
<para>Some ports, particularly the p5- ports, need to change their <para>Some ports, particularly the p5- ports, need to change their
<filename>PLIST</filename> depending on what options they are <filename>pkg-plist</filename> depending on what options they are
configured with (or version of perl, in the case of p5- ports). To configured with (or version of perl, in the case of p5- ports). To
make this easy, any instances in the <filename>PLIST</filename> of make this easy, any instances in the <filename>pkg-plist</filename> of
<literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
<literal>%%PERL_VERSION%%</literal> will be substituted for <literal>%%PERL_VERSION%%</literal> will be substituted for
appropriately. The value of <literal>%%OSREL%%</literal> is the appropriately. The value of <literal>%%OSREL%%</literal> is the
@ -2115,7 +2134,7 @@ diff -u -r1.15 PLIST
pairs and instances of pairs and instances of
<literal>%%<replaceable>VAR</replaceable>%%</literal>' will be <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
substituted with <replaceable>VALUE</replaceable> in the substituted with <replaceable>VALUE</replaceable> in the
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<para>For instance, if you have a port that installs many files in a <para>For instance, if you have a port that installs many files in a
version-specific subdirectory, you can put something like version-specific subdirectory, you can put something like
@ -2126,12 +2145,12 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
in the <filename>Makefile</filename> and use in the <filename>Makefile</filename> and use
<literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up
in <filename>PLIST</filename>. That way, when you upgrade the port, in <filename>pkg-plist</filename>. That way, when you upgrade the port,
you will not have to change dozens (or in some cases, hundreds) of you will not have to change dozens (or in some cases, hundreds) of
lines in the <filename>PLIST</filename>.</para> lines in the <filename>pkg-plist</filename>.</para>
<para>This substitution (as well as addition of any <link <para>This substitution (as well as addition of any <link
linkend="porting-manpages">man pages</link>) will be done between linkend="porting-manpages">man pages</link>) will be done between
the <maketarget>do-install</maketarget> and the <maketarget>do-install</maketarget> and
<maketarget>post-install</maketarget> targets, by reading from <maketarget>post-install</maketarget> targets, by reading from
<makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar> <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
@ -2145,20 +2164,21 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
</sect1> </sect1>
<sect1> <sect1>
<title id="porting-pkgsubdir">Changing the names of files in the <title id="porting-pkgfiles">Changing the names of
<filename>pkg</filename> subdirectory</title> <filename>pkg-<replaceable>*</replaceable></filename> files</title>
<para>All the filenames in the <filename>pkg</filename> subdirectory <para>All the names of <filename>pkg-<replaceable>*</replaceable></filename> files
are defined using variables so you can change them in your are defined using variables so you can change them in your
<filename>Makefile</filename> if need be. This is especially useful <filename>Makefile</filename> if need be. This is especially useful
when you are sharing the same <filename>pkg</filename> subdirectory when you are sharing the same <filename>pkg-<replaceable>*</replaceable></filename> files
among several ports or have to write to one of the above files (see among several ports or have to write to one of the above files (see
<link linkend="porting-wrkdir">writing to places other than <link linkend="porting-wrkdir">writing to places other than
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write <makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg</filename> subdirectory).</para> directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para>
<para>Here is a list of variable names and their default <para>Here is a list of variable names and their default
values.</para> values. (<makevar>PKGDIR</makevar> defaults to
<makevar>${MASTERDIR}</makevar>.)</para>
<informaltable frame="none"> <informaltable frame="none">
<tgroup cols="2"> <tgroup cols="2">
@ -2172,37 +2192,37 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<tbody> <tbody>
<row> <row>
<entry><makevar>COMMENT</makevar></entry> <entry><makevar>COMMENT</makevar></entry>
<entry><literal>${PKGDIR}/COMMENT</literal></entry> <entry><literal>${PKGDIR}/pkg-comment</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>DESCR</makevar></entry> <entry><makevar>DESCR</makevar></entry>
<entry><literal>${PKGDIR}/DESCR</literal></entry> <entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PLIST</makevar></entry> <entry><makevar>PLIST</makevar></entry>
<entry><literal>${PKGDIR}/PLIST</literal></entry> <entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGINSTALL</makevar></entry> <entry><makevar>PKGINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/INSTALL</literal></entry> <entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGDEINSTALL</makevar></entry> <entry><makevar>PKGDEINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/DEINSTALL</literal></entry> <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGREQ</makevar></entry> <entry><makevar>PKGREQ</makevar></entry>
<entry><literal>${PKGDIR}/REQ</literal></entry> <entry><literal>${PKGDIR}/pkg-req</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGMESSAGE</makevar></entry> <entry><makevar>PKGMESSAGE</makevar></entry>
<entry><literal>${PKGDIR}/MESSAGE</literal></entry> <entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -2383,8 +2403,9 @@ post-install:
place that is guaranteed to be writable during the port build (see place that is guaranteed to be writable during the port build (see
<ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an <ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an
example of building ports from a read-only tree). If you need to example of building ports from a read-only tree). If you need to
modify some file in <makevar>PKGDIR</makevar>, do so by <link modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
linkend="porting-pkgsubdir">redefining a variable</link>, not by files, do so by <link
linkend="porting-pkgfiles">redefining a variable</link>, not by
writing over it.</para> writing over it.</para>
</sect1> </sect1>
@ -3140,20 +3161,20 @@ post-install:
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
.endif</programlisting> .endif</programlisting>
<para>Do not forget to add them to <filename>pkg/PLIST</filename> too! <para>Do not forget to add them to <filename>pkg-plist</filename> too.
(Do not worry about <makevar>NOPORTDOCS</makevar> here; there is (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is
currently no way for the packages to read variables from currently no way for the packages to read variables from
<filename>/etc/make.conf</filename>.)</para> <filename>/etc/make.conf</filename>.)</para>
<para>You can also use the <filename>pkg/MESSAGE</filename> file to <para>You can also use the <filename>pkg-message</filename> file to
display messages upon installation. See the <link display messages upon installation. See the <link
linkend="porting-message">using linkend="porting-message">using
<filename>pkg/MESSAGE</filename></link> section for <filename>pkg-message</filename></link> section for
details.</para> details.</para>
<note> <note>
<para><filename>MESSAGE</filename> does not need to be added to <para><filename>pkg-message</filename> does not need to be added to
<filename>pkg/PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
</note> </note>
</sect1> </sect1>
@ -3190,8 +3211,8 @@ post-install:
<title>Package information</title> <title>Package information</title>
<para>Do include package information, i.e. <para>Do include package information, i.e.
<filename>COMMENT</filename>, <filename>DESCR</filename>, and <filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and
<filename>PLIST</filename>, in <filename>pkg</filename>.</para> <filename>pkg-plist</filename>.</para>
<note> <note>
<para>Note that these files are not used only for packaging anymore, <para>Note that these files are not used only for packaging anymore,
@ -3343,7 +3364,7 @@ lib/X11/oneko/sounds/cat.au
<title>UIDs</title> <title>UIDs</title>
<para>If your port requires a certain user to be on the installed <para>If your port requires a certain user to be on the installed
system, let the <filename>pkg/INSTALL</filename> script call system, let the <filename>pkg-install</filename> script call
<command>pw</command> to create it automatically. Look at <command>pw</command> to create it automatically. Look at
<filename>net/cvsup-mirror</filename> for an example.</para> <filename>net/cvsup-mirror</filename> for an example.</para>
@ -3429,7 +3450,7 @@ vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting>
<para>If your port requires some configuration files in <para>If your port requires some configuration files in
<filename><makevar>PREFIX</makevar>/etc</filename>, do <filename><makevar>PREFIX</makevar>/etc</filename>, do
<emphasis>not</emphasis> just install them and list them in <emphasis>not</emphasis> just install them and list them in
<filename>pkg/PLIST</filename>. That will cause <filename>pkg-plist</filename>. That will cause
<command>pkg_delete</command> to delete files carefully edited by <command>pkg_delete</command> to delete files carefully edited by
the user and a new installation to wipe them out.</para> the user and a new installation to wipe them out.</para>
@ -3470,8 +3491,8 @@ vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting>
<sect1> <sect1>
<title>Miscellanea</title> <title>Miscellanea</title>
<para>The files <filename>pkg/DESCR</filename>, <para>The files <filename>pkg-comment</filename>,
<filename>pkg/COMMENT</filename>, and <filename>pkg/PLIST</filename> <filename>pkg-descr</filename>, and <filename>pkg-plist</filename>
should each be double-checked. If you are reviewing a port and feel should each be double-checked. If you are reviewing a port and feel
they can be worded better, do so.</para> they can be worded better, do so.</para>
@ -3600,10 +3621,10 @@ pre-install:
<title>Automated package list creation</title> <title>Automated package list creation</title>
<para>First, make sure your port is almost complete, with only <para>First, make sure your port is almost complete, with only
<filename>PLIST</filename> missing. Create an empty <filename>pkg-plist</filename> missing. Create an empty
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<screen>&prompt.root; <userinput>touch PLIST</userinput></screen> <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen>
<para>Next, create a new set of directories which your port can be <para>Next, create a new set of directories which your port can be
installed, and install any dependencies.</para> installed, and install any dependencies.</para>
@ -3619,12 +3640,12 @@ pre-install:
you can then install the port and create the package list.</para> you can then install the port and create the package list.</para>
<screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput> <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput>
&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) &gt; pkg/PLIST</userinput></screen> &prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) &gt; pkg-plist</userinput></screen>
<para>You must also add any newly created directories to the packing <para>You must also add any newly created directories to the packing
list.</para> list.</para>
<screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' &gt;&gt; pkg/PLIST</replaceable></userinput></screen> <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' &gt;&gt; pkg-plist</replaceable></userinput></screen>
<para>Finally, you need to tidy up the packing list by hand. I lied <para>Finally, you need to tidy up the packing list by hand. I lied
when I said this was all automated. Manual pages should be listed in when I said this was all automated. Manual pages should be listed in
@ -3677,15 +3698,11 @@ pre-install:
</listitem> </listitem>
<listitem> <listitem>
<para>The <filename>name</filename> part should be all lowercase, <para>The first letter of <filename>name</filename> part
except for a really large package (with lots of programs in it). should be lowercase. (The rest of the name can contain
Things like XFree86 (yes there really is a port of it, check it capital letters, so use your own descretion when you are
out) and ImageMagick fall into this category. Otherwise, convert converting a software name that has some capital letters in it.)
the name (or at least the first letter) to lowercase. If the There is a tradition of naming Perl 5 modules by
capital letters are important to the name (for example, with
one-letter names like <literal>R</literal> or
<literal>V</literal>) you may use capital letters at your
discretion. There is a tradition of naming Perl 5 modules by
prepending <literal>p5-</literal> and converting the double-colon prepending <literal>p5-</literal> and converting the double-colon
separator to a hyphen; for example, the separator to a hyphen; for example, the
<literal>Data::Dumper</literal> module becomes <literal>Data::Dumper</literal> module becomes

303
en_US.ISO_8859-1/books/porters-handbook/book.sgml
View file

@ -1,7 +1,7 @@
<!-- <!--
The FreeBSD Documentation Project The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.130 2000/09/29 01:02:30 marko Exp $ $FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.131 2000/10/03 22:29:31 bmah Exp $
--> -->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
@ -123,14 +123,16 @@ USE_IMAKE= yes
<sect1> <sect1>
<title>Writing the description files</title> <title>Writing the description files</title>
<para>There are three description files that are required for any <para>There are three description files that are required for
port, whether they actually package or not. They are any port, whether they actually package or not. They are
<filename>COMMENT</filename>, <filename>DESCR</filename>, and <filename>pkg-comment</filename>,
<filename>PLIST</filename>, and reside in the <filename>pkg-descr</filename>, and
<filename>pkg</filename> subdirectory.</para> <filename>pkg-plist</filename>, and their
<filename>pkg-</filename> prefix distinguishes them from
other files.</para>
<sect2> <sect2>
<title><filename>COMMENT</filename></title> <title><filename>pkg-comment</filename></title>
<para>This is the one-line description of the port. <para>This is the one-line description of the port.
<emphasis>Please</emphasis> do not include the package name (or <emphasis>Please</emphasis> do not include the package name (or
@ -143,7 +145,7 @@ A cat chasing a mouse all over the screen</programlisting>
</sect2> </sect2>
<sect2> <sect2>
<title><filename>DESCR</filename></title> <title><filename>pkg-descr</filename></title>
<para>This is a longer description of the port. One to a few <para>This is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is paragraphs concisely explaining what the port does is
@ -152,8 +154,8 @@ A cat chasing a mouse all over the screen</programlisting>
<note> <note>
<para>This is <emphasis>not</emphasis> a manual or an in-depth <para>This is <emphasis>not</emphasis> a manual or an in-depth
description on how to use or compile the port! <emphasis>Please description on how to use or compile the port! <emphasis>Please
be careful if you are copying from the be careful if you are copying from the
<filename>README</filename> or manpage</emphasis>; too often <filename>README</filename> or manpage</emphasis>; too often
they are not a concise description of the port or are in an they are not a concise description of the port or are in an
awkward format (e.g., manpages have justified spacing). If the awkward format (e.g., manpages have justified spacing). If the
ported software has an official WWW homepage, you should list it ported software has an official WWW homepage, you should list it
@ -178,7 +180,7 @@ asami@cs.berkeley.edu</programlisting>
</sect2> </sect2>
<sect2> <sect2>
<title><filename>PLIST</filename></title> <title><filename>pkg-plist</filename></title>
<para>This file lists all the files installed by the port. It is <para>This file lists all the files installed by the port. It is
also called the &ldquo;packing list&rdquo; because the package is also called the &ldquo;packing list&rdquo; because the package is
@ -226,7 +228,7 @@ lib/X11/oneko/mouse.xpm
<para>Just type <command>make makesum</command>. The ports make rules <para>Just type <command>make makesum</command>. The ports make rules
will automatically generate the file will automatically generate the file
<filename>files/md5</filename>.</para> <filename>distinfo</filename>.</para>
</sect1> </sect1>
<sect1 id="porting-testing"> <sect1 id="porting-testing">
@ -238,12 +240,12 @@ lib/X11/oneko/mouse.xpm
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><filename>PLIST</filename> does not contain anything not <para><filename>pkg-plist</filename> does not contain anything not
installed by your port</para> installed by your port</para>
</listitem> </listitem>
<listitem> <listitem>
<para><filename>PLIST</filename> contains everything that is <para><filename>pkg-plist</filename> contains everything that is
installed by your port</para> installed by your port</para>
</listitem> </listitem>
@ -421,9 +423,10 @@ lib/X11/oneko/mouse.xpm
<step> <step>
<para>The <maketarget>patch</maketarget> target is run. First, <para>The <maketarget>patch</maketarget> target is run. First,
any patches defined in <makevar>PATCHFILES</makevar> are any patches defined in <makevar>PATCHFILES</makevar> are
applied. Second, if any patches are found in applied. Second, if any patch files named
<filename>patch-<replaceable>*</replaceable></filename> are found in
<makevar>PATCHDIR</makevar> (defaults to the <makevar>PATCHDIR</makevar> (defaults to the
<filename>patches</filename> subdirectory), they are applied at <filename>files</filename> subdirectory), they are applied at
this time in alphabetical order.</para> this time in alphabetical order.</para>
</step> </step>
@ -585,11 +588,14 @@ lib/X11/oneko/mouse.xpm
changed can be picked up with a recursive diff for later feeding to changed can be picked up with a recursive diff for later feeding to
patch. Each set of patches you wish to apply should be collected patch. Each set of patches you wish to apply should be collected
into a file named into a file named
<filename>patch-<replaceable>xx</replaceable></filename> where <filename>patch-<replaceable>*</replaceable></filename> where
<replaceable>xx</replaceable> denotes the sequence in which the <replaceable>*</replaceable> denotes the sequence in which the
patches will be applied &mdash; these are done in patches will be applied &mdash; these are done in
<emphasis>alphabetical order</emphasis>, thus <literal>aa</literal> <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal>
first, <literal>ab</literal> second and so on. These files should first, <literal>ab</literal> second and so on. If you wish,
you can use names that indicate the pathnames of the files that
are patched, such as <filename>patch-Imakefile</filename> or
<filename>patch-src-config.h</filename>. These files should
be stored in <makevar>PATCHDIR</makevar>, from where they will be be stored in <makevar>PATCHDIR</makevar>, from where they will be
automatically applied. All patches should be relative to automatically applied. All patches should be relative to
<makevar>WRKSRC</makevar> (generally the directory your port's <makevar>WRKSRC</makevar> (generally the directory your port's
@ -723,10 +729,10 @@ lib/X11/oneko/mouse.xpm
<listitem> <listitem>
<para>Silent changes to the port distfile which have <para>Silent changes to the port distfile which have
significant functional differences, i.e. changes to significant functional differences, i.e. changes to
the distfile requiring a correction to files/md5 with the distfile requiring a correction to
no corresponding change to <filename>distinfo</filename> with no corresponding change to
<makevar>PORTVERSION</makevar>, where a <command>diff <makevar>PORTVERSION</makevar>, where a <command>diff
-ru</command> of the old and new versions shows -ru</command> of the old and new versions shows
non-trivial changes to the code.</para> non-trivial changes to the code.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -882,13 +888,15 @@ PORTEPOCH= 1</programlisting>
<para><makevar>PKGNAME</makevar> becomes <para><makevar>PKGNAME</makevar> becomes
<literal>gtkmumble-0.3,1</literal></para> <literal>gtkmumble-0.3,1</literal></para>
<para>Note that if <makevar>PORTEPOCH</makevar> were reset <note>
to <literal>0</literal> with this upgrade, someone who had <para>If <makevar>PORTEPOCH</makevar> were reset
installed the gtkmumble-0.10_1 package would not detect to <literal>0</literal> with this upgrade, someone who had
the gtkmumble-0.3 package as newer, since installed the gtkmumble-0.10_1 package would not detect
<literal>3</literal> is still numerically less than the gtkmumble-0.3 package as newer, since
<literal>10</literal>.</para> <literal>3</literal> is still numerically less than
</sect2> <literal>10</literal>.</para>
</note>
</sect2>
</sect1> </sect1>
<sect1> <sect1>
@ -927,9 +935,20 @@ PORTEPOCH= 1</programlisting>
subdirectory named <makevar>WRKSRC</makevar>, which defaults subdirectory named <makevar>WRKSRC</makevar>, which defaults
to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para> to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
<para>Note that <makevar>PKGNAMEPREFIX</makevar> and <note>
<makevar>PKGNAMESUFFIX</makevar> do not affect <para><makevar>PKGNAMEPREFIX</makevar> and
<makevar>DISTNAME</makevar>.</para> <makevar>PKGNAMESUFFIX</makevar> do not affect
<makevar>DISTNAME</makevar>. Also note that when
<makevar>WRKSRC</makevar> is equal to
<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
while the original source archive is named something other than
<makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>,
you should probably leave <makevar>DISTNAME</makevar>
alone&mdash; you are better off defining
<makevar>DISTFILES</makevar> than having to set both
<makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
(and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
</note>
</sect1> </sect1>
<sect1> <sect1>
@ -957,12 +976,6 @@ PORTEPOCH= 1</programlisting>
all the existing ones, you can even create a new category name. In all the existing ones, you can even create a new category name. In
that case, please send mail to the &a.ports; to propose a new that case, please send mail to the &a.ports; to propose a new
category.</para> category.</para>
<note>
<para>There is no error checking for category names. <command>make
package</command> will happily create a new directory if you
mistype the category name, so be careful!</para>
</note>
</sect1> </sect1>
<sect1> <sect1>
@ -983,14 +996,13 @@ PORTEPOCH= 1</programlisting>
for automatically determining the closest master site and fetching for automatically determining the closest master site and fetching
from there!</para> from there!</para>
<para>If the original tarball is part of one of the following popular <para>If the original tarball is part of one of the popular
archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you archives such as X-contrib, GNU, or Perl CPAN, you may be able
refer to those sites in an easy compact form using refer to those sites in an easy compact form using
<makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
<makevar>MASTER_SITE_GNU</makevar>, (e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and
<makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set
<makevar>MASTER_SITE_TEX_CTAN</makevar>, and <makevar>MASTER_SITES</makevar> to one of these variables and
<makevar>MASTER_SITE_SUNSITE</makevar>. Simply set
<makevar>MASTER_SITE_SUBDIR</makevar> to the path within the <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the
archive. Here is an example:</para> archive. Here is an example:</para>
@ -998,6 +1010,11 @@ PORTEPOCH= 1</programlisting>
MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications</programlisting> MASTER_SITE_SUBDIR= applications</programlisting>
<para>These variables are defined in
<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
new archives added all the time, so make sure to check the
latest version of this file before submitting a port.</para>
<para>The user can also set the <makevar>MASTER_SITE_*</makevar> <para>The user can also set the <makevar>MASTER_SITE_*</makevar>
variables in <filename>/etc/make.conf</filename> to override our variables in <filename>/etc/make.conf</filename> to override our
choices, and use their favorite mirrors of these popular archives choices, and use their favorite mirrors of these popular archives
@ -1029,11 +1046,12 @@ MASTER_SITE_SUBDIR= applications</programlisting>
<makevar>PATCHFILES</makevar>. If that is the case, add the name <makevar>PATCHFILES</makevar>. If that is the case, add the name
and the location of the patch tarball to and the location of the patch tarball to
<makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>. <makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>.
Then, from the <maketarget>pre-patch</maketarget> target, apply the Then, use the <makevar>EXTRA_PATCHES</makevar> variable to
patch either by running the patch command from there, or copying the point to those files and <filename>bsd.port.mk</filename>
patch file into the <makevar>PATCHDIR</makevar> directory and will automatically apply them for you. In particular, do
calling it <emphasis>not</emphasis> copy patch files into the
<filename>patch-<replaceable>xx</replaceable></filename>.</para> <makevar>PATCHDIR</makevar> directory&mdash;that directory may
not be writable.</para>
<note> <note>
<para>Note that the tarball will have been extracted alongside the <para>Note that the tarball will have been extracted alongside the
@ -1234,8 +1252,8 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
define the variable <makevar>NOCLEANDEPENDS</makevar> in your define the variable <makevar>NOCLEANDEPENDS</makevar> in your
environment.</para> environment.</para>
<para>To depend on another port unconditionally, it is customary to <para>To depend on another port unconditionally, use the
use the string <literal>nonexistent</literal> as the first field variable <makevar>${NONEXISTENT}</makevar> as the first field
of <makevar>BUILD_DEPENDS</makevar> or of <makevar>BUILD_DEPENDS</makevar> or
<makevar>RUN_DEPENDS</makevar>. Use this only when you need to <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
the to get to the source of the other port. You can often save the to get to the source of the other port. You can often save
@ -1243,7 +1261,7 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
instance instance
<programlisting> <programlisting>
BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting> BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
will always descend to the JPEG port and extract it.</para> will always descend to the JPEG port and extract it.</para>
@ -1320,7 +1338,7 @@ BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
facilitate addition of an appropriate facilitate addition of an appropriate
<literal>@exec /sbin/ldconfig -m</literal> and <literal>@exec /sbin/ldconfig -m</literal> and
<literal>@unexec /sbin/ldconfig -R</literal> pair into your <literal>@unexec /sbin/ldconfig -R</literal> pair into your
<filename>pkg/PLIST</filename> file, so that a user who installed <filename>pkg-plist</filename> file, so that a user who installed
the package can start using the shared library immediately and the package can start using the shared library immediately and
deinstallation will not cause the system to still believe the deinstallation will not cause the system to still believe the
library is there.</para> library is there.</para>
@ -1340,7 +1358,7 @@ INSTALLS_SHLIB= yes
LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting> LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
<para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed <para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed
through &man.sed.1; just like the rest of <filename>pkg/PLIST</filename>, through &man.sed.1; just like the rest of <filename>pkg-plist</filename>,
so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is
recommended that you use <literal>%%PREFIX%%</literal> for recommended that you use <literal>%%PREFIX%%</literal> for
<makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for
@ -1463,7 +1481,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<filename>libfoo.so</filename> to <filename>libfoo.so</filename> to
<filename>libfoo.so.<replaceable>N</replaceable></filename> to make <filename>libfoo.so.<replaceable>N</replaceable></filename> to make
ELF linkers happy. Since it should be listed in ELF linkers happy. Since it should be listed in
<filename>PLIST</filename> too, and it won't hurt in the a.out case <filename>pkg-plist</filename> too, and it won't hurt in the a.out case
(some ports even require the link for dynamic loading), you should (some ports even require the link for dynamic loading), you should
just make this link regardless of the setting of just make this link regardless of the setting of
<makevar>PORTOBJFORMAT</makevar>.</para> <makevar>PORTOBJFORMAT</makevar>.</para>
@ -1480,9 +1498,9 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
</sect1> </sect1>
<sect1> <sect1>
<title><filename>PLIST</filename></title> <title><filename>pkg-plist</filename></title>
<para><filename>PLIST</filename> should contain the short (ELF) shlib <para><filename>pkg-plist</filename> should contain the short (ELF) shlib
names if the a.out minor number is zero, and the long (a.out) names names if the a.out minor number is zero, and the long (a.out) names
otherwise. <filename>bsd.port.mk</filename> will automatically add otherwise. <filename>bsd.port.mk</filename> will automatically add
<literal>.0</literal> to the end of short shlib lines if <literal>.0</literal> to the end of short shlib lines if
@ -1496,7 +1514,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
system (for instance, ports that install compatibility libraries for system (for instance, ports that install compatibility libraries for
other operating systems), define the variable other operating systems), define the variable
<makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing
of <filename>PLIST</filename> mentioned in the previous of <filename>pkg-plist</filename> mentioned in the previous
paragraph.</para> paragraph.</para>
</sect1> </sect1>
@ -1509,7 +1527,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<programlisting> <programlisting>
${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> ${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
<para>In <filename>PLIST</filename> it should read;</para> <para>In <filename>pkg-plist</filename> it should read;</para>
<programlisting> <programlisting>
@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... @exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ...
@ -1574,8 +1592,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<filename>xdvi400/Makefile</filename> are similar). The <filename>xdvi400/Makefile</filename> are similar). The
<makevar>MASTERDIR</makevar> definition tells <makevar>MASTERDIR</makevar> definition tells
<filename>bsd.port.mk</filename> that the regular set of <filename>bsd.port.mk</filename> that the regular set of
subdirectories like <makevar>PATCHDIR</makevar> and subdirectories like <makevar>FILESDIR</makevar> and
<makevar>PKGDIR</makevar> are to be found under <makevar>SCRIPTDIR</makevar> are to be found under
<filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal>
line will override the <literal>RESOLUTION=300</literal> line in line will override the <literal>RESOLUTION=300</literal> line in
<filename>xdvi300/Makefile</filename> and the port will be built with <filename>xdvi300/Makefile</filename> and the port will be built with
@ -1622,9 +1640,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<title>Manpages</title> <title>Manpages</title>
<para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add
any manpages to <filename>pkg/PLIST</filename> (this means you must any manpages to <filename>pkg-plist</filename> (this means you must
<emphasis>not</emphasis> list manpages in the <emphasis>not</emphasis> list manpages in the
<filename>PLIST</filename>&mdash;see <link <filename>pkg-plist</filename>&mdash;see <link
linkend="porting-plist">generating PLIST</link> for more). It also linkend="porting-plist">generating PLIST</link> for more). It also
makes the install stage automatically compress or uncompress manpages makes the install stage automatically compress or uncompress manpages
depending on the setting of <makevar>NOMANCOMPRESS</makevar> in depending on the setting of <makevar>NOMANCOMPRESS</makevar> in
@ -1636,7 +1654,7 @@ MASTERDIR= ${.CURDIR}/../xdvi300
be destroyed and recreated by <filename>bsd.port.mk</filename> be destroyed and recreated by <filename>bsd.port.mk</filename>
to make sure it points to the correct file. Any manpages to make sure it points to the correct file. Any manpages
listed in MLINKS must not be listed in the listed in MLINKS must not be listed in the
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<para>To specify whether the manpages are compressed upon installation, <para>To specify whether the manpages are compressed upon installation,
use the <makevar>MANCOMPRESSED</makevar> variable. This variable can use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
@ -1845,12 +1863,12 @@ Options:
in <emphasis>three</emphasis> places in <emphasis>three</emphasis> places
(<filename>Makefile</filename> and (<filename>Makefile</filename> and
<literal>@exec</literal>/<literal>@unexec</literal> of <literal>@exec</literal>/<literal>@unexec</literal> of
<filename>PLIST</filename>; see below). However, if you have <filename>pkg-plist</filename>; see below). However, if you have
Japanese (or other multibyte encoding) info files, you will have Japanese (or other multibyte encoding) info files, you will have
to use the extra arguments to <command>install-info</command> to use the extra arguments to <command>install-info</command>
because <command>makeinfo</command> cannot handle those texinfo because <command>makeinfo</command> cannot handle those texinfo
sources. (See <filename>Makefile</filename> and sources. (See <filename>Makefile</filename> and
<filename>PLIST</filename> of <filename>japanese/skk</filename> <filename>pkg-plist</filename> of <filename>japanese/skk</filename>
for examples on how to do this).</para> for examples on how to do this).</para>
</step> </step>
@ -1930,19 +1948,19 @@ Options:
<step> <step>
<para>(This step is only necessary if you are modifying an existing <para>(This step is only necessary if you are modifying an existing
port.) Take a look at <filename>pkg/PLIST</filename> and delete port.) Take a look at <filename>pkg-plist</filename> and delete
anything that is trying to patch up <filename>info/dir</filename>. anything that is trying to patch up <filename>info/dir</filename>.
They may be in <filename>pkg/INSTALL</filename> or some other They may be in <filename>pkg-install</filename> or some other
file, so search extensively.</para> file, so search extensively.</para>
<programlisting> <programlisting>
Index: pkg/PLIST Index: pkg-plist
=================================================================== ===================================================================
RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
retrieving revision 1.15 retrieving revision 1.15
diff -u -r1.15 PLIST diff -u -r1.15 pkg-plist
--- PLIST 1997/03/04 08:04:00 1.15 --- pkg-plist 1997/03/04 08:04:00 1.15
+++ PLIST 1997/04/15 06:32:12 +++ pkg-plist 1997/04/15 06:32:12
@@ -15,9 +15,6 @@ @@ -15,9 +15,6 @@
man/man1/emacs.1.gz man/man1/emacs.1.gz
man/man1/etags.1.gz man/man1/etags.1.gz
@ -1985,19 +2003,19 @@ diff -u -r1.26 Makefile
</step> </step>
<step> <step>
<para>Edit <filename>PLIST</filename> and add equivalent <para>Edit <filename>pkg-plist</filename> and add equivalent
<literal>@exec</literal> statements and also <literal>@exec</literal> statements and also
<literal>@unexec</literal> for <literal>@unexec</literal> for
<command>pkg_delete</command>.</para> <command>pkg_delete</command>.</para>
<programlisting> <programlisting>
Index: pkg/PLIST Index: pkg-plist
=================================================================== ===================================================================
RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
retrieving revision 1.15 retrieving revision 1.15
diff -u -r1.15 PLIST diff -u -r1.15 pkg-plist
--- PLIST 1997/03/04 08:04:00 1.15 --- pkg-plist 1997/03/04 08:04:00 1.15
+++ PLIST 1997/05/20 10:25:12 1.17 +++ pkg-plist 1997/05/20 10:25:12 1.17
@@ -16,7 +14,14 @@ @@ -16,7 +14,14 @@
man/man1/etags.1.gz man/man1/etags.1.gz
man/man1/ctags.1.gz man/man1/ctags.1.gz
@ -2034,24 +2052,24 @@ diff -u -r1.15 PLIST
</chapter> </chapter>
<chapter> <chapter>
<title>The <filename>pkg/</filename> subdirectory</title> <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title>
<para>There are some tricks we have not mentioned yet about the <para>There are some tricks we have not mentioned yet about the
<filename>pkg/</filename> subdirectory that come in handy <filename>pkg-<replaceable>*</replaceable></filename> files
sometimes.</para> that come in handy sometimes.</para>
<sect1 id="porting-message"> <sect1 id="porting-message">
<title><filename>MESSAGE</filename></title> <title><filename>pkg-message</filename></title>
<para>If you need to display a message to the installer, you may place <para>If you need to display a message to the installer, you may place
the message in <filename>pkg/MESSAGE</filename>. This capability is the message in <filename>pkg-message</filename>. This capability is
often useful to display additional installation steps to be taken often useful to display additional installation steps to be taken
after a <command>pkg_add</command> or to display licensing after a <command>pkg_add</command> or to display licensing
information.</para> information.</para>
<note> <note>
<para>The <filename>pkg/MESSAGE</filename> file does not need to be <para>The <filename>pkg-message</filename> file does not need to be
added to <filename>pkg/PLIST</filename>. Also, it will not get added to <filename>pkg-plist</filename>. Also, it will not get
automatically printed if the user is using the port, not the automatically printed if the user is using the port, not the
package, so you should probably display it from the package, so you should probably display it from the
<maketarget>post-install</maketarget> target yourself.</para> <maketarget>post-install</maketarget> target yourself.</para>
@ -2059,15 +2077,16 @@ diff -u -r1.15 PLIST
</sect1> </sect1>
<sect1> <sect1>
<title><filename>INSTALL</filename></title> <title><filename>pkg-install</filename></title>
<para>If your port needs to execute commands when the binary package <para>If your port needs to execute commands when the binary package
is installed with <command>pkg_add</command> you can do this via the is installed with <command>pkg_add</command> you can do this via the
<filename>pkg/INSTALL</filename> script. This script will <filename>pkg-install</filename> script. This script will
automatically be added to the package, and will be run twice by automatically be added to the package, and will be run twice by
<command>pkg_add</command>. The first time will as <literal>INSTALL <command>pkg_add</command>. The first time as
&dollar;{PKGNAME} PRE-INSTALL</literal> and the second time as <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
<literal>INSTALL &dollar;{PKGNAME} POST-INSTALL</literal>. 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 <literal>&dollar;2</literal> can be tested to determine which mode
the script is being run in. The <envar>PKG_PREFIX</envar> the script is being run in. The <envar>PKG_PREFIX</envar>
environmental variable will be set to the package installation environmental variable will be set to the package installation
@ -2083,23 +2102,23 @@ diff -u -r1.15 PLIST
</sect1> </sect1>
<sect1> <sect1>
<title><filename>REQ</filename></title> <title><filename>pkg-req</filename></title>
<para>If your port needs to determine if it should install or not, you <para>If your port needs to determine if it should install or not, you
can create a <filename>pkg/REQ</filename> &ldquo;requirements&rdquo; can create a <filename>pkg-req</filename> &ldquo;requirements&rdquo;
script. It will be invoked automatically at script. It will be invoked automatically at
installation/deinstallation time to determine whether or not installation/deinstallation time to determine whether or not
installation/deinstallation should proceed.</para> installation/deinstallation should proceed.</para>
</sect1> </sect1>
<sect1 id="porting-plist"> <sect1 id="porting-plist">
<title>Changing <filename>PLIST</filename> based on make <title>Changing <filename>pkg-plist</filename> based on make
variables</title> variables</title>
<para>Some ports, particularly the p5- ports, need to change their <para>Some ports, particularly the p5- ports, need to change their
<filename>PLIST</filename> depending on what options they are <filename>pkg-plist</filename> depending on what options they are
configured with (or version of perl, in the case of p5- ports). To configured with (or version of perl, in the case of p5- ports). To
make this easy, any instances in the <filename>PLIST</filename> of make this easy, any instances in the <filename>pkg-plist</filename> of
<literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
<literal>%%PERL_VERSION%%</literal> will be substituted for <literal>%%PERL_VERSION%%</literal> will be substituted for
appropriately. The value of <literal>%%OSREL%%</literal> is the appropriately. The value of <literal>%%OSREL%%</literal> is the
@ -2115,7 +2134,7 @@ diff -u -r1.15 PLIST
pairs and instances of pairs and instances of
<literal>%%<replaceable>VAR</replaceable>%%</literal>' will be <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
substituted with <replaceable>VALUE</replaceable> in the substituted with <replaceable>VALUE</replaceable> in the
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<para>For instance, if you have a port that installs many files in a <para>For instance, if you have a port that installs many files in a
version-specific subdirectory, you can put something like version-specific subdirectory, you can put something like
@ -2126,12 +2145,12 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
in the <filename>Makefile</filename> and use in the <filename>Makefile</filename> and use
<literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up
in <filename>PLIST</filename>. That way, when you upgrade the port, in <filename>pkg-plist</filename>. That way, when you upgrade the port,
you will not have to change dozens (or in some cases, hundreds) of you will not have to change dozens (or in some cases, hundreds) of
lines in the <filename>PLIST</filename>.</para> lines in the <filename>pkg-plist</filename>.</para>
<para>This substitution (as well as addition of any <link <para>This substitution (as well as addition of any <link
linkend="porting-manpages">man pages</link>) will be done between linkend="porting-manpages">man pages</link>) will be done between
the <maketarget>do-install</maketarget> and the <maketarget>do-install</maketarget> and
<maketarget>post-install</maketarget> targets, by reading from <maketarget>post-install</maketarget> targets, by reading from
<makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar> <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
@ -2145,20 +2164,21 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
</sect1> </sect1>
<sect1> <sect1>
<title id="porting-pkgsubdir">Changing the names of files in the <title id="porting-pkgfiles">Changing the names of
<filename>pkg</filename> subdirectory</title> <filename>pkg-<replaceable>*</replaceable></filename> files</title>
<para>All the filenames in the <filename>pkg</filename> subdirectory <para>All the names of <filename>pkg-<replaceable>*</replaceable></filename> files
are defined using variables so you can change them in your are defined using variables so you can change them in your
<filename>Makefile</filename> if need be. This is especially useful <filename>Makefile</filename> if need be. This is especially useful
when you are sharing the same <filename>pkg</filename> subdirectory when you are sharing the same <filename>pkg-<replaceable>*</replaceable></filename> files
among several ports or have to write to one of the above files (see among several ports or have to write to one of the above files (see
<link linkend="porting-wrkdir">writing to places other than <link linkend="porting-wrkdir">writing to places other than
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write <makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg</filename> subdirectory).</para> directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para>
<para>Here is a list of variable names and their default <para>Here is a list of variable names and their default
values.</para> values. (<makevar>PKGDIR</makevar> defaults to
<makevar>${MASTERDIR}</makevar>.)</para>
<informaltable frame="none"> <informaltable frame="none">
<tgroup cols="2"> <tgroup cols="2">
@ -2172,37 +2192,37 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<tbody> <tbody>
<row> <row>
<entry><makevar>COMMENT</makevar></entry> <entry><makevar>COMMENT</makevar></entry>
<entry><literal>${PKGDIR}/COMMENT</literal></entry> <entry><literal>${PKGDIR}/pkg-comment</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>DESCR</makevar></entry> <entry><makevar>DESCR</makevar></entry>
<entry><literal>${PKGDIR}/DESCR</literal></entry> <entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PLIST</makevar></entry> <entry><makevar>PLIST</makevar></entry>
<entry><literal>${PKGDIR}/PLIST</literal></entry> <entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGINSTALL</makevar></entry> <entry><makevar>PKGINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/INSTALL</literal></entry> <entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGDEINSTALL</makevar></entry> <entry><makevar>PKGDEINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/DEINSTALL</literal></entry> <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGREQ</makevar></entry> <entry><makevar>PKGREQ</makevar></entry>
<entry><literal>${PKGDIR}/REQ</literal></entry> <entry><literal>${PKGDIR}/pkg-req</literal></entry>
</row> </row>
<row> <row>
<entry><makevar>PKGMESSAGE</makevar></entry> <entry><makevar>PKGMESSAGE</makevar></entry>
<entry><literal>${PKGDIR}/MESSAGE</literal></entry> <entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -2383,8 +2403,9 @@ post-install:
place that is guaranteed to be writable during the port build (see place that is guaranteed to be writable during the port build (see
<ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an <ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an
example of building ports from a read-only tree). If you need to example of building ports from a read-only tree). If you need to
modify some file in <makevar>PKGDIR</makevar>, do so by <link modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
linkend="porting-pkgsubdir">redefining a variable</link>, not by files, do so by <link
linkend="porting-pkgfiles">redefining a variable</link>, not by
writing over it.</para> writing over it.</para>
</sect1> </sect1>
@ -3140,20 +3161,20 @@ post-install:
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
.endif</programlisting> .endif</programlisting>
<para>Do not forget to add them to <filename>pkg/PLIST</filename> too! <para>Do not forget to add them to <filename>pkg-plist</filename> too.
(Do not worry about <makevar>NOPORTDOCS</makevar> here; there is (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is
currently no way for the packages to read variables from currently no way for the packages to read variables from
<filename>/etc/make.conf</filename>.)</para> <filename>/etc/make.conf</filename>.)</para>
<para>You can also use the <filename>pkg/MESSAGE</filename> file to <para>You can also use the <filename>pkg-message</filename> file to
display messages upon installation. See the <link display messages upon installation. See the <link
linkend="porting-message">using linkend="porting-message">using
<filename>pkg/MESSAGE</filename></link> section for <filename>pkg-message</filename></link> section for
details.</para> details.</para>
<note> <note>
<para><filename>MESSAGE</filename> does not need to be added to <para><filename>pkg-message</filename> does not need to be added to
<filename>pkg/PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
</note> </note>
</sect1> </sect1>
@ -3190,8 +3211,8 @@ post-install:
<title>Package information</title> <title>Package information</title>
<para>Do include package information, i.e. <para>Do include package information, i.e.
<filename>COMMENT</filename>, <filename>DESCR</filename>, and <filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and
<filename>PLIST</filename>, in <filename>pkg</filename>.</para> <filename>pkg-plist</filename>.</para>
<note> <note>
<para>Note that these files are not used only for packaging anymore, <para>Note that these files are not used only for packaging anymore,
@ -3343,7 +3364,7 @@ lib/X11/oneko/sounds/cat.au
<title>UIDs</title> <title>UIDs</title>
<para>If your port requires a certain user to be on the installed <para>If your port requires a certain user to be on the installed
system, let the <filename>pkg/INSTALL</filename> script call system, let the <filename>pkg-install</filename> script call
<command>pw</command> to create it automatically. Look at <command>pw</command> to create it automatically. Look at
<filename>net/cvsup-mirror</filename> for an example.</para> <filename>net/cvsup-mirror</filename> for an example.</para>
@ -3429,7 +3450,7 @@ vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting>
<para>If your port requires some configuration files in <para>If your port requires some configuration files in
<filename><makevar>PREFIX</makevar>/etc</filename>, do <filename><makevar>PREFIX</makevar>/etc</filename>, do
<emphasis>not</emphasis> just install them and list them in <emphasis>not</emphasis> just install them and list them in
<filename>pkg/PLIST</filename>. That will cause <filename>pkg-plist</filename>. That will cause
<command>pkg_delete</command> to delete files carefully edited by <command>pkg_delete</command> to delete files carefully edited by
the user and a new installation to wipe them out.</para> the user and a new installation to wipe them out.</para>
@ -3470,8 +3491,8 @@ vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting>
<sect1> <sect1>
<title>Miscellanea</title> <title>Miscellanea</title>
<para>The files <filename>pkg/DESCR</filename>, <para>The files <filename>pkg-comment</filename>,
<filename>pkg/COMMENT</filename>, and <filename>pkg/PLIST</filename> <filename>pkg-descr</filename>, and <filename>pkg-plist</filename>
should each be double-checked. If you are reviewing a port and feel should each be double-checked. If you are reviewing a port and feel
they can be worded better, do so.</para> they can be worded better, do so.</para>
@ -3600,10 +3621,10 @@ pre-install:
<title>Automated package list creation</title> <title>Automated package list creation</title>
<para>First, make sure your port is almost complete, with only <para>First, make sure your port is almost complete, with only
<filename>PLIST</filename> missing. Create an empty <filename>pkg-plist</filename> missing. Create an empty
<filename>PLIST</filename>.</para> <filename>pkg-plist</filename>.</para>
<screen>&prompt.root; <userinput>touch PLIST</userinput></screen> <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen>
<para>Next, create a new set of directories which your port can be <para>Next, create a new set of directories which your port can be
installed, and install any dependencies.</para> installed, and install any dependencies.</para>
@ -3619,12 +3640,12 @@ pre-install:
you can then install the port and create the package list.</para> you can then install the port and create the package list.</para>
<screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput> <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput>
&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) &gt; pkg/PLIST</userinput></screen> &prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) &gt; pkg-plist</userinput></screen>
<para>You must also add any newly created directories to the packing <para>You must also add any newly created directories to the packing
list.</para> list.</para>
<screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' &gt;&gt; pkg/PLIST</replaceable></userinput></screen> <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' &gt;&gt; pkg-plist</replaceable></userinput></screen>
<para>Finally, you need to tidy up the packing list by hand. I lied <para>Finally, you need to tidy up the packing list by hand. I lied
when I said this was all automated. Manual pages should be listed in when I said this was all automated. Manual pages should be listed in
@ -3677,15 +3698,11 @@ pre-install:
</listitem> </listitem>
<listitem> <listitem>
<para>The <filename>name</filename> part should be all lowercase, <para>The first letter of <filename>name</filename> part
except for a really large package (with lots of programs in it). should be lowercase. (The rest of the name can contain
Things like XFree86 (yes there really is a port of it, check it capital letters, so use your own descretion when you are
out) and ImageMagick fall into this category. Otherwise, convert converting a software name that has some capital letters in it.)
the name (or at least the first letter) to lowercase. If the There is a tradition of naming Perl 5 modules by
capital letters are important to the name (for example, with
one-letter names like <literal>R</literal> or
<literal>V</literal>) you may use capital letters at your
discretion. There is a tradition of naming Perl 5 modules by
prepending <literal>p5-</literal> and converting the double-colon prepending <literal>p5-</literal> and converting the double-colon
separator to a hyphen; for example, the separator to a hyphen; for example, the
<literal>Data::Dumper</literal> module becomes <literal>Data::Dumper</literal> module becomes