19.1. Adding a New Port |
- 19.1.1. How do I add a new port?
- 19.1.2. Any other things I need to know when I add a new
port?
|
19.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 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 <[email protected]>, Will Andrews <[email protected]>, and
Renato Botelho <[email protected]>. When sending questions about this
script to the FreeBSD ports mailing list, please also CC Chris Rees <[email protected]>,
the current maintainer. |
19.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, change the state to Issue
Resolved and the resolution as
Fixed. |
19.2. Removing an Existing Port |
- 19.2.1. How do I remove an existing port?
|
19.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. Alternatively, you can use the
rmport script, from
ports/Tools/scripts. This script
was written by Vasil Dimov <[email protected]>. When sending questions
about this script to the FreeBSD ports mailing list, please also CC
Chris Rees <[email protected]>, the current maintainer. |
19.3. Re-adding a Deleted Port |
- 19.3.1. How do I re-add a deleted port?
|
19.3.1. | How do I re-add a deleted port? |
| This is essentially the reverse of deleting a
port. Important: Do not use svn add to add the
port. Follow these steps. If they are unclear, or
are not working, ask for help, do not just
svn add the port. Figure out when the port was removed. Use this
list,
or look for the port on freshports,
and then copy the last living revision of the
port: % cd /usr/ports/category
% svn cp 'svn+ssh://svn.freebsd.org/ports/head/category/portname/@XXXXXX' portname
Pick the revision that is just before the
removal. For example, if the revision where it was
removed is 269874, use
269873. It is also possible to specify a date. In that
case, pick a date that is before the removal but
after the last commit to the port. % cd /usr/ports/category
% svn cp 'svn+ssh://svn.freebsd.org/ports/head/category/portname/@{YYYY-MM-DD}' portname
Make the changes necessary to get the port
working again. If it was deleted because the
distfiles are no longer available, either
volunteer to host the distfiles, or find someone
else to do so. If some files have been added, or were removed
during the resurrection process, use svn
add or svn remove to
make sure all the files in the port will be
committed. Restore the SUBDIR listing of
the port in the parent directory
Makefile, keeping the entries
sorted. Delete the port entry from
ports/MOVED. If the port had an entry in
ports/LEGAL, restore it. svn commit these changes,
preferably in one step.
Tip: The addport script mentioned in
Q & A 19.1, “Adding a New Port” now detects when the
port to add has previously existed, and attempts to
handle all except the ports/LEGAL
step automatically. |
19.4. Repository Copies |
- 19.4.1. When do we need a repository copy?
- 19.4.2. What do I need to do?
|
19.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. |
19.4.2. | What do I need to do? |
| With Subversion, a repo copy can be done by any
committer: |
19.5. Ports Freeze |
- 19.5.1. What is a “ports freeze”?
|
19.5.1. | What is a “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: 19.7.5. |
19.6. Creating a New Category |
- 19.6.1. What is the procedure for creating a new
category?
- 19.6.2. What do I need to do to implement a new physical
category?
- 19.6.3. What do I need to do to implement a new virtual
category?
|
19.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 <[email protected]>, it is their
decision whether or not to approve it. If they do, it
is their responsibility to do the following: 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.
|
19.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: 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. 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, 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
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. Add appropriate entries to
ports/MOVED. Update the documentation by modifying the
following: the list
of categories in the Porter's
Handbook
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. |
19.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: |
19.7. Miscellaneous Questions |
- 19.7.1. How do I know if my port is building correctly or
not?
- 19.7.2. I added a new port. Do I need to add it to the
INDEX?
- 19.7.3. Are there any other files I am not allowed to
touch?
- 19.7.4. What is the proper procedure for updating the
checksum for a port's distfile when the file changes
without a version change?
- 19.7.5. What is the procedure to request authorization for
merging a commit to the quarterly branch?
|
19.7.1. | How do I know if my port is building correctly or
not? |
| The packages are built multiple times each week. If
a port fails, the maintainer will receive an email from
[email protected]. Reports for all the package builds (official,
experimental, and non-regression) are aggregated at
pkg-status.FreeBSD.org. |
19.7.2. | 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. |
19.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 <[email protected]> is very protective of
ports/Mk/bsd.port*.mk so do not
commit changes to those files unless you want to face
their wra(i)th. |
19.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. |
19.7.5. | What is the procedure to request authorization for
merging a commit to the quarterly branch? |
| When doing the commit, add the branch name to the
MFH: line, for example: MFH: 2014Q1 It will automatically notify Ports Security Team <[email protected]> and
Ports Management Team <[email protected]>. They will then decide if the commit can be
merged and answer with the procedure. If the commit has already been made, send an email
to Ports Security Team <[email protected]> and Ports Management Team <[email protected]> with the revision
number and a small description of why the commit needs
to be merged. A script is provided to automate merging a specific
commit: ports/Tools/scripts/mfh.
It is used as follows: % /usr/ports/Tools/scripts/mfh 2015Q1 380362
U 2015Q1
Checked out revision 380443.
A 2015Q1/security
Updating '2015Q1/security/rubygem-sshkit':
A 2015Q1/security/rubygem-sshkit
A 2015Q1/security/rubygem-sshkit/Makefile
A 2015Q1/security/rubygem-sshkit/distinfo
A 2015Q1/security/rubygem-sshkit/pkg-descr
Updated to revision 380443.
--- Merging r380362 into '2015Q1':
U 2015Q1/security/rubygem-sshkit/Makefile
U 2015Q1/security/rubygem-sshkit/distinfo
--- Recording mergeinfo for merge of r380362 into '2015Q1':
U 2015Q1
--- Recording mergeinfo for merge of r380362 into '2015Q1/security':
G 2015Q1/security
--- Eliding mergeinfo from '2015Q1/security':
U 2015Q1/security
--- Recording mergeinfo for merge of r380362 into '2015Q1/security/rubygem-sshkit':
G 2015Q1/security/rubygem-sshkit
--- Eliding mergeinfo from '2015Q1/security/rubygem-sshkit':
U 2015Q1/security/rubygem-sshkit
M 2015Q1
M 2015Q1/security/rubygem-sshkit/Makefile
M 2015Q1/security/rubygem-sshkit/distinfo
Index: 2015Q1/security/rubygem-sshkit/Makefile
===================================================================
--- 2015Q1/security/rubygem-sshkit/Makefile (revision 380443)
+++ 2015Q1/security/rubygem-sshkit/Makefile (working copy)
@@ -2,7 +2,7 @@
# $FreeBSD: release/10.2.0/en_US.ISO8859-1/articles/committers-guide/article.xml 46853 2015-06-22 03:26:55Z gjb $
PORTNAME= sshkit
-PORTVERSION= 1.6.1
+PORTVERSION= 1.7.0
CATEGORIES= security rubygems
MASTER_SITES= RG
Index: 2015Q1/security/rubygem-sshkit/distinfo
===================================================================
--- 2015Q1/security/rubygem-sshkit/distinfo (revision 380443)
+++ 2015Q1/security/rubygem-sshkit/distinfo (working copy)
@@ -1,2 +1,2 @@
-SHA256 (rubygem/sshkit-1.6.1.gem) = 8ca67e46bb4ea50fdb0553cda77552f3e41b17a5aa919877d93875dfa22c03a7
-SIZE (rubygem/sshkit-1.6.1.gem) = 135680
+SHA256 (rubygem/sshkit-1.7.0.gem) = 90effd1813363bae7355f4a45ebc8335a8ca74acc8d0933ba6ee6d40f281a2cf
+SIZE (rubygem/sshkit-1.7.0.gem) = 136192
Index: 2015Q1
===================================================================
--- 2015Q1 (revision 380443)
+++ 2015Q1 (working copy)
Property changes on: 2015Q1
___________________________________________________________________
Modified: svn:mergeinfo
Merged /head:r380362
Do you want to commit? (no = start a shell) [y/n]
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
svn.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 svn.freebsd.org # Can be *.freebsd.org
User freebsd-login |