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 @@ <makevar>INSTALL_*</makevar> Macros Do 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