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
$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" [
@ -123,14 +123,16 @@ USE_IMAKE= yes
<sect1>
<title>Writing the description files</title>
<para>There are three description files that are required for any
port, whether they actually package or not. They are
<filename>COMMENT</filename>, <filename>DESCR</filename>, and
<filename>PLIST</filename>, and reside in the
<filename>pkg</filename> subdirectory.</para>
<para>There are three description files that are required for
any port, whether they actually package or not. They are
<filename>pkg-comment</filename>,
<filename>pkg-descr</filename>, and
<filename>pkg-plist</filename>, and their
<filename>pkg-</filename> prefix distinguishes them from
other files.</para>
<sect2>
<title><filename>COMMENT</filename></title>
<title><filename>pkg-comment</filename></title>
<para>This is the one-line description of the port.
<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>
<title><filename>DESCR</filename></title>
<title><filename>pkg-descr</filename></title>
<para>This is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is
@ -152,8 +154,8 @@ A cat chasing a mouse all over the screen</programlisting>
<note>
<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
<filename>README</filename> or manpage</emphasis>; too often
be careful if you are copying from the
<filename>README</filename> or manpage</emphasis>; too often
they are not a concise description of the port or are in an
awkward format (e.g., manpages have justified spacing). If the
ported software has an official WWW homepage, you should list it
@ -178,7 +180,7 @@ asami@cs.berkeley.edu</programlisting>
</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
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
will automatically generate the file
<filename>files/md5</filename>.</para>
<filename>distinfo</filename>.</para>
</sect1>
<sect1 id="porting-testing">
@ -238,12 +240,12 @@ lib/X11/oneko/mouse.xpm
<itemizedlist>
<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>
</listitem>
<listitem>
<para><filename>PLIST</filename> contains everything that is
<para><filename>pkg-plist</filename> contains everything that is
installed by your port</para>
</listitem>
@ -421,9 +423,10 @@ lib/X11/oneko/mouse.xpm
<step>
<para>The <maketarget>patch</maketarget> target is run. First,
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
<filename>patches</filename> subdirectory), they are applied at
<filename>files</filename> subdirectory), they are applied at
this time in alphabetical order.</para>
</step>
@ -585,11 +588,14 @@ lib/X11/oneko/mouse.xpm
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
into a file named
<filename>patch-<replaceable>xx</replaceable></filename> where
<replaceable>xx</replaceable> denotes the sequence in which the
<filename>patch-<replaceable>*</replaceable></filename> where
<replaceable>*</replaceable> denotes the sequence in which the
patches will be applied &mdash; these are done in
<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
automatically applied. All patches should be relative to
<makevar>WRKSRC</makevar> (generally the directory your port's
@ -723,10 +729,10 @@ lib/X11/oneko/mouse.xpm
<listitem>
<para>Silent changes to the port distfile which have
significant functional differences, i.e. changes to
the distfile requiring a correction to files/md5 with
no corresponding change to
the distfile requiring a correction to
<filename>distinfo</filename> with no corresponding change to
<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>
</listitem>
</itemizedlist>
@ -882,13 +888,15 @@ PORTEPOCH= 1</programlisting>
<para><makevar>PKGNAME</makevar> becomes
<literal>gtkmumble-0.3,1</literal></para>
<para>Note that if <makevar>PORTEPOCH</makevar> were reset
to <literal>0</literal> with this upgrade, someone who had
installed the gtkmumble-0.10_1 package would not detect
the gtkmumble-0.3 package as newer, since
<literal>3</literal> is still numerically less than
<literal>10</literal>.</para>
</sect2>
<note>
<para>If <makevar>PORTEPOCH</makevar> were reset
to <literal>0</literal> with this upgrade, someone who had
installed the gtkmumble-0.10_1 package would not detect
the gtkmumble-0.3 package as newer, since
<literal>3</literal> is still numerically less than
<literal>10</literal>.</para>
</note>
</sect2>
</sect1>
<sect1>
@ -927,9 +935,20 @@ PORTEPOCH= 1</programlisting>
subdirectory named <makevar>WRKSRC</makevar>, which defaults
to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
<para>Note that <makevar>PKGNAMEPREFIX</makevar> and
<makevar>PKGNAMESUFFIX</makevar> do not affect
<makevar>DISTNAME</makevar>.</para>
<note>
<para><makevar>PKGNAMEPREFIX</makevar> and
<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>
@ -957,12 +976,6 @@ PORTEPOCH= 1</programlisting>
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
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>
@ -983,14 +996,13 @@ PORTEPOCH= 1</programlisting>
for automatically determining the closest master site and fetching
from there!</para>
<para>If the original tarball is part of one of the following popular
archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you
<para>If the original tarball is part of one of the popular
archives such as X-contrib, GNU, or Perl CPAN, you may be able
refer to those sites in an easy compact form using
<makevar>MASTER_SITE_XCONTRIB</makevar>,
<makevar>MASTER_SITE_GNU</makevar>,
<makevar>MASTER_SITE_PERL_CPAN</makevar>,
<makevar>MASTER_SITE_TEX_CTAN</makevar>, and
<makevar>MASTER_SITE_SUNSITE</makevar>. Simply set
<makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
(e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and
<makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set
<makevar>MASTER_SITES</makevar> to one of these variables and
<makevar>MASTER_SITE_SUBDIR</makevar> to the path within the
archive. Here is an example:</para>
@ -998,6 +1010,11 @@ PORTEPOCH= 1</programlisting>
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
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>
variables in <filename>/etc/make.conf</filename> to override our
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
and the location of the patch tarball to
<makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>.
Then, from the <maketarget>pre-patch</maketarget> target, apply the
patch either by running the patch command from there, or copying the
patch file into the <makevar>PATCHDIR</makevar> directory and
calling it
<filename>patch-<replaceable>xx</replaceable></filename>.</para>
Then, use the <makevar>EXTRA_PATCHES</makevar> variable to
point to those files and <filename>bsd.port.mk</filename>
will automatically apply them for you. In particular, do
<emphasis>not</emphasis> copy patch files into the
<makevar>PATCHDIR</makevar> directory&mdash;that directory may
not be writable.</para>
<note>
<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
environment.</para>
<para>To depend on another port unconditionally, it is customary to
use the string <literal>nonexistent</literal> as the first field
<para>To depend on another port unconditionally, use the
variable <makevar>${NONEXISTENT}</makevar> as the first field
of <makevar>BUILD_DEPENDS</makevar> or
<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
@ -1243,7 +1261,7 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
instance
<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>
@ -1320,7 +1338,7 @@ BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
facilitate addition of an appropriate
<literal>@exec /sbin/ldconfig -m</literal> and
<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
deinstallation will not cause the system to still believe the
library is there.</para>
@ -1340,7 +1358,7 @@ INSTALLS_SHLIB= yes
LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
<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
recommended that you use <literal>%%PREFIX%%</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.<replaceable>N</replaceable></filename> to make
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
just make this link regardless of the setting of
<makevar>PORTOBJFORMAT</makevar>.</para>
@ -1480,9 +1498,9 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
</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
otherwise. <filename>bsd.port.mk</filename> will automatically add
<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
other operating systems), define the variable
<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>
</sect1>
@ -1509,7 +1527,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<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>
@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ...
@ -1574,8 +1592,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<filename>xdvi400/Makefile</filename> are similar). The
<makevar>MASTERDIR</makevar> definition tells
<filename>bsd.port.mk</filename> that the regular set of
subdirectories like <makevar>PATCHDIR</makevar> and
<makevar>PKGDIR</makevar> are to be found under
subdirectories like <makevar>FILESDIR</makevar> and
<makevar>SCRIPTDIR</makevar> are to be found under
<filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal>
line will override the <literal>RESOLUTION=300</literal> line in
<filename>xdvi300/Makefile</filename> and the port will be built with
@ -1622,9 +1640,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<title>Manpages</title>
<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
<filename>PLIST</filename>&mdash;see <link
<filename>pkg-plist</filename>&mdash;see <link
linkend="porting-plist">generating PLIST</link> for more). It also
makes the install stage automatically compress or uncompress manpages
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>
to make sure it points to the correct file. Any manpages
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,
use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
@ -1845,12 +1863,12 @@ Options:
in <emphasis>three</emphasis> places
(<filename>Makefile</filename> and
<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
to use the extra arguments to <command>install-info</command>
because <command>makeinfo</command> cannot handle those texinfo
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>
</step>
@ -1930,19 +1948,19 @@ Options:
<step>
<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>.
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>
<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
diff -u -r1.15 PLIST
--- PLIST 1997/03/04 08:04:00 1.15
+++ PLIST 1997/04/15 06:32:12
diff -u -r1.15 pkg-plist
--- pkg-plist 1997/03/04 08:04:00 1.15
+++ pkg-plist 1997/04/15 06:32:12
@@ -15,9 +15,6 @@
man/man1/emacs.1.gz
man/man1/etags.1.gz
@ -1985,19 +2003,19 @@ diff -u -r1.26 Makefile
</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>@unexec</literal> for
<command>pkg_delete</command>.</para>
<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
diff -u -r1.15 PLIST
--- PLIST 1997/03/04 08:04:00 1.15
+++ PLIST 1997/05/20 10:25:12 1.17
diff -u -r1.15 pkg-plist
--- pkg-plist 1997/03/04 08:04:00 1.15
+++ pkg-plist 1997/05/20 10:25:12 1.17
@@ -16,7 +14,14 @@
man/man1/etags.1.gz
man/man1/ctags.1.gz
@ -2034,24 +2052,24 @@ diff -u -r1.15 PLIST
</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
<filename>pkg/</filename> subdirectory that come in handy
sometimes.</para>
<filename>pkg-<replaceable>*</replaceable></filename> files
that come in handy sometimes.</para>
<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
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
after a <command>pkg_add</command> or to display licensing
information.</para>
<note>
<para>The <filename>pkg/MESSAGE</filename> file does not need to be
added to <filename>pkg/PLIST</filename>. Also, it will not get
<para>The <filename>pkg-message</filename> file does not need to be
added to <filename>pkg-plist</filename>. Also, it will not get
automatically printed if the user is using the port, not the
package, so you should probably display it from the
<maketarget>post-install</maketarget> target yourself.</para>
@ -2059,15 +2077,16 @@ diff -u -r1.15 PLIST
</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
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
<command>pkg_add</command>. The first time will as <literal>INSTALL
&dollar;{PKGNAME} PRE-INSTALL</literal> and the second time as
<literal>INSTALL &dollar;{PKGNAME} POST-INSTALL</literal>.
<command>pkg_add</command>. The first 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
@ -2083,23 +2102,23 @@ diff -u -r1.15 PLIST
</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
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
installation/deinstallation time to determine whether or not
installation/deinstallation should proceed.</para>
</sect1>
<sect1 id="porting-plist">
<title>Changing <filename>PLIST</filename> based on make
<title>Changing <filename>pkg-plist</filename> based on make
variables</title>
<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
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>%%PERL_VERSION%%</literal> will be substituted for
appropriately. The value of <literal>%%OSREL%%</literal> is the
@ -2115,7 +2134,7 @@ diff -u -r1.15 PLIST
pairs and instances of
<literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
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
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
<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
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
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
<maketarget>post-install</maketarget> targets, by reading from
<makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
@ -2145,20 +2164,21 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
</sect1>
<sect1>
<title id="porting-pkgsubdir">Changing the names of files in the
<filename>pkg</filename> subdirectory</title>
<title id="porting-pkgfiles">Changing the names of
<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
<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
<link linkend="porting-wrkdir">writing to places other than
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg</filename> subdirectory).</para>
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para>
<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">
<tgroup cols="2">
@ -2172,37 +2192,37 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<tbody>
<row>
<entry><makevar>COMMENT</makevar></entry>
<entry><literal>${PKGDIR}/COMMENT</literal></entry>
<entry><literal>${PKGDIR}/pkg-comment</literal></entry>
</row>
<row>
<entry><makevar>DESCR</makevar></entry>
<entry><literal>${PKGDIR}/DESCR</literal></entry>
<entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row>
<row>
<entry><makevar>PLIST</makevar></entry>
<entry><literal>${PKGDIR}/PLIST</literal></entry>
<entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row>
<row>
<entry><makevar>PKGINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/INSTALL</literal></entry>
<entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row>
<row>
<entry><makevar>PKGDEINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/DEINSTALL</literal></entry>
<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row>
<row>
<entry><makevar>PKGREQ</makevar></entry>
<entry><literal>${PKGDIR}/REQ</literal></entry>
<entry><literal>${PKGDIR}/pkg-req</literal></entry>
</row>
<row>
<entry><makevar>PKGMESSAGE</makevar></entry>
<entry><literal>${PKGDIR}/MESSAGE</literal></entry>
<entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row>
</tbody>
</tgroup>
@ -2383,8 +2403,9 @@ post-install:
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
example of building ports from a read-only tree). If you need to
modify some file in <makevar>PKGDIR</makevar>, do so by <link
linkend="porting-pkgsubdir">redefining a variable</link>, not by
modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
files, do so by <link
linkend="porting-pkgfiles">redefining a variable</link>, not by
writing over it.</para>
</sect1>
@ -3140,20 +3161,20 @@ post-install:
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
.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
currently no way for the packages to read variables from
<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
linkend="porting-message">using
<filename>pkg/MESSAGE</filename></link> section for
linkend="porting-message">using
<filename>pkg-message</filename></link> section for
details.</para>
<note>
<para><filename>MESSAGE</filename> does not need to be added to
<filename>pkg/PLIST</filename>.</para>
<para><filename>pkg-message</filename> does not need to be added to
<filename>pkg-plist</filename>.</para>
</note>
</sect1>
@ -3190,8 +3211,8 @@ post-install:
<title>Package information</title>
<para>Do include package information, i.e.
<filename>COMMENT</filename>, <filename>DESCR</filename>, and
<filename>PLIST</filename>, in <filename>pkg</filename>.</para>
<filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and
<filename>pkg-plist</filename>.</para>
<note>
<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>
<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
<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
<filename><makevar>PREFIX</makevar>/etc</filename>, do
<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
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>
<title>Miscellanea</title>
<para>The files <filename>pkg/DESCR</filename>,
<filename>pkg/COMMENT</filename>, and <filename>pkg/PLIST</filename>
<para>The files <filename>pkg-comment</filename>,
<filename>pkg-descr</filename>, and <filename>pkg-plist</filename>
should each be double-checked. If you are reviewing a port and feel
they can be worded better, do so.</para>
@ -3600,10 +3621,10 @@ pre-install:
<title>Automated package list creation</title>
<para>First, make sure your port is almost complete, with only
<filename>PLIST</filename> missing. Create an empty
<filename>PLIST</filename>.</para>
<filename>pkg-plist</filename> missing. Create an empty
<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
installed, and install any dependencies.</para>
@ -3619,12 +3640,12 @@ pre-install:
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>
&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
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
when I said this was all automated. Manual pages should be listed in
@ -3677,15 +3698,11 @@ pre-install:
</listitem>
<listitem>
<para>The <filename>name</filename> part should be all lowercase,
except for a really large package (with lots of programs in it).
Things like XFree86 (yes there really is a port of it, check it
out) and ImageMagick fall into this category. Otherwise, convert
the name (or at least the first letter) to lowercase. If the
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
<para>The first letter of <filename>name</filename> part
should be lowercase. (The rest of the name can contain
capital letters, so use your own descretion when you are
converting a software name that has some capital letters in it.)
There is a tradition of naming Perl 5 modules by
prepending <literal>p5-</literal> and converting the double-colon
separator to a hyphen; for example, the
<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
$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" [
@ -123,14 +123,16 @@ USE_IMAKE= yes
<sect1>
<title>Writing the description files</title>
<para>There are three description files that are required for any
port, whether they actually package or not. They are
<filename>COMMENT</filename>, <filename>DESCR</filename>, and
<filename>PLIST</filename>, and reside in the
<filename>pkg</filename> subdirectory.</para>
<para>There are three description files that are required for
any port, whether they actually package or not. They are
<filename>pkg-comment</filename>,
<filename>pkg-descr</filename>, and
<filename>pkg-plist</filename>, and their
<filename>pkg-</filename> prefix distinguishes them from
other files.</para>
<sect2>
<title><filename>COMMENT</filename></title>
<title><filename>pkg-comment</filename></title>
<para>This is the one-line description of the port.
<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>
<title><filename>DESCR</filename></title>
<title><filename>pkg-descr</filename></title>
<para>This is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is
@ -152,8 +154,8 @@ A cat chasing a mouse all over the screen</programlisting>
<note>
<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
<filename>README</filename> or manpage</emphasis>; too often
be careful if you are copying from the
<filename>README</filename> or manpage</emphasis>; too often
they are not a concise description of the port or are in an
awkward format (e.g., manpages have justified spacing). If the
ported software has an official WWW homepage, you should list it
@ -178,7 +180,7 @@ asami@cs.berkeley.edu</programlisting>
</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
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
will automatically generate the file
<filename>files/md5</filename>.</para>
<filename>distinfo</filename>.</para>
</sect1>
<sect1 id="porting-testing">
@ -238,12 +240,12 @@ lib/X11/oneko/mouse.xpm
<itemizedlist>
<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>
</listitem>
<listitem>
<para><filename>PLIST</filename> contains everything that is
<para><filename>pkg-plist</filename> contains everything that is
installed by your port</para>
</listitem>
@ -421,9 +423,10 @@ lib/X11/oneko/mouse.xpm
<step>
<para>The <maketarget>patch</maketarget> target is run. First,
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
<filename>patches</filename> subdirectory), they are applied at
<filename>files</filename> subdirectory), they are applied at
this time in alphabetical order.</para>
</step>
@ -585,11 +588,14 @@ lib/X11/oneko/mouse.xpm
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
into a file named
<filename>patch-<replaceable>xx</replaceable></filename> where
<replaceable>xx</replaceable> denotes the sequence in which the
<filename>patch-<replaceable>*</replaceable></filename> where
<replaceable>*</replaceable> denotes the sequence in which the
patches will be applied &mdash; these are done in
<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
automatically applied. All patches should be relative to
<makevar>WRKSRC</makevar> (generally the directory your port's
@ -723,10 +729,10 @@ lib/X11/oneko/mouse.xpm
<listitem>
<para>Silent changes to the port distfile which have
significant functional differences, i.e. changes to
the distfile requiring a correction to files/md5 with
no corresponding change to
the distfile requiring a correction to
<filename>distinfo</filename> with no corresponding change to
<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>
</listitem>
</itemizedlist>
@ -882,13 +888,15 @@ PORTEPOCH= 1</programlisting>
<para><makevar>PKGNAME</makevar> becomes
<literal>gtkmumble-0.3,1</literal></para>
<para>Note that if <makevar>PORTEPOCH</makevar> were reset
to <literal>0</literal> with this upgrade, someone who had
installed the gtkmumble-0.10_1 package would not detect
the gtkmumble-0.3 package as newer, since
<literal>3</literal> is still numerically less than
<literal>10</literal>.</para>
</sect2>
<note>
<para>If <makevar>PORTEPOCH</makevar> were reset
to <literal>0</literal> with this upgrade, someone who had
installed the gtkmumble-0.10_1 package would not detect
the gtkmumble-0.3 package as newer, since
<literal>3</literal> is still numerically less than
<literal>10</literal>.</para>
</note>
</sect2>
</sect1>
<sect1>
@ -927,9 +935,20 @@ PORTEPOCH= 1</programlisting>
subdirectory named <makevar>WRKSRC</makevar>, which defaults
to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
<para>Note that <makevar>PKGNAMEPREFIX</makevar> and
<makevar>PKGNAMESUFFIX</makevar> do not affect
<makevar>DISTNAME</makevar>.</para>
<note>
<para><makevar>PKGNAMEPREFIX</makevar> and
<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>
@ -957,12 +976,6 @@ PORTEPOCH= 1</programlisting>
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
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>
@ -983,14 +996,13 @@ PORTEPOCH= 1</programlisting>
for automatically determining the closest master site and fetching
from there!</para>
<para>If the original tarball is part of one of the following popular
archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you
<para>If the original tarball is part of one of the popular
archives such as X-contrib, GNU, or Perl CPAN, you may be able
refer to those sites in an easy compact form using
<makevar>MASTER_SITE_XCONTRIB</makevar>,
<makevar>MASTER_SITE_GNU</makevar>,
<makevar>MASTER_SITE_PERL_CPAN</makevar>,
<makevar>MASTER_SITE_TEX_CTAN</makevar>, and
<makevar>MASTER_SITE_SUNSITE</makevar>. Simply set
<makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
(e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and
<makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set
<makevar>MASTER_SITES</makevar> to one of these variables and
<makevar>MASTER_SITE_SUBDIR</makevar> to the path within the
archive. Here is an example:</para>
@ -998,6 +1010,11 @@ PORTEPOCH= 1</programlisting>
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
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>
variables in <filename>/etc/make.conf</filename> to override our
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
and the location of the patch tarball to
<makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>.
Then, from the <maketarget>pre-patch</maketarget> target, apply the
patch either by running the patch command from there, or copying the
patch file into the <makevar>PATCHDIR</makevar> directory and
calling it
<filename>patch-<replaceable>xx</replaceable></filename>.</para>
Then, use the <makevar>EXTRA_PATCHES</makevar> variable to
point to those files and <filename>bsd.port.mk</filename>
will automatically apply them for you. In particular, do
<emphasis>not</emphasis> copy patch files into the
<makevar>PATCHDIR</makevar> directory&mdash;that directory may
not be writable.</para>
<note>
<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
environment.</para>
<para>To depend on another port unconditionally, it is customary to
use the string <literal>nonexistent</literal> as the first field
<para>To depend on another port unconditionally, use the
variable <makevar>${NONEXISTENT}</makevar> as the first field
of <makevar>BUILD_DEPENDS</makevar> or
<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
@ -1243,7 +1261,7 @@ RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
instance
<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>
@ -1320,7 +1338,7 @@ BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
facilitate addition of an appropriate
<literal>@exec /sbin/ldconfig -m</literal> and
<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
deinstallation will not cause the system to still believe the
library is there.</para>
@ -1340,7 +1358,7 @@ INSTALLS_SHLIB= yes
LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
<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
recommended that you use <literal>%%PREFIX%%</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.<replaceable>N</replaceable></filename> to make
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
just make this link regardless of the setting of
<makevar>PORTOBJFORMAT</makevar>.</para>
@ -1480,9 +1498,9 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
</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
otherwise. <filename>bsd.port.mk</filename> will automatically add
<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
other operating systems), define the variable
<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>
</sect1>
@ -1509,7 +1527,7 @@ PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</p
<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>
@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ...
@ -1574,8 +1592,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<filename>xdvi400/Makefile</filename> are similar). The
<makevar>MASTERDIR</makevar> definition tells
<filename>bsd.port.mk</filename> that the regular set of
subdirectories like <makevar>PATCHDIR</makevar> and
<makevar>PKGDIR</makevar> are to be found under
subdirectories like <makevar>FILESDIR</makevar> and
<makevar>SCRIPTDIR</makevar> are to be found under
<filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal>
line will override the <literal>RESOLUTION=300</literal> line in
<filename>xdvi300/Makefile</filename> and the port will be built with
@ -1622,9 +1640,9 @@ MASTERDIR= ${.CURDIR}/../xdvi300
<title>Manpages</title>
<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
<filename>PLIST</filename>&mdash;see <link
<filename>pkg-plist</filename>&mdash;see <link
linkend="porting-plist">generating PLIST</link> for more). It also
makes the install stage automatically compress or uncompress manpages
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>
to make sure it points to the correct file. Any manpages
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,
use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
@ -1845,12 +1863,12 @@ Options:
in <emphasis>three</emphasis> places
(<filename>Makefile</filename> and
<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
to use the extra arguments to <command>install-info</command>
because <command>makeinfo</command> cannot handle those texinfo
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>
</step>
@ -1930,19 +1948,19 @@ Options:
<step>
<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>.
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>
<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
diff -u -r1.15 PLIST
--- PLIST 1997/03/04 08:04:00 1.15
+++ PLIST 1997/04/15 06:32:12
diff -u -r1.15 pkg-plist
--- pkg-plist 1997/03/04 08:04:00 1.15
+++ pkg-plist 1997/04/15 06:32:12
@@ -15,9 +15,6 @@
man/man1/emacs.1.gz
man/man1/etags.1.gz
@ -1985,19 +2003,19 @@ diff -u -r1.26 Makefile
</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>@unexec</literal> for
<command>pkg_delete</command>.</para>
<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
diff -u -r1.15 PLIST
--- PLIST 1997/03/04 08:04:00 1.15
+++ PLIST 1997/05/20 10:25:12 1.17
diff -u -r1.15 pkg-plist
--- pkg-plist 1997/03/04 08:04:00 1.15
+++ pkg-plist 1997/05/20 10:25:12 1.17
@@ -16,7 +14,14 @@
man/man1/etags.1.gz
man/man1/ctags.1.gz
@ -2034,24 +2052,24 @@ diff -u -r1.15 PLIST
</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
<filename>pkg/</filename> subdirectory that come in handy
sometimes.</para>
<filename>pkg-<replaceable>*</replaceable></filename> files
that come in handy sometimes.</para>
<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
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
after a <command>pkg_add</command> or to display licensing
information.</para>
<note>
<para>The <filename>pkg/MESSAGE</filename> file does not need to be
added to <filename>pkg/PLIST</filename>. Also, it will not get
<para>The <filename>pkg-message</filename> file does not need to be
added to <filename>pkg-plist</filename>. Also, it will not get
automatically printed if the user is using the port, not the
package, so you should probably display it from the
<maketarget>post-install</maketarget> target yourself.</para>
@ -2059,15 +2077,16 @@ diff -u -r1.15 PLIST
</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
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
<command>pkg_add</command>. The first time will as <literal>INSTALL
&dollar;{PKGNAME} PRE-INSTALL</literal> and the second time as
<literal>INSTALL &dollar;{PKGNAME} POST-INSTALL</literal>.
<command>pkg_add</command>. The first 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
@ -2083,23 +2102,23 @@ diff -u -r1.15 PLIST
</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
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
installation/deinstallation time to determine whether or not
installation/deinstallation should proceed.</para>
</sect1>
<sect1 id="porting-plist">
<title>Changing <filename>PLIST</filename> based on make
<title>Changing <filename>pkg-plist</filename> based on make
variables</title>
<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
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>%%PERL_VERSION%%</literal> will be substituted for
appropriately. The value of <literal>%%OSREL%%</literal> is the
@ -2115,7 +2134,7 @@ diff -u -r1.15 PLIST
pairs and instances of
<literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
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
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
<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
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
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
<maketarget>post-install</maketarget> targets, by reading from
<makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
@ -2145,20 +2164,21 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
</sect1>
<sect1>
<title id="porting-pkgsubdir">Changing the names of files in the
<filename>pkg</filename> subdirectory</title>
<title id="porting-pkgfiles">Changing the names of
<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
<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
<link linkend="porting-wrkdir">writing to places other than
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg</filename> subdirectory).</para>
<makevar>WRKDIR</makevar></link> for why it is a bad idea to write
directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para>
<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">
<tgroup cols="2">
@ -2172,37 +2192,37 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<tbody>
<row>
<entry><makevar>COMMENT</makevar></entry>
<entry><literal>${PKGDIR}/COMMENT</literal></entry>
<entry><literal>${PKGDIR}/pkg-comment</literal></entry>
</row>
<row>
<entry><makevar>DESCR</makevar></entry>
<entry><literal>${PKGDIR}/DESCR</literal></entry>
<entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row>
<row>
<entry><makevar>PLIST</makevar></entry>
<entry><literal>${PKGDIR}/PLIST</literal></entry>
<entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row>
<row>
<entry><makevar>PKGINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/INSTALL</literal></entry>
<entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row>
<row>
<entry><makevar>PKGDEINSTALL</makevar></entry>
<entry><literal>${PKGDIR}/DEINSTALL</literal></entry>
<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row>
<row>
<entry><makevar>PKGREQ</makevar></entry>
<entry><literal>${PKGDIR}/REQ</literal></entry>
<entry><literal>${PKGDIR}/pkg-req</literal></entry>
</row>
<row>
<entry><makevar>PKGMESSAGE</makevar></entry>
<entry><literal>${PKGDIR}/MESSAGE</literal></entry>
<entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row>
</tbody>
</tgroup>
@ -2383,8 +2403,9 @@ post-install:
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
example of building ports from a read-only tree). If you need to
modify some file in <makevar>PKGDIR</makevar>, do so by <link
linkend="porting-pkgsubdir">redefining a variable</link>, not by
modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
files, do so by <link
linkend="porting-pkgfiles">redefining a variable</link>, not by
writing over it.</para>
</sect1>
@ -3140,20 +3161,20 @@ post-install:
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
.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
currently no way for the packages to read variables from
<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
linkend="porting-message">using
<filename>pkg/MESSAGE</filename></link> section for
linkend="porting-message">using
<filename>pkg-message</filename></link> section for
details.</para>
<note>
<para><filename>MESSAGE</filename> does not need to be added to
<filename>pkg/PLIST</filename>.</para>
<para><filename>pkg-message</filename> does not need to be added to
<filename>pkg-plist</filename>.</para>
</note>
</sect1>
@ -3190,8 +3211,8 @@ post-install:
<title>Package information</title>
<para>Do include package information, i.e.
<filename>COMMENT</filename>, <filename>DESCR</filename>, and
<filename>PLIST</filename>, in <filename>pkg</filename>.</para>
<filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and
<filename>pkg-plist</filename>.</para>
<note>
<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>
<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
<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
<filename><makevar>PREFIX</makevar>/etc</filename>, do
<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
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>
<title>Miscellanea</title>
<para>The files <filename>pkg/DESCR</filename>,
<filename>pkg/COMMENT</filename>, and <filename>pkg/PLIST</filename>
<para>The files <filename>pkg-comment</filename>,
<filename>pkg-descr</filename>, and <filename>pkg-plist</filename>
should each be double-checked. If you are reviewing a port and feel
they can be worded better, do so.</para>
@ -3600,10 +3621,10 @@ pre-install:
<title>Automated package list creation</title>
<para>First, make sure your port is almost complete, with only
<filename>PLIST</filename> missing. Create an empty
<filename>PLIST</filename>.</para>
<filename>pkg-plist</filename> missing. Create an empty
<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
installed, and install any dependencies.</para>
@ -3619,12 +3640,12 @@ pre-install:
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>
&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
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
when I said this was all automated. Manual pages should be listed in
@ -3677,15 +3698,11 @@ pre-install:
</listitem>
<listitem>
<para>The <filename>name</filename> part should be all lowercase,
except for a really large package (with lots of programs in it).
Things like XFree86 (yes there really is a port of it, check it
out) and ImageMagick fall into this category. Otherwise, convert
the name (or at least the first letter) to lowercase. If the
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
<para>The first letter of <filename>name</filename> part
should be lowercase. (The rest of the name can contain
capital letters, so use your own descretion when you are
converting a software name that has some capital letters in it.)
There is a tradition of naming Perl 5 modules by
prepending <literal>p5-</literal> and converting the double-colon
separator to a hyphen; for example, the
<literal>Data::Dumper</literal> module becomes