Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables and sections in that template to make your port easier for others to read.
Now, consider the following problems in sequence as you design your new Makefile:
Does it live in ${DISTDIR} as a standard
gzip'd tarball? If so, you can go on to the next step. If
not, you should look at overriding any of the
${EXTRACT_CMD},
${EXTRACT_BEFORE_ARGS},
${EXTRACT_AFTER_ARGS},
${EXTRACT_SUFX}, or
${DISTFILES} variables, depending on how
alien a format your port's distribution file is. (The most
common case is `EXTRACT_SUFX=.tar.Z', when the
tarball is condensed by regular compress, not gzip.)
In the worst case, you can simply create your own
`do-extract' target to override the default, though
this should be rarely, if ever, necessary.
You should set ${DISTNAME} to be the base
name of your port. The default rules expect the
distribution file list (${DISTFILES}) to be
named
${DISTNAME}${EXTRACT_SUFX}
which, if it is a normal tarball, is going to be
something like:
foozolix-1.0.tar.gz
DISTNAME=foozolix-1.0'.
The default rules also expect the tarball(s) to extract into
a subdirectory called work/${DISTNAME}, e.g.
work/foozolix-1.0/
All this behavior can be overridden, of course; it simply
represents the most common time-saving defaults. For a port
requiring multiple distribution files, simply set
${DISTFILES} explicitly. If only a subset
of ${DISTFILES} are actual extractable
archives, then set them up in
${EXTRACT_ONLY}, which will override the
${DISTFILES} list when it comes to
extraction, and the rest will be just left in
${DISTDIR} for later use.
If ${DISTNAME} does not conform to our
guidelines for a good package name, you should set the ${PKGNAME}
variable to something better. See the abovementioned
guideline for more details.
When a package is created, it is put under
/usr/ports/packages/All and links are made from one
or more subdirectories of /usr/ports/packages. The
names of these subdirectories are specified by the variable
${CATEGORIES}. It is intended to make life
easier for the user when he is wading through the pile of
packages on the ftp site or the CD-ROM. Please take a look
at the existing
categories and pick the ones that are suitable for
your port.
This list also determines where in the ports tree the port is imported. If you put more than one category here, it is assumed that the port files will be put in the subdirectory with the name in the first category. See the categories section for more discussion about how to pick the right categories.
If your port truly belongs to something that is different
from all the existing ones, you can even create a new
category name. In that case, please send mail to the FreeBSD ports mailing list
<freebsd-ports@FreeBSD.ORG>
to propose a new category.
Note that there is no error checking for category names;
`make package' will happily create a new directory
if you mistype the category name, so be careful!
Record the directory part of the ftp/http-URL pointing at
the original tarball in ${MASTER_SITES}.
Do not forget the trailing slash (/)!
The make macros will try to use this specification for
grabbing the distribution file with ${FETCH}
if they cannot find it already on the system.
It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems, and we are even planning to add support for automatically determining the closest master site and fetching from there!
If the original tarball is part of one of the following popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or Linux Sunsite, you refer to those sites in an easy compact form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the path with in the archive. Here is an example:
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications
The user can also set the MASTER_SITE_* variables in
/etc/make.conf to override our choices, and use their
favorite mirrors of these popular archives instead.
If your port requires some additional patches that are
available by ftp or http, set ${PATCHFILES}
to the names of the files and ${PATCH_SITES}
to the URL of the directory that contains them (the format
is the same as ${MASTER_SITES}).
If the patch is not relative to the top of the source tree
(i.e., ${WKRSRC}) because it contains some
extra pathnames, set ${PATCH_DIST_STRIP}
accordingly. For instance, if all the pathnames in the
patch have an extra `foozolix-1.0/' in front of the
filenames, then set `PATCH_DIST_STRIP=-p1'.
Do not worry if the patches are compressed, they will be
decompressed automatically if the filenames end with
`.gz' or `.Z'.
If the patch is distributed with some other files, such as
documentation, in a gzip'd tarball, you can't just use
${PATCHFILES}. If that is the case, add the
name and the location of the patch tarball to
${DISTFILES} and
${MASTER_SITES}. Then, from the
pre-patch target, apply the patch either by running
the patch command from there, or copying the patch file into
the ${PATCHDIR} directory and calling it
patch-<xx>. (Note the tarball will have been
extracted alongside the regular source by then, so there is
no need to explicitly extract it if it is a regular gzip'd
or compress'd tarball.) If you do the latter, take extra
care not to overwrite something that already exists in that
directory. Also do not forget to add a command to remove
the copied patch in the pre-clean target.
Set your mail-address here. Please. :)
For detailed description of the responsibility of maintainers, refer to MAINTAINER on Makefiles section.
Many ports depend on other ports. There are five variables that you can use to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies.
This variable specifies the shared libraries this port
depends on. It is a list of `lib:dir[:target]' tuples
where lib is the name of the shared library, and
dir is the directory in which to find it in case
it is not available, and target is the target to call
in that directory. For example,
LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install
graphics/jpeg subdirectory
of your ports tree to build and install it if it is not
found. The `:target' part can be omitted if it is
equal to ${DEPENDS_TARGET} (which defaults to
`install').
Note that the lib part is an argument given
to `ldconfig -r | grep -wF'. There shall be no
regular expressions in this variable.
The dependency is checked twice, once from within the
extract target and then from within the install
target. (This is to ensure that the library is available
even if the port is installed on a different machine from
where it was built.) Also, the name of the dependency is
put in to the package so that pkg_add will
automatically install it if it is not on the user's
system.
This variable specifies executables or files this port
depends on during run-time. It is a list of
`path:dir[:target]' tuples where path is the name
of the executable or file, and dir is the
directory in which to find it in case it is not
available, and `target' is the target to call in that
directory. If path starts with a slash
(/), it is treated as a file or directory and its
existence is
tested with `test -e'; otherwise, it is assumed
to be an executable, and `which -s' is used to
determine if the program exists in the user's search path.
For example,
RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
wish8.0:${PORTSDIR}/x11-toolkits/tk80
/usr/local/etc/innd'
exists, and build and install it from the
news/inn subdirectory of the ports tree if it is
not found. It will also see if an executable called
`wish8.0' is in your search path, and descend into
the x11-toolkits/tk80 subdirectory of your ports tree to
build and install it if it is not found. (Note that in
this case, `innd' is actually an executable; if
an executable is in a place that is not expected to be in
a normal user's search path, you should use the full
pathname.)
The dependency is checked from within the install
target. Also, the name of the dependency is put in to the
package so that pkg_add will automatically
install it if it is not on the user's system. The
`:target' part can be omitted if it is the same as
${DEPENDS_TARGET}.
This variable specifies executables or files this port
requires to build. Like RUN_DEPENDS, it is a
list of `path:dir[:target]' tuples. For example,
BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip
unzip', and
descend into the archivers/unzip subdirectory of
your ports tree to build and install it if it is not found.
Note that `build' here means everything from extracting to
compilation. The dependency is checked from within the
extract target. The `:target' part can be
omitted if it is the same as ${DEPENDS_TARGET}.
This variable specifies executables or files this port
requires to fetch. Like the previous two, it is a list of
`path:dir[:target]' pairs. For example,
FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2
ncftp2', and
descend into the net/ncftp2 subdirectory of
your ports tree to build and install it if it is not found.
The dependency is checked from within the fetch
target. The `:target' part can be omitted if it is the
same as ${DEPENDS_TARGET}.
If there is a dependency that does not fall into either of
the above four categories, or your port requires to have
the source of the other port extracted in addition to
having them installed, then use this variable. This is
a list of `dir[:target]', as there is nothing to check,
unlike the previous four. The `:target' part can be
omitted if it is the same as ${DEPENDS_TARGET}.
Define `USE_XLIB=yes' if your port requires the
X Window System to be installed (it is implied by
USE_IMAKE). Define `USE_GMAKE=yes' if
your port requires GNU make instead of BSD make.
Define `USE_AUTOCONF=yes' if your port requires
GNU autoconf to be run. Define `USE_QT=yes' if
your port uses the latest qt toolkit. Use
`USE_PERL5=yes' if your port requires version 5
of the perl language. (The last is especially important
since some versions of FreeBSD has perl5 as part of the
base system while others don't.)
As mentioned above, the default target to call when a
dependency is required is ${DEPENDS_TARGET}. It
defaults to `install'. This is a user variable; it
is never defined in a port's Makefile. If your port needs
a special way to handle a dependency, use the
`:target' part of the *_DEPENDS variables
instead of redefining ${DEPENDS_TARGET}.
When you type `make clean', its dependencies are
automatically cleaned too. If you do not wish this to
happen, define the variable NOCLEANDEPENDS in your
environment.
To depend on another port unconditionally, it is
customary to use the string `nonexistent' as the
first field of BUILD_DEPENDS or RUN_DEPENDS.
Use this only when you need the to get to the source of
the other port. You can often save compilation time by
specifying the target too. For instance,
BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract
Do not use `DEPENDS' unless there is no other way
the behavior you want can be accomplished. It will cause
the other port to be always built (and installed, by
default), and the dependency will go into the package as
well. If this is really what you need, I recommend you
write it as BUILD_DEPENDS and RUN_DEPENDS
instead -- at least the intention will be clear.
If your package uses GNU make, set
`USE_GMAKE=yes'. If your package uses configure,
set `HAS_CONFIGURE=yes'. If your package uses
GNU configure, set `GNU_CONFIGURE=yes' (this
implies HAS_CONFIGURE). If you want to give some extra
arguments to configure (the default argument list
`--prefix=${PREFIX}' for GNU configure and
empty for non-GNU configure), set those extra arguments in
${CONFIGURE_ARGS}. If your package uses GNU
autoconf, set `USE_AUTOCONF=yes'. This
implies GNU_CONFIGURE, and will cause autoconf to
be run before configure.
If your package is an X application that creates Makefiles
from Imakefiles using imake, then set
`USE_IMAKE=yes'. This will cause the configure
stage to automatically do an xmkmf -a. If the
`-a' flag is a problem for your port, set
`XMKMF=xmkmf'.
If the port uses imake but does not understand the
`install.man' target,
`NO_INSTALL_MANPAGES=yes' should be set. In
addition, the author of the original port should be
shot. :>
If your port's source Makefile has something else than
`all' as the main build target, set
${ALL_TARGET} accordingly. Same goes for
`install' and ${INSTALL_TARGET}.