# echo DEVELOPER=yes >> /etc/make.confThis 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 Slow Porting .
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 FreeBSD system. If anything had to be changed, refer to Slow Porting . |
|
It is recommended to set the
This setting enables the "developer mode" that displays deprecation warnings and activates some further quality checks on calling
|
The minimal Makefile would look something like this:
PORTNAME= oneko DISTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.rediris.es/sites/ftp.freebsd.org/pub/FreeBSD/ MAINTAINER= youremail@example.com COMMENT= Cat chasing a mouse all over the screen WWW= http://www.daidouji.com/oneko/ .include <bsd.port.mk>
Try to figure it out. A more detailed example is shown in the sample Makefile section.
There 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.
This 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
|
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.
|
The URL that used to be included as the last line of the pkg-descr file has been moved to the Makefile . |
This 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.xpm
Refer to the 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. The sorting should be applied after variable expansion takes place. The framework does this correctly when the package list is generated automatically . |
|
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.xpm
|
Usage of
|
|
If a port needs to create an empty directory, or creates directories outside of ${PREFIX} during installation, refer to Cleaning Up Empty Directories for more information. |
|
As
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
.
Just type
make makesum
.
The ports framework will automatically generate
distinfo
.
Do not try to generate the file manually.
Make 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
fakeroot
and
uidfix
.
make stage
make stage-qa
make package
make install
make deinstall
make 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
poudriere
for more information.
It maintains
jails
where all of the steps shown above can be tested without affecting the state of the host system.
portlint
Please 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
|
Before 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 FreeBSD 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
patch(1)
, file.
Assuming the port is called
oneko
and is in the
games
category.
Add all the files with
git add .
, then review the diff with
git diff
. For example:
% git add .
% git diff --staged
Make sure that all required files are included, then commit the change to your local branch and generate a
patch with
git format-patch
% git commit
% git format-patch origin/main
Patch generated with
git format-patch
will include author identity and email addresses, making it
easier for developers to apply (with
git am
) and give proper credit.
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 and triagers a lot easier. The expected format for new ports is "[NEW PORT] category/portname short description of the port ". 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 FreeBSD can vary from a few days to a few months. A simple search form of the Problem Report database can be searched at https://bugs.freebsd.org/bugzilla/query.cgi .
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 FreeBSD Contributors and other files.
Last modified on : February 18, 2025 by Fernando Apesteguía