Index: book.xml
===================================================================
--- book.xml (revision 43072)
+++ book.xml (working copy)
@@ -271,6 +271,7 @@
following lines to the Makefile:
PLIST_FILES= bin/oneko \
+ man/man1/oneko.1.gz \
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
@@ -335,23 +336,33 @@
pkg-plist does not contain
- anything not installed by your port
+ anything not installed by your port.
pkg-plist contains everything
- that is installed by your port
+ that is installed by your port.
- Your port can be installed multiple times using the
- reinstall target
+ The port can be installed using the
+ install target. This helps to
+ verify if the install script works fine.
- Your port cleans
- up after itself upon deinstall
+ The port can be deinstalled properly using the
+ deinstall target. This helps to
+ veryify if the deinstall script works fine.
+
+
+ Make sure that make package can be
+ run as a normal user (that is, not as
+ root). If that fails,
+ NEED_ROOT=yes has to be added to the
+ port's Makefile.
+
@@ -358,20 +369,19 @@
Recommended Test Ordering
- make install
+ make stage
- make package
+ make check-orphans
- make deinstall
+ make package
- pkg_add
- package-name
+ make install
@@ -379,32 +389,29 @@
- make reinstall
-
+ pkg_add package-name
-
- make package
+ Or, in case of pkgng:
+
+ pkg add package-name
- make readme
+ make package (as user)Make sure that there are not any warnings issued in any of
- the package and
- deinstall stages. After step 3,
- check to see if all the new directories are correctly deleted.
- Also, try using the software after step 4, to ensure that it
- works correctly when installed from a package.
+ the stages.
The most thorough way to automate these steps is via
- installing the ports tinderbox.
- This maintains jails in which you can
- test all of the above steps without changing the state of
- your running system. Please see
- ports/ports-mgmt/tinderbox for more
- information.
+ installing the tinderbox or
+ poudriere. These maintain
+ jails in which you can test all of the above
+ steps without changing the state of your running system. Please
+ see ports-mgmt/tinderbox or
+ ports-mgmt/poudriere in the Ports
+ Collection for more information.
@@ -572,11 +579,12 @@
- The stage target is run.
- This puts the final set of built files into a temporary
- directory (STAGEDIR). The hierarchy of
- this directory mirrors that of the system on which the
- package will be installed.
+ The stage target is run. This
+ puts the final set of built files into a temporary directory
+ (STAGEDIR, see ). The hierarchy of this directory
+ mirrors that of the system on which the package will be
+ installed.
@@ -4980,9 +4988,17 @@
INSTALL_* MacrosDo use the macros provided in
- bsd.port.mk to ensure correct modes and
- ownership of files in your own
- *-install targets.
+ bsd.port.mk to ensure correct modes of
+ files in your own *-install targets.
+ Ownership should be set directly in the
+ pkg-plist file with the corresponding
+ entries, such as @owner
+ owner and @group
+ group. Note that these
+ operators work until being overridden, or until the end of
+ pkg-plist, so do not forget to reset them
+ afterwards they are not needed any more. The default
+ ownership is root:wheel.
@@ -5060,7 +5076,11 @@
files, preserving their hierarchical organization, i.e.,
copying over a whole directory tree from
WRKSRC to a target directory under
- PREFIX.
+ PREFIX. Note that
+ PREFIX, EXAMPLESDIR,
+ DATADIR, and such have to be always
+ prepended with STAGEDIR in order to respect
+ staging (see ).
Two macros exist for this situation. The advantage of
using these macros instead of cp is that
@@ -5105,7 +5125,13 @@
Note that these macros does not add the installed files
to pkg-plist. You still need to list
- them.
+ them. For optional documentation
+ (PORTDOCS, see ) and examples
+ (PORTEXAMPLES), the
+ %%PORTDOCS%% or
+ %%PORTEXAMPLES%% prefixes have to be
+ prepended in pkg-plist.
@@ -5127,8 +5153,10 @@
Since only the files listed in
pkg-plist are installed it is safe to
- always install documentation to
- STAGEDIR.
+ always install documentation to STAGEDIR
+ (see ). Hence .if
+ blocks has to only be associated when the installed files are
+ large enough to cause significant I/O overhead.
post-install:
${MKDIR} ${STAGEDIR}${DOCSDIR}
@@ -5271,6 +5299,90 @@
when you create a port. This section explains the most common
of those.
+
+ Staging
+
+ bsd.port.mk expects ports to work with
+ a so-called stage directory. This means that a
+ port should not install files directly to the regular
+ destination directories (that is, under
+ PREFIX, for example) but instead into a
+ separate directory from which the package is then built. In
+ many cases, this does not require root privileges, therefore it
+ enables building packages as an unprivileged user. With
+ staging, the package is first built, installed into the stage
+ directory, referenced as STAGEDIR, packaged,
+ and then installed from the package. Automake tools refers to
+ this concept as DESTDIR, but in &os;,
+ DESTDIR has a different meaning (see ).
+
+ When a port still requires system-wide privileges in order
+ to run the package target, the
+ following line has to be added to its
+ Makefile:
+
+ NEED_ROOT= yes
+
+ For meta ports, add the following line, otherwise they would
+ needlessly extract the &man.mtree.8;, the basic directory layout
+ of the package, to the stage directory, and will be counted as
+ orphans. Meta ports are the ports that do not install files
+ themselves but depend on other ports, hence this
+ distinction.
+
+ NO_MTREE= yes
+
+ To enable staging for a port, the
+ STAGEDIR variable has to prepended before the
+ uses of PREFIX, ETCDIR,
+ DATADIR, EXAMPLESDIR,
+ MANPREFIX, DOCSDIR, etc.
+ at the pre-install,
+ do-install, and
+ post-install targets (see the examples
+ through the book). Directories should be created as part of the
+ post-install target. Try to avoid using
+ absolute paths whenever possible.
+
+ When creating a symlink, STAGEDIR should
+ be prepended to the target path only. For example:
+
+ ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so
+
+ Note that the source path,
+ ${PREFIX}/lib/libfoo.so.42, while looks
+ fine, could be in fact incorrect, since absolute paths can
+ potentially point to a wrong location, e.g. when remote
+ filesystem is mounted via NFS under a non-root mount point.
+ Relative paths are less fragile, and often much shorter.
+
+ For ports that install kernel modules, the
+ STAGEDIR variable has to be prepended to
+ their default destination, /boot/modules. Then the
+ pre-install target may be used to take
+ care of the creation of this directory:
+
+ pre-install:
+ ${MKDIR} ${STAGEDIR}/boot/modules
+
+ Furthermore, one should pay attention to disallow running
+ &man.kldxref.8; on install. This can be usually disabled via
+ defining the NO_XREF variable and adding it
+ to MAKE_ENV in the port's
+ Makefile.
+
+ MAKE_ENV+= KMODDIR=/boot/modules NO_XREF=yes
+ Instead, the hints files for the kernel loader should be
+ only generated when the package is installed or
+ deinstalled. This can be achieved by invoking &man.kldxref.8; in the
+ pkg-plist file.
+
+ @unexec kldxref /boot/modules
+@exec kldxref /boot/modules
+
+
Shared Libraries
@@ -6219,6 +6331,18 @@
p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee
+
+ For Perl ports that install manual pages, the macro
+ PERL5_MANx (where
+ x ranges from 1 to
+ 9) can be used inside
+ pkg-plist. For example
+
+ lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz
+
+ can be replaced with
+
+ %%PERL5_MAN3%%/AnyEvent::I3.3.gz
@@ -7829,6 +7953,33 @@
A complete list of available variables can be found in
/usr/ports/Mk/bsd.python.mk.
+
+ Note that some of the Python applications claim to have
+ DESTDIR support (which would be required for
+ staging) but it is broken (Mailman up to 2.1.16, for instance).
+ This can be worked around by recompiling the scripts. This can
+ be done, for example, in the post-build
+ target. Assuming the Python scripts are supposed to reside in
+ PYTHONPREFIX_SITELIBDIR after
+ installation, the following solution can be applied:
+
+ (cd ${STAGEDIR}${PREFIX} \
+ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \
+ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})
+
+
+ This recompiles the sources with a path relative to the
+ stage directory, and prepends the value of
+ PREFIX to the file name recorded in the
+ byte-compiled output file by -d. The
+ -f flag is required to force recompilation,
+ and the :S;${PREFIX}/;; strips prefixes from
+ the value of the PYTHONPREFIX_SITELIBDIR
+ variable to make it relative to
+ PREFIX.
+
+ This requires Python 2.7 or newer, and does not work
+ with Python 2.6.
@@ -10236,10 +10387,9 @@
which generate docs with
Javadoc).
- Maintainers who prefer dynamic package lists are
- encouraged to add a new target to their port which generates
- the pkg-plist file so that users may
- examine the contents.
+ Note that the makeplist target can
+ be used for ports that support staging to display the package
+ list.
@@ -10625,7 +10775,12 @@
PREFIX, the package creation process will
complain that it cannot find the files.
- This test will not find hard-coded paths inside the
+ In addition, it is worthwhile to check the same via the
+ stage directory support (see ):
+
+ &prompt.root; make stage && make check-orphans && make package
+
+ These tests will not find hard-coded paths inside the
port's files, nor will it verify that
LOCALBASE is being used to correctly refer
to files from other ports. The temporarily-installed port in