Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm.
First, this is the sequence of events which occurs when the
user first types `make
' in your port's directory,
and you may find that having bsd.port.mk
in another
window while you read this really helps to understand it.
But do not worry if you do not really understand what
bsd.port.mk
is doing, not many people
do... :>
${DISTDIR}
. If fetch cannot
find the required files in ${DISTDIR}
it
will look up the URL ${MASTER_SITES}
,
which is set in the Makefile, as well as our main ftp
site at ftp://ftp.freebsd.org/pub/FreeBSD/ports/distfiles/,
where we put sanctioned distfiles as backup. It will then
attempt to
fetch the named distribution file with
${FETCH}
, assuming that the requesting
site has direct access to the Internet. If that succeeds,
it will save the file in ${DISTDIR}
for
future use and proceed.
${DISTDIR}
and unpacks it into a temporary
subdirectory specified by ${WRKDIR}
(defaults to work
).
${PATCHFILES}
are applied. Second, if
any patches are found in ${PATCHDIR}
(defaults to the patches
subdirectory), they are
applied at this time in alphabetical order.
scripts/configure
is run.
${HAS_CONFIGURE}
or
${GNU_CONFIGURE}
is set,
${WRKSRC}/configure
is run.
${USE_IMAKE}
is set,
${XMKMF}
(default: `xmkmf
-a
') is run.
${WRKSRC}
) and building it. If
${USE_GMAKE}
is set, GNU make
will be used, otherwise the system make
will be
used.
The above are the default actions. In addition, you can
define targets `pre-<something>
' or
`post-<something>
', or put scripts with those
names, in the scripts
subdirectory, and they will
be run before or after the default actions are done.
For example, if you have a post-extract
target
defined in your Makefile, and a file pre-build
in
the scripts
subdirectory, the
post-extract
target will be called after the
regular extraction actions, and the pre-build
script will be executed before the default build rules are
done. It is recommended that you use Makefile targets if
the actions are simple enough, because it will be easier for
someone to figure out what kind of non-default action the
port requires.
The default actions are done by the bsd.port.mk
targets `do-<something>
'. For example, the
commands to extract a port are in the target
`do-extract
'. If you are not happy with the
default target, you can fix it by redefining the
`do-<something>
' target in your Makefile.
Note that the `main' targets (e.g., extract
,
configure
, etc.) do nothing more than make sure all
the stages up to that one are completed and call the real
targets or scripts, and they are not intended to be
changed. If you want to fix the extraction, fix
do-extract
, but never ever touch extract
!
Now that you understand what goes on when the user types
`make
', let us go through the recommended steps to
create the perfect port.
Get the original sources (normally) as a compressed tarball
(<foo>.tar.gz
or <foo>.tar.Z
)
and copy it into ${DISTDIR}
. Always use
mainstream sources when and where you can.
If you cannot find a ftp/http site that is well-connected
to the net, or can only find sites that have irritatingly
non-standard formats, you might want to put a copy on a
reliable ftp or http server that you control (e.g., your
home page). Make sure you set MASTER_SITES
to
reflect your choice.
If you cannot find somewhere convenient and reliable to put
the distfile (note that if you are a FreeBSD committer, you
can just put it in the public_html
directory on
freefall), we can `house' it ourselves by putting it on
ftp://ftp.freebsd.org/pub/FreeBSD/ports/distfiles/LOCAL_PORTS/
as the last resort. Please refer to this location as
${MASTER_SITE_LOCAL}
. Send mail to the FreeBSD ports mailing list
<freebsd-ports@FreeBSD.ORG>
if you are not sure what to do.
If your port's distfile changes all the time for no good
reason, consider putting the distfile in your home page and
listing it as the first MASTER_SITES
. This will
prevent users from getting `checksum mismatch' errors, and
also reduce the workload of maintainers of our ftp site.
Also, if there is only one master site for the port, it is
recommended that you house a backup at your site and list it
as the second MASTER_SITES
.
If your port requires some additional `patches' that are
available on the Internet, fetch them too and put them in
${DISTDIR}
. Do not worry if they come from
a site other than where you got the main source tarball,
we have a way to handle these situations (see the
description of
${PATCHFILES} below).
Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition or modification of files should be doable using an automated script or patch file when your port is finished.
If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as `plug-and-play' as possible for the end-user while using a minimum of disk space.
Note: Unless explicitly stated, patch files, scripts, and other files you have created and contributed to the FreeBSD ports collection are assumed to be covered by the standard BSD copyright conditions.
In the preparation of the port, files that have been added
or changed can be picked up with a recursive diff for later
feeding to patch. Each set of patches you wish to apply
should be collected into a file named
`patch-<xx>
' where <xx>
denotes the sequence in which the patches will be applied --
these are done in alphabetical order, thus
`aa
' first, `ab
' second and so on. These
files should be stored in ${PATCHDIR}
, from
where they will be automatically applied. All patches
should be relative to ${WRKSRC}
(generally
the directory your port's tarball unpacks itself into, that
being where the build is done). To make fixes and upgrades
easier, you should avoid having more than one patch fix the
same file (e.g., patch-aa and patch-ab both changing
${WRKSRC}
/foobar.c).
Include any additional customization commands to your
configure
script and save it in the
`scripts
' subdirectory. As mentioned above, you
can also do this as Makefile targets and/or scripts with the
name pre-configure
or post-configure
.
If your port requires user input to build, configure or
install, then set IS_INTERACTIVE
in your Makefile.
This will allow `overnight builds' to skip your port if the
user sets the variable BATCH
in his environment
(and if the user sets the variable INTERACTIVE
,
then only those ports requiring interaction are
built).
It is also recommended that if there are reasonable
default answers to the questions, you check the
PACKAGE_BUILDING
variable and turn off the interactive
script when it is set. This will allow us to build the
packages for CD-ROMs and ftp.