Welcome to the FreeBSD 2.X FAQ!
As is usual with Usenet FAQs, this document aims to cover the most
frequently asked questions concerning the FreeBSD operating system
(and of course answer them!). Although originally intended to reduce
bandwidth and avoid the same old questions being asked over and over
again, FAQs have become recognized as valuable information resources.
Every effort has been made to make this FAQ as informative as
possible; if you have any suggestions as to how it may be improved,
please feel free to mail them to the Briefly, FreeBSD 2.X is a UN*X-like operating system based on
U.C. Berkeley's 4.4BSD-lite release for the i386 platform. It is
also based indirectly on William Jolitz's port of U.C. Berkeley's
Net/2 to the i386, known as 386BSD, though very little of the 386BSD
code remains. A fuller description of what FreeBSD is and how
it can work for you may be found on the FreeBSD is used by companies, Internet Service Providers, researchers,
computer professionals, students and home users all over the world
in their work, education and recreation. See some of them in the
For more detailed information on FreeBSD, please see the
The goals of the FreeBSD Project are to provide software that may
be used for any purpose and without strings attached. Many of us
have a significant investment in the code (and project) and would
certainly not mind a little financial compensation now and then,
but we're definitely not prepared to insist on it. We believe
that our first and foremost "mission" is to provide code to any
and all comers, and for whatever purpose, so that the code gets
the widest possible use and provides the widest possible benefit.
This is, we believe, one of the most fundamental goals of Free
Software and one that we enthusiastically support.
That code in our source tree which falls under the GNU Public License
(GPL) or GNU Library Public License (GLPL) comes with slightly more
strings attached, though at least on the side of enforced
access rather than the usual opposite. Due to the additional
complexities that can evolve in the commercial use of GPL software,
we do, however, endeavor to replace such software with submissions
under the more relaxed BSD copyright whenever possible.
For those of our readers whose first language is not English, it
may be worth pointing out that the word ``free'' is being used in two
ways here, one meaning ``at no cost'', the other meaning ``you can do
whatever you like''. Apart from one or two things you
Version Briefly explained, This is not to say that a 3.0-STABLE release is unusable for
business services, and many people who need some 3.0 specific feature
(newer compiler technology, faster networking code, etc) have decided
to take a chance with it with very good results. We simply do not
wish to "certify" 3.0 as mission-worthy until it's been released
as 3.1-RELEASE in February, 1999.
If you are not familiar with the operating system or are not
capable of identifying the difference between a real problem and
a temporary problem, you should not use FreeBSD-current. This
branch sometimes evolves quite quickly and can be un-buildable
for a number of days at a time. People that use FreeBSD-current
are expected to be able to analyze any problems and only report them
if they are deemed to be mistakes rather than ``glitches''. Questions
such as ``make world produces some error about groups'' on the
-current mailing list are sometimes treated with contempt.
Every now and again, a No claims are made that any snapshot can be considered
``production quality'' for any purpose. For stability
and tested mettle, you will have to stick to full releases.
Snapshot releases are directly available from Back when FreeBSD 2.0.5 was released, we decided to branch FreeBSD
development into two parts. One branch was named The -current branch is slowly progressing towards 4.0 and beyond,
the previous 2.2-stable branch having just retired with the release
of 2.2.8. 3.0-stable has now replaced it, the next release coming
up with 3.1 in early 1999. 4.0-current is now the "current branch",
with the first 4.0 releases appearing in Q1 2000.
As a general principle, the FreeBSD core team only release a new
version of FreeBSD when they believe that there are sufficient new
features and/or bug fixes to justify one, and are satisfied that the
changes made have settled down sufficiently to avoid compromising the
stability of the release. Many users regard this caution as one of
the best things about FreeBSD, although it can be a little
frustrating when waiting for all the latest goodies to become
available...
Releases are made about every 4 months on average.
For people needing (or wanting) a little more excitement, there are
SNAPs released more frequently, particularly during the month or so
leading up to a release.
FreeBSD 3.x currently runs on the The key decisions concerning the FreeBSD project, such as the
overall direction of the project and who is allowed to add code to
the source tree, are made by a However, most non-trivial changes are discussed in advance in the
, and there are no restrictions
on who may take part in the discussion.
Every significant release of FreeBSD is available via anonymous ftp
from the FreeBSD is also available via CDROM, from the following place(s):
Walnut Creek CDROM In Australia, you may find it at:
Advanced Multimedia Distributors You can find full information in the You can find full information in the Yes, most major IRC networks host a FreeBSD chat
channel:
Each of these channels are distinct and are not connected to
each other. Their chat styles also differ, so you may need to try
each to find one suited to your chat style. As with *all* types
of IRC traffic, if you're easily offended or can't deal with lots
of young people (and more than a few older ones) doing the verbal
equivalent of jello wrestling, don't even bother with it.
There is a FreeBSD Documentation Project which you may contact (or
even better, join) on the doc mailing list:
A FreeBSD ``handbook'' is available, and can be found as:
The definitive printed guide on FreeBSD is ``The Complete FreeBSD'',
written by Greg Lehey and published by Walnut Creek CDROM Books. Now
in its second edition, the book contains 1,750 pages of install &
system administration guidance, program setup help, and manual pages.
The book (and current FreeBSD release) can be ordered from
However, as FreeBSD 2.2.X is based upon Berkeley 4.4BSD-Lite2, most
of the 4.4BSD manuals are applicable to FreeBSD 2.2.X. O'Reilly
and Associates publishes these manuals:
A description of these can be found via WWW as:
For a more in-depth look at the 4.4BSD kernel organization,
you can't go wrong with:
McKusick, Marshall Kirk, Keith Bostic, Michael J Karels,
and John Quarterman. The Design and Implementation of the 4.4BSD Operating
System. Reading, Mass. : Addison-Wesley, 1996. A good book on system administration is:
Evi Nemeth, Garth Snyder, Scott Seebass & Trent R. Hein, The Problem Report database of all open user change requests
may be queried (or submitted to) by using our web-based PR
The up-to-date FAQ is available from the FreeBSD Web Server or any
mirror as PostScript and plain text (7 bit ASCII and 8-bit Latin1).
As PostScript (about 370KB):
As ASCII text (about 220KB):
As ISO 8859-1 text (about 220KB):
The up-to-date Handbook is available from the FreeBSD Web Server or any
mirror as PostScript and plain text (7 bit ASCII and 8-bit Latin1).
As PostScript (about 1.7MB):
As ASCII text (about 1080KB):
As ISO 8859-1 text (about 1080KB):
True, the ASCII and Latin1 versions of the FAQ and Handbook aren't
strictly plaintext; they contain underlines and overprints that
assume the output is going directly to a dot matrix printer. If you
need to reformat them to be human-readable, run the file through col:
Certainly! There are multiple ways to mirror the Web pages.
Well, we can't pay, but we might arrange a free CD or T-shirt and a
Contributor's Handbook entry if you submit a translation of the
documentation.
The following newsgroups contain pertinent discussion for FreeBSD
users:
Web resources:
The FreeBSD handbook also has a fairly complete
Contributed by &a.jkh;.
FreeBSD-current is, quite literally, nothing more than a daily
snapshot of the working sources for FreeBSD. These include work in
progress, experimental changes and transitional mechanisms that may or
may not be present in the next official release of the software.
While many of us compile almost daily from FreeBSD-current sources,
there are periods of time when the sources are literally un-compilable.
These problems are generally resolved as expeditiously as possible,
but whether or not FreeBSD-current sources bring disaster or greatly
desired functionality can literally be a matter of which part of any
given 24 hour period you grabbed them in!
FreeBSD-current is aimed at 3 primary interest groups:
Members of the FreeBSD group who are actively working on some
part of the source tree and for whom keeping `current' is an
absolute requirement.
Members of the FreeBSD group who are active testers,
willing to spend time working through problems in order to
ensure that FreeBSD-current remains as sane as possible. These
are also people who wish to make topical suggestions on changes
and the general direction of FreeBSD.
Peripheral members of the FreeBSD (or some other) group who merely
wish to keep an eye on things and use the current sources for
reference purposes (e.g. for reading, not running). These
people also make the occasional comment or contribute code.
A fast-track to getting pre-release bits because you heard there
is some cool new feature in there and you want to be the first on
your block to have it.
A quick way of getting bug fixes.
In any way ``officially supported'' by us.
We do our best to help people genuinely in one of the 3
``legitimate'' FreeBSD-current categories, but we simply do not
have the time to provide tech support for it.
This is not because we are mean and nasty people who do not like
helping people out (we would not even be doing FreeBSD if we were),
it is literally because we cannot answer 400 messages a day
and actually work on FreeBSD! I am sure that, if given
the choice between having us answer lots of questions or continuing to
improve FreeBSD, most of you would vote for us improving it.
Join the &a.current and the &a.cvsall .
This is not just a good idea, it is essential.
If you are not on the FreeBSD-current mailing list, you
will not see the comments that people are making about the
current state of the system and thus will probably end up stumbling
over a lot of problems that others have already found and
solved. Even more importantly, you will miss out on important
bulletins which may be critical to your system's continued health.
The cvs-all mailing list also allows you to see the commit log
entry for each change as it is made, along with any pertinent
information on possible side-effects, and is another good mailing list
to subscribe to.
To join these lists, send mail to &a.majordomo and specify:
Grab the sources from ftp.FreeBSD.ORG. You can do this in
one of three ways:
Use the facility. Unless you
have a good TCP/IP connection at a flat rate, this is
the way to do it.
Be active! If you are running FreeBSD-current, we want to know
what you have to say about it, especially if you have suggestions
for enhancements or bug fixes. Suggestions with accompanying code
are received most enthusiastically!
Contributed by &a.jdp;.
CVSup is a software package for distributing and updating source
trees from a master CVS repository on a remote server host. The
FreeBSD sources are maintained in a CVS repository on a central
development machine in California. With CVSup, FreeBSD users can
easily keep their own source trees up to date.
CVSup uses the so-called pull model of updating. Under the pull
model, each client asks the server for updates, if and when they are
wanted. The server waits passively for update requests from its
clients. Thus all updates are instigated by the client. The server
never sends unsolicited updates. Users must either run the CVSup client
manually to get an update, or they must set up a cron job to run it
automatically on a regular basis.
The term "CVSup", capitalized just so, refers to the entire software
package. Its main components are the client "cvsup" which runs on each
user's machine, and the server "cvsupd" which runs at each of the
FreeBSD mirror sites.
As you read the FreeBSD documentation and mailing lists, you may
see references to sup. Sup was the predecessor of CVSup,
and it served a similar purpose. CVSup is in used in much the same
way as sup and, in fact, uses configuration files which are
backward-compatible with sup's. Sup is no longer used in the FreeBSD
project, because CVSup is both faster and more flexible.
The easiest way to install CVSup if you are running FreeBSD 2.2 or
later is to use either If you are running FreeBSD-2.1.6 or 2.1.7, you unfortunately cannot use the
binary package versions due to the fact that it requires a version of
the C library that does not yet exist in FreeBSD-2.1.{6,7}. You can easily
-use Because CVSup is written in The Modula-3 libraries are rather large, and fetching and compiling
them is not an instantaneous process. For that reason, a third option
is provided. You can get statically linked FreeBSD
executables for CVSup from the USA distribution site:
Most users will need only the client. These executables are entirely
self-contained, and they will run on any version of FreeBSD from
FreeBSD-2.1.0 to FreeBSD-current.
In summary, your options for installing CVSup are:
CVSup's operation is controlled by a configuration file called the
"supfile". Beginning with FreeBSD-2.2, there are some sample supfiles
in the directory The information in a supfile answers the following questions for cvsup:
In the following sections, we will construct a typical supfile by
answering each of these questions in turn. First, we describe the
overall structure of a supfile.
A supfile is a text file. Comments begin with "#" and extend to
the end of the line. Lines that are blank and lines that contain only
comments are ignored.
Each remaining line describes a set of files that the user wishes
to receive. The line begins with the name of a "collection", a
logical grouping of files defined by the server. The name of the
collection tells the server which files you want. After the
collection name come zero or more fields, separated by white space.
These fields answer the questions listed above. There are two types
of fields: flag fields and value fields. A flag field consists of a
keyword standing alone, e.g., "delete" or "compress". A value field
also begins with a keyword, but the keyword is followed without
intervening white space by "=" and a second word. For example,
"release=cvs" is a value field.
A supfile typically specifies more than one collection to receive.
One way to structure a supfile is to specify all of the relevant
fields explicitly for each collection. However, that tends to make
the supfile lines quite long, and it is inconvenient because most
fields are the same for all of the collections in a supfile. CVSup
provides a defaulting mechanism to avoid these problems. Lines
beginning with the special pseudo-collection name "*default" can be
used to set flags and values which will be used as defaults for the
subsequent collections in the supfile. A default value can be
overridden for an individual collection, by specifying a different
value with the collection itself. Defaults can also be changed or
augmented in mid-supfile by additional "*default" lines.
With this background, we will now proceed to construct a supfile
for receiving and updating the main source tree of .
You are now ready to try an update. The command line for doing this is
quite simple:
where "supfile" is of course the name of the supfile you have just created.
Assuming you are running under X11, cvsup will display a GUI window with
some buttons to do the usual things. Press the "go" button, and watch
it run.
Since you are updating your actual "/usr/src" tree in this example, you
will need to run the program as root so that cvsup has the permissions
it needs to update your files. Having just created your configuration
file, and having never used this program before, that might
understandably make you nervous. There is an easy way to do a trial run
without touching your precious files. Just create an empty directory
somewhere convenient, and name it as an extra argument on the command
line:
The directory you specify will be used as the destination directory
for all file updates. CVSup will examine your usual files in
"/usr/src", but it will not modify or delete any of them. Any file
updates will instead land in "/var/tmp/dest/usr/src". CVSup will also
leave its base directory status files untouched when run this way.
The new versions of those files will be written into the specified
directory. As long as you have read access to "/usr/src", you do not
even need to be root to perform this kind of trial run.
If you are not running X11 or if you just do not like GUIs, you
should add a couple of options to the command line when you run cvsup:
The "-g" tells cvsup not to use its GUI. This is automatic if you are
not running X11, but otherwise you have to specify it.
The "-L 2" tells cvsup to print out the details of all the file updates
it is doing. There are three levels of verbosity, from "-L 0" to "-L 2".
The default is 0, which means total silence except for error messages.
There are plenty of other options available. For a brief list of them,
type "cvsup -H". For more detailed descriptions, see the manual page.
Once you are satisfied with the way updates are working, you can arrange
for regular runs of cvsup using cron(8). Obviously, you should not let
cvsup use its GUI when running it from cron.
The file collections available via CVSup are organized
hierarchically. There are a few large collections, and they are
divided into smaller sub-collections. Receiving a large collection
is equivalent to receiving each of its sub-collections.
The hierarchical relationships among collections are reflected by
the use of indentation in the list below.
The most commonly used collections are
Most FreeBSD-related discussion of CVSup takes place on the
&a.hackers;. New versions of the software are announced there, as
well as on the &a.announce;.
Questions and bug reports should be addressed to the author of the
program at FreeBSD is available on CD-ROM from Walnut Creek CDROM:
The official sources for FreeBSD are available via anonymous FTP from:
The Additionally, FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain FreeBSD via
anonymous FTP, please try to use a site near you.
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
.
/FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain CTM via
anonymous FTP, please try to use a site near you.
In case of problems, please contact &a.phk;.
servers for FreeBSD are running at
the following sites:
The following CVSup site is especially designed for users. Unlike the other CVSup mirrors, it is kept
up-to-date by CTM. That means if you CVSup cvs-all with
release=cvs from this site, you get a version of the
repository (including the inevitable .ctm_status file)
which is suitable for being updated using the CTM cvs-cur
deltas. This allows users who track the entire cvs-all
tree to go from CVSup to CTM without having to rebuild their
repository from scratch using a fresh CTM base delta.
Please note that this special feature only works for the
cvs-all distribution with cvs as the release tag.
CVSupping any other distribution and/or release will get you the
specified distribution, but it will not be suitable for CTM updating.
Also please note that, because the current version of CTM does
not preserve the timestamps of files, the timestamps at this mirror
site are not the same as those at other mirror sites. Switching
between this site and other sites is not recommended. It will work
correctly, but will be somewhat inefficient.
AFS servers for FreeBSD are running at
the following sites:
Contributed by &a.jkh;, &a.gpalmer;, &a.asami;, &a.obrien; and
&a.hoek;. So, now you are interested in making your own port? Great! What follows are some guidelines for creating a new port for
FreeBSD. The bulk of the work is done by
/usr/share/mk/bsd.port.mk, which all port Makefiles include.
Please refer to that file for more details on the inner workings of
the ports collection. Even if you don't hack Makefiles daily, it is
well commented, and you will still gain much knowledge from it.
Note: Only a fraction of the overridable variables
(${..}) are mentioned in this document. Most (if not
all) are documented at the start of bsd.port.mk. This file
uses a non-standard tab setting. Emacs and Vim
should recognize 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.
This section tells you how to do a quick port. In many
cases, it is not enough, but we will 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 will have to refer to the next section
too.
The minimal Makefile would look something like this:
See if you can figure it out. Do not 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. You can find a more detailed example in the section.
There are three 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. Please
do not include the package name (or version number of the
software) in the comment.
Here is an example:
This is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is
sufficient. This is not a manual or an
in-depth description on how to use or compile the port!
Please be careful if you are copying from the
README or manpage; too often they are not a
concise description of the port or are in an awkward format
(e.g. manpages have justified spacing). If the ported software
has an official WWW homepage, you should list it here.
It is recommended that you sign the name at the end of
this file, 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). If you are
using the Here is a small example:
Refer to the pkg_create(1) man page for details
on the packing list. Note that you should list all the
files, but not the name directories, in the list.
Also, if the port creates directories for itself during
installation, make sure to add It is recommended you keep all the filenames in this file
sorted alphabetically. It will make verifying the changes
when you upgrade the port much easier.
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. These
are the important points you need to verify:
The recommended ordering of tests is:
Please use portlint to see if your port conforms
to our guidelines. The
First, make sure you have read the section.
Now that you are 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. We do not need
your work/ directory or the pkgname.tgz
package, so delete them now. Next, simply include the
output of `shar `find port_dir`' in a
bug report and send it with the send-pr(1)
program (see for more information about
send-pr). If the uncompressed port is larger than 20KB,
you should compress it into a tarfile and use
uuencode(1) before including it in the bug report
(uuencoded tarfiles are acceptable even if the report is
smaller than 20KB but are not preferred). Be sure to classify
the bug report as category `ports' and class `change-request'.
(Do not mark the report `confidential'!)
One more time, do not include the original source distfile,
the work/ directory, or the package you built with
`make package'!
Note: in the past, we asked you to upload new port
submissions in our ftp site (:<
We will look at your port, get back to you if necessary, and put
it in the tree. Your name will also appear in the list of
`Additional FreeBSD contributors' on the FreeBSD Handbook
and other files. Isn't that great?!? :)
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... :>
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
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 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
Configuring the Makefile is pretty simple, and again we
suggest that you look at existing examples before starting.
Also, there is a 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:
If ${DISTNAME} does not conform to our , 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 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 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 &a.ports;
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:
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 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 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 `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,
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,
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,
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 `${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 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 `*_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 To depend on another port unconditionally, it is
customary to use the string ` Do not use `
If your package uses GNU make, set
`USE_GMAKE=yes'. If your package uses configure,
set `HAS_CONFIGURE=yes'. If your package uses
GNU GNU_CONFIGURE=yes' (this
implies --prefix=${PREFIX}' for GNU ${CONFIGURE_ARGS}. If your package uses GNU
USE_AUTOCONF=yes'. This
implies 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}.
There are some more things you have to take into account when
you create a port. This section explains the most common of those.
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 a matching `@exec /sbin/ldconfig
-m'/`@unexec /sbin/ldconfig -R' pair to your
pkg/PLIST file so that a user who installed the
package can start using the shared library immediately and
deinstallation will not cause the system to still believe
the library is there. These lines should immediately follow
the line for the shared library itself, as in:
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 does not 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)....
Since FreeBSD moved to ELF shortly after 3.0-release,
we need to convert many ports that build shared libraries
to support ELF. Complicating this task is that a 3.0
system can run as both ELF and a.out, and that there will
be one more release (2.2.8) from the 2.2 branch. Below
are the guidelines on how to convert a.out only ports to
support both a.out and ELF compilation.
Some part of this list is only applicable during the
conversion, but will be left here for awhile for reference
in case you have come across some old port you wish to
upgrade.
A.out libraries should be moved out of
/usr/local/lib and similar to an `src/Makefile (called from `
The ports tree will build packages in the format the
machine is in. This means a.out for 2.2 and a.out or
ELF for 3.0 depending on what `objformat`
returns. Also, once users move a.out libraries
to a subdirectory, building a.out libraries will be
unsupported. (I.e., it may still work if you know what
you are doing, but you are on your own.)
Note: if a port only works for a.out, set
PORTOBJFORMAT=${PORTOBJFORMAT}'. (See comment
on The variable is set using this line:
The following are differences in handling shared
libraries for a.out and ELF.
You need to install a symlink libfoo.so ->
libfoo.so.N to make ELF linkers happy. Since
it should be listed in
All port Makefiles are edited to remove minor numbers
from foo\\.1\\.\\(33|40\\)' -> `foo.2'.)
They will be matched using `grep -wF'.
In cases where you really need to install shlibs with
two versions on an ELF system or those with one version
on an a.out system (for instance, ports that install
compatibility libraries for other operating systems),
define the variable
The If your port needs to build slightly different versions
of packages by having a variable (for instance, resolution
or paper size) take different values, create one
subdirectory per package to make it easier for users to
see what to do, but try to share as many files as possible
between ports. Typically you only need a very short
Makefile in all but one of the directories if you use
variables cleverly. In the sole Makefiles, you can use
${MASTERDIR} to specify the directory
where the rest of the files are. Also, use a variable as
part of
so the packages will have different names.
This will be best demonstrated by an example. This is
part of japanese/xdvi300/Makefile:
First, please read our to understand
what to do with shared library versions in general. Do
not blindly assume software authors know what they are
doing; many of them do not. It is very important that
these details are carefully considered, as we have quite a
unique situation where we are trying to have dozens of
potentially incompatible software pairs co-exist.
Careless port imports have caused great trouble regarding
shared libraries in the past (ever wondered why the port
However, if there is a port which is a different version
of the same software already in the tree, the situation is
much more complex. In short, the FreeBSD implementation
does not allow the user to specify to the linker which
version of shared library to link against (the linker will
always pick the highest numbered version). This means, if
there is a
The pkg/PLIST (this means you must for more).
It also makes the install stage automatically compress or
uncompress manpages depending on the setting of
/etc/make.conf.
To specify whether the manpages are compressed upon
installation, use the If your port anchors its man tree somewhere other than
PREFIX, you can use the MANPREFIX to set
it. Also, if only manpages in certain sections go in a
non-standard place, such as some Perl modules ports, you can
set individual man paths using
MANsectPREFIX (where
sect is one of 1-9, L or N).
If your manpages go to language-specific subdirectories,
set the name of the languages to "" (i.e., English only).
Here is an example that puts it all together.
There are many programs that require a Motif library
(available from several commercial vendors, while there is
a free clone reported to be able to run many applications in
x11-toolkits/lesstif) to compile. Since
it is a popular toolkit and their licenses usually permit
redistribution of statically linked binaries, we have made
special provisions for handling ports that require Motif in a
way that we can easily compile binaries linked either
dynamically (for people who are compiling from the port) or
statically (for people who distribute packages).
If your port requires Motif, define this variable in the
Makefile. This will prevent people who don't own a copy of
Motif from even attempting to build it.
This variable will be set by bsd.port.mk to be the
appropriate reference to the Motif library. Please patch
the source to use this wherever the Motif library is
referenced in the Makefile or Imakefile.
There are two common cases:
Note that ${MOTIFLIB} (usually) expands to
`-L/usr/X11R6/lib -lXm' or
`/usr/X11R6/lib/libXm.a', so there is no need to
add `-L' or `-l' in front.
If your port installs fonts for the X window system, put
them in ${X11BASE}/lib/X11/fonts/local. This
directory is new to XFree86 release 3.3.3. If it does not
exist, please create it, and print out a message urging the
user to update their XFree86 to 3.3.3 or newer, or at least
add this directory to the font path in
/etc/XF86Config.
The new version of texinfo (included in 2.2.2-RELEASE and
onwards) contains a utility called `&dollar{PREFIX}/info/dir file. (Sorry for the length
of this section, but it is imperative to weave all the info
files together. If done correctly, it will produce a
beautiful listing, so please bear with me! First, this is what you (as a porter) need to know:
Note that this program will not actually Here's a seven-step procedure to convert ports to use
editors/emacs as an
example.
The format should be self-explanatory. Many authors leave
a Note that you can put only one info entry per file because
of a bug in `install-info --delete' that deletes
only the first entry if you specify multiple entries in the
You can give the three The second hunk was necessary because the default target in
the /usr/share/info
(that patch is not shown here).
Do not use anything other than /usr/share/info/dir
and the above command to create a new info file. In fact,
I'd add the first three lines of the above patch to
Edit info/dir with Note that the `@unexec install-info --delete'
commands have to be listed before the info files themselves
so they can read the files. Also, the `@exec
install-info' commands have to be after the info files
and the and admire your
work.
There are some tricks we haven't mentioned yet about the
Walnut Creek CDROM