4.7.1. Quick Porting

This section tells you how to do a quick port. In many cases, it is not enough, but we will see.

First, get the original tarball and put it into ${DISTDIR}, which defaults to /usr/ports/distfiles.

Note: The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too.

4.7.1.1. Writing the Makefile

The minimal Makefile would look something like this:

 # New ports collection makefile for:	oneko
 # Version required:	1.1b
 # Date created:	5 December 1994
 # Whom:		asami
 #
 # $Id$
 #
 
 DISTNAME=	oneko-1.1b
 CATEGORIES=	games
 MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
 
 MAINTAINER=	asami@FreeBSD.ORG
 
 MAN1=		oneko.1
 MANCOMPRESSED=	yes
 USE_IMAKE=	yes
 
 .include <bsd.port.mk>

See if you can figure it out. Do not worry about the contents of the $Id$ line, it will be filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section.

4.7.1.2. Writing the description files

There are three description files that are required for any port, whether they actually package or not. They are COMMENT, DESCR, and PLIST, and reside in the pkg subdirectory.

COMMENT

This is the one-line description of the port. Please do not include the package name (or version number of the software) in the comment. Here is an example:

A cat chasing a mouse all over the screen.

DESCR

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 if you are copying from the README or manpage; too often they are not a concise description of the port or are in an awkward format (e.g. manpages have justified spacing). If the ported software has an official WWW homepage, you should list it here.

It is recommended that you sign your name at the end of this file, as in:

This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

http://www.oneko.org/

- Satoshi
asami@cs.berkeley.edu

PLIST

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 or /usr/X11R6). If you are using the MANx variables (as you should be), do not list any manpages here.

Here is a small example:

bin/oneko
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/oneko

Refer to the pkg_create(1) man page for details on the packing list. Note that you should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add @dirrm lines as necessary to remove them when the port is deleted.

It is recommended you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier.

4.7.1.3. Creating the checksum file

Just type `make makesum'. The ports make rules will automatically generate the file files/md5.

4.7.1.4. Testing the port

You should make sure that the port rules do exactly what you want it to do, including packaging up the port. These are the important points you need to verify:

• PLIST does not contain anything not installed by your port
• PLIST contains everything that is installed by your port
• your port can be installed multiple times using the reinstall target
• your port cleans up after itself upon deinstall

The recommended ordering of tests is:

1. make install
2. make package
3. make deinstall
4. pkg_add `make package-name`
5. make deinstall
6. make reinstall
7. make package

4.7.1.5. Checking your port with portlint

Please use portlint to see if your port conforms to our guidelines. The portlint program is part of the ports collection. In particular, you may want to check if the Makefile is in the right shape and the package is named appropriately.

4.7.1.6. Submitting the port

First, make sure you have read the Do's and Dont's section.

Now that you are happy with your 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 your work/ directory or the pkgname.tgz package, so delete them now. Next, simply include the output of `shar `find port_dir`' in a bug report and send it with the send-pr(1) program (see Bug Reports and General Commentary for more information about send-pr). If the uncompressed port is larger than 20KB, you should compress it into a tarfile and use uuencode(1) before including it in the bug report (uuencoded tarfiles are acceptable even if the report is smaller than 20KB but are not preferred). Be sure to classify the bug report as category `ports' and class `change-request'. (Do not mark the report `confidential'!)

One more time, do not include the original source distfile, the work/ directory, or the package you built with `make package'!

Note: in the past, we asked you to upload new port submissions in our ftp site (ftp.freebsd.org). This is no longer recommended as read access is turned off on that incoming directory of that site due to the large amount of pirated software showing up there. :<

We will look at your port, get back to you if necessary, and put it in the tree. Your name will also appear in the list of `Additional FreeBSD contributors' on the FreeBSD Handbook and other files. Isn't that great?!? :)