OpenBSD Journal

How to Create an OpenBSD Port and Package

Contributed by johan on from the dirty-harry dept.

Clint Pachl writes in with this walk through on how to assemble your own port...

I've attempted to create a port several times in the past, but it looked like too much work, so I gave up. Today, I finally decided to bite the bullet. It was actually fairly simple. Below I show how to create an extremely minimal port. This could be used to package some common scripts you would like to effortlessly deploy on all of your machines. I assume the line "SUDO=/usr/bin/sudo" is in /etc/mk.conf and /usr/ports is writable by the regular user.

A great example of a simple port that consists of a shell script (and a man page) is sysutils/mergemaster.

First, create the actual data structure (i.e. distribution files) for the package. Then tar and compress the distribution into the distfiles directory, which will bypass the remote fetch during port make.


  $ mkdir -p ~/myscripts/myscripts-1.0
  $ cd ~/myscripts/myscripts-1.0
  $ mkdir -p bin share/myscripts
  $ echo 'Docs for myscripts.' > share/myscripts/README

  $ cat << EOF > bin/myscript1
  > #!/bin/sh
  > echo 'this is myscript1'
  > EOF

  $ cat << EOF > bin/myscript2
  > #!/bin/sh
  > echo 'this is myscript2'
  > EOF

  $ cd ..
  $ tar czf /usr/ports/distfiles/myscripts-1.0.tar.gz myscripts-1.0

Make a directory under which you can maintain your local ports.


  $ mkdir -p /usr/ports/mystuff/misc
  $ cd /usr/ports/mystuff/misc

Make a package directory that will resemble your package name.


  $ mkdir myscripts
  $ cd myscripts

