OpenBSD Porting Checklist

1. If you want to be a maintainer, subscribe to ports@openbsd.org.
   • This is where all ports discussions take place.
   • Reading this list is important since many announcements go over this list.
   • You will find a lot of porting-savvy people here. They can often give you good advice or test ports for you.
   
   
2. Being a maintainer means more than just submitting ports. It also means trying to keep them up-to-date, and to answer questions about them.
   
3. Check out a copy of the ports tree from cvs. You can find instructions to do this at http://www.openbsd.org/anoncvs.html.
   
   
4. Pick a place to put your port and create the basic infrastructure there. Use the template Makefile at /usr/ports/infrastructure/templates/Makefile.template.
   NEED_VERSION relates to the version in the $OpenBSD tag of $(PORTSDIR)/infrastructure/mk/bsd.port.mk: e.g. $OpenBSD: bsd.port.mk,v 1.287 ... would get NEED_VERSION=1.287 in your Makefile. The fullproof and right way is to choose the most recent version you can find. As you are a port developer, you are supposed to update your ports, including bsd.port.mk.
   
   • Create the directories files, patches, pkg.
   • Create these empty files pkg/COMMENT, pkg/DESCR, pkg/PLIST
   
   
5. Add the fetch portions of the Makefile.
   • Fill in EXTRACT_SUFX if its anything besides .tar.gz. Other examples are .tar.Z, or .tgz.
   • Fill in DISTNAME which is the name of the file minus the extract suffix. E.g. if you have foo-1.0.tar.gz, DISTNAME is foo-1.0.
   • Fill in MASTER_SITES which is a URL to the directory where the distfile is kept. E.g. ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/ . Don't forget the trailing slash. Try to have at least three distinct sites as well. Place the most easily accessible first as they are traversed in order.
   • Keep in mind that fetch references the file as ${MASTER_SITE}${DISTNAME}${EXTRACT_SUFX}. All three are used. Don't set DISTNAME to point to the file directly.
   • You can check to see if you have filled this values in correctly by typing make fetch-all

   For more complex ports, you have more options and tools available to you:

   • You also have the variable PATCHFILES available. This is a list of vendor (not OpenBSD) patches to the port. Common uses are things like security or reliability fixes.
   • If your ports are available over large public mirrors such as GNU, SunSite, or CPAN, we have already provided a list of sites for your use in /usr/ports/infrastructure/template/network.conf.template. Set MASTER_SITES to ${MASTER_SITE_GNU}, or ${MASTER_SITE_SUNSITE}, etc. To simplify this process, the construct %SUBDIR% is replaced by the variable MASTER_SITE_SUBDIR in your Makefile.
   • Ports normally correspond to given versions of software. Once they are retrieved, files are checksummed and compared to the recorded checksum in files/md5. So, to avoid confusion, DISTFILES and PATCHFILES should have clearly visible version numbers: don't retrieve foo-latest.tar.gz if it is a link to foo-1.0.5.tar.gz. If necessary, gently ask the original program author to make such distinctions clear.
   • If a given port needs more than about 5 DISTFILES + PATCHFILES to work, use DIST_SUBDIR to avoid cluttering /usr/ports/distfiles too much.
   • DIST_SUBDIR must not include version numbers. When the port is updated to a later version, some distfiles may not change, but will be refetched if DIST_SUBDIR is changed. Even if all distfiles change, it is easier for the user to track cruft.
   • All DISTFILES and PATCHFILES don't necessarily come from the same set of MASTER_SITES. Supplementary sites can be defined using the variables MASTER_SITES0 to MASTER_SITES9. Just write DISTFILES=foo-1.0.5.tar.gz:5 to retrieve foo-1.0.5.tar.gz from MASTER_SITES5.
   • Some ports don't always need to retrieve all files in all circumstances. For instance, some ports may have some compilation options, and associated files which are only required in such a case. Or they may need some files for some architectures only. In such a case, those supplementary optional files must be mentioned in the SUPDISTFILES variable. Targets such as makesum or mirror-distfiles will fetch those supplementary files that the casual user doesn't need.
   
   
