FreeBSD Porter's Handbook
Prev |  | Next

# Chapter 10 Upgrading an Individual Port

When you notice that a port is out of date compared to the latest version from the original authors, you should first ensure that you have the latest port. You can find them in the `ports/ports-current` directory of the FreeBSD FTP mirror sites. However, if you are working with more than a few ports, you will probably find it easier to use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. This will have the added benefit of tracking all the ports' dependencies.

The next step is to see if there is an update already pending. To do this, you have two options. There is a searchable interface to the FreeBSD Problem Report (PR) database (also known as `GNATS`). Select `ports` in the dropdown, and enter the name of the port.

However, sometimes people forget to put the name of the port into the Synopsis field in an unambiguous fashion. In that case, you can 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); you would not want to duplicate their work. Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, 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 you have a chance to help out FreeBSD by preparing the update yourself! 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 your changes to `something` and then create your patch:

    % /usr/bin/diff something.orig something > something.diff

Otherwise, you should either use the `cvs diff` method (Section 10.1) 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 (e.g., if your 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 you first clean out the work directories with `make clean`).

To simplify common operations with patch files, you can use `/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 yourself, 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.)

The best way to send us the diff is by including it via send-pr(1) (category `ports`). If you are maintaining the port, be sure to put `[maintainer update]` at the beginning of your synopsis line and set the ``Class'' of your PR to `maintainer-update`. Otherwise, the ``Class'' of your PR should be `change-request`. Please mention any added or deleted files in the message, as they have to be explicitly specified to cvs(1) when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is.

Before you send-pr(1), you should review the Writing the problem report section in the Problem Reports article; it contains far more information about how to write useful problem reports.

> Important: If your upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the Ports Management Team `<portmgr@FreeBSD.org>` to request immediate rebuilding and redistribution of your port's package. Unsuspecting users of pkg_add(1) will otherwise continue to install the old version via `pkg_add -r` for several weeks.

> Note: Once again, please use diff(1) and not shar(1) to send updates to existing ports! This helps ports committers understand exactly what is being changed.

Now that you have done all that, you will want to read about how to keep up-to-date in Chapter 14.

# 10.1 Using `CVS` to Make Patches

If you can, please submit a cvs(1) diff; they are easier to handle than diffs between ``new and old'' directories. Plus it is easier for you to see what you have changed and to update your diff if something is modified in the Ports Collection from when you started to work on it until you submit your changes, or if the committer asks you to fix something.

    % cd ~/my_wrkdir
    % cvs -d R_CVSROOT co pdnsd
    % cd ~/my_wrkdir/pdnsd

  This can be anywhere you want, of course; building ports is not limited to within `/usr/ports/`.
  R_CVSROOT is any public cvs server, take your pick from the list in the FreeBSD Handbook.
  pdnsd is the module name for the port; it is generally the name of the port, although there are some exceptions, notably for language-specific categories (`german/selfhtml` has the module name de-selfhtml); you can either look up the module name via the cvsweb interface or use the whole path, in our example `ports/dns/pdnsd`.

While in the working directory, make any changes that you would usually make to the port. If you add or remove a file, use `cvs` to track these changes:

    % cvs add new_file
    % cvs remove deleted_file

Make sure that you check the port using the checklist in Section 3.4 and Section 3.5.

    % cvs status
    % cvs update

  This will try to merge the differences between your patch and current CVS; watch the output carefully. The letter in front of each file name indicates what was done with it. See Table 10-1 for a complete list.

Table 10-1. `CVS` Update File Prefixes

U | The file was updated without problems.
P | The file was updated without problems (you will only see this when working against a remote repository).
M | The file had been modified, and was merged without conflicts.
C | The file had been modified, and was merged with conflicts.

If you get `C` as a result of `cvs update` it means something changed in the CVS and cvs(1) was not able to merge your local changes and those from CVS. It is always a good idea to inspect the changes anyway, since `cvs` does not know anything about how a port should be, 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 files against CVS:

    % cvs diff -uN > ../`basename ${PWD}`.diff

> Note: It is important to use `-N` to ensure that files you have added or removed are accounted for in the patch. The patch will include any removed files when applied, though the file contents will be empty, so remember to include these in the PR so the committer knows to remove them.

Send your patch following the guidelines in Chapter 10.

Prev | Home | Next
Tinderbox |  | The Files `UPDATING` and `MOVED`

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.