The maintainer's guide to Updating ports
Since OpenBSD 3.8, pkg_add can update packages. So maintainers have to
be aware of one simple fact: update is not instantaneous. Even if a user
just goes from release to release, each time they run pkg_add -ui, the
system will replace each package with a new version, one package at a time.
So the user will run a mixed system, even if it is for just a few minutes.
There are basically two update models of which maintainers must be
- Some users follow current on a loose basis. They update their packages
every few days/every few weeks. Either all packages, or only some selected
packages. The update mechanism should work for them: it can force them to
update some specific packages, or to install some new stuff, but it should
not fail silently. Micro-updates must be tested. These users will most
often be able to cope with small changes, like program name changes, or
- Some users update every six months with a new release. They also will
download stable updates (security and critical updates). During six months,
a large part of the ports tree changes. These users do not care about
individual software changes. They just want a system that works. Changing
binary names is completely unfriendly to these users. Tweaking hundreds
of configuration files will be a major pain for them.
Maintainers can help by providing smooth update paths, and major hints
whenever something important changes.
You should note that part of the update process, especially the
macroscopic changes for users who update every six months, is not yet
automated. The global update mechanism is still a work in progress, and
pkg_add will be able to cope with more issues in the future.
As of now, you should focus on making sure the system updates
correctly, one port at a time, and that one port's update takes other ports
into account, as far as conflicts and other issues are concerned.
Naming packages and the update process
Conflicts, planning for the future
The icky business of renames and branches
Configuration files and update issues
Shared libraries issues
Part of the work is to be done when making the port itself.
Ports often need minor updates without a new version upstream.
- Make sure the software authors are aware of your tweaks to make it
run on OpenBSD. You must endeavor to get OpenBSD patches into the next
release of the software. Otherwise, you can be prepared to rewrite most
of your patches from scratch every release.
- Make sure the software authors understand version numbering. If the
distfiles do not contain any version numbers, or if they reference
current stuff, communicate with the authors so that you can get some
- Document work-arounds. This will help you remember to check whether
they are still necessary when you try to update a port.
- Document dependencies. Especially the stuff you don't use. Some ports
can use external software that may not be available at the time of porting.
Make sure you do not pick it up, and document it, so that you can update
your port when this software becomes available later.
- If the port uses libtool, copy its log verbatim as a basis for your
SHARED_LIBS setup. This will help during updates.
PLIST_DB and build a database of packing-lists.
This is useful to find out about forgotten package name bumps, and also
to check for conflicts with older packages.
- Make sure dependencies stay as loose as they can be. By default,
RUN_ and LIB_DEPENDS will be satisfied by any version of a package.
Do not insist on a given version unless you have to. Use minimal versions
Part of the work will happen before the update itself.
- Each port update needs a package name bump. Otherwise, the update
mechanism for binary packages won't work. Anything that affects the binary
package implies a bump. This includes
MAINTAINER or description changes.
- If the package does not build, no bump is needed: changes to restore
a port to working order after it got broken do not warrant bumps.
- Changes to make sure a port does not pick/does pick an external
dependency warrant a bump.
- Changes in dependencies generally do not affect a port version number.
The package system uses a signature mechanism such that a binary package
is fully identified by its package names, plus the dependencies against
which it was built, plus the version numbers of all shared libraries it
And then the update.
make patch to have an initial copy of the port before
- Edit the port's Makefile to grab the new version, run
make makesum and
make patch as a starting basis.
- Once you've fixed patches that failed, run a full diff between the old
and the new version to figure out exactly what changed. Take notes, be
prepared to revisit things later.
- Do whatever porting work is necessary to get the new version to run
under OpenBSD, adjust dependencies, change package contents, etc.
- Double check shared library versions. For libtool-based ports, you have
the shared_libs.log to check whether the software authors did significant
changes. Note well that this is not enough. Most software authors
do not really understand shared library issues. You have to read the full
diff between the old and the new version, and bump library versions
accordingly. When in doubt, bump the major version.
- Be aware of conflicts with already built packages. For simple
updates, nothing needs to be done. If you split a package into several
subpackages, make sure the subpackages have proper conflict annotations:
they should usually conflict with the `old' single package.
- Help the user. If some specific steps must be taken beyond
pkg_add -ui, make sure they are visible in the package.
When your packaging policy changes, document it in the package description.
For instance, if you move the documentation into a separate package for
space constraints, the main package description should mention that the
documentation is now available as a separate package.
$OpenBSD: update.html,v 1.4 2006/11/05 18:19:20 espie Exp $