6. Create a checksum in files/md5 by typing make makesum. Then verify the checksum is correct by typing make checksum
   • In some rare cases, files checksums can't be verified reliably. By all means, porters should try to find sites that are reliable. Communicating with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be mentioned in the IGNOREFILES variable.
   • All files in DISTFILES are usually processed during make extract. EXTRACT_ONLY may be used to limit extraction to a subset of files (possibly empty). The customary use of this variable is to customize extraction: for instance, if some DISTFILES need some special treatment, they will be removed from EXTRACT_ONLY and handled manually at post-extract stage. For historic reasons, make extract does set up the working directory first along with extracting files. Thus, providing a pre-extract or a do-extract target is highly unusual (and fairly suspicious behavior, indicative of a high degree of obfuscation in the port).
   • Patches that need specific treatment should be mentioned in DISTFILES, and removed from EXTRACT_ONLY, for historic reasons.
   
   
7. Extract the port with make extract. Pay attention to where the base of the sources are. Usually, its work/DISTNAME You may need to modify the Makefile's WRKDIST variable if it is different.
   
   
8. Read the installation documentation and note what you have to do to build the port and any special options that might be needed.
   
   
9. Now is also a good time to figure out what kind of licensing restrictions apply to your port. Many are freely redistribution but then again, quite a few are not. We need four questions answered to distribute ports properly. These are the PERMIT_* values in the Makefile.
   • PERMIT_PACKAGE_CDROM tells us if we can put the package on the cdrom.
   • PERMIT_PACKAGE_FTP tells us if we can put the package on the ftp sites.
   • PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
   • PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.

   Set these values to Yes if it is permitted or to a comment string stating why it is not. Pay attention to any special conditions you may need to fulfill later on. E.g. some ports require to install a copy of the license. We recommend you place the license in /usr/local/share/DISTNAME/.
   
   

10. Add configuration options to Makefile and/or create the 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.
    • Use CONFIGURE_ARGS+= to append to the variable. CONFIGURE_ARGS= will overwrite it.
    
    
11. Try building the port with make build.
    • If you're lucky, the port will go all the way through without errors.
    • If it exits with an error, you will need to generate patches for your port. Figure out what needs to be changed and make patch for it.
    • Patches must be relative to ${WRKDIST}.
    • The easiest way to reset the port and test your patches is make clean patch. This will delete the work directory, re-extract, and patch your port.
    
    
12. Begin and cycle of make build, generate a patch (or use make update-patches), and make clean patch.
    • Patches go in the directory patches/ and should be named patch-* with * being something meaningful. We recommend you name your patches patch-FILENAME where FILENAME is the name of the file it is patching. (make update-patches does this automatically for you.)
    • Applying PATCHFILES is the first half of the make patch stage. It can be invoked separately as make distpatch, which is a convenient target for porters. Ignore this if you haven't set it.
    • Only patch one source file per patchfile, please,
    • Use diff -p -u to generate patches,
    • All patches MUST be relative to ${WRKDIST},
    • Check that patches DON'T contain tags that cvs will replace. If they do, your patches won't apply after you check them in. You can check in your changes with -kk to avoid this.
    • Add a small explanation of the patch role in the patchfile before the patch itself, and an OpenBSD CVS tag $OpenBSD$.
    • Please feed your patches back to the author of that piece of software.
    
    
13. 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.
    
    
14. Peruse the output (if any) and tweak any options in the Makefile. To repeat issue the command `make clean configure'.

    Note: make sure host dependent files go in /etc or /etc/<name>, but NEVER REPLACE OR MODIFY existing files in /etc. Best to have install place in /usr/local/share/<name> and then copy to /etc or /etc/<name> only if the files do not exist. If the files exist, display a message that says such-and-such files need to be modified. This also guarantees that the files will be included in the package since everything under /usr/local is included in the PLIST

    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>
    

15. 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.
    
    
16. 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.
    
    
17. Edit pkg/DESCR, pkg/COMMENT, pkg/PLIST.
    • 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 with an uppercase letter unless semantically significant, do NOT end with a period. DON'T EVER START WITH AN UNDETERMINATE ARTICLE SUCH AS `a' or `as', remove the article altogether.
    • 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.
    
    
