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
Subversion or portsnap(8)
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:
%
diff -u something.orig something > something.diff
Otherwise, you should either use the
svn diff
method (Section 10.1, “Using SVN
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 (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 svn(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.
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.
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, Keeping Up.
If you can, please submit a svn(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
%
svn co https://svn0.us-west.FreeBSD.org
/ports/head/dns/pdnsd
%
cd ~/my_wrkdir/pdnsd
This can be anywhere you want, of course; building
ports is not limited to within
| |
svn0.us-west.FreeBSD.org
is a public |
While in the working directory, make any changes that you
would usually make to the port. If you add or remove a file,
use svn
to track these changes:
%
svn add new_file
%
svn remove deleted_file
Make sure that you check the port using the checklist in
Section 3.4, “Testing the Port” and
Section 3.5, “Checking Your Port with
portlint
”.
This will try to merge the differences between your
patch and current SVN; watch the output carefully. The
letter in front of each file name indicates what was done
with it. See Table 10.1, “ |
SVN
Update File PrefixesU | The file was updated without problems. |
G | 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
svn update
it means something changed in
the SVN repository and svn(1) was not able to merge your
local changes and those from the repository. It is always a
good idea to inspect the changes anyway, since svn(1)
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 SVN:
%
svn diff > ../`basename ${PWD}`.diff
Any files that have been removed should be explicitly mentioned in the PR, because file removal may not be obvious to the committer.
Send your patch following the guidelines in Chapter 10, Upgrading an Individual Port.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.