Chapter 4. Slow Porting

First, this is the sequence of events which occurs when the user first types make in the port’s directory. Having bsd.port.mk in another window while reading this really helps to understand it.

But do not worry, not many people understand exactly how bsd.port.mk is working…​ :-)

The above are the default actions. In addition, 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 there is a post-extract target defined in the Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and pre-build will be executed before the default build rules are done. It is recommended to 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 do-something targets from bsd.port.mk. For example, the commands to extract a port are in the target do-extract. If the default target does not do the job right, redefine the do-something target in the Makefile.

Now that what goes on when the user types make install is better understood, 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.bz2) and copy it into DISTDIR. Always use mainstream sources when and where possible.

Set the variable MASTER_SITES to reflect where the original tarball resides. Shorthand definitions exist for most mainstream sites in bsd.sites.mk. Please use these sites-and the associated definitions-if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved. See MASTER_SITES for details.

If there is no FTP/HTTP site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, put a copy on a reliable FTP or HTTP server (for example, a home page).

If a convenient and reliable place to put the distfile cannot be found, we can "house" it ourselves on ftp.FreeBSD.org; however, this is the least-preferred solution. The distfile must be placed into ~/public_distfiles/ of someone’s freefall account. Ask the person who commits the port to do this. This person will also set MASTER_SITES to LOCAL/username where username is their FreeBSD cluster login.

If the port’s distfile changes all the time without any kind of version update by the author, consider putting the distfile on a home page and listing it as the first MASTER_SITES. Try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting a specific version 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 to house a backup on a home page and list it as the second MASTER_SITES.

If the port requires 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 the main source tarball comes, 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 steps, as they will be needed to automate the process shortly. Everything, including the deletion, addition, or modification of files has to be doable using an automated script or patch file when the port is finished.

If the port requires significant user interaction/customization to compile or install, take a look at one of Larry Wall’s classic Configure scripts and perhaps do something similar. 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.

In the preparation of the port, files that have been added or changed can be recorded with diff(1) for later feeding to patch(1). Doing this with a typical file involves saving a copy of the original file before making any changes using a .orig suffix.

After all changes have been made, cd back to the port directory. Use make makepatch to generate updated patch files in the files directory.

Include any additional customization commands in the configure script and save it in the scripts subdirectory. As mentioned above, it is also possible do this with Makefile targets and/or scripts with the name pre-configure or post-configure.

If the port requires user input to build, configure, or install, set IS_INTERACTIVE in the Makefile. This will allow "overnight builds" to skip it. If the user sets the variable BATCH in their environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are built). This will save a lot of wasted time on the set of machines that continually build ports (see below).

It is also recommended that if there are reasonable default answers to the questions, PACKAGE_BUILDING be used to turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP.