20.1. Adding a New Port

The easiest way to add a new port is the
addport script located in the
ports/Tools/scripts directory. It
adds a port from the directory specified, determining
the category automatically from the port
Makefile. It also adds an entry to
the port's category Makefile. It
was written by Michael Haro <mharo@FreeBSD.org>, Will Andrews <will@FreeBSD.org>, and
Renato Botelho <garga@FreeBSD.org>. When sending questions about this
script to the FreeBSD ports mailing list, please also CC Chris Rees <crees@FreeBSD.org>,
the current maintainer.

20.1.2.

Any other things I need to know when I add a new
port?

Check the port, preferably to make sure it compiles
and packages correctly. This is the recommended
sequence:

20.4. Repository Copies

When you want to add a port that is related to any
port that is already in the tree in a separate
directory, you have to do a repository copy. Here
related means it is a different
version or a slightly modified version. Examples are
print/ghostscript* (different
versions) and x11-wm/windowmaker*
(English-only and internationalized version).

Another example is when a port is moved from one
subdirectory to another, or when the name of a directory
must be changed because the authors renamed their
software even though it is a descendant of a port
already in a tree.

20.4.2.

What do I need to do?

With Subversion, a repo copy can be done by any
committer:

Doing a repo copy:

Verify that the target directory does
not exist.

Use svn up to make
certain the original files, directories, and
checkout information is current.

Use svn move or
svn copy to do the repo
copy.

Upgrade the copied port to the new version.
Remember to add or change the
PKGNAMEPREFIX or
PKGNAMESUFFIX so there are no
duplicate ports with the same name. In some
rare cases it may be necessary to change the
PORTNAME instead of adding
PKGNAMEPREFIX or
PKGNAMESUFFIX, but this is
only done when it is really needed — for
example, using an existing port as the base for
a very similar program with a different name, or
upgrading a port to a new upstream version which
actually changes the distribution name, like the
transition from
textproc/libxml to
textproc/libxml2. In most
cases, adding or changing
PKGNAMEPREFIX or
PKGNAMESUFFIX
suffices.

Add the new subdirectory to the
SUBDIR listing in the parent
directory Makefile. You
can run make checksubdirs in
the parent directory to check this.

If the port changed categories, modify the
CATEGORIES line of the port's
Makefile accordingly

Add an entry to
ports/MOVED, if you remove
the original port.

Commit all changes on one commit.

When removing a port:

Perform a thorough check of the ports
collection for any dependencies on the old port
location/name, and update them. Running
grep on
INDEX is not enough because
some ports have dependencies enabled by
compile-time options. A full
grep -r of the ports
collection is recommended.

Remove the old port and the
old SUBDIR entry.

Add an entry to
ports/MOVED.

After repo moves (“rename”
operations where a port is copied and the old
location is removed):

Follow the same steps that are outlined in
the previous two entries, to activate the new
location of the port and remove the old
one.

20.5. Ports Freeze

A “ports freeze” was a restricted state
the ports tree was put in before a release. It was used
to ensure a higher quality for the packages shipped with
a release. It usually lasted a couple of weeks. During
that time, build problems were fixed, and the release
packages were built. This practice is no longer used,
as the packages for the releases are built from the
current stable, quarterly branch.

For more information on how to merge commits to the
quarterly branch, see Q:Â 20.6.1.

If the commit has already been made, send an email
to the Ports Security Team <ports-secteam@FreeBSD.org> and the Ports Management Team <portmgr@FreeBSD.org> with the
revision number and a small description of why the
commit needs to be merged.

Tip:

If the MFH is covered by a blanket approval,
please explain why with a couple of words on the
MFH line, so that the reviewing
team can skip this commit and save time. For
example:

At that point, the script will either open a shell
for you to fix things, or open your text editor with the
commit message all prepared and then commit the
merge.

The script assumes that you can connect to
repo.FreeBSD.org with
SSH directly, so if your
local login name is different than your FreeBSD cluster
account, you need a few lines in your
~/.ssh/config:

Host *.freebsd.org
User freebsd-login

Tip:

The script is also able to merge more than one
revision at a time. If there have been other updates
to the port since the branch was created that have not
been merged because they were not security related.
Add the different revisions in the order
they were committed on the
mfh line. The new commit log
message will contain the combined log messages from
all the original commits. These messages
must be edited to show what is
actually being done with the new commit.

Note:

The mfh script can also take an optional first
argument, the branch where the merge is being done.
Only the latest quarterly branch is supported, so
specifying the branch is discouraged. To be safe, the
script will give a warning if the quarterly branch is
not the latest:

%/usr/ports/Tools/scripts/mfh 2016Q1 r407208 r407713
/!\ The latest branch is 2016Q2, do you really want to commit to 2016Q1? [y/n]

