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.

To avoid duplication, subscribe to the ports@openbsd.org mailing list - somebody may be already working on the same port as you.
Create Makefile -- start with this skeleton makefile.
make fetch
This verifies that the master site, distname, and extract suffix are correct.
make makesum
This creates the files directory and the md5 checksum for the fetched files.
make extract
Ensures that the file can be extracted into the work directory. This also verifies that the checksum created in step 3 is good.
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.
- only patch one source file per patchfile, please
- use diff -u to generate patches
- all patches MUST be relative to ${WRKSRC}
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.
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 thay you may want to override can be changed by adding the --option flags to the CONFIGURE_ARGS parameter in the Makefile

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/, but NEVER replace existing files in /etc. Best to have install place in /usr/local/lib/ and then copy to /etc or /etc/ only 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/
   installed include files:		/usr/local/include or
					/usr/local/include/
   single-machine data:			/etc or /etc/
   local state:				/var/run
   GNU info files:			/usr/local/info
   man pages:				/usr/local/man/...
   read-only architecture-independent:	/usr/local/share/
   misc documentation:			/usr/local/share/doc/

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.
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.
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.
sudo make install
install the application.
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:
- 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. You'll have to add that by hand. 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.
Copy `PLIST-auto' to `PLIST'
uninstall and reinstall; repeat until perfect.
Perfect is when everything installs and uninstalls in its proper location. `pkg_delete ' 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.
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'.
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.
- First, get others to test it on a variety of platforms (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).
  The ports@openbsd mailing list is a good place to find porting-savy people with different platforms!
- 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.
- Finally, include it in the "ports" tree. 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 CVS_ROOT 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
$ 
		
```
  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.
  If you do not have CVS commit access, send mail to the ports maintainers at ports@openbsd.org, stating that you have a port ready to go into the tree. List the name and version of the program, the platforms it's been tested on, and any limitations.
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!

Skeleton ports makefile

;;; indicates values that must be supplied by the porter. Remove extraneous comments when done.

# $OpenBSD: checklist.html,v 1.7 1998/11/19 04:14:56 espie Exp $
#

# What port/package will be created
#
DISTNAME=		;;;
#DIST_SUBDIR=		;;;
#PKGNAME=		;;;
CATEGORIES=     	;;;

# Reasons why the port/package shouldn't be built
#
#COMES_WITH=		2.3
#ONLY_FOR_ARCHS=	list architectures here
#BROKEN=		"reason"
#RESTRICTED=		"reason"
#NO_CDROM=		"reason"
#NO_PACKAGE=		"reason"

# where to send bitches about this port
#
MAINTAINER=		ports@openbsd.org

# where the source files and patches can be fetched
#
MASTER_SITES=		;;;
#MASTER_SITE_SUBDIR=	;;;
#DISTFILES=		;;;
#PATCH_SITES=		;;;
#PATCHFILES=		;;;
#PATCH_DIST_STRIP=	-p0

# How to extract the sources
#
#EXTRACT_SUFX=		.tar.Z
#EXTRACT_CMD=		;;;
#EXTRACT_BEFORE_ARGS=	;;;
#EXTRACT_AFTER_ARGS=	;;;

# Dependencies
#
#FETCH_DEPENDS=		;;;
#BUILD_DEPENDS=		;;;
#RUN_DEPENDS=		;;;
#LIB_DEPENDS=		;;;

# Is the build automagic or is it interactive
#
#IS_INTERACTIVE=	yes

# build/configuration variables
#
#USE_GMAKE=		yes
#USE_IMAKE=		yes
#USE_X11=		yes (assumed if USE_IMAKE is yes)

#GNU_CONFIGURE=		yes
#HAS_CONFIGURE=		yes (assumed if GNU_CONFIGURE is yes)
#CONFIGURE_SCRIPT=	;;; (if other than configure)
#.if (${MACHINE_ARCH} != "alpha")
#CONFIGURE_ARGS+=	--enable-shared
#.endif
#CONFIGURE_ARGS+=	--enable-static
#CONFIGURE_ENV=		${SETENV}


# Things that we don't want to do for this port/package
#
#NO_DEPENDS=		yes
#NO_WRKDIR=		yes
#NO_WRKSUBDIR=		yes
#NO_CHECKSUM=		yes
#NO_EXTRACT=		yes
#NO_PATCH=		yes
#NO_CONFIGURE=		yes
#NO_BUILD=		yes
#NO_INSTALL=		yes
#NO_MTREE=		yes

# This section is only needed if man pages are distributed in compressed
# form.  Define MANCOMPRESSED and the man pages by section.  The pages
# will be uncompressed after being installed.
#
#MANCOMPRESSED=		yes
#MAN1=			;;;
#MAN3=			;;;
#MAN4=			;;;
#MAN5=			;;;
#MAN8=			;;;

# Overrides for default values
#
#MAKEFILE=		;;;
#MAKE_FLAGS=		;;;
#MAKE_ENV=		;;;
#SCRIPTS_ENV=		;;;
#LDFLAGS=		;;;
#WRKDIR=		;;; if other than work
#WRKSRC=		;;; if other than ${WRKDIR}/$DISTNAME

#ALL_TARGET=		;;;
#INSTALL_TARGET=	;;;

# This target may be necessary if a shared library may have been created
#
#post-install:
#	${LDCONFIG} -m ${PREFIX}/lib

.include <bsd.port.mk>

www@openbsd.org
$OpenBSD: checklist.html,v 1.7 1998/11/19 04:14:56 espie Exp $