Chapter 10. Upgrading a Port

When a port is not the most recent version available from the authors, update the local working copy of /usr/ports. The port might have already been updated to the new version.

When working with more than a few ports, it will probably be easier to use Subversion to keep the whole ports collection up-to-date, as described in the Handbook. This will have the added benefit of tracking all the port's dependencies.

The next step is to see if there is an update already pending. To do this, there are two options. There is a searchable interface to the FreeBSD Problem Report (PR) or bug database. Select Ports Tree in the Product dropdown, and enter the name of the port in the Summary field.

However, sometimes people forget to put the name of the port into the Summary field in an unambiguous fashion. In that case, try searching in the Comment field in the Detailled Bug Information section, or try the FreeBSD Ports Monitoring System (also known as portsmon). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the Overview of One Port.

If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by make maintainer. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version), and there is no need to duplicate their work. Note that unmaintained ports are listed with a maintainer of [email protected], which is just the general ports mailing list, so sending mail there probably will not help in this case.

If the maintainer asks you to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the diff(1) command in the base system.

To create a suitable diff for a single patch, copy the file that needs patching to something.orig, save the changes to something and then create the patch:

% diff -u something.orig something > something.diff

Otherwise, either use the svn diff method (Section 10.1, “Using Subversion to Make Patches”) or copy the contents of the port to an entire different directory and use the result of the recursive diff(1) output of the new and old ports directories (for example, if the modified port directory is called superedit and the original is in our tree as superedit.bak, then save the result of diff -ruN superedit.bak superedit). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the -N option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. (In particular, make sure to first clean out the work directories with make clean).

To simplify common operations with patch files, use make makepatch as described in Section 4.4, “Patching”. Other tools exists, like /usr/ports/Tools/scripts/patchtool.py. Before using it, please read /usr/ports/Tools/scripts/README.patchtool.

If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the section in the Developer's Handbook.)

To submit the diff, use the bug submit form (category Ports Tree). If the submitter is also maintaining the port, be sure to put [maintainer update] at the beginning of the Summary line. Please mention any added or deleted files in the message, as they have to be explicitly specified to svn(1) when doing a commit. Do not compress or encode the diff.

Before submitting the bug, review the Writing the problem report section in the Problem Reports article. It contains far more information about how to write useful problem reports.

Now that all of that is done, read about how to keep up-to-date in Chapter 14, Keeping Up.

% cd ~/my_wrkdir 
% svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd 
% cd ~/my_wrkdir/pdnsd

% svn add new_file
% svn copy some_file file_copy
% svn move old_name new_name
% svn remove deleted_file

% svn status
% svn update  
This will attempt to merge the differences between the
	  patch and current repository version.  Watch the output
	  carefully.  The letter in front of each file name
	  indicates what was done with it.  See
	  Table 10.1, “Subversion Update File
	Prefixes” for a complete list.

If C is displayed as a result of svn update, it means something changed in the Subversion repository and svn(1) was not able to merge the local changes with those from the repository. It is always a good idea to inspect the changes anyway, since svn(1) does not know anything about the structure of a port, so it might (and probably will) merge things that do not make sense.

The last step is to make a unified diff(1) of the changes:

% svn diff > ../`make -VPKGNAME`.diff

Send the patch following the guidelines in Chapter 10, Upgrading a Port.