Please see
Proposing a New Category in the Porter's
Handbook. Once that procedure has been followed and the
PR has been assigned to the Ports Management Team <portmgr@FreeBSD.org>, it is their
decision whether or not to approve it. If they do, it
is their responsibility to:

Perform any needed moves. (This only applies
to physical categories.)

Update the VALID_CATEGORIES
definition in
ports/Mk/bsd.port.mk.

Assign the PR back to you.

20.7.2.

What do I need to do to implement a new physical
category?

Upgrade each moved port's
Makefile. Do not connect the
new category to the build yet.

To do this, you will need to:

Change the port's
CATEGORIES (this was the
point of the exercise, remember?) The new
category is listed
first. This will help to
ensure that the PKGORIGIN is
correct.

Run a make describe.
Since the top-level
make index that you will be
running in a few steps is an iteration of
make describe over the entire
ports hierarchy, catching any errors here will
save you having to re-run that step later
on.

If you want to be really thorough, now
might be a good time to run
portlint(1).

Check that the PKGORIGINs are
correct. The ports system uses each port's
CATEGORIES entry to create its
PKGORIGIN, which is used to
connect installed packages to the port directory
they were built from. If this entry is wrong,
common port tools like pkg_version(1) and
portupgrade(1) fail.

To do this, use the
chkorigin.sh tool:
env
PORTSDIR=/path/to/ports
sh -e
/path/to/ports/Tools/scripts/chkorigin.sh.
This will check every port in
the ports tree, even those not connected to the
build, so you can run it directly after the move
operation. Hint: do not forget to look at the
PKGORIGINs of any slave ports of
the ports you just moved!

On your own local system, test the proposed
changes: first, comment out the
SUBDIR entries in the old ports'
categories' Makefiles; then
enable building the new category in
ports/Makefile. Run
make checksubdirs in the affected
category directories to check the
SUBDIR entries. Next, in the
ports/
directory, run make index. This
can take over 40 minutes on even modern systems;
however, it is a necessary step to prevent problems
for other people.

Once this is done, you can commit the updated
ports/Makefile to connect the
new category to the build and also commit the
Makefile changes for the old
category or categories.

doc/en_US.ISO8859-1/htdocs/ports.
Note that these are now displayed by sub-groups,
as specified in
doc/en_US.ISO8859-1/htdocs/ports/categories.descriptions.

(Note: these are in the docs, not the ports,
repository). If you are not a docs committer, you
will need to submit a PR for this.

Only once all the above have been done, and no
one is any longer reporting problems with the new
ports, should the old ports be deleted from their
previous locations in the repository.

It is not necessary to manually update the
ports web
pages to reflect the new category. This is
done automatically via the change to
en_US.ISO8859-1/htdocs/ports/categories
and the automated rebuild of
INDEX.

20.7.3.

What do I need to do to implement a new virtual
category?

This is much simpler than a physical category. Only
a few modifications are needed:

Are there changes that can be committed without
asking the maintainer for approval?

Blanket approval for most ports applies to these
types of fixes:

Most infrastructure changes to a port (that is,
modernizing, but not changing the functionality).
For example, the blanket covers converting to new
USES macros, enabling verbose
builds, and switching to new ports system
syntaxes.

The packages are built multiple times each week. If
a port fails, the maintainer will receive an email from
pkg-fallout@FreeBSD.org.

Reports for all the package builds (official,
experimental, and non-regression) are aggregated at
pkg-status.FreeBSD.org.

20.8.3.

I added a new port. Do I need to add it to the
INDEX?

No. The file can either be generated by running
make index, or a pre-generated
version can be downloaded with
make fetchindex.

20.8.4.

Are there any other files I am not allowed to
touch?

Any file directly under ports/,
or any file under a subdirectory that starts with an
uppercase letter (Mk/,
Tools/, etc.). In particular, the
Ports Management Team <portmgr@FreeBSD.org> is very protective of
ports/Mk/bsd.port*.mk so do not
commit changes to those files unless you want to face
their wrath.

20.8.5.

What is the proper procedure for updating the
checksum for a port distfile when the file changes
without a version change?

When the checksum for a distribution file is updated
due to the author updating the file without changing the
port revision, the commit message includes a
summary of the relevant diffs between the original and
new distfile to ensure that the distfile has not been
corrupted or maliciously altered. If the current
version of the port has been in the ports tree for a
while, a copy of the old distfile will usually be
available on the ftp servers; otherwise the author or
maintainer should be contacted to find out why the
distfile has changed.

20.8.6.

How can an experimental test build of the ports tree
(exp-run) be requested?

An exp-run must be completed before patches with a
significant ports impact are committed. The patch can
be against the ports tree or the base system.

Full package builds will be done with the patches
provided by the submitter, and the submitter is required
to fix detected problems (fallout)
before commit.