20.1. Adding a New Port |
- 20.1.1. How do I add a new port?
- 20.1.2. Any other things I need to know when I add a new
port?
|
20.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 <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: # 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. |
20.2. Removing an Existing Port |
- 20.2.1. How do I remove an existing port?
|
20.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 <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. |
20.3. Re-adding a Deleted Port |
- 20.3.1. How do I re-add a deleted port?
|
20.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://repo.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://repo.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 20.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. |
20.4. Repository Copies |
- 20.4.1. When do we need a repository copy?
- 20.4.2. What do I need to do?
|
20.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 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: |
20.5. Ports Freeze |
- 20.5.1. What is a “ports freeze”?
|
20.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: 20.6.1. |
20.6. Quarterly Branches |
- 20.6.1. What is the procedure to request authorization for
merging a commit to the quarterly branch?
- 20.6.2. Are there any changes that can be merged without
asking for approval?
- 20.6.3. What is the procedure for merging commits to the
quarterly branch?
|
20.6.1. | 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 the Ports Security Team <ports-secteam@FreeBSD.org>
and the Ports Management Team <portmgr@FreeBSD.org>. 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 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: MFH: 2014Q1 (runtime fix)
MFH: 2014Q1 (browser blanket) The list of blanket approvals is available in
Q: 20.6.2. |
20.6.2. | Are there any changes that can be merged without
asking for approval? |
| The following blanket approvals for merging to the
quarterly branches are in effect: Note: This blanket approval also applies to direct
commits for ports that have been removed from
head. Important: These fixes must be
tested on the quarterly branch. Fixes that do not result in a change in contents
of the resulting package. For example: Build, runtime or packaging fixes, if the
quarterly branch version is currently broken. Missing dependencies (detected, linked against
but not registered via
*_DEPENDS Fixing shebangs,
stripping installed libraries and binaries, and
plist fixes. Backport of security and reliability fixes which
only result in PORTREVISION bumps
and no changes to enabled features. for example,
adding a patch fixing a buffer overflow. Minor version changes that do nothing but fix
security or crash-related issues. Adding/fixing
CONFLICTS. Web Browsers, browser plugins, and their
required dependencies.
|
20.6.3. | What is the procedure for merging commits to the
quarterly branch? |
| A script is provided to automate merging a specific
commit: ports/Tools/scripts/mfh.
It is used as follows: % /usr/ports/Tools/scripts/mfh 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$
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
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-loginTip: 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. % /usr/ports/Tools/scripts/mfh r407208 r407713 r407722 r408567 r408943 r410728
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]
|
20.7. Creating a New Category |
- 20.7.1. What is the procedure for creating a new
category?
- 20.7.2. What do I need to do to implement a new physical
category?
- 20.7.3. What do I need to do to implement a new virtual
category?
|
20.7.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 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. Add appropriate entries to
ports/MOVED. Update the documentation by modifying: 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. |
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: |
20.8. Miscellaneous Questions |
- 20.8.1. Are there changes that can be committed without
asking the maintainer for approval?
- 20.8.2. How do I know if my port is building correctly or
not?
- 20.8.3. I added a new port. Do I need to add it to the
INDEX?
- 20.8.4. Are there any other files I am not allowed to
touch?
- 20.8.5. What is the proper procedure for updating the
checksum for a port distfile when the file changes
without a version change?
- 20.8.6. How can an experimental test build of the ports tree
(exp-run) be requested?
|
20.8.1. | 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. Trivial and tested build
and runtime fixes. Documentations or metadata changes to ports,
like pkg-descr or
COMMENT.
Important: Exceptions to this are anything maintained by the
Ports Management Team <portmgr@FreeBSD.org>, or the Security Officer Team <security-officer@FreeBSD.org>. No
unauthorized commits may ever be made to ports
maintained by those groups. |
20.8.2. | 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
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. Go to the Bugzilla
new PR page. Select the product your patch is about. Fill in the bug report as normal. Remember to
attach the patch. If at the top it says “Show Advanced
Fields” click on it. It will now say
“Hide Advanced Fields”. Many new
fields will be available. If it already says
“Hide Advanced Fields”, no need to do
anything. In the “Flags” section, set the
“exp-run” one to ?.
As for all other fields, hovering the mouse over any
field shows more details. Submit. Wait for the build to run. Ports Management Team <portmgr@FreeBSD.org> will reply with a possible
fallout. Depending on the fallout:
If there is no fallout, the procedure stops
here, and the change can be committed, pending
any other approval required. If there is fallout, it
must be fixed, either
by fixing the ports directly in the ports
tree, or adding to the submitted
patch. When this is done, go back to step 6
saying the fallout was fixed and wait for
the exp-run to be run again. Repeat as long
as there are broken ports.
|