
Prev		Next

1. Adding a New Port

12.1.1. How do I add a new port?

First, please read the section about repository copies.

The easiest way to add a new port is to use the addport script on freefall. It will add a port from the directory you specify, determining the category automatically from the port Makefile. It will also add an entry to the CVSROOT/modules file and the port's category Makefile. It was written by Michael Haro <mharo@FreeBSD.org> and Will Andrews <will@FreeBSD.org>, but Will is the current maintainer so please send questions/patches about addport to him.

12.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:

# make install
# make package
# make deinstall
# pkg_add package you built above
# make deinstall
# make reinstall
# make package

The Porters Handbook contains more detailed instructions.

Use portlint(1) to check the syntax of the port. You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones.

If the port came from a submitter who has not contributed to the project before, add that person's name to the Additional Contributors section of the FreeBSD Contributors List.

Close the PR if the port came in as a PR. To close a PR, just do edit-pr PR# on freefall and change the state from open to closed. You will be asked to enter a log message and then you are done.

2. Repository Copies

12.2.1. When do we need a repository copy?

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 you want to change the name of a directory because the author(s) renamed their software even though it is a descendant of a port already in a tree.

12.2.2. When do we not need a repository copy?

When there is no history to preserve. If a port is added into a wrong category and is moved immediately, it suffices to simply cvs remove the old one and addport the new one.

12.2.3. What do I need to do?

File a PR in GNATS, listing the reasons for the repository copy request. Assign it to portmgr and set state to repocopy. If Ports Management Team <portmgr@FreeBSD.org> approves it, it will be reassigned to pcvs. If so inclined, portmgr may do the copy directly; otherwise, CVS ports Repository Meisters <pcvs@FreeBSD.org> will do a repository copy from the old to the new location, and reassign the PR back to you. Once everything is done, perform the following:

When a port has been repo copied:
1. Upgrade the copied port to the new version (remember to change the PORTNAME so there are not duplicate ports with the same name).
2. 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.
3. If the port changed categories, modify the CATEGORIES line of the port's Makefile accordingly
4. Add the new module entry.
5. Add an entry to ports/MOVED.
When removing a port:
1. 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.
2. Remove the old port, the old SUBDIR entry and the old module entry.
3. Add an entry to ports/MOVED.
After repo moves (“rename” operations where a port is copied and the old location is removed):
1. 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.

3. Ports Freeze

12.3.1. What is a “ports freeze”?

Before a release, it is necessary to restrict commits to the ports tree for a short period of time while the packages and the release itself are being built. This is to ensure consistency among the various parts of the release, and is called the “ports freeze”.

12.3.2. How long is a ports freeze?

Usually an hour or two.

12.3.3. What does it mean to me?

During the ports freeze, you are not allowed to commit anything to the tree without explicit approval from the ports manager. “Explicit approval” here means either of the following:

You asked the ports manager and got a reply saying, “Go ahead and commit it.”
The ports manager sent a mail to you or the mailing lists during the ports freeze pointing out that the port is broken and has to be fixed.

Note that you do not have implicit permission to fix a port during the freeze just because it is broken.

12.3.4. How do I know when the ports freeze starts?

The ports manager will send out warning messages to the FreeBSD ports mailing list and FreeBSD committer's mailing list announcing the start of the impending release, usually two or three weeks in advance. The exact starting time will not be determined until a few days before the actual release. This is because the ports freeze has to be synchronized with the release, and it is usually not known until then when exactly the release will be rolled.

When the freeze starts, there will be another announcement to the FreeBSD committer's mailing list, of course.

12.3.5. How do I know when the ports freeze ends?

A few hours after the release, the ports manager will send out a mail to the FreeBSD ports mailing list and FreeBSD committer's mailing list announcing the end of the ports freeze. Note that the release being cut does not automatically end the freeze. We have to make sure there will not be any last minute snafus that result in an immediate re-rolling of the release.

4. Creating a New Category

12.4.1. What is the procedure for creating a new category?

A developer who wishes to propose a new category should submit a detailed rationale for the new category, including why existing categories are not sufficient, and the list of ports proposed to move.

Before submitting, keep in mind that there is a fair amount of work involved from multiple parties; that the changes affect everyone who wants to keep up-to-date with the entire ports tree; and that such proposals tend to attract controversy.

12.4.2. What do I need to do?

The procedure is a strict superset of the one to repocopy individual ports (see above).

File a PR in GNATS, listing the reasons for the category request. Preferably, this should also include patches for Makefiles for the old ports, the Makefiles for their old categories, and the VALID_CATEGORIES definition in ports/Mk/bsd.port.mk. Assign the PR to the Ports Management Team <portmgr@FreeBSD.org> (as portmgr). If they approve it, it will be reassigned to CVS Repository Meisters <cvsadm@FreeBSD.org> (as cvs), who will do a repository copy from the old to the new locations and reassign the PR back to you. Once everything is done, perform the following steps:

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

To do this, you will need to:
1. Change the port's CATEGORIES (this was the point of the exercise, remember?) The new category should be listed first. This will help to ensure that the the PKGORIGIN is correct.
2. 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.
3. 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, as follows: 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 repocopy. Hint: do not forget to look at the PKGORIGINs of any slave ports of the ports you just repocopied!
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.
Change all the affected module entries in CVSROOT-ports/modules.
Add appropriate entries to ports/MOVED.
Update the instructions for cvsup(1) by modifying distrib/cvsup/sup/README and adding the following files into cvsup/sup/ports-categoryname: list.cvs and releases. (Note: these are in the src, not the ports, repository).
Submit a docs PR to add the new category to both the Porter's Handbook and to www/en/ports/categories.
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 now done automatically via your change to www/en/ports/categories and the daily automated rebuild of INDEX.

5. Miscellaneous Questions

12.5.1. How do I know if my port is building correctly or not?

First, go check http://pointyhat.FreeBSD.org/errorlogs/. There you will find error logs from the latest package building runs on all supported platforms for the most recent branches.

However, just because the port does not show up there does not mean it is building correctly. (One of the dependencies may have failed, for instance.) The relevant directories are available on pointyhat under /a/portbuild/<arch>/<major_version> so feel free to dig around. Each architecture and version has the following subdirectories:

errors        error logs from latest <major_version> run on <arch>
logs          all logs from latest <major_version> run on <arch>
packages      packages from latest <major_version> run on <arch>
bak/errors    error logs from last complete <major_version> run on <arch>
bak/logs      all logs from last complete <major_version> run on <arch>
bak/packages  packages from last complete <major_version> run on <arch>

Basically, if the port shows up in packages, or it is in logs but not in errors, it built fine. (The errors directories are what you get from the web page.)

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

No, INDEX is no longer stored in the CVS repository. The file can either be generated by running make index, or a pre-generated version can be downloaded with make fetchindex.

12.5.3. 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 manager is very protective of ports/Mk/bsd.port*.mk so do not commit changes to those files unless you want to face his wra(i)th.

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

When the checksum for a port's distfile is updated due to the author updating the file without changing the port's revision, the commit message should include 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.

Prev	Home	Next
Support for Multiple Architectures		Perks of the Job

12 Ports Specific FAQ

1. Adding a New Port

2. Repository Copies

3. Ports Freeze

4. Creating a New Category

5. Miscellaneous Questions