Create the port's Makefile using the port system template. When finished, it should look similar to the following:


  $ cp /usr/ports/infrastructure/templates/Makefile.template Makefile
  $ vi Makefile
  $ cat Makefile

  # port/package comment, name, category, and maintainer.
  COMMENT=                extremely minimal porting example
  DISTNAME=               myscripts-1.0
  CATEGORIES=             misc
  MAINTAINER=             Clint Pachl <pachl@ecentryx.com>

  # Mandatory licensing variables.
  PERMIT_PACKAGE_CDROM=   NO
  PERMIT_PACKAGE_FTP=     NO
  PERMIT_DISTFILES_CDROM= NO
  PERMIT_DISTFILES_FTP=   NO

  # Don't build or run regress tests; specify all architectures.
  NO_BUILD=               Yes
  NO_REGRESS=             Yes
  PKG_ARCH=               *

  # Install myscripts under /usr/local/.
  do-install:
        ${INSTALL_SCRIPT} ${WRKSRC}/bin/* ${PREFIX}/bin/
        ${INSTALL_DATA_DIR} ${PREFIX}/share/myscripts/
        ${INSTALL_DATA} ${WRKSRC}/share/myscripts/* ${PREFIX}/share/myscripts/

  # Include the BSD port system.
  .include <bsd.port.mk>

Create the distinfo file, which contains hash digests of the distribution. At this point, try to fake install the port to make sure everything works. The fake target will fetch, verify checksum, extract, patch, configure, build, and fake install the distfile under the working directory.


  $ make makesum
  $ make fake

The description and packing list files are prerequisites to creating a package. The description file is a long description of the package, as opposed to the short comment in the port's Makefile. The plist target generates a default packing list derived from the fake install.


  $ mkdir pkg
  $ echo 'This is the myscripts package example.' > pkg/DESCR
  $ make plist

Finally, create the myscripts package under /usr/ports/packages. To install the package, run either make install or pkg_add(1). Test the install by verifying that the scripts are installed in your PATH and are executable.


  $ make package
  $ make install
  $ myscript1 && myscript2
  $ pkg_info myscripts
  $ sudo pkg_delete myscripts

For more info, check out ports(7); pay attention to the URLs and other man pages mentioned in the "SEE ALSO" section.

Thanks to Marc Espie and friends for a great porting/packaging system. And as always, if you make a port of something that you think may be useful to other OpenBSD users, please test it on current and submit it to ports@.

Editor's Note:

If you're going to submit your stuff to ports@, please make sure to first clean it up and then double check that everything is working correctly. All that is needed for a proper submission is a 'tar-ball' of the specific port directory that you are working on, specifically:


cd /usr/ports/mystuff/misc && make clean && tar -czvf ./myscripts.tgz ./myscripts

Keep in mind that messy or broken ports are going to be easily discarded so take your time and get it right the first time.

Thanks Clint for your great submission!Good luck and happy porting!

(Comments are closed)


Comments
  1. By jtorin (193.15.214.188) on

    Also see the excellent presentation given by Bernd Ahlers on OpenCON 2007.

  2. By Anonymous Coward (24.37.242.64) on

    Nice article! Great to see something like this. Good job!

    Thank you!

  3. By Anonymous Coward (2a01:348:108:155:20a:e4ff:fe2d:99ee) on

    Some more important resources are available on the web page, Building an OpenBSD port which has links to various other information.

    Also some more manual pages: bsd.port.mk(5), packages(7), OpenBSD::Intro(3p) (new in -current/4.3), pkg_create(1) and others. There have also been ports tutorials at various events, slides are available (linked from the events page).

    Some other things recommended for porters include adding -E to the SUDO= line, setup PLIST_DB in mk.conf to help make sure you don't forget to bump version numbers when you update things, and become familiar with the various tools, in particular "make update-patches", "make plist", "make port-lib-depends-check" are used very often.

  4. By Anonymous Coward (222.124.156.122) on

    Nice tutorial..

    Look like easy to make a ports on OpenBSD.

    Thanks

  5. By Anonymous Coward (208.176.170.170) on

    The hardest part about creating a port is converting all the
    linux-isms/gnu-isms in the software you are trying to port.

    Niall O'Higgins' blog sorta helps out, but it's the only
    thing I've seen:

    http://niallohiggins.com/tag/porting/

    and it's only OpenBSD->Win32 or OpenBSD->Linux which is
    still interesting and helpful but I'm much much more
    interested in seeing Linux->OpenBSD.

    Does anyone know of any blogs/articles like this?

  6. By ficovh (189.130.7.63) ficovh@yahoo.com on http://blog.bsdguy.net

    Nice article.

    Sometime creating a OpenBSD port can be a frustrate task.

    thanks.

  7. By Richard (69.65.81.5) on

    I appreciate how difficult it is to put this sort of thing out there, however, this post is a trivial example of the package construction process. For it to be useful it should have included the OBSD 4.3 Makefile-template and maybe a hello.c file.

    For me, while the simple example needed changes to work for 4.2, anything beyond that was infuriating because I was expecting it to be as simple or at least marginally more complicated.

    1. what does the author mean my the ports tree should be user writable?
    2. why does "make fake" seem to require being executed by SUDO?
    3. what happens when I want to install in /opt/local instead of /usr/local?
    4. what happens when I do not have a MASTER_SITE?

    these are things I would have included if I knew what I was talking about.

    Comments
    1. By Andrew Fresh (Andrew) on http://openbsd.somedomain.net

      > I appreciate how difficult it is to put this sort of thing out there, however, this post is a trivial example of the package construction process. For it to be useful it should have included the OBSD 4.3 Makefile-template and maybe a hello.c file.

      I think the point was to be trivial. To show just how easy it can be to
      create a port.

      > For me, while the simple example needed changes to work for 4.2, anything beyond that was infuriating because I was expecting it to be as simple or at least marginally more complicated.

      Ports work is supposed to be done in current. Writing ports for release or
      stable is not supported.

      > 1. what does the author mean my the ports tree should be user writable?

      That means you can do most stuff as yourself rather than having to use sudo or
      some other way of getting more permissions.

      > 2. why does "make fake" seem to require being executed by SUDO?

      Because the INSTALL_* macros change the owner of files (and probably other
      reasons, but that is the one I know of)

      > 3. what happens when I want to install in /opt/local instead of /usr/local?

      change LOCALBASE when installing the package. (Should work, may not)

      > 4. what happens when I do not have a MASTER_SITE?

      If you have FETCH_MANUALLY set, it echoes that message to stdout and stops
      (Error code 1). If you don't have FETCH_MANUALLY set, it tries the default
      MASTER_SITE.

      > these are things I would have included if I knew what I was talking about.

      Or, you could have just tried it to see what happens. None of these questions
      would stop you from creating a port though.

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]