From owner-svn-doc-head@FreeBSD.ORG Tue Sep 2 09:48:26 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 4BE0C586; Tue, 2 Sep 2014 09:48:26 +0000 (UTC) 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)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 2B7961542; Tue, 2 Sep 2014 09:48:26 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s829mQSD027312; Tue, 2 Sep 2014 09:48:26 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s829mQE2027310; Tue, 2 Sep 2014 09:48:26 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201409020948.s829mQE2027310@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Tue, 2 Sep 2014 09:48:26 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45542 - head/en_US.ISO8859-1/books/porters-handbook/testing 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.18-1 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: Tue, 02 Sep 2014 09:48:26 -0000 Author: mat (ports committer) Date: Tue Sep 2 09:48:25 2014 New Revision: 45542 URL: http://svnweb.freebsd.org/changeset/doc/45542 Log: - Minor wording fixes. (igor -y) - Mention poudriere, and poudriere-devel. - Explain what the test build targets will do. Differential Revision: https://reviews.freebsd.org/D654 Reviewed by: wblock Sponsored by: Absolight Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Tue Sep 2 08:44:01 2014 (r45541) +++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Tue Sep 2 09:48:25 2014 (r45542) @@ -34,7 +34,7 @@ If make describe produces a string rather - than an error message, you are probably safe. See + than an error message, everything is probably safe. See bsd.port.mk for the meaning of the string produced. @@ -47,10 +47,10 @@ Portlint - Do check your work with Do check the port with portlint - before you submit or commit it. portlint - warns you about many common errors, both functional and + before submitting or committing it. portlint + warns about many common errors, both functional and stylistic. For a new (or repocopied) port, portlint -A is the most thorough; for an existing port, portlint -C is @@ -71,14 +71,14 @@ program is part of the Ports Collection. port is the front-end script, which can - help you simplify the testing job. Whenever you want to test a - new port or update an existing one, you can use - port test to test your port, including the + help simplify the testing job. Whenever a new port or an update + to an existing one needs testing, use + port test to test the port, including the portlint checking. This command also detects and lists any files that - are not listed in pkg-plist. See the - following example: + are not listed in pkg-plist. For + example: &prompt.root; port test /usr/ports/net/csup @@ -90,7 +90,7 @@ PREFIX determines where the port will be installed. It defaults to /usr/local, but can be set by the user to a custom path like - /opt. Your port must respect the value of + /opt. The port must respect the value of this variable. DESTDIR, if set by the user, determines @@ -100,7 +100,7 @@ DESTDIR/PREFIX, and register with the package database in DESTDIR/var/db/pkg. As DESTDIR is handled automatically by the ports - infrastructure with &man.chroot.8;, you do not need any + infrastructure with &man.chroot.8;. There is no need for modifications or any extra care to write DESTDIR-compliant ports. @@ -114,18 +114,18 @@ Avoiding hard-coded /usr/local paths in the source makes the port much more flexible and able to cater to the needs of other sites. Often, this can be accomplished by - simply replacing occurrences of /usr/local + replacing occurrences of /usr/local in the port's various Makefiles with ${PREFIX}. This variable is automatically passed down to every stage of the build and install processes. - Make sure your application is not installing things in + Make sure the application is not installing things in /usr/local instead of PREFIX. A quick test for such hard-coded paths is: - &prompt.root; make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` + &prompt.user; make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` If anything is installed outside of PREFIX, the package creation process will @@ -134,24 +134,39 @@ In addition, it is worth checking the same with the stage directory support (see ): - &prompt.root; make stage && make check-orphans && make package + &prompt.user; make stage && make check-plist && make stage-qa && make package + + + + check-plist checks for files + missing from the plist, and files in the plist that are not + installed by the port. + + + + stage-qa checks for common + problems like bad shebang, symlinks pointing outside the + stage directory, setuid files, and non-stripped + libraries... + + 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 - /var/tmp/`make -V PORTNAME` should be + /var/tmp/`make -V PORTNAME` must be tested for proper operation to make sure there are no problems with paths. - PREFIX should not be set explicitly in a + PREFIX must not be set explicitly in a port's Makefile. Users installing the port may have set PREFIX to a custom location, and - the port should respect that setting. + the port must respect that setting. Refer to programs and files from other ports with the variables mentioned above, not explicit pathnames. For - instance, if your port requires a macro PAGER + instance, if the port requires a macro PAGER to have the full pathname of less, do not use a literal path of /usr/local/bin/less. Instead, use ${LOCALBASE}: @@ -161,14 +176,23 @@ The path with LOCALBASE is more likely to still work if the system administrator has moved the whole /usr/local tree somewhere else. + + + All these tests are done automatically when running + poudriere testport or poudriere + bulk -t. It is highly recommended that every + ports contributor install it, and tests all his ports with it. + See for more + information. + Tinderbox - If you are an avid ports contributor, you might want to take + As an avid ports contributor, take a look at Tinderbox. It is a - powerful system for building and testing ports. You can install + powerful system for building and testing ports. Install Tinderbox using ports-mgmt/tinderbox port. Be sure to read supplied documentation since the configuration is @@ -188,6 +212,11 @@ Poudriere can be installed with ports-mgmt/poudriere. + There is also a ports-mgmt/poudriere-devel that often + has newer features that are mostly helpful when testing + ports. + Visit the Poudriere website for more details.