Pending the completion of this section, please refer to
+ documentation supplied by the Contributed by &a.jkh;.
+ Contributed by &a.jkh;, &a.gpalmer; and
+ &a.asami;. Note: Only a fraction of the overridable variables
- are mentioned in this document. Most (if not all) are
- documented at the start of the bsd.port.mk
- file which can be found in /usr/share/mk. This file
- uses a non-standard tab setting. Emacs should
- recognise the setting on loading the file. vi
- or ex can be set to using the correct value by
- typing ":set tabstop=4" once the file has been
- loaded. - &a.gpalmer;
+ Note: Only a fraction of the overridable variables are
+ mentioned in this document. Most (if not all) are documented
+ at the start of the bsd.port.mk file which can be
+ found in /usr/share/mk. This file uses a non-standard tab
+ setting. Emacs should recognise the setting on
+ loading the file. vi or ex can be set to
+ using the correct value by typing `:set tabstop=4'
+ once the file has been loaded.
- You may come across code that needs modifications or
- conditional compilation based upon what version of UNIX
- it's running under. If you need to make such changes to
- the code for conditional compilation, make sure you make
- the changes as general as possible so that we can
- back-port code to FreeBSD 1.x systems and cross-port to
- other BSD systems such as 4.4bsd from CSRG, BSD/386,
- 386BSD and NetBSD.
+ You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it's
+ running under. If you need to make such changes to the code
+ for conditional compilation, make sure you make the changes as
+ general as possible so that we can back-port code to FreeBSD
+ 1.x systems and cross-port to other BSD systems such as 4.4BSD
+ from CSRG, BSD/386, 386BSD and NetBSD.
- The preferred way to tell 4.3BSD/Reno and newer versions
- of the BSD code apart is by using the "BSD"
- macro defined in <sys/param.h>. Hopefully
- that file is already included; if not, add the code:
+ The preferred way to tell 4.3BSD/Reno and newer versions of
+ the BSD code apart is by using the `BSD' macro
+ defined in <sys/param.h>. Hopefully that file
+ is already included; if not, add the code:
Use sparingly:
- In the dozens of ports that have been done, there have
only been one or two cases where __FreeBSD__
should have been used. Just because an earlier port
screwed up and used it in the wrong place doesn't mean
you should do so too.
NOTE: If your sources work without change under FreeBSD,
- skip to the next section.
+ This section tells you how to do a quick port. In many
+ cases, it is not enough, but we'll see.
+
+ First, get the original tarball and put it into
+ ${DISTDIR}, which defaults to
+ /usr/ports/distfiles.
+
+ Note: The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you'll have to refer to the next section
+ too.
+
+ The minimal Makefile would look something like this:
+
+ See if you can figure it out. Don't worry about the contents
+ of the $Id$ line, it will be filled in
+ automatically by CVS when the port is imported to our main
+ ports tree.
+
+ There are three required description files that are
+ required for any port, whether they actually package or not.
+ They are COMMENT, DESCR, and
+ PLIST, and reside in the pkg subdirectory.
+
+ This is the one-line description of the port. It is
+ recommended to have the name of the package at the
+ beginning, as in:
+ This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient. Note: This is not a manual nor an
+ in-depth description on how to use or compile the port.
+ In particular, please do not just copy the README
+ file here, unless, of course, it's a concise description
+ of the port.
+
+ It is recommended that you sign the name at the end of
+ this file, and also state the version number, as in:
+
+ This file lists all the files installed by the port. It
+ is also called the `packing list' because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ /usr/local or /usr/X11R6).
+
+ Here is a small example:
+
+ Just type `make makesum'. The ports make rules
+ will automatically generate the file files/md5.
+
+ You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. Try
+ doing `make install', `make package' and
+ then `pkg_delete -d <pkgname>' and see if all
+ the files are correctly deleted. Then do a `pkg_add
+ <pkgname>.tgz' and see if everything re-appears
+ and works correctly.
+
+ Now that you're happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and
+ make everybody else happy about it too. To accomplish this,
+ pack the necessary files (everything described in this
+ section -- in particular do not include the
+ original source tarball or the `work' subdirectory)
+ into a .tar.gz file, stick it in the directory
+ 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.
+
+ 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... :>
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.
+
+ 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
+ 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).
+
+ 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.
+
+ 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).
+
+ 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).
+
+ Configuring the Makefile is pretty simple, and again I
+ Configuring the Makefile is pretty simple, and again we
suggest that you look at existing examples before
starting. 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
+ ${DISTFILE} 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
+ ${DISTFILE}${EXTRACT_SUFX}
+ by default which, if it's a normal tarball, is going to be
+ something like:
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 (some of them have different
+ names from subdirectories of /usr/ports) and pick
+ the ones that are suitable for your port. If your port
+ truly belongs to something that is different from all the
+ existing ones, you can even create a new category name.
- If your package uses imake (e.g. is an X
- application that has an Imakefile), then set
- "USE_IMAKE=yes". This will cause the
- configure stage to automatically do an xmkmf and then
- a `make Makefiles'.
+ If you want to add more information than just the category
+ names, add them to ${KEYWORDS}. The value
+ of this variable defaults to that of
+ ${CATEGORIES}. This is currently used only
+ as a field of the /usr/ports/INDEX file.
- If you have a ftp-URL pointing at the the original tarball,
+ record the directory containing the tarball in
+ ${MASTER_SITES}. This will provide a backup
+ site, as well as a direct pointer to the original source
+ location. Don't forget the trailing slash (/)!
- The make macros will currently try to use this
- specification for grabbing the distribution file with
- ${NCFTP} if they can't find it
- already on the system. See some of the other ports
- for examples.
+ The make macros will try to use this specification for
+ grabbing the distribution file with ${NCFTP}
+ if they can't 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 your port requires some additional patches that are
+ available by ftp, 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 has an extra `foozolix-1.0/' in front of the
+ filenames, then set `PATCH_DIST_STRIP=-p1'.
- Don't worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ `.gz' or `.Z'.
+
+ Set your mail-address here. Please. :)
+
+ Many ports depend on other ports. There are three
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine.
+ This variable specifies the shared libraries this port
+ depends on. It is a list of `lib:dir' pairs
+ where lib is the name of the shared library, and
+ dir is the directory in which to find it in case
+ it's not available. For example,
+ This variable specifies executables this port depends
+ on. It is a list of `exec:dir' pairs
+ where exec is the name of the executable, and
+ dir is the directory in which to find it in case
+ it's not available. For example,
+ If there is a dependency that doesn't fall into either of
+ the above two categories, or your port requires to have
+ the source of the other port extracted (i.e., having them
+ installed is not enough), then use this variable. This is
+ just a list of directories, as there is nothing to check,
+ unlike the previous two.
+
+ If your package uses GNU make, set
+ `USE_GMAKE=yes'. If your package uses GNU
+ configure, set `GNU_CONFIGURE=yes'. If
+ you want to override the default GNU configure
+ arguments from `--prefix=${PREFIX}' to
+ something else, set those arguments in
+ ${CONFIGURE_ARGS}.
+
+ If your package uses imake (e.g. is an X
+ application that has an Imakefile), 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 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}.
+
+ If the port uses imake but doesn't understand the
+ `install.man' target,
+ `NO_INSTALL_MANPAGES=yes' should be set. In
+ addition, the author of the original port should be shot.
+
+ Some software packages have restrictive licenses or are in
+ violation to the law (PKP's patent on public key crypto,
+ ITAR (export of crypto software) to name just two of them).
+ What we can do with them vary a lot, depending on the exact
+ wordings of the respective licenses.
+
+ Note that it is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project won't held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact
+ ports@freebsd.org.
+
+ We usually get around this problem by setting
+ ${NO_PACKAGE} in the Makefile, and not putting
+ the distfile up for ftp. However, for most cases, you should
+ at least be able to make a port, so don't let the license
+ scare you away!
+
+ Note: The GNU General Public License (GPL), both version 1
+ and 2, shouldn't be a problem for ports.
+
+ Note: If you are a commiter, make sure you update the
+ ports/LEGAL file too.
+
+ This section is still under construction, sorry.
+
+ 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:
+ 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
+ `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:
+ 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! :)
+
+ Here is a sample Makefile that you can use to create a new
+ port. Make sure you remove all the extra comments (ones
+ between brackets)!
+
+ It is recommended that you follow this format (ordering of
+ variables, etc.). Not all of the existing Makefiles are in
+ this format (mostly old ones), but we are trying to uniformize
+ how they look. This format is designed so that the most
+ important information is easy to locate.
+
+ The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages
+ and users are going to turn away if they hurt their eyes!
+
+ If your ${DISTNAME} does not look like
+ `<name>-<version.string.numbers>', set
+ ${PKGNAME} to something in that format.
+
+ Here are some (real) examples on how to convert a
+ ${DISTNAME} into a suitable
+ ${PKGNAME}:
+
+ If there is absolutely no trace of version information in the
+ original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to `1.0' (like the piewm example above). Otherwise, ask the
+ original author or use the date string (`yy.mm.dd') as the
+ version.
+
+ Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.
+
+ Well, now that you know how to do a port, let's go at it and
+ convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ :)