Committer's Guide
Prev |  | Next

# 13 Ports Specific FAQ

1. Adding a New Port
  13.1.1. How do I add a new port?
  13.1.2. Any other things I need to know when I add a new port?
2. Removing an Existing Port
  13.2.1. How do I remove an existing port?
3. Re-adding a Deleted Port
  13.3.1. How do I re-add a deleted port?
4. Repository Copies
  13.4.1. When do we need a repository copy?
  13.4.2. What do I need to do?
5. Ports Freeze
  13.5.1. What is a “ports freeze”?
  13.5.2. What is a “ports slush” or “feature freeze”?
  13.5.3. How long is a ports freeze or slush?
  13.5.4. What does it mean to me?
  13.5.5. How do I know when the ports slush starts?
  13.5.6. How do I know when the freeze or slush ends?
6. Creating a New Category
  13.6.1. What is the procedure for creating a new category?
  13.6.2. What do I need to do to implement a new physical category?
  13.6.3. What do I need to do to implement a new virtual category?
7. Miscellaneous Questions
  13.7.1. How do I know if my port is building correctly or not?
  13.7.2. I added a new port. Do I need to add it to the `INDEX`?
  13.7.3. Are there any other files I am not allowed to touch?
  13.7.4. What is the proper procedure for updating the checksum for a port's distfile when the file changes without a version change?

### 1. Adding a New Port

13.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 from your machine (located in the `ports/Tools/scripts` directory). 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 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.

13.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. Removing an Existing Port

13.2.1. How do I remove an existing port?

First, please read the section about repository copies. Before you remove the port, you have to verify there are no other ports depending on it.

- Make sure there is no dependency on the port in the ports collection:

  - The port's PKGNAME should appear in exactly one line in a recent INDEX file.

  - No other ports should contain any reference to the port's directory or PKGNAME in their Makefiles

- Then, remove the port:

  1. Remove the port's files via `svn remove`.

  2. Remove the `SUBDIR` listing of the port in the parent directory `Makefile`.

  3. Add an entry to `ports/MOVED`.

  4. Remove the port from `ports/LEGAL` if it is there.

Alternatively, you can use the `rmport` script, from `ports/Tools/scripts`. This script was written by Vasil Dimov `<vd@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.

### 3. Re-adding a Deleted Port

13.3.1. How do I re-add a deleted port?

This is essentially the reverse of deleting a port.

1. Figure out when the port was removed. Use this list and then copy the last living revision of the port:

       % cd /usr/ports/category

       % svn cp 'svn+ssh://svn.freebsd.org/ports/category/portname/@{YYYY-MM-DD}' portname

   Pick a date that is before the removal but after the last true commit.

2. Perform whatever changes are necessary to make the port work again. If it was deleted because the distfiles are no longer available you will need to volunteer to host them yourself, or find someone else to do so.

3. `svn add` or `svn remove` any appropriate files.

4. Restore the `SUBDIR` listing of the port in the parent directory `Makefile`, and delete the entry from `ports/MOVED`.

5. If the port had an entry in `ports/LEGAL`, restore it.

6. `svn commit` these changes, preferably in one step.

> Tip: `addport` now detects when the port to add has previously existed, and should handle all except the `ports/LEGAL` step automatically.

### 4. Repository Copies

13.4.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.

13.4.2. What do I need to do?

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

- Doing a repo copy:

  1. First make sure that you were using an up to date ports tree and the target directory does not exist.

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

  3. Upgrade the copied port to the new version. Remember to change the `LATEST_LINK` so there are no duplicate ports with the same name. In some rare cases it may be necessary to change the `PORTNAME` instead of `LATEST_LINK`, but this should only be done when it is really needed — e.g., 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, changing `LATEST_LINK` should suffice.

  4. 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.

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

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

  7. Commit all changes on one commit. A forced commit is no longer needed with Subversion.

- 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 and the old `SUBDIR` 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.

### 5. Ports Freeze

13.5.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”.

For more information on the background and policies surrounding a ports freeze, see the Portmgr Quality Assurance page.

13.5.2. What is a “ports slush” or “feature freeze”?

During a release cycle the ports tree may be in a “slush” state instead of in a hard freeze. The goal during a slush is to reach a stable ports tree to avoid rebuilding large sets of packages for the release and to tag the tree. During this time “sweeping changes” are prohibited unless specifically permitted by portmgr. Complete details about what qualifies as a sweeping change can be found on the Portmgr Implementation page.

The benefit of a slush as opposed to a complete freeze is that it allows maintainers to continue adding new ports, making routine version updates, and bug fixes to most existing ports, as long as the number of affected ports is minimal. For example, updating the shared library version on a port that many other ports depend on.

13.5.3. How long is a ports freeze or slush?

A freeze only lasts long enough to tag the tree. A slush usually lasts a week or two, but may last longer.

13.5.4. What does it mean to me?

During a ports freeze, you are not allowed to commit anything to the tree without explicit approval from the Ports Management Team. “Explicit approval” here means that you send a patch to the Ports Management Team for review and get a reply saying, “Go ahead and commit it.”

Not everything is allowed to be committed during a freeze. Please see the Portmgr Quality Assurance page for more information.

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

During a ports slush, you are still allowed to commit but you must exercise more caution in what you commit. Furthermore a special note (typically “Feature Safe: yes”) must be added to the commit message.

13.5.5. How do I know when the ports slush starts?

The Ports Management Team 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 slush has to be synchronized with the release, and it is usually not known until then when exactly the release will be rolled.

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

13.5.6. How do I know when the freeze or slush ends?

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

### 6. Creating a New Category

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

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

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

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

3. Assign the PR back to you.

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

  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 `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 `PKGORIGIN`s 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 move operation. Hint: do not forget to look at the `PKGORIGIN`s 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' `Makefile`s; 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.

- Add appropriate entries to `ports/MOVED`.

- Update the documentation by modifying the following:

  - the list of categories in the Porter's Handbook

  - `www/en/ports/categories`. Note that these are now displayed by sub-groups, as specified in `www/en/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 now done automatically via your change to `www/en/ports/categories` and the daily automated rebuild of `INDEX`.

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

This is much simpler than a physical category. You only need to modify the following:

- the list of categories in the Porter's Handbook

- `www/en/ports/categories`

### 7. Miscellaneous Questions

13.7.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.)

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

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

13.7.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 Management Team 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.

13.7.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 |  | Issues Specific To Developers Who Are Not Committers