Quick PortingThis section describes how to quickly create a new port. For
applications where this quick method is not adequate, the full
Slow Porting process is described in
.First, get the original tarball and put it into
DISTDIR, which defaults to
/usr/ports/distfiles.These steps assume that the software compiled
out-of-the-box. In other words, absolutely no changes were
required for the application to work on a &os; system. If
anything had to be changed, refer to .It is recommended to set the DEVELOPER
&man.make.1; variable in /etc/make.conf
before getting into porting.&prompt.root; echo DEVELOPER=yes >> /etc/make.confThis setting enables the developer mode
that displays deprecation warnings and activates some further
quality checks on calling make.Writing the MakefileThe minimal Makefile would look
something like this:# $FreeBSD$
PORTNAME= oneko
DISTVERSION= 1.1b
CATEGORIES= games
MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
MAINTAINER= youremail@example.com
COMMENT= Cat chasing a mouse all over the screen
.include <bsd.port.mk>In some cases, the Makefile of an
existing port may contain additional lines in the header,
such as the name of the port and the date it was created.
This additional information has been declared obsolete, and
is being phased out.Try to figure it out. Do not worry about the
contents of the $FreeBSD$
line, it will be filled in automatically by
Subversion when the port is
imported to our main ports tree. A more detailed
example is shown in the
sample Makefile
section.Writing the Description FilesThere are two description files that are required for
any port, whether they actually package or not. They are
pkg-descr and
pkg-plist. Their
pkg- prefix distinguishes them from other
files.pkg-descrThis is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is
sufficient.This is not a manual or an
in-depth description on how to use or compile the port!
Please be careful when copying from the
README or manpage. Too
often they are not a concise description of the port or
are in an awkward format. For example, manpages have
justified spacing, which looks particularly bad with
monospaced fonts.On the other hand, the content of
pkg-descr must be longer than the COMMENT
line from the Makefile. It must explain in more depth what
the port is all about.A well-written pkg-descr describes
the port completely enough that users would not have to
consult the documentation or visit the website to understand
what the software does, how it can be useful, or what
particularly nice features it has. Mentioning certain
requirements like a graphical toolkit, heavy dependencies,
runtime environment, or implementation languages help users
decide whether this port will work for them.Include a URL to the official WWW homepage. Prepend
one of the websites (pick the most
common one) with WWW: (followed by single
space) so that automated tools will work correctly. If the
URI is the root of the website or directory, it must be
terminated with a slash.If the listed webpage for a port is not available, try
to search the Internet first to see if the official site
moved, was renamed, or is hosted elsewhere.This example shows how
pkg-descr looks:This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
:
(etc.)
WWW: http://www.oneko.org/pkg-plistThis file lists all the files installed by the port. It
is also called the packing list because the
package is generated by packing the files listed here. The
pathnames are relative to the installation prefix (usually
/usr/local).Here is a small example:bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpmRefer to the &man.pkg-create.8; manual page for details
on the packing list.It is recommended to keep all the filenames in
this file sorted alphabetically. It will make verifying
changes when upgrading the port much easier.Creating a packing list manually can be a very tedious
task. If the port installs a large numbers of files,
creating the packing list
automatically might save time.There is only one case when
pkg-plist can be omitted from a port.
If the port installs just a handful of files, list them in
PLIST_FILES, within the
port's Makefile. For instance, we
could get along without pkg-plist in
the above oneko port by adding these
lines to the Makefile:PLIST_FILES= bin/oneko \
man/man1/oneko.1.gz \
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
lib/X11/oneko/mouse.xpmUsage of PLIST_FILES should not be
abused. When looking for the origin of a file, people
usually try to grep through the
pkg-plist files in the ports tree.
Listing files in PLIST_FILES in the
Makefile makes that search more
difficult.If a port needs to create an empty directory, or creates
directories outside of ${PREFIX} during
installation, refer to
for more information.As PLIST_FILES is a &man.make.1; variable,
any entry with spaces must be quoted. For example, if using
keywords described in &man.pkg-create.8; and , the entry must be quoted.PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample"Later we will see how pkg-plist
and PLIST_FILES can be used to fulfill
more sophisticated
tasks.Creating the Checksum FileJust type make makesum. The ports
framework will automatically generate
distinfo. Do not try to generate the file
manually.Testing the PortMake sure that the port rules do exactly what
is desired, including packaging up the port. These
are the important points to verify:pkg-plist does not contain
anything not installed by the port.pkg-plist contains everything
that is installed by the port.The port can be installed using the
install target. This verifies
that the install script works correctly.The port can be deinstalled properly using the
deinstall target. This
verifies that the deinstall script works correctly.The port only has access to network resources during the
fetch target phase. This is
important for package builders, such as ports-mgmt/poudriere.Make sure that make package can be
run as a normal user (that is, not as
root). If that
fails, the software may need to be patched. See also and .Recommended Test Orderingmake stagemake stage-qamake packagemake installmake deinstallmake package (as user)Make certain no warnings are shown in any of
the stages.Thorough automated testing can be done with
ports-mgmt/poudriere from the
Ports Collection, see for
more information. It maintains jails where
all of the steps shown above can be tested without affecting the
state of the host system.Checking the Port with
portlintPlease use portlint to see if the port
conforms to our guidelines. The
ports-mgmt/portlint
program is part of the ports collection. In particular,
check that the
Makefile is in the
right shape and the
package is named
appropriately.Do not blindly follow the output of
portlint. It is a static lint tool and
sometimes gets things wrong.Submitting the New PortBefore submitting the new port, read the
DOs and DON'Ts
section.Once happy with the port, the only thing remaining is to
put it in the main &os; ports tree and make everybody else
happy about it too.We do not need the work directory or
the pkgname.txz package, so delete them
now.Next, create a &man.patch.1;, file.
Assuming the port is called oneko and is in
the games category.Creating a .diff for a New
PortAdd all the files with svn add.
cd to the base of the ports tree so full
paths to the changed files are included in the diff, then
generate the diff with svn diff. For
example:&prompt.user; svn add .
&prompt.user; cd ../..
&prompt.user; svn diff games/oneko > oneko.diffTo make it easier for committers to apply the patch on
their working copy of the ports tree, please generate the
.diff from the base of your ports
tree.Submit oneko.diff with the bug submission
form. Use product Ports &
Packages, component Individual Port(s),
and follow the guidelines shown there.
Add a short description of the program to the Description field
of the PR (perhaps a short version of
COMMENT), and remember to add
oneko.diff as an attachment.Giving a good description in the summary of the problem
report makes the work of port committers a lot easier. We
prefer something like New port:
category/portnameshort description of
the port for new ports. Using this
scheme makes it easier and faster to begin the work of
committing the new port.After submitting the port, please be patient. The time
needed to include a new port in &os; can vary from a few days
to a few months. A simple search form of the Problem Report
database can be searched at .To get a listing of open port
PRs, select Open and
Ports & Packages in the search form,
then click [ Search ].After looking at the new port, we will reply if necessary,
and commit it to the tree. The submitter's name will also be
added to the list of Additional
&os; Contributors and other files.It is also possible to submit ports using a &man.shar.1; file. Using
the previous example with the oneko port above.Creating a .shar for a New Portgo to the directory above where the
port directory is located, and use tar to
create the shar archive:&prompt.user; cd ..
&prompt.user; tar cf oneko.shar --format shar onekooneko.shar can then be submitted in the same way
as oneko.diff above.