The Porter's Handbook is confusing

[Eponasoft]

Ok so I'd like to update a port which is no longer maintained and a more recent version of the port has been available for more than 5 years. I am eventually going to fork the app, but for now I just want to be able to update it. The Porter's Handbook is very unclear in many many places so I have no idea where to start. I have the original tgz that was downloaded when I did make, and I updated the source files inside of it with the most recent version (despite being 5 years old)... so now what?

 

[ckester]

If you would be more specific about the steps where you're unsure how to proceed, we could give you a more specific answer.

Here's a brief overview of the process. It is in no way intended as a substitute for the Porter's Handbook, which is still the best guide.

Since this is an update to an existing port, I would start by copying the port files from /usr/ports/category/portname into a directory also named portname under your $HOME. You'll need the Makefile, pkg-plist, pkg-descr and anything in the files subdir if there is one. You'll be replacing the distinfo file, so you can skip that.

Edit the PORTVERSION line in the Makefile so that it reflects the new version number. Delete the PORTREVISION line if there is one. Save your changes and exit the editor.

As root, run

make fetch

to download the latest distfile. In most cases, this works without any further tweaking. But sometimes you'll need to edit the MASTER_SITES or DISTNAME line(s) in the Makefile to account for changes at whatever site is providing the distfile. (Sourceforge is notorious for this.)

If the distfile downloads OK, run the following command, still as root:

make makesum

which will create a new distinfo file containing the appropriate checksums.

Now the fun begins. Try building the app with

make build

If you're lucky it will build OK. If not, you'll need to debug the build. You might need to remove or modify some of the patches in the files subdir. Or add some new patches of your own. Or make more edits to the Makefile, for example to define a variable in the CONFIGURE_ENV.

Once you get it building OK, it's time to test the install. I like to use ports-mgmt/genplist for this, because it installs into a temporary directory that's easy to clean up afterwards:

genplist create /tmp/portname

(You can also use ports-mgmt/tinderbox for this, but it's more complex to setup and use.)

To uninstall and cleanup after genplist, use

genplist clean

When the build and install are all running OK and you're ready to submit a PR with your updates, make sure you've run

make clean

to clean out and remove the sourcecode, etc. in the WORKDIR. Then cd to the parent directory and generate a patchfile:

cd ..
diff -ruN /usr/ports/category/portname ./portname > portname-version.diff

 

[Eponasoft]

Actually, that was amazingly helpful... thanks very much. I was stumped at just about every step, so it wasn't easy to narrow it down... the PH really isn't all that user-friendly for us lesser folk. I'll be sure to bug again if anything else goes wrong that I don't understand...

 

[SirDice]

If you're going to fork the port it's probably the easiest just to copy the old port and change the version numbers in it. Then see if it builds and fix any errors that might pop up (patches not being applied for instance).

 

[ckester]

Adding a useful tip someone gave me a while ago re creating/modifying patches:

Starting from a clean workdir (ie, following a "make clean", if necessary), extract a fresh copy of the sourcecode and apply any existing patches with

make patch

Now descend down into the workdir to make your changes to the sourcecode. Files that have already been patched will have a copy of the original, with a .orig extension. If you edit any files that don't already have these "originals", create them before you do the edit.

To make this easier, I have the following alias defined in my .cshrc:

 alias pe        $HOME/bin/pe.csh

and here's pe.csh:

#!/bin/csh
#
# make sure a copy of the original file is saved before editing,
# in preparation for doing a diff on it later
#

if ( "X$1" == "X" ) then
        echo "need at least one argument"
        exit -1
endif

set ORIG=$1.orig

test -r $ORIG

if ( $? == 0 ) then
        ${EDITOR} $1
else
        cp $1 ${ORIG}
        ${EDITOR} $1
endif

So to edit any of the source files for a port, I just use the command "pe filename" and it creates an "original" copy if one isn't already found.

(Obviously, you can name the alias and script whatever you like. I like "pe" as a shorthand for patchedit.)

Then, when you're all done making your changes, cd back up to the topdir for the port (the one where the port Makefile is) and enter the following command:

make makepatch

This will create a patchfile in the files subdir for every sourcefile where there's a corresponding .orig file and it will name the patchfiles using the recommended convention. Neat, huh?

Rinse (make clean) and repeat (to apply your new patches and make any further changes) as often as necessary.