[OpenBSD]

OpenBSD Porting Checklist

I use this checklist as a reminder of things to do when creating new ports and when validating old ports. I don't claim this list is totally accurate, much less perfect, but only hope that some find it useful. Direct any questions and/or comments to me at marc@snafu.org.

  1. To avoid duplication, subscribe to the ports@openbsd.org mailing list - somebody may be already working on the same port as you.

  2. Create Makefile -- start with the provided Makefile template /usr/ports/infrastructure/templates/Makefile.template. This file can be retrieved from any of the anoncvs servers or via the OpenBSD cvs/web source browser system http://www.openbsd.org/cgi-bin/cvsweb/.

  3. make fetch-all
    This verifies that the master site, distname, and extract suffix are correct. This should fetch all files needed for that port, not only those corresponding to current option or the current architecture.

  4. make makesum
    This creates the files directory and the md5 checksum for the fetched files.

  5. make extract
    Ensures that the file can be extracted into the work directory. This also verifies that the checksum created in step 4 is good.

  6. Create initial patches
    When the extract is complete cd to the work directory and read any install docs. You may need to modify the WRKSRC variable in the makefile as well as generate initial patches to configure for OpenBSD.

    Note: Patches go in the directory `patches' and are names patch-xx where xx should be aa, ab, ..., az, ba, bb ... zz.

  7. make patch
    this will apply patches to the extracted sources. If you want to see the output use the command:

    make PATCH_DEBUG=YES patch

    The easiest way to re-run patches is to `make clean && make patch'. This will delete the work directory and re-extract and patch.

  8. add configuration options to Makefile and/or create configuration script.
    You can add a port configuration script named `configure' to a directory named scripts. This will be run before any configuration specified by GNU_CONFIGURE or HAS_CONFIGURE is run.

    If GNU_CONFIGURE is used you may want to run ./configure --help to see what options are available. Anything that you may want to override can be changed by adding the --option flags to the CONFIGURE_ARGS parameter in the Makefile

  9. try setting SEPARATE_BUILD
    If the port can build with object files outside its source tree, this is cleaner (many programs using GNU_CONFIGURE can), and may help people who mount their ports tree on several arches. This can also spare you some effort, as you will possibly be able to restart the cycle at configure most of the time.

  10. make configure
    Peruse the output (if any) and tweak any options in the Makefile. To repeat issue the command `make clean && make configure'.

    Note: make sure host dependent files go in /etc or /etc/<name>, but NEVER replace existing files in /etc. Best to have install place in /usr/local/lib/<name> and then copy to /etc or /etc/<name> only if the files do not exist.

    The OpenBSD file locations are: 

       user executables:			/usr/local/bin
   system admin executables:		/usr/local/sbin
   program executables:			/usr/local/libexec
   libraries				/usr/local/lib
   architecture dependent data		/usr/local/lib/<name>
   installed include files:		/usr/local/include or
					/usr/local/include/<name>
   single-machine data:			/etc or /etc/<name>
   local state:				/var/run
   GNU info files:			/usr/local/info
   man pages:				/usr/local/man/...
   read-only architecture-independent:	/usr/local/share/<name>
   misc documentation:			/usr/local/share/doc/<name>

  11. make
    Begin a cycle of makes until the port is ready. Patch (see above) clean, and make until the port is generated. Get rid of all warnings if possible, especially security related warnings.

  12. Control SEPARATE_BUILD semantics
    You have to do this only if the port builds with SEPARATE_BUILD defined. Ideally, the port should no longer modify any file in ${WRKSRC} after make patch. You can check this by making sure you don't have any write access to ${WRKSRC}. Then you can set SEPARATE_BUILD=concurrent: someone can use the same source tree to build on distinct arches simultaneously. Otherwise, set SEPARATE_BUILD=simple: building on distinct arches simultaneously may meet with problems, as some source files may be regenerated at awkward moments.

  13. mkdir pkg; touch pkg/{DESCR,COMMENT,PLIST}
    Create dummy versions of the package files. Edit DESCR and COMMENT.

    COMMENT is a SHORT one-line description of the port (max. 60 characters). Do NOT include the package name (or version number of the software) in the comment. Do NOT start by an uppercase letter unless semantically significant, do NOT end by a dot.

    DESCR is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient.

    PLIST is kept empty at this point.

  14. sudo make install
    install the application.

  15. If the port installs dynamic libraries, check their symbol tables with nm, as some mistaken software strips dynamic libraries, which may lead to weird failures later.

  16. Check port for security holes again. This is especially important for network and setuid programs. See our security recommendations for that. Log interesting stuff and fixes in the pkg/SECURITY file. This file should list audited potential problems, along with relevant patches, so that another person can see at first glance what has been done. Example: 
     
      $OpenBSD$

      ${WRKDIR}/receiver.c
         call to mktemp (wrapper function do_mktemp) does seem to be correct.

      The server makes extensive use of strlcpy/strlcat/snprintf.
  17. Create pkg/PLIST
    After the install is complete use the developers command:

    make plist

    which makes a the file PLIST-auto in the pkg directory. This file is a candidate packing list. Beware: the files are found by timestamp. This means it does NOT:

    Peruse `PLIST-auto' and verify that everything was installed and that it was installed in the proper locations. Anything not installed can be added to a port Makefile `post-install' rule.

    Copy `PLIST-auto' to `PLIST'

    Ports that install shared libraries will need two versions of the PLIST file. PLIST describes the files installed on those architectures that support shared libraries, and PLIST.noshared describes the files installed on architectures that do not support shared libs. Typically, PLIST.noshared is a copy of PLIST less references to any shared libraries.

  18. uninstall and reinstall; repeat until perfect.
    Perfect is when everything installs and uninstalls in its proper location. `pkg_delete <pkg_name>' is used to uninstall. `sudo make reinstall' is used to reinstall. See the `pkg_create' man page for other commands that may be added to PLIST to ensure all is cleaned up. After an uninstall the command

    find /usr/local -newer work/.install_started -print

    should only list standard directory names.

  19. Create package:
    After the port installs correctly issue the command make package to create a package. To test the package first do a pkg_delete and then do a pkg_add The results after an add should EXACTLY match the results after a `make install'.

  20. Distribute it!
    Since the whole point of this process is to make your ported version of the software available to other OpenBSD users, you now need to disseminate it.

  21. Maintain the port!
    As time goes by, problems may arise, or new versions of the software may be released. You should strive to keep your port up to date. In other words - iterate, test, test, iterate, ...
Thank you for supporting the OpenBSD "ports" process!
Porting www@openbsd.org
$OpenBSD: checklist.html,v 1.16 1999/06/01 22:26:38 espie Exp $