## Creating a Port
## Jim Mock <>
Ok, so you're surfing the 'net and you find an app that you really like.
You decide to save yourself some time and install the port from the
ports collection instead. Whoops, there isn't a port, now what?
Well, first, compile the source and make sure it works. After that,
if you think other people will like it, you can attempt to port it for
inclusion in the ports collection yourself. As I said, make sure the
app is working properly before you attempt to make a port of it.
This article will attempt to get you on your way to creating your first
port. This example is a very simple one. It assumes that the source
compiled with no changes required for it to work on your FreeBSD box.
I may write a follow-up article to this in the next issue which will show
how to create a port that doesn't compile out of the box and requires a
patch in order to compile.
Note:��The URLs in this article may change by
the time you read this as the Handbook is updated daily. If the URL isn't
valid, you can always get to it by going to the Handbook table of contents
at .
Creating the Port
The first thing you'll need to do is get the original tarball and put it
in the ${DISTDIR}, which is /usr/ports/distfiles by default.
First, create a directory for the port. It doesn't really matter where
you create it, but you'll need it because that's where the Makefile and
other things needed for the port will go. I have a directory in my home
directory.. /home/jim/freebsd/ports. I put ports that I'm working on
there. This port in particular is in /home/jim/freebsd/ports/wmpinboard.
The next thing you need to do is create a Makefile. To do so, cd to the
directory and type pico Makefile, replacing pico with the editor of your
choice.
Writing the Makefile
Here's an example Makefile:
# New ports collection makefile for: wmpinboard
# Version required: 0.7
# Date created: 17 January 1999
# Whom: Jim Mock <[email protected]>
#
# $Id$
#
DISTNAME= wmpinboard-0.7
CATEGORIES= misc deskutils
MASTER_SITES= http://www.tu-ilmenau.de/~gomar/stuff/wmpinboard/
MAINTAINER= [email protected]
LIB_DEPENDS= Xpm.4:${PORTSDIR}/graphics/xpm
WRKSRC= ${WRKDIR}/wmpinboard.app
USE_IMAKE= yes
NO_INSTALL_MANPAGES= yes
do-install:
${INSTALL_PROGRAM} ${WRKSRC}/wmpinboard ${X11BASE}/bin
.include <bsd.port.mk>
Don't worry about the $Id$ line. It's filled out automatically
when the port is imported into the ports tree.
Here's an explanation of the above. Comments are below each line.
# New ports collection makefile for: wmpinboard
The above line is the header. It's there to make it easy to identify
the port.
# Version required: 0.7
This should be changed to the new version whenever a port is upgraded.
# Date created: 17 January 1999
This is the date the Makefile was originally created. Don't change this
line if updating a port.
# Whom: Jim Mock <[email protected]>
This is the person who wrote the original Makefile and did the original
port. This should not be changed if upgrading a port.
#
# $Id$
#
Leave this as is. It will be replaced with an ID string by CVS when the
port is committed to the repository.
DISTNAME= wmpinboard-0.7
CATEGORIES= misc deskutils
MASTER_SITES= http://www.tu-ilmenau.de/~gomar/stuff/wmpinboard/
These three sections are to describe the port itself and where the tarball
should be fetched from. The DISTNAME is the name of the tarball (before
the .tar.gz extension) it always comes first, followed by package name (if
necessary). The second example will show this. CATEGORIES are the categories
the port should be put into in the ports tree. This port falls into two
categories, misc, and deskutils. MASTER_SITES is the ftp site(s) (or web
server as in this case) where the tarball can be found. This can have
multiple entries.
MAINTAINER= [email protected]
This is mandatory. It's the email address of a person that users can contact
for questions and or bug reports. This person should be the porter or someone
who can forward questions to the original porter promptly. If you really
don't want your email address here, use the ports mailing list address
([email protected]).
LIB_DEPENDS= Xpm.4:${PORTSDIR}/graphics/xpm
The dependencies can be empty if your port doesn't depend on another in order
to build or run. In this case, wmpinboard depends on xpm.
WRKSRC= ${WRKDIR}/wmpinboard.app
The WRKSRC is used if the tarball is extracted to something other than the
${DISTNAME}. In this case it uncompresses to a wmpinboard.app directory
instead of wmpinboard-0.7.
USE_IMAKE= yes
This is used if it's an X application and requires 'xmkmf -a' to be run.
NO_INSTALL_MANPAGES= yes
This is for ports using imake that don't like the install.man target.
do-install:
${INSTALL_PROGRAM} ${WRKSRC}/wmpinboard ${X11BASE}/bin
This tells where to install the wmpinboard binary. It takes it from the
${WRKSRC} directory (which is the work directory inside the port directory
that's created when make is run), and in this case installs it to
${X11BASE}/bin (/usr/X11R6/bin, /usr/X11R6 is the X11BASE).
.include <bsd.port.mk>
This goes at the end of every Makefile for any ports.
For more detailed examples, you can look at the Makefiles for the ports
in /usr/ports, and at bsd.port.mk in either /usr/share/mk or /usr/ports/Mk
depending on when you last updated your ports collection.
Writing the description files
Each port requires three description files. They are COMMENT, DESCR, and
PLIST. Each should be created in a pkg subdirectory of the port
directory. For example, /home/jim/freebsd/ports/wmpinboard/pkg.
COMMENT
This is a one line description of the port. Please don't include the
package name or version number of the software in the COMMENT. Here's the
one I used for wmpinboard:
Post-it notes for the WindowMaker dock or AfterStep Wharf.
DESCR
This is a longer description of the port. A few paragraphs that explain
what the port does is plenty (most are only a paragraph or so). This
isn't a manual or a detailed description on how to use or compile the
port. If the port has an official homepage, you should list it here.
It's also recommended that you sign the end of the DESCR file. Here's the
DESCR from the port of aterm I did:
aterm is a color vt102 terminal emulator, based on rxvt 2.4.8 with
additions for fast transparency.
It was created with AfterStep users in mind, but is not tied to
any libraries, and can be used anywhere.
- Jim <[email protected]>
PLIST
This file lists all of the files installed by the port. It's also called
the 'packing list' because the package is created by packing the files
listed in PLIST. The pathnames are relative to the installation prefix
(usually /usr/local or /usr/X11R6). Don't list any man pages here. Here's
an example from the ascd port I did:
bin/ascd
share/doc/ascd/README
@dirrm share/doc/ascd
Looking at the man page for pkg_create(1) will give you more details on
packing lists. Be sure to list all the files, but not the name
directories in the list. Also, if the port creates directories during the
installation, use @dirrm lines to remove them when the port is deleted.
It's also recommended that you keep the files listed alphabetically
because it makes upgrading the port much easier.
Creating the checksum file
To create the checksum for your port, be sure the tarball is in
/usr/ports/distfiles and that you're in the port directory. Once you've
assured the tarball is there, and you're where you should be, type
'make makesum'. The port will then generate a files directory with the
md5 checksum file in it.
Testing your port
You should always test your port before submitting it. It's a good idea
to have other people to test it as well to see if there's any problems.
I've had ports compile fine on my box, but when others tested them they
were broken. It's very easy to miss dependencies if you already have the
dependency installed, so the more people who test your port, the more
likely the chances of finding an error are.
Make sure that the port rules do exactly what you want them to do,
including creating the package. Here are the important things to verify:
PLIST doesn't contact anything not installed by your port
PLIST contains everything installed by your port
your port can be installed multiple times using make reinstall
your port cleans up after itself when make deinstall is run
This is the recommended order of testing:
1) make install
2) make package
3) make deinstall
4) pkg_add 'package-name'
5) make deinstall
6) make reinstall
7) make package
Make sure there aren't any warning issued in any of the package and
deinstall stages. After doing step 3, make sure any directories created
by the port are deleted, and after doing step 4, try running the software
to make sure it works correctly if installed from a package.
Using portlint to check your port
It's always a very good idea to run portlint on your port to make sure no
errors are found. You can find portlint in the ports collection in
/usr/ports/devel/portlint. Be sure there are no error generated when
running portlint. If there are, please correct them before submitting the
port.
Submitting the port
Once you're satisfied that your port works, the only thing left to do is
to get it put into the ports tree. When submitting a port, the work
directory or the package-name.tgz are NOT needed. Please delete them
before performing the next step. Also, please read the
.
Once you've deleted the package, and run make clean to remove the work
directory, run "shar `find port_dir` and include the output in a bug
report and send it in using send-pr. See the man page for send-pr(1) for
more info on send-pr. I usually redirect the output of shar to a text
file that I import into the bug report, like so:
[jim@corp:~/freebsd/ports]$ shar `find wmdate` > wmdate.txt
It makes it much easier to include in the bug report if you can just
import it as a text file. If the uncompressed port is larger than 20KB,
you should compress it into a tarball and use uuencode(1) before including
it in the bug report. Be sure to classify the bug report as category
'ports' and class 'change-request'. Do NOT mark the report 'confidential'!
To recap, don't include the orignal source tarball from
/usr/ports/distfiles, the work directory, or the package.
Once your port is submitted, it will be looked at, and if all is ok, it
will be put into the ports tree. You'll also get your name listed in the
list of 'Additional FreeBSD contributors' in the Handbook.. pretty cool
dontcha think? =)
That's all there is to it. I suggest starting with something simple (most
of the dockapps for WindowMaker are a good place to start, they're pretty
easy), and work your way up to more difficult ports once you start to get
the hang of it. As always, the docs in the Handbook, the existing ports
(you've got over 2,000 Makefiles to use as examples if you have the ports
collection installed), and the bsd.port.mk file are your friend. It's
also a good idea to subscribe to the ports mailing list ([email protected])
and post questions if you really get stuck. Please read through the
documentation first though.. you might be able to answer your own
question.
Happy porting,
- Jim
Return to Issue #3
|