Integrating with the Ports Collection

Introduction

Sometimes the state of the ports in the development overlay and the FreeBSD Ports Collection diverge:

• Somebody commits a change to one or more ports in the (common) ports tree that has to be merged with the current state of the ports staged for development, optionally bumping the port revision for the affected ports.

• An update from the overlay was made to the (common) ports tree, which usually comes with a lot of port revision bumps.

Both type of changes shall be migrated to the development overlay, otherwise portshaker(8) will not merge the ports in the overlay to the ports tree. The script checks for the versions of the individual ports, that is how it can decide whether to merge ("overlap") the port in the overlay or not. If the version of the overlaid port is lesser (including port revision), the merge will be aborted.

Hence an out-of-sync overlay is essentially useless, continuous integration is needed to keep it usable for the users.

Merge the Overlay with the Ports Collection

The merge-trees-sdiff.sh in the Haskell Maintainer's Toolkit (see the hsmtk repository) can help with this. Please make sure that you have an up-to-date version of the ports tree, obtained either via using portsnap(8) or checked out from the Project's Subversion repository.

In this document, no existing overlay is assumed, so clone the hsmtk and ports repositories first and enter the ports directory.

$ git clone http://github.com/freebsd-haskell/hsmtk
$ git clone http://github.com/freebsd-haskell/ports
$ cd ports

Launch the merge-trees-sdiff script and follow the instructions. Note that the script assumes that the Ports Collection is available under the /usr/ports directory. If a different location is preferred (e.g. a local partial Subversion checkout), just override the PORTSDIR environment variable before running the script.

$ env PORTSDIR=/usr/ports sh ../hsmtk/merge-trees-sdiff.sh

Then follow the instructions. The whole process is based on the sdiff(1) merging tool in a fashion similar to the mergemaster(8) tool (for the FreeBSD base system), which lets the user to choose between the "left" and "right" version of the file sections. Here:

• left (l) is the state of the file in the Ports Collection.
• right (r) is the state of the file in the overlay.

Note that sdiff(1) will be only invoked when there are differences between the files (and they exist in the both version of the tree), otherwise the script will just skip them.

Once the merging finished, the user may decide to view the result (v), install it (i), or redo the merge (r) or leave the files alone.

After the merge of ports has completed (disclaimer: this may take a while, some patience is recommended to go through all the ports), check the resulting changes with git(1).

$ git diff

If everything is okay, just commit the results.

$ git commit -a

The Tricky Parts

Note that there are certain ports, such as devel/hs-haskell-platform and www/hs-yesod-platform that depend on exact versions of other ports. Unfortunately, currently it cannot be expressed in the FreeBSD ports framework to depend on a given version but with arbitrary port epoch or port revision, so exact package versions have to be added.

Since this is a tedious and a quite error-prone process, it is aided by the show-deppkgvers make(1) target in bsd.cabal.mk. Therefore the value for the USE_CABAL variable can be easily regenerated on each integration.

Here is how to do that for the Haskell Platform port:

$ cd devel/hs-haskell-platform
$ make show-deppkgvers | sed 's|^|%%|; s|$| \\|' | tr "%" "\t" > new_use_cabal.txt

Then replace the contents of the corresponding Makefile at the USE_CABAL line with the contents of the file was generated by the above command.