Index: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml (revision 45541) +++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml (revision 45542) @@ -1,195 +1,224 @@ Testing the Port Running <command>make describe</command> Several of the &os; port maintenance tools, such as &man.portupgrade.1;, rely on a database called /usr/ports/INDEX which keeps track of such items as port dependencies. INDEX is created by the top-level ports/Makefile via make index, which descends into each port subdirectory and executes make describe there. Thus, if make describe fails in any port, no one can generate INDEX, and many people will quickly become unhappy. It is important to be able to generate this file no matter what options are present in make.conf, so please avoid doing things such as using .error statements when (for instance) a dependency is not satisfied. (See .) 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. Also note that running a recent version of portlint (as specified in the next section) will cause make describe to be run automatically. 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 sufficient. Since portlint uses heuristics to try to figure out errors, it can produce false positive warnings. In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework. When in doubt, the best thing to do is ask on &a.ports;. Port Tools The ports-mgmt/porttools 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 <varname>PREFIX</varname> and <varname>DESTDIR</varname> 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 the complete alternative environment, usually a jail or an installed system mounted somewhere other than /. A port will actually install into 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. The value of PREFIX will be set to LOCALBASE (defaulting to /usr/local). If USE_LINUX_PREFIX is set, PREFIX will be LINUXBASE (defaulting to /compat/linux). 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 complain that it cannot find the files. 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}: -DPAGER=\"${LOCALBASE}/bin/less\" 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 not trivial. Visit the Tinderbox website for more details. Poudriere As a ports contributor, consider installing poudriere. It is a powerful system for building and testing ports. 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.