4.3.3. Slow Porting

Ok, so it wasn't that simple, and the port required some modifications to get it to work. In this section, we'll explain, step by step, how to modify it to get it to work with the ports paradigm.

4.3.3.1. How things work

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 don't worry if you don't really understand what bsd.port.mk is doing, not many people do... :>

1. The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in ${DISTDIR}. If fetch cannot find the required files in ${DISTDIR} it will look up the ftp-URL ${MASTER_SITES}, which is set in the Makefile. It will then attempt to fetch the named distribution file with ${NCFTP}, 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.

2. The extract target is run. It looks for your ports' distribution file in ${DISTDIR} (typically a gzip'd tarball) and unpacks it into a temporary subdirectory specified by ${WRKDIR} (defaults to work).

3. The patch target is run. First, any patches defined in ${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.

4. The configure target is run. This can do any one of many different things.
   1. If it exists, scripts/configure is run.

   2. If ${HAS_CONFIGURE} or ${GNU_CONFIGURE} is set, ${WRKSRC}/configure is run.

   3. If ${USE_IMAKE} is set, ${XMKMF} (default: `xmkmf -a') is run.

5. The build target is run. This is responsible for descending into the ports' private working directory (${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 possible, 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, and you can't 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 is 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's go through the recommended steps to create the perfect port.

4.3.3.2. Getting the original sources

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 can't find a ftp site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, we can `house' it ourselves by putting it on

ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/

If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in ${DISTDIR}. Don't worry if they come from site other than where you got the the main source tarball, we have a way to handle these situations (see the description of ${PATCHFILES} below).

4.3.3.3. Modifying the port

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.

4.3.3.4. Patching

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. This is the easiest kind of change to make as it doesn't involve any mucking around with configuration files. 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 make is done). To make fixes and upgrades easier you should avoid having more than one patch fix the same file (e.g., patch-ab and patch-ab both changing ${WRKSRC}/foobar.c).

4.3.3.5. Configuring

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.

4.3.3.6. Handling user input

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).