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 &
Packages
in the Product
multiple
select menu, 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
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 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
,
save the changes to
something
.orig
and then
create the patch:something
%
diff -u
something
.origsomething
> something.diff
Otherwise, either use the
svn diff
method (Section 11.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
).
If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what svn(1) commands to run.
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 (product Ports & Packages
,
component Individual Port(s)
).
Always include the category
with the port name, followed by colon, and brief descripton of the
issue. Examples:
;
category/portname
:
add FOO option
.
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.category/portname
:
Update to X.Y
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.
If the 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 the port's package. Unsuspecting users
of pkg
will otherwise continue to install
the old version via pkg install
for several
weeks.
Please use diff(1) or svn diff
to
create updates to existing ports. Other formats include the
whole file and make it impossible to see just what has changed.
When diffs are not included, the entire update might be
ignored.
Now that all of that is done, read about how to keep up-to-date in Chapter 16, Keeping Up.
When possible, please submit a svn(1) diff. They
are easier to handle than diffs between
“new and old” directories. It is easier
to see what has changed, and to update the diff if
something was modified in the Ports Collection since the
work on it began, or if the
committer asks for something to be fixed. Also, a patch
generated with svn diff
can be easily applied
with svn patch
and will save some time to the
committer.
%
cd ~/my_wrkdir
%
svn co
https://svn.FreeBSD.org
/ports/head/dns/pdnsd%
cd ~/my_wrkdir/pdnsd
This can be anywhere, of course. Building
ports is not limited to within
| |
svn.FreeBSD.org is the FreeBSD public Subversion server. See Subversion mirror sites for more information. |
While in the port directory, make any changes that are
needed. If adding, copying, moving, or removing a
file, use svn
to track these changes:
%
svn add
new_file
%
svn copy
some_file
file_copy
%
svn move
old_name
new_name
%
svn remove
deleted_file
Make sure to check the port using the checklist in
Section 3.4, “Testing the Port” and
Section 3.5, “Checking the Port with
portlint
”.
%
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 11.1, “Subversion Update File Prefixes” for a complete list. |
U | The file was updated without problems. |
G | The file was updated without problems (only 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 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
If files have been added, copied, moved, or removed,
include the svn(1) add
,
copy
, move
, and
remove
commands that were used.
svn move
or svn copy
must be run before the patch can be applied. svn
add
or svn remove
must be run
after the patch is applied.
Send the patch following the problem report submission guidelines.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.