Ports - Testing Guide

• Introduction
• Testing
• Commenting
• More Testing

---

Introduction

The ports tree is a huge piece of work that permits OpenBSD users to use third party programs without wasting time patching, configuring and installing each one individually. This work is done by a group of volunteers who spend their time porting and testing applications across the range of OpenBSD platforms.

Many people think that they cannot help this process because they do not have enough knowledge, but this is wrong because they can help porters work better and faster. Test submitted updates or new ports which are posted on the ports mailing list. By doing this, you reduce the latency of commits and also increase the number of ports to be committed. Many ports are not committed because of lack of testing.

The ports tree is developed against -current; there is no guarantee that new ports or updates will work correctly on the other branches. This means you should upgrade your system and ports tree to -current. Instructions on how to do this can be found at the following current page. It is also recommended that you subscribe to the ports and ports-changes mailing lists. This way, you will be notified about new or updated ports and about changes in the ports tree.

Testing

There are two types of submissions on the mailing lists: new ports and updates. New ports are generally posted as tarball attachments or URLs. A good idea is to extract them into the /usr/ports/mystuff/ directory and test from there. Updates are generally a diff against the -current ports tree, so it is best to copy the port to mystuff/ and apply the diff to prevent tree breakage. If the previous version of the port is installed, it is a good idea to remove it before building the newer version to avoid side effects, like symbols missing from the older version of a library.

Step-by-step building is needed to verify that every target, see ports(7), is achieved correctly:

• fetch
  • Needed to verify that distfile(s) are correctly downloaded. Try to test all of the MASTER_SITES specified to make sure they are all valid sources.
• checksum
  • Verify that downloaded distfiles match the checksums recorded in the distinfo file. You can re-run make clean=dist && make makesum and verify that nothing changes.
• extract
  • The prepare target is automatically invoked before extract and should install all {BUILD,LIB}_DEPENDS for this port (such as bzip2).
• patch
  • Patches should apply cleanly without any warnings.
  • There shouldn't be any ".orig" files left behind in the patches/ directory.
  • Another common mistake is to include RCS tags in a patch; this may break when the port is checked into the repository and the RCS tag expanded.
• configure
  • Check that configure scripts correctly detect features on your platform.
  • The configure script should not detect stray applications already installed on your system without explicit dependencies being set in the port.
  • If the port does not build with the libtool from base, you can try setting USE_LIBTOOL=gnu which uses a patched version from ports. GNU libtool is notorious for undesired 'features' on OpenBSD, so if the port does not build with the libtool from base, that should be fixed and there should be a XXX comment about why in the ports Makefile.
  • If the port uses CMake and you see undesired results of configure stage, make sure to check or send the following files additionally:
    • ${WRKBUILD}/CMakeCache.txt
    • ${WRKBUILD}/CMakeFiles/CMakeError.log
    • ${WRKBUILD}/CMakeFiles/CMakeOutput.log
• build
  • Check for build errors and suspicious warnings.
  • Warnings about tmpnam(3) issues should be resolved by using mkstemp(3).
  • Try to set the SEPARATE_BUILD variable to 'Yes' and test if the build still works.
  • Make sure dependencies on GNU make are really necessary.
• test
  • Check for errors (empty tests means okay).
  • If the tests have dependencies other than specified in {BUILD,RUN}_DEPENDS, check that TEST_DEPENDS is defined correctly.
• fake
  • This target installs the application into a fake working directory, to ensure that all files can be easily packaged up without affecting the base system.
  • The port should never install files outside of the fake directory such as into /usr/local.
  • GNU libtool occasionally has trouble relinking libraries during the fake process on some architectures.
  • Check whether all files get installed with correct ownerships and permissions.
• port-lib-depends-check
  • This will check whether all libraries on which the port depends can be reached through either LIB_DEPENDS or WANTLIB. The result should be empty. The above variables should be inspected when you see lines starting "Extra" or "Missing."
• check-shlib-syms
  • This can be used during port updates to quickly identify some situations where a shared library changed such that a version number in SHARED_LIBS needs to be bumped. It requires a source tree checkout, normally in /usr/src, and you will need to reinstall the previous version of the port if it was removed during build. It compares shared libraries installed locally with those in the port's fake-install directory and shows differences in exported symbols.
• package
  • Package creation can break if pkg/PLIST* and/or pkg/PFRAG* are wrong.
• install
  • Packages should install all of the files from their packaging lists successfully and with the correct permissions. Be especially careful of files with the setuid bits set.
  • Make sure that the package INSTALL script works correctly, and does not overwrite any files in /etc.
• deinstall
  • This should remove all files installed by the package, except those in /etc.
  • System files created by the package at runtime should be marked with @extra and/or @extraunexec annotations in pkg/PLIST*.

Remaining pkg/ files like DESCR and MESSAGE should be checked for grammar and typos. Paragraphs should be formatted using fmt(1) and wrapped at 80 characters.

Commenting

At the end of the test comes the really important thing: comments. Even if the port is working fine, comments are required. If we have ten posts where people say that the port runs fine under different architectures then the commit is done faster. If it does not work, then some information must be given. There are tools that can help in this task, like portslogger(1) which is like an "intelligent tee" that redirects output into a log file.

Example:

# make install 2>&1 | /usr/ports/infrastructure/bin/portslogger .

This will redirect the output into a log file located in the current directory.

Finally, once the port is found to be okay, other ports depending on it should also be tested, to check whether they are still working correctly. The show-required-by make target will help to find other ports which depend on the current one.

More Testing

Check the port's Makefile for correct dependencies, typos, incorrect links, useless or missing variables, correct licensing and categories. Those who are more skilled can help by examining patches, as well as providing diffs to correct bugs, add flavors, or other enhancements.

These diffs should be done with the -uNprx CVS options. cvs diff -uNp can also be used to generate patches against the CVS repository.