Here's a list of common do's and dont's that you encounter during the porting process.
Don't leave anything valuable lying around in the
`work' subdirectory, `make clean' will
nuke it completely! If you need auxiliary files
that aren't scripts or patches, put them in the subdirectory
`files' and use the post-extract target to
copy them to the `work' subdirectory.
Do install package information, i.e., the three files in
pkg. Note that these files are not used only for
packaging anymore, and are mandatory now, even if
${NO_PACKAGE} is set.
Do compress manpages and strip binaries. If the original
source already does that, fine; otherwise, you can add a
post-install rule to do it yourself. Make sure
that you check the variable NOMANCOMPRESS that the
user can set in /etc/make.conf to disable man page
compression. Here's an example:
post-install:
strip ${PREFIX}/bin/xdl
.if !defined(NOMANCOMPRESS)
gzip -9nf ${PREFIX}/man/man1/xdl.1
.endif
Use the file command on the installed executable
to check whether the binary is stripped or not. If it
doesn't say `not stripped', it is stripped.
Don't rely on custom utilities in your local configure script or anything -- they may not be there on the user's system! If you really need something else to be installed before you can work, detect this from your configure script, print a helpful message and exit with a non-zero status! At least you'll have given the user some idea of what's needed. If the custom utility or package is actually part of the ports tree, this should be dealt by the dependency mechanism of ports.
Actually, if this utility is not part of the ports tree you
should probably make a port of this utility (this is how
many of the ports made it into the tree!). Depending on
something that is not part of the main FreeBSD distribution
or the ports tree is a bad idea, and the user should be able
to go to any subdirectory of /usr/ports and type
`make' and have that port, as well as everything it
requires, built automatically.
Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release.
Don't put RCS strings in patches. CVS will mangle them
when we put the files into the ports tree, and when we check
them out again, they will come out different and the patch
will fail. RCS strings are surrounded by dollar
(`$') signs, and typically start with
`$Id' or `$RCS'.
Using the recurse (`-r') option to diff
to generate patches is fine, but please take a look at the
resulting patches to make sure you don't have any
unnecessary junk in there. In particular, diffs between two
backup files, Makefiles when the port uses imake or GNU
configure, etc., are unnecessary and should be deleted.
Also, if you had to delete a file, then you can do it in the
post-extract target rather than as part of the
patch.
Do try to make your port install relative to
${PREFIX} in your Makefiles. This will
normally be set to /usr/local, or
/usr/X11R6 if ${USE_IMAKE} or
${USE_X11} is set, though it can be
reassigned in your Makefile or in the users environment, if
need be.
Not hard-coding /usr/local anywhere in your
installation will make the port much more flexible and cater
to the needs of other sites. Note that this doesn't count
for package `packing list' files since they have their own
scheme for relocating themselves and can be left independent
of ${PREFIX} unless the package is one that
hard-codes itself to a compiled-in location.
Try to let the port put things in the right subdirectories
of ${PREFIX}. Some ports lump everything
and put it in the subdirectory with the port's name, which is
incorrect. Also, many ports put everything except binaries,
header files and manual pages in the a subdirectory of
`lib', which does not bode well with the BSD
paradigm. Many of the files should me moved to one of the
following: `etc' (setup/configuration files),
`libexec' (executables started internally),
`sbin' (executables for superusers/managers) or
`share' (architecture independent files). See
hier(7) for details, the rule governing
/usr pretty much applies to /usr/local
too.
If your port installs a shared library, add a
post-install target to your Makefile that runs
`/sbin/ldconfig -m' on the directory where the new
library is installed (usually ${PREFIX}/lib)
to register it into the shared library cache.
Also, add an @exec line to your pkg/PLIST
file so that a user who installed the package can start
using the shared library immediately. This line should
immediately follow the line for the shared library itself,
as in:
lib/libtcl.so.7.3
@exec /sbin/ldconfig -m %D/lib
Note: the `-m' option is new since 2.0.5 and 2.1.0-950726-SNAP, so don't be alarmed if it doesn't work on your machine.
Never, ever, ever add a line that says
`ldconfig' without any arguments to your Makefile
or pkg/PLIST. This will reset the shared library cache to
the contents of /usr/lib only, and will royally
screw up the user's machine ("Help, xinit doesn't run
anymore after I install this port!"). Anybody who does this
will be shot and cut into 65,536 pieces by a rusty knife and
have his liver chopped out by a bunch of crows and will
eternally rot to death in the deepest bowels of hell (not
necessarily in that order)....
Do look at existing examples and the bsd.port.mk
file before asking us questions! ;)
Do ask us questions if you have any trouble! Don't just
beat your head against a wall! :)