18. Install the application with make install

    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.
    
    

19. 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.
    

20. Create pkg/PLIST. After the install is complete use the developer's command, make plist which makes 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:

    • list any files installed with `tar' as their timestamp will not change and thus won't be found by `find'
    • Update the info/dir file if .info files are added. Also, be sure that the info/dir is not part of the PLIST.
    • Try to do anything special with links or symbolic links. A cursory test of tar shows it does the right thing with links and symbolic links so I don't see why we need to special case anything in the packing list. But still...

    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.

    Move `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.
    • 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.
    
    
21. Keep repeating uninstall and reinstall 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.
    
    

22. Test the packaging:
    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'.
    
    
23. Mail ports@openbsd.org with a short note asking for comments and testing. Attach the port to this email and sent it out. If you don't get any comments, send email to turan@openbsd.org and I will pick it for you.

    Try to get others to test it on a variety of platforms for you.

    • The DEC Alpha is good because it has only static libraries and because sizeof(int) != sizeof(long)
    • Sun SPARC is good because it is very common and because its byte order is the reverse of i386; if you developed on SPARC, of course, you'd want it tested on i386).
    
    
24. Incorporate any feedback you get. Test it again on your platform. Get those who gave you feedback to test it again from your new port.
    
    
25. Finally, include it in the "ports" tree.

    If you do not have CVS access, ask someone on ports@openbsd.org to commit it. Don't forget about me, turan@openbsd.org if no one picks it up.
    
    

26. If you are a developer with CVS access, check it in. We normally use "import" for a new port, rather than adding a zillion (or a dozen) files individually. Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry about that! :-) If you make changes to a specific file (edit, then cvs commit), it will be 1.2, and that will be used.

    In short, import is typically used when a port is created. From that point on cvs add and cvs rm are typically used to add or remove files, and the normal edit->commit cycle for changes. You might use something like this:

    cd kaffe1
    make clean	# you really really don't want to check in all of work!
    cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
    	YourName YourName_YYYY-MMM-DD
    

    • -d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you have a CVSROOT environment variable defined.
    • -m 'kaffe port' is your login message. Change it to whatever you like
    • ports/lang/kaffe1 is the path relative to /cvs where the port lives
    • YourName (replaced with your login name) is the "vendor tag". You imported it so you are the vendor.
    • YourName_YYYY-MMM-DD (e.g., ian_2000-Jan-01) is the 'vendor release tag'. This is as good as any.
    As a real example, here is the output of checking in the Kaffe1 port, which one of us did on September 8, 1998:

    $ cd kaffe1
    $ make clean >/dev/null
    $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
    ian@cvs.openbsd.org's password: (not shown, obviously)
    I ports/lang/kaffe1/CVS
    I ports/lang/kaffe1/files/CVS
    I ports/lang/kaffe1/pkg/CVS
    N ports/lang/kaffe1/Makefile
    cvs server: Importing /cvs/ports/lang/kaffe1/files
    N ports/lang/kaffe1/files/md5
    cvs server: Importing /cvs/ports/lang/kaffe1/pkg
    N ports/lang/kaffe1/pkg/COMMENT
    N ports/lang/kaffe1/pkg/DESCR
    N ports/lang/kaffe1/pkg/PLIST
    
    No conflicts created by this import
    $ 
    

27. Last but not least, add a one-line entry for the new port in its parent directory's makefile, i.e., for ports/lang/kaffe1, add it to ports/lang/Makefile.
    
    
28. 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...
    
29. When updating a port, remember to handle dependencies! You shouldn't break any port that depends on yours. In case of problems, communicate with the maintainers of such ports. Likewise, be alert for dependency updates, and check that the maintainer did their job.