How to upgrade a port's version locally
- Audience: Those who don't want to wait for a port to be updated
- Requires: MacPorts >=1.6
Introduction
Sometimes ports will fall behind the currently-available version. When other ports are updated this can cause issues when the newer version of a port is needed for compatibility. The Portfile for a port can be updated locally to allow you to upgrade it now, without waiting for an official update from the maintainer.
Anytime you see <portname> in this document, replace with the actual name of the port in which you are interested, it is only a placeholder here.
Updating the port
Step 1: Getting into the port directory and keeping a copy of the original
First, cd into the port's directory (which contains the Portfile) by running:
cd $(port dir <portname>)
Then save a copy of the Portfile:
sudo cp -p Portfile Portfile.orig
Step 2: Editing the Portfile
Use:
sudo port edit <portname>
to edit the Portfile for the given port (this will open it in whatever editor you have defined via the VISUAL or EDITOR environment variables, or vi if not defined). Since you're already in the directory containing the Portfile, you can also open it directly from here, but port edit always works.
As of MacPorts 1.7, you can also choose your editor from the command line directly instead of the environment variables:
sudo port edit --editor nano <portname>
This will open nano to edit the Portfile for the given port.
Step 3: Updating the version
Once the Portfile has been opened, find the line which starts with version:
version 1.4.1
Update the version given on that line (1.4.1 in this example) to the newly-desired version, then save the Portfile. For example, if the new version is 1.5, it should simply look like:
version 1.5
Also, search for a revision line like:
revision 2
and if found reset it to zero. Updated versions should start with revision 0 (which is the default when revision isn't present).
Step 4: Fetching and updating the checksums
Now fetch and run the checksum phase (which will fail, since it hasn't been updated for the new version) by running:
sudo port -d checksum <portname>
This will fetch the new version you've specified then run a checksum against the downloaded file. This will fail and since the debug (-d) flag was used, specify the checksums from the new file (among other lines):
...
checksums rmd160 1799d0d28adaaae58063d387b4d6f36d4aedadcf \
sha256 fb3a1109cbe888fb0920bf13e910265d8be17048e17555ee323fa9cf85cdd9f2 \
size 66351584
...
Copy this section (all three lines), use sudo port edit <portname> again, and change the checksum lines to be what you just copied.
Similarly, if the Portfile has a livecheck section which uses livecheck.check md5, run:
sudo port -d livecheck <portname>
and update the Portfile's livecheck.md5 key with the new md5sum.
Step 5: Installing the new version
Now that the correct checksum has been specified, you can install the new version with:
sudo port -d install <portname>
Use the debug flag again so that, in case something bad happens, the error message will be seen. If it doesn't succeed, that goes beyond the scope of this document.
Otherwise, the port will be installed with the latest version specified.
Step 6: Filing an update ticket
Since it succeeded, file a pull request on GitHub or file a ticket with Trac to upgrade the port to the new version.
Filing a pull request on GitHub is considered superior. Your request will get faster attention and it is much easier for the MacPorts team to process it that way.
If you decide to file a Trac ticket instead: First, please don't forget to add the port maintainer's email addresses in CC. Second, to make it easier for the maintainer you should attach a diff against the Portfile to the new ticket, so generate a diff by running:
diff -u Portfile.orig Portfile | sudo tee <portname>.diff
Then specify the <portname>.diff as a file to be attached to the new ticket.
Step 7: Cleaning up
Do a little clean up so extra files aren't left around:
sudo rm <portname>.diff sudo mv Portfile.orig Portfile
TODO
One thing to add is about patches, some may no longer be needed (they're irrelevant with the new version, they've been integrated upstream, etc), so should be removed. Others may need updates which gets more complicated.
Also, this only covers basic port updates, need to also cover changing versions of the various groupcode-based ports.