From owner-svn-doc-head@FreeBSD.ORG Wed Oct 30 20:15:06 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id C6C1782A; Wed, 30 Oct 2013 20:15:06 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id B27062025; Wed, 30 Oct 2013 20:15:06 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r9UKF6X5029094; Wed, 30 Oct 2013 20:15:06 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r9UKF6RD029093; Wed, 30 Oct 2013 20:15:06 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201310302015.r9UKF6RD029093@svn.freebsd.org> From: Warren Block Date: Wed, 30 Oct 2013 20:15:06 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43079 - head/en_US.ISO8859-1/books/porters-handbook X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 30 Oct 2013 20:15:07 -0000 Author: wblock Date: Wed Oct 30 20:15:06 2013 New Revision: 43079 URL: http://svnweb.freebsd.org/changeset/doc/43079 Log: Add an edited version of Gabor Pali 's contribution on port staging support. Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Wed Oct 30 19:42:08 2013 (r43078) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Wed Oct 30 20:15:06 2013 (r43079) @@ -271,6 +271,7 @@ lib/X11/oneko/mouse.xpm 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,22 +336,32 @@ PLIST_DIRS= lib/X11/oneko pkg-plist does not contain - anything not installed by your port + anything not installed by the port. pkg-plist contains everything - that is installed by your port + that is installed by the port. - Your port can be installed multiple times using the - reinstall target + The port can be installed using the + install target. This verifies + that the install script works correctly. - Your port cleans - up after itself upon deinstall + The port can be deinstalled properly using the + deinstall target. This verifies + that the deinstall script works correctly. + + + + Make sure that make package can be + run as a normal user (that is, not as + root). If that fails, + NEED_ROOT=yes must be added to the + port Makefile. @@ -358,20 +369,19 @@ PLIST_DIRS= lib/X11/onekoRecommended Test Ordering - make install + make stage - make package + make check-orphans - make deinstall + make package - pkg_add - package-name + make install @@ -379,32 +389,26 @@ PLIST_DIRS= lib/X11/oneko - make reinstall - + pkg_add package-name - - make package + Or, for users of pkg: + + 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 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. + Make certain no warnings are shown in any of + the stages. + + Thorough automated testing can be done with ports-mgmt/tinderbox or + ports-mgmt/poudriere from the Ports Collection. + These applications maintain + jails where all of the steps shown above + can be tested without affecting the state of the host system. @@ -572,11 +576,12 @@ PLIST_DIRS= lib/X11/oneko - 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. @@ -4979,10 +4984,18 @@ PORTVERSION= 1.0 <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. + Use the macros provided in + bsd.port.mk to ensure correct modes of + files in the port's *-install targets. + Set ownership directly in + pkg-plist with the corresponding + entries, such as @owner + owner and @group + group. These + operators work until being overridden, or until the end of + pkg-plist, so do not forget to reset them + after they are no longer needed. The default + ownership is root:wheel. @@ -5056,11 +5069,15 @@ PORTVERSION= 1.0 Installing a Whole Tree of Files - Sometimes, there is a need to install a big number of - files, preserving their hierarchical organization, i.e., + Sometimes, a large number of + files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from WRKSRC to a target directory under - PREFIX. + PREFIX. Note that + PREFIX, EXAMPLESDIR, + DATADIR, and other path varialbes must always be + prepended with STAGEDIR to respect + staging (see ). Two macros exist for this situation. The advantage of using these macros instead of cp is that @@ -5103,9 +5120,15 @@ PORTVERSION= 1.0 (cd ${WRKSRC}/examples && \ ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile") - Note that these macros does not add the installed files - to pkg-plist. You still need to list - them. + These macros do not add the installed files + to pkg-plist. They must be added manually. + For optional documentation + (PORTDOCS, see ) and examples + (PORTEXAMPLES), the + %%PORTDOCS%% or + %%PORTEXAMPLES%% prefixes must be + prepended in pkg-plist. @@ -5126,9 +5149,11 @@ PORTVERSION= 1.0 PKGNAME. Since only the files listed in - pkg-plist are installed it is safe to - always install documentation to - STAGEDIR. + pkg-plist are installed, it is safe to + always install documentation to STAGEDIR + (see ). Hence .if + blocks are only needed when the installed files are + large enough to cause significant I/O overhead. post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} @@ -5271,6 +5296,91 @@ PORTVERSION= 1.0 when you create a port. This section explains the most common of those. + + Staging + + bsd.port.mk expects ports to work with + a 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, making it + possible to build packages as an unprivileged user. With + staging, the port is built and installed into the stage + directory, STAGEDIR. A package is created + from the stage directory and then installed on the system. Automake tools refer 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, this + line must be added to the + Makefile: + + NEED_ROOT= yes + + Meta ports, or ports that do not install files themselves + but only depend on other ports, should avoid + needlessly extracting the &man.mtree.8; to the stage directory. + This is the basic directory layout + of the package, and these empty directories will be seens as + orphans. To prevent &man.mtree.8; extraction, add this line: + + NO_MTREE= yes + + Staging is enabled by prepending the + STAGEDIR variable to paths used in + the pre-install, + do-install, and + post-install targets (see the examples + through the book). Typically, this includes + PREFIX, ETCDIR, + DATADIR, EXAMPLESDIR, + MANPREFIX, DOCSDIR, and so on. + Directories should be created as part of the + post-install target. 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 + + The source path + ${PREFIX}/lib/libfoo.so.42 looks + fine but could, in fact, be incorrect. Absolute paths can + point to a wrong location, like when a remote + file system has been mounted with NFS under a non-root mount point. + Relative paths are less fragile, and often much shorter. + + Ports that install kernel modules must prepend the + STAGEDIR variable to + their default destination, /boot/modules. Then the + pre-install target can be used to handle + the creation of this directory: + + pre-install: + ${MKDIR} ${STAGEDIR}/boot/modules + + &man.kldxref.8; should not be run when installing to + the temporary staging directory. To prevent this, define + theNO_XREF variable and add it + to MAKE_ENV in the port's + Makefile: + + MAKE_ENV+= KMODDIR=/boot/modules NO_XREF=yes + The hints files for the kernel loader should + be regenerated only when the package is installed or + deinstalled. Do this by invoking &man.kldxref.8; from + pkg-plist: + + @unexec kldxref /boot/modules +@exec kldxref /boot/modules + + Shared Libraries @@ -6219,6 +6329,18 @@ PLIST_SUB+= NLS="@comment " 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 +7951,33 @@ _DOCSDIR= . A complete list of available variables can be found in /usr/ports/Mk/bsd.python.mk. + + Some 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, this 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. + -f 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. + + Python 2.7 or newer is required for this. It does not work + with Python 2.6. @@ -10236,10 +10385,9 @@ etc/orbit.conf.sample 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 +10773,12 @@ as .putsy.conf and edit it.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 worth checking the same with 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