[wiki:howto <- Back to the HOWTO section]

= 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, [https://github.com/macports/macports-ports/pulls file a pull request on GitHub] or [/newticket 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.

[wiki:howto <- Back to the HOWTO section]