diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index 3503c0ecf1..74c17dcee1 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,3487 +1,3506 @@
The Cutting EdgeRestructured, reorganized, and parts updated by &a.jim;
March 2000. Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik;
with feedback from various others.SynopsisFreeBSD is under constant development between releases. For
people who want to be on the cutting edge, there are several easy
mechanisms for keeping your system in sync with the latest
developments. Be warned—the cutting edge is not for everyone!
This chapter will help you decide if you want to track the
development system, or stick with one of the released
versions.-CURRENT vs. -STABLEThere are two development branches to FreeBSD; -CURRENT and
-STABLE. This section will explain a bit about each and describe
how to keep your system up-to-date with each respective tree.
-CURRENT will be discussed first, then -STABLE.Staying Current with FreeBSDAs you are reading this, keep in mind that -CURRENT is the
“bleeding edge” of FreeBSD development and that if you
are new to FreeBSD, you are most likely going to want to think
twice about running it.What is FreeBSD-CURRENT?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!Who needs FreeBSD-CURRENT?FreeBSD-CURRENT is made generally available for 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.What is FreeBSD-CURRENT not?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.Using FreeBSD-CURRENTJoin 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 &a.cvsall; mailing list will allow you to see the
commit log entry for each change as it is made along with
any pertinent information on possible side-effects.To join these lists, send mail to &a.majordomo; and
specify the following in the body of your message:
subscribe freebsd-current
subscribe cvs-allOptionally, you can also say help
and Majordomo will send you full help on how to subscribe
and unsubscribe to the various other mailing lists we
support.Grab the sources from ftp.FreeBSD.org. You can do this in
one of three ways:Use the CTM facility. Unless
you have a good TCP/IP connection at a flat rate, this
is the way to do it.Use the cvsup program
with this
supfile. This is the second most recommended
method, since it allows you to grab the entire
collection once and then only what has changed from then
on. Many people run cvsup from cron and keep their
sources up-to-date automatically. For a fairly easy
interface to this, simply type:
Use ftp. The source tree for
FreeBSD-CURRENT is always “exported” on:
ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/.
We also use wu-ftpd which allows
compressed/tar'd grabbing of whole trees. e.g. you
see:usr.bin/lexYou can do the following to get the whole directory
as a tar file:ftp>cd usr.binftp>get lex.tarEssentially, if you need rapid on-demand access to the
source and communications bandwidth is not a consideration,
use cvsup or ftp.
Otherwise, use CTM.If you are grabbing the sources to run, and not just
look at, then grab all of current, not
just selected portions. The reason for this is that various
parts of the source depend on updates elsewhere, and trying
to compile just a subset is almost guaranteed to get you
into trouble.Before compiling current, read the
Makefilein /usr/src
carefully. You should at least run a make world the first time through
as part of the upgrading process. Reading the &a.current;
will keep you up-to-date on other bootstrapping procedures
that sometimes become necessary as we move towards the next
release.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!Staying Stable with FreeBSDIf you are using FreeBSD in a production environment and want
to make sure you have the latest fixes from the -CURRENT branch,
you want to be running -STABLE. This is the tree that -RELEASEs
are branched from when we are putting together a new release. For
example, if you have a copy of 3.4-RELEASE, that is really just a
“snapshot” from the -STABLE branch that we put on
CDROM. In order to get any changes merged into -STABLE after the
-RELEASE, you need to “track” the -STABLE
branch.What is FreeBSD-STABLE?FreeBSD-STABLE is our development branch for a more low-key
and conservative set of changes intended for our next mainstream
release. Changes of an experimental or untested nature do not
go into this branch (see FreeBSD-CURRENT).Who needs FreeBSD-STABLE?If you are a commercial user or someone who puts maximum
stability of their FreeBSD system before all other concerns, you
should consider tracking stable. This is
especially true if you have installed the most recent release
(&rel.current;-RELEASE
at the time of this writing) since the
stable branch is effectively a bug-fix
stream relative to the previous release.The stable tree endeavors, above all,
to be fully compilable and stable at all times, but we do
occasionally make mistakes (these are still active sources
with quickly-transmitted updates, after all). We also do our
best to thoroughly test fixes in current
before bringing them into stable, but
sometimes our tests fail to catch every case. If something
breaks for you in stable, please let us
know immediately! (see next
section).Using FreeBSD-STABLEJoin the &a.stable;. This will keep you informed of
build-dependencies that may appear in
stable or any other issues requiring
special attention. Developers will also make announcements
in this mailing list when they are contemplating some
controversial fix or update, giving the users a chance to
respond if they have any issues to raise concerning the
proposed change.The &a.cvsall; mailing list will allow you to see the
commit log entry for each change as it is made along with
any pertinent information on possible side-effects.To join these lists, send mail to &a.majordomo; and
specify the following in the body of your message:
subscribe freebsd-stable
subscribe cvs-allOptionally, you can also say help
and Majordomo will send you full help on how to subscribe
and unsubscribe to the various other mailing lists we
support.If you are installing a new system and want it to be as
stable as possible, you can simply grab the latest dated
branch snapshot from ftp://releng3.FreeBSD.org/pub/FreeBSD/
and install it like any other release.If you are already running a previous release of FreeBSD
and wish to upgrade via sources then you can easily do so
from ftp.FreeBSD.org. This can
be done in one of three ways:Use the CTM facility. Unless
you have a good TCP/IP connection at a flat rate, this
is the way to do it.Use the cvsup program
with this
supfile. This is the second most recommended
method, since it allows you to grab the entire
collection once and then only what has changed from then
on. Many people run cvsup from cron to keep their
sources up-to-date automatically. For a fairly easy
interface to this, simply type:
Use ftp. The source tree for
FreeBSD-STABLE is always “exported” on:
ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/We also use wu-ftpd which allows
compressed/tar'd grabbing of whole trees. e.g. you
see:usr.bin/lexYou can do the following to get the whole directory
for you as a tar file:ftp>cd usr.binftp>get lex.tarEssentially, if you need rapid on-demand access to the
source and communications bandwidth is not a consideration,
use cvsup or ftp.
Otherwise, use CTM.Before compiling stable, read the
Makefile in /usr/src
carefully. You should at least run a make world the first time through
as part of the upgrading process. Reading the &a.stable; will
keep you up-to-date on other bootstrapping procedures that
sometimes become necessary as we move towards the next
release.Synchronizing Your SourceThere are various ways of using an Internet (or email)
connection to stay up-to-date with any given area of the FreeBSD
project sources, or all areas, depending on what interests you. The
primary services we offer are Anonymous
CVS, CVSup, and CTM.Anonymous CVS and
CVSup use the pull
model of updating sources. In the case of
CVSup the user (or a cron script) invokes
the cvsup program, and it interacts with a
cvsupd server somewhere to bring your files
up-to-date. The updates you receive are up-to-the-minute and you
get them when, and only when, you want them. You can easily
restrict your updates to the specific files or directories that are
of interest to you. Updates are generated on the fly by the server,
according to what you have and what you want to have.
Anonymous CVS is quite a bit more
simplistic than CVSup in that it's just an extension to
CVS which allows it to pull changes
directly from a remote CVS repository.
CVSup can do this far more efficiently,
but Anonymous CVS is easier to
use.CTM, on the other hand, does not
interactively compare the sources you have with those on the master
archive or otherwise pull them across.. Instead, a script which
identifies changes in files since its previous run is executed
several times a day on the master CTM machine, any detected changes
being compressed, stamped with a sequence-number and encoded for
transmission over email (in printable ASCII only). Once received,
these “CTM deltas” can then be handed to the
&man.ctm.rmail.1; utility which will automatically decode, verify
and apply the changes to the user's copy of the sources. This
process is far more efficient than CVSup,
and places less strain on our server resources since it is a
push rather than a pull
model.There are other trade-offs, of course. If you inadvertently
wipe out portions of your archive, CVSup
will detect and rebuild the damaged portions for you.
CTM won't do this, and if you wipe some
portion of your source tree out (and don't have it backed up) then
you will have to start from scratch (from the most recent CVS
“base delta”) and rebuild it all with CTM or, with
anoncvs, simply delete the bad bits and resync.More information about Anonymous CVS,
CTM, and
CVSup is available further down in this
section.Anonymous CVSIntroductionAnonymous CVS (or, as it is otherwise known,
anoncvs) is a feature provided by the CVS
utilities bundled with FreeBSD for synchronizing with a remote
CVS repository. Among other things, it allows users of FreeBSD
to perform, with no special privileges, read-only CVS operations
against one of the FreeBSD project's official anoncvs servers.
To use it, one simply sets the CVSROOT
environment variable to point at the appropriate anoncvs server,
provides the well-known password anoncvs with the
cvs login command, and then uses the
&man.cvs.1; command to access it like any local
repository.While it can also be said that the CVSup and anoncvs
services both perform essentially the same function, there are
various trade-offs which can influence the user's choice of
synchronization methods. In a nutshell,
CVSup is much more efficient in its
usage of network resources and is by far the most technically
sophisticated of the two, but at a price. To use
CVSup, a special client must first be
installed and configured before any bits can be grabbed, and
then only in the fairly large chunks which
CVSup calls
collections.Anoncvs, by contrast, can be used
to examine anything from an individual file to a specific
program (like ls or grep)
by referencing the CVS module name. Of course,
anoncvs is also only good for
read-only operations on the CVS repository, so if it's your
intention to support local development in one repository shared
with the FreeBSD project bits then
CVSup is really your only
option.Using Anonymous CVSConfiguring &man.cvs.1; to use an Anonymous CVS repository
is a simple matter of setting the CVSROOT
environment variable to point to one of the FreeBSD project's
anoncvs servers. At the time of this
writing, the following servers are available:USA:
:pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
(Use cvs login and enter the password
anoncvs when prompted.)Since CVS allows one to “check out” virtually
any version of the FreeBSD sources that ever existed (or, in
some cases, will exist :-), you need to be
familiar with the revision () flag to
&man.cvs.1; and what some of the permissible values for it in
the FreeBSD Project repository are.There are two kinds of tags, revision tags and branch tags.
A revision tag refers to a specific revision. Its meaning stays
the same from day to day. A branch tag, on the other hand,
refers to the latest revision on a given line of development, at
any given time. Because a branch tag does not refer to a
specific revision, it may mean something different tomorrow than
it means today.Here are the branch tags that users might be interested
in (keep in mind that the only tags valid for the ports collection is
HEAD).HEADSymbolic name for the main line, or FreeBSD-CURRENT.
Also the default when no revision is specified.RELENG_3The line of development for FreeBSD-3.X, also known
as FreeBSD-STABLE.RELENG_2_2The line of development for FreeBSD-2.2.X, also known
as 2.2-STABLE. This branch is mostly obsolete.Here are the revision tags that users might be interested
in. Again, none of these are valid for the ports collection
since the ports collection does not have multiple
revisions.RELENG_3_4_0_RELEASEFreeBSD-3.4.RELENG_3_3_0_RELEASEFreeBSD-3.3.RELENG_3_2_0_RELEASEFreeBSD-3.2.RELENG_3_1_0_RELEASEFreeBSD-3.1.RELENG_3_0_0_RELEASEFreeBSD-3.0.RELENG_2_2_8_RELEASEFreeBSD-2.2.8.RELENG_2_2_7_RELEASEFreeBSD-2.2.7.RELENG_2_2_6_RELEASEFreeBSD-2.2.6.RELENG_2_2_5_RELEASEFreeBSD-2.2.5.RELENG_2_2_2_RELEASEFreeBSD-2.2.2.RELENG_2_2_1_RELEASEFreeBSD-2.2.1.RELENG_2_2_0_RELEASEFreeBSD-2.2.0.When you specify a branch tag, you normally receive the
latest versions of the files on that line of development. If
you wish to receive some past version, you can do so by
specifying a date with the flag.
See the &man.cvs.1; man page for more details.ExamplesWhile it really is recommended that you read the manual page
for &man.cvs.1; thoroughly before doing anything, here are some
quick examples which essentially show how to use Anonymous
CVS:Checking out something from -CURRENT (&man.ls.1;) and
deleting it again:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co ls
&prompt.user; cvs release -d ls
&prompt.user; cvs logoutChecking out the version of &man.ls.1; in the 2.2-STABLE
branch:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co -rRELENG_2_2 ls
&prompt.user; cvs release -d ls
&prompt.user; cvs logoutCreating a list of changes (as unidiffs) to &man.ls.1;
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls
&prompt.user; cvs logoutFinding out what other module names can be used:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co modules
&prompt.user; more modules/modules
&prompt.user; cvs release -d modules
&prompt.user; cvs logoutOther ResourcesThe following additional resources may be helpful in learning
CVS:CVS Tutorial from Cal Poly.Cyclic Software,
commercial maintainers of CVS.CVSWeb is
the FreeBSD Project web interface for CVS.CTMCTM is a method for keeping a
remote directory tree in sync with a central one. It has been
developed for usage with FreeBSD's source trees, though other
people may find it useful for other purposes as time goes by.
Little, if any, documentation currently exists at this time on the
process of creating deltas, so talk to &a.phk; for more
information should you wish to use CTM
for other things.Why should I use CTM?CTM will give you a local copy of
the FreeBSD source trees. There are a number of
“flavors” of the tree available. Whether you wish
to track the entire CVS tree or just one of the branches,
CTM can provide you the information.
If you are an active developer on FreeBSD, but have lousy or
non-existent TCP/IP connectivity, or simply wish to have the
changes automatically sent to you,
CTM was made for you. You will need
to obtain up to three deltas per day for the most active
branches. However, you should consider having them sent by
automatic email. The sizes of the updates are always kept as
small as possible. This is typically less than 5K, with an
occasional (one in ten) being 10-50K and every now and then a
biggie of 100K+ or more coming around.You will also need to make yourself aware of the various
caveats related to working directly from the development sources
rather than a pre-packaged release. This is particularly true
if you choose the “current” sources. It is
recommended that you read Staying
current with FreeBSD.What do I need to use
CTM?You will need two things: The CTM
program, and the initial deltas to feed it (to get up to
“current” levels).The CTM program has been part of
FreeBSD ever since version 2.0 was released, and lives in
/usr/src/usr.sbin/CTM if you have a copy
of the source available.If you are running a pre-2.0 version of FreeBSD, you can
fetch the current CTM sources
directly from:ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/The “deltas” you feed
CTM can be had two ways, FTP or
email. If you have general FTP access to the Internet then the
following FTP sites support access to
CTM:ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/or see section mirrors.FTP the relevant directory and fetch the
README file, starting from there.If you wish to get your deltas via email:Send email to &a.majordomo; to subscribe to one of the
CTM distribution lists.
“ctm-cvs-cur” supports the entire cvs tree.
“ctm-src-cur” supports the head of the development
branch. “ctm-src-2_2” supports the 2.2 release
branch, etc.. (If you do not know how to subscribe yourself
using majordomo, send a message first containing the word
help — it will send you back usage
instructions.)When you begin receiving your CTM
updates in the mail, you may use the
ctm_rmail program to unpack and apply them.
You can actually use the ctm_rmail program
directly from a entry in /etc/aliases if
you want to have the process run in a fully automated fashion.
Check the ctm_rmail man page for more
details.No matter what method you use to get the
CTM deltas, you should subscribe to
the ctm-announce@FreeBSD.org mailing list. In
the future, this will be the only place where announcements
concerning the operations of the
CTM system will be posted. Send an
email to &a.majordomo; with a single line of
subscribe ctm-announce to get added to the
list.Using CTM for the first
timeBefore you can start using CTM
deltas, you will need to get to a starting point for the deltas
produced subsequently to it.First you should determine what you already have. Everyone
can start from an “empty” directory. You must use
an initial “Empty” delta to start off your
CTM supported tree. At some point it
is intended that one of these “started” deltas be
distributed on the CD for your convenience, however, this does
not currently happen.Since the trees are many tens of megabytes, you should
prefer to start from something already at hand. If you have a
-RELEASE CD, you can copy or extract an initial source from it.
This will save a significant transfer of data.You can recognize these “starter” deltas by the
X appended to the number
(src-cur.3210XEmpty.gz for instance). The
designation following the X corresponds to
the origin of your initial “seed”.
Empty is an empty directory. As a rule a
base transition from Empty is produced
every 100 deltas. By the way, they are large! 25 to 30
Megabytes of gzip'd data is common for the
XEmpty deltas.Once you've picked a base delta to start from, you will also
need all deltas with higher numbers following it.Using CTM in your daily
lifeTo apply the deltas, simply say:&prompt.root; cd /where/ever/you/want/the/stuff
&prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.*CTM understands deltas which have
been put through gzip, so you do not need to
gunzip them first, this saves disk space.Unless it feels very secure about the entire process,
CTM will not touch your tree. To
verify a delta you can also use the flag and
CTM will not actually touch your
tree; it will merely verify the integrity of the delta and see
if it would apply cleanly to your current tree.There are other options to CTM
as well, see the manual pages or look in the sources for more
information.I would also be very happy if somebody could help with the
“user interface” portions, as I have realized that I
cannot make up my mind on what options should do what, how and
when...That is really all there is to it. Every time you get a new
delta, just run it through CTM to
keep your sources up to date.Do not remove the deltas if they are hard to download again.
You just might want to keep them around in case something bad
happens. Even if you only have floppy disks, consider using
fdwrite to make a copy.Keeping your local changesAs a developer one would like to experiment with and change
files in the source tree. CTM
supports local modifications in a limited way: before checking
for the presence of a file foo, it first
looks for foo.ctm. If this file exists,
CTM will operate on it instead of
foo.This behaviour gives us a simple way to maintain local
changes: simply copy the files you plan to modify to the
corresponding file names with a .ctm
suffix. Then you can freely hack the code, while CTM keeps the
.ctm file up-to-date.Other interesting CTM optionsFinding out exactly what would be touched by an
updateYou can determine the list of changes that
CTM will make on your source
repository using the option to
CTM.This is useful if you would like to keep logs of the
changes, pre- or post- process the modified files in any
manner, or just are feeling a tad paranoid
:-).Making backups before updatingSometimes you may want to backup all the files that would
be changed by a CTM update.Specifying the option
causes CTM to backup all files that
would be touched by a given CTM
delta to backup-file.Restricting the files touched by an updateSometimes you would be interested in restricting the scope
of a given CTM update, or may be
interested in extracting just a few files from a sequence of
deltas.You can control the list of files that
CTM would operate on by specifying
filtering regular expressions using the
and options.For example, to extract an up-to-date copy of
lib/libc/Makefile from your collection of
saved CTM deltas, run the commands:&prompt.root; cd /where/ever/you/want/to/extract/it/
&prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*For every file specified in a
CTM delta, the
and options are applied in the order given
on the command line. The file is processed by
CTM only if it is marked as
eligible after all the and
options are applied to it.Future plans for CTMTons of them:Use some kind of authentication into the CTM system, so
as to allow detection of spoofed CTM updates.Clean up the options to CTM,
they became confusing and counter intuitive.Miscellaneous stuffAll the “DES infected” (e.g. export controlled)
source is not included. You will get the
“international” version only. If sufficient
interest appears, we will set up a sec-cur
sequence too. There is a sequence of deltas for the
ports collection too, but interest has not
been all that high yet. Tell me if you want an email list for
that too and we will consider setting it up.CVSupIntroductionCVSup 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.InstallationThe easiest way to install CVSup
is to use the net/cvsup-bin port
from the FreeBSD ports collection.
If you prefer to build CVSup from
source, you can use the net/cvsup
port instead. But be forewarned: the
net/cvsup port depends on the Modula-3
system, which takes a substantial amount of time, memory, and
disk space to build.If you do not know anything about cvsup at all and want a
single package which will install it, set up the configuration
file and start the transfer via a pointy-clicky type of
interface, then get the cvsupit
package. Just hand it to &man.pkg.add.1; and it will lead you
through the configuration process in a menu-oriented
fashion.CVSup ConfigurationCVSup's operation is controlled
by a configuration file called the supfile.
There are some sample supfiles in the
directory /usr/share/examples/cvsup/.The information in a supfile answers
the following questions for cvsup:Which files do you
want to receive?Which versions of them
do you want?Where do you want to
get them from?Where do you want to
put them on your own machine?Where do you want to
put your status files?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 FreeBSD-CURRENT.Which files do you want
to receive?The files available via CVSup
are organized into named groups called
“collections”. The collections that are
available are described here. In this example, we
wish to receive the entire main source tree for the FreeBSD
system. There is a single large collection
src-all which will give us all of that,
except the export-controlled cryptography support. Let us
assume for this example that we are in the USA or Canada.
Then we can get the cryptography code with one additional
collection, cvs-crypto. As a first step
toward constructing our supfile, we
simply list these collections, one per line:
src-all
cvs-cryptoWhich version(s) of them
do you want?With CVSup, you can receive
virtually any version of the sources that ever existed.
That is possible because the cvsupd server works directly
from the CVS repository, which contains all of the versions.
You specify which one of them you want using the
tag= and value
fields.Be very careful to specify any tag=
fields correctly. Some tags are valid only for certain
collections of files. If you specify an incorrect or
misspelled tag, CVSup will delete files which you probably
do not want deleted. In particular, use only
tag=. for the
ports-* collections.The tag= field names a symbolic tag
in the repository. There are two kinds of tags, revision
tags and branch tags. A revision tag refers to a specific
revision. Its meaning stays the same from day to day. A
branch tag, on the other hand, refers to the latest revision
on a given line of development, at any given time. Because
a branch tag does not refer to a specific revision, it may
mean something different tomorrow than it means
today.Here are the branch tags that users might be interested
in. Keep in mind that only the tag=. is
relevant for the ports collection.tag=.The main line of development, also known as
FreeBSD-CURRENT.The . is not punctuation; it
is the name of the tag. Valid for all
collections.RELENG_3The line of development for FreeBSD-3.X, also
known as FreeBSD-STABLE.RELENG_2_2The line of development for FreeBSD-2.2.X, also
known as 2.2-STABLE.Here are the revision tags that users might be interested
in. Again, these are not valid for the ports
collection.RELENG_3_4_0_RELEASEFreeBSD-3.4.tag=RELENG_3_3_0_RELEASEFreeBSD-3.3.tag=RELENG_3_2_0_RELEASEFreeBSD-3.2.tag=RELENG_3_1_0_RELEASEFreeBSD-3.1.tag=RELENG_3_0_0_RELEASEFreeBSD-3.0.tag=RELENG_2_2_8_RELEASEFreeBSD-2.2.8.tag=RELENG_2_2_7_RELEASEFreeBSD-2.2.7.tag=RELENG_2_2_6_RELEASEFreeBSD-2.2.6.tag=RELENG_2_2_5_RELEASEFreeBSD-2.2.5.tag=RELENG_2_2_2_RELEASEFreeBSD-2.2.2.tag=RELENG_2_2_1_RELEASEFreeBSD-2.2.1.tag=RELENG_2_2_0_RELEASEFreeBSD-2.2.0.Be very careful to type the tag name exactly as shown.
CVSup cannot distinguish
between valid and invalid tags. If you misspell the tag,
CVSup will behave as though you
had specified a valid tag which happens to refer to no
files at all. It will delete your existing sources in
that case.When you specify a branch tag, you normally receive the
latest versions of the files on that line of development.
If you wish to receive some past version, you can do so by
specifying a date with the value
field. The &man.cvsup.1; manual page explains how to do
that.For our example, we wish to receive FreeBSD-CURRENT. We
add this line at the beginning of our
supfile:
*default tag=.There is an important special case that comes into play
if you specify neither a tag= field nor a
date= field. In that case, you receive
the actual RCS files directly from the server's CVS
repository, rather than receiving a particular version.
Developers generally prefer this mode of operation. By
maintaining a copy of the repository itself on their
systems, they gain the ability to browse the revision
histories and examine past versions of files. This gain is
achieved at a large cost in terms of disk space,
however.Where do you want to get
them from?We use the host= field to tell
cvsup where to obtain its updates. Any
of the CVSup mirror
sites will do, though you should try to select one
that is close to you in cyberspace. In this example we will
use a fictional FreeBSD distribution site,
cvsup666.FreeBSD.org:
*default host=cvsup666.FreeBSD.orgYou will need to change the host to one that actually
exists before running CVSup. On any particular run of
cvsup, you can override the host setting
on the command line, with .Where do you want to put
them on your own machine?The prefix= field tells
cvsup where to put the files it receives.
In this example, we will put the source files directly into
our main source tree, /usr/src. The
src directory is already implicit in
the collections we have chosen to receive, so this is the
correct specification:
*default prefix=/usrWhere should
cvsup maintain its status files?The cvsup client maintains certain status files in what
is called the “base” directory. These files
help CVSup to work more
efficiently, by keeping track of which updates you have
already received. We will use the standard base directory,
/usr/local/etc/cvsup:
*default base=/usr/local/etc/cvsupThis setting is used by default if it is not specified
in the supfile, so we actually do not
need the above line.If your base directory does not already exist, now would
be a good time to create it. The cvsup
client will refuse to run if the base directory does not
exist.Miscellaneous supfile
settings:There is one more line of boiler plate that normally
needs to be present in the
supfile:
*default release=cvs delete use-rel-suffix compressrelease=cvs indicates that the server
should get its information out of the main FreeBSD CVS
repository. This is virtually always the case, but there
are other possibilities which are beyond the scope of this
discussion.delete gives
CVSup permission to delete files.
You should always specify this, so that
CVSup can keep your source tree
fully up-to-date. CVSup is
careful to delete only those files for which it is
responsible. Any extra files you happen to have will be
left strictly alone.use-rel-suffix is ... arcane. If you
really want to know about it, see the &man.cvsup.1; manual
page. Otherwise, just specify it and do not worry about
it.compress enables the use of
gzip-style compression on the communication channel. If
your network link is T1 speed or faster, you probably should
not use compression. Otherwise, it helps
substantially.Putting it all together:Here is the entire supfile for our
example:
*default tag=.
*default host=cvsup666.FreeBSD.org
*default prefix=/usr
*default base=/usr/local/etc/cvsup
*default release=cvs delete use-rel-suffix compress
src-all
cvs-cryptoRunning CVSupYou are now ready to try an update. The command line for
doing this is quite simple:&prompt.root; cvsup supfilewhere 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:&prompt.root; mkdir /var/tmp/dest
&prompt.root; cvsup supfile /var/tmp/destThe 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:&prompt.root; cvsup -g -L 2 supfileThe tells cvsup not to use its GUI.
This is automatic if you are not running X11, but otherwise you
have to specify it.The tells cvsup to print out the
details of all the file updates it is doing. There are three
levels of verbosity, from to
. 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 &man.cron.8;.
Obviously, you should not let cvsup use its GUI when running it
from cron.CVSup File CollectionsThe 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
src-all, cvs-crypto, and
ports-all. The other collections are used
only by small groups of people for specialized purposes, and
some mirror sites may not carry all of them.cvs-all release=cvsThe main FreeBSD CVS repository, excluding the
export-restricted cryptography code.distrib release=cvsFiles related to the distribution and mirroring
of FreeBSD.doc-all release=cvsSources for the FreeBSD handbook and other
documentation.ports-all release=cvsThe FreeBSD ports collection.ports-archivers
release=cvsArchiving tools.ports-astro
release=cvsAstronomical ports.ports-audio
release=cvsSound support.ports-base
release=cvsMiscellaneous files at the top of
/usr/ports.ports-benchmarks
release=cvsBenchmarks.ports-biology
release=cvsBiology.ports-cad
release=cvsComputer aided design tools.ports-chinese
release=cvsChinese language support.ports-comms
release=cvsCommunication software.ports-converters
release=cvscharacter code converters.ports-databases
release=cvsDatabases.ports-deskutils
release=cvsThings that used to be on the desktop
before computers were invented.ports-devel
release=cvsDevelopment utilities.ports-editors
release=cvsEditors.ports-emulators
release=cvsEmulators for other operating
systems.ports-ftp
release=cvsFTP client and server utilities.ports-games
release=cvsGames.ports-german
release=cvsGerman language support.ports-graphics
release=cvsGraphics utilities.ports-irc
release=cvsInternet Relay Chat utilities.ports-japanese
release=cvsJapanese language support.ports-java
release=cvsJava utilities.ports-korean
release=cvsKorean language support.ports-lang
release=cvsProgramming languages.ports-mail
release=cvsMail software.ports-math
release=cvsNumerical computation software.ports-mbone
release=cvsMBone applications.ports-misc
release=cvsMiscellaneous utilities.ports-net
release=cvsNetworking software.ports-news
release=cvsUSENET news software.ports-palm
release=cvsSoftware support for 3Com Palm(tm)
series.ports-print
release=cvsPrinting software.ports-russian
release=cvsRussian language support.ports-security
release=cvsSecurity utilities.ports-shells
release=cvsCommand line shells.ports-sysutils
release=cvsSystem utilities.ports-textproc
release=cvstext processing utilities (does not
include desktop publishing).ports-vietnamese
release=cvsVietnamese language support.ports-www
release=cvsSoftware related to the World Wide
Web.ports-x11
release=cvsPorts to support the X window
system.ports-x11-clocks
release=cvsX11 clocks.ports-x11-fm
release=cvsX11 file managers.ports-x11-fonts
release=cvsX11 fonts and font utilities.ports-x11-toolkits
release=cvsX11 toolkits.ports-x11-serversX11 servers.ports-x11-wmX11 window managers.src-all release=cvsThe main FreeBSD sources, excluding the
export-restricted cryptography code.src-base
release=cvsMiscellaneous files at the top of
/usr/src.src-bin
release=cvsUser utilities that may be needed in
single-user mode
(/usr/src/bin).src-contrib
release=cvsUtilities and libraries from outside the
FreeBSD project, used relatively unmodified
(/usr/src/contrib).src-etc
release=cvsSystem configuration files
(/usr/src/etc).src-games
release=cvsGames
(/usr/src/games).src-gnu
release=cvsUtilities covered by the GNU Public
License (/usr/src/gnu).src-include
release=cvsHeader files
(/usr/src/include).src-kerberos5
release=cvsKerberos5 security package
(/usr/src/kerberos5).src-kerberosIV
release=cvsKerberosIV security package
(/usr/src/kerberosIV).src-lib
release=cvsLibraries
(/usr/src/lib).src-libexec
release=cvsSystem programs normally executed by other
programs
(/usr/src/libexec).src-release
release=cvsFiles required to produce a FreeBSD
release
(/usr/src/release).src-sbin
release=cvsSystem utilities for single-user mode
(/usr/src/sbin).src-share
release=cvsFiles that can be shared across multiple
systems
(/usr/src/share).src-sys
release=cvsThe kernel
(/usr/src/sys).src-tools
release=cvsVarious tools for the maintenance of
FreeBSD
(/usr/src/tools).src-usrbin
release=cvsUser utilities
(/usr/src/usr.bin).src-usrsbin
release=cvsSystem utilities
(/usr/src/usr.sbin).www release=cvsThe sources for the World Wide Web data.cvs-crypto release=cvsThe export-restricted cryptography code.src-crypto release=cvsExport-restricted utilities and libraries from
outside the FreeBSD project, used relatively
unmodified
(/usr/src/crypto).src-eBones release=cvsKerberos and DES
(/usr/src/eBones). Not
used in current releases of FreeBSD.src-secure release=cvsDES (/usr/src/secure).src-sys-crypto
release=cvsKernel cryptography code
(/usr/src/sys/crypto).distrib release=selfThe CVSup server's own configuration files. Used by
CVSup mirror sites.gnats release=currentThe GNATS bug-tracking database.mail-archive release=currentFreeBSD mailing list archive.www release=currentThe installed World Wide Web data. Used by WWW mirror
sites.For more informationFor the CVSup FAQ and other information about CVSup, see
The
CVSup Home Page.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 cvsup-bugs@polstra.com.Using make worldOnce you have synchronised your local source tree against a
particular version of FreeBSD (stable,
current and so on) you must then use the source
tree to rebuild the system.Take a backupI cannot stress highly enough how important it is to take a
backup of your system before you do this.
While remaking the world is (as long as you follow these
instructions) an easy task to do, there will inevitably be times
when you make mistakes, or when mistakes made by others in the
source tree render your system unbootable.Make sure you have taken a backup. And have a fixit floppy to
hand. I have never needed to use them, and, touch wood, I never
will, but it is always better to be safe than sorry.Subscribe to the right mailing listThe -STABLE and -CURRENT FreeBSD code branches are, by their
nature, in development. People that
contribute to FreeBSD are human, and mistakes occasionally
happen.Sometimes these mistakes can be quite harmless, just causing
your system to print a new diagnostic warning. Or the change may
be catastrophic, and render your system unbootable or destroy your
filesystems (or worse).If problems like these occur, a heads up is
posted to the appropriate mailing list, explaining the nature of
the problem and which systems it affects. And an all
clear announcement is posted when the problem has been
solved.If you try and track -STABLE or -CURRENT and do not read the
stable@FreeBSD.org or
current@FreeBSD.org mailing lists then you are
asking for trouble.
+
+ Read /usr/src/UPDATING
+
+ Before you do anything else, read
+ /usr/src/UPDATING (or the equivalent file
+ wherever you have a copy of the source code). This file should
+ contain important information about problems you might encounter, or
+ specify the order in which you might have to run certain commands.
+ If UPDATING contradicts something you read here,
+ UPDATING takes precedence.
+
+
+ Reading UPDATING is not an acceptable
+ substitute for subscribing to the correct mailing list, as described
+ previously. The two requirements are complementary, not
+ exclusive.
+
+
+
Check /etc/make.confExamine the file /etc/make.conf. This
contains some default defines for Everything is, by default, commented out. Uncomment those
entries that look useful. For a typical user (not a developer),
you will probably want to uncomment the CFLAGS and NOPROFILE
definitions.If your machine has a floating point unit (386DX, 486DX,
Pentium and up class machines) then you can also uncomment the
HAVE_FPU line.This definition was removed for version 2.2.2 and up of
FreeBSD.Examine the other definitions (COPTFLAGS, NOPORTDOCS and so
on) and decide if they are relevant to you.Update /etc/groupThe /etc directory contains a large part
of your system's configuration information, as well as scripts
that are run at system startup. Some of these scripts change from
version to version of FreeBSD.Some of the configuration files are also used in the day to
day running of the system. In particular,
/etc/group.There have been occasions when the installation part of
make world has expected certain usernames or groups
to exist. When performing an upgrade it is likely that these
groups did not exist. This caused problems when upgrading.The most recent example of this is when the ppp subsystem were installed using a
non-existent (for them) group name.The solution is to examine
/usr/src/etc/group and compare its list of
groups with your own. If they are any groups in the new file that
are not in your file then copy them over. Similarly, you should
rename any groups in /etc/group which have
the same GID but a different name to those in
/usr/src/etc/group.If you are feeling particularly paranoid, you can check your
system to see which files are owned by the group you are
renaming or deleting.&prompt.root; find / -group GID -printwill show all files owned by group
GID (which can be either a group name
or a numeric group ID).You may want to compile the system in single user mode. Apart
from the obvious benefit of making things go slightly faster,
reinstalling the system will touch a lot of important system
files, all the standard system binaries, libraries, include files
and so on. Changing these on a running system (particularly if
you have active users on their at the time) is asking for
trouble.
That said, if you are confident, you can omit this
step.Version 2.2.5 and aboveAs described in more detail below, versions 2.2.5 and above
of FreeBSD have separated the building process from the
installing process. You can therefore
build the new system in multi-user mode,
and then drop to single user mode to do the installation.As the superuser, you can execute&prompt.root; from a running system, which will drop it to single user
mode.Alternatively, reboot the system, and at the boot prompt,
enter the flag. The system will then boot
single user. At the shell prompt you should then run:&prompt.root; fsck -p
&prompt.root; mount -u /
&prompt.root; mount -a -t ufs
&prompt.root; swapon -aThis checks the filesystems, remounts /
read/write, mounts all the other UFS filesystems referenced in
/etc/fstab and then turns swapping on.Remove /usr/objAs parts of the system are rebuilt they are placed in
directories which (by default) go under
/usr/obj. The directories shadow those under
/usr/src.You can speed up the make world process, and
possibly save yourself some dependency headaches by removing this
directory as well.Some files below /usr/obj will have the
immutable flag set (see &man.chflags.1; for more information)
which must be removed first.&prompt.root; cd /usr/obj
&prompt.root; chflags -R noschg *
&prompt.root; rm -rf *All versionsYou must be in the /usr/src
directory...&prompt.root; cd /usr/src(unless, of course, your source code is elsewhere, in which
case change to that directory instead).To rebuild the world you use the &man.make.1; command. This
command reads instructions from the
Makefile which describes how the programs
that comprise FreeBSD should be rebuilt, the order they should
be built in, and so on.The general format of the command line you will type is as
follows:&prompt.root; make In this example,
-x
is an option that you would pass to &man.make.1;. See the
&man.make.1; manual page for an example of the options you can
pass.
-DVARIABLE
passes a variable to the Makefile. The
behavior of the Makefile is controlled by
these variables. These are the same variables as are set in
/etc/make.conf, and this provides another
way of setting them.&prompt.root; make -DNOPROFILE=true targetis another way of specifying that profiled libaries should
not be built, and corresponds with theNOPROFILE= true
# Avoid compiling profiled librarieslines in /etc/make.conf.target tells &man.make.1; what
you want to do. Each Makefile defines a
number of different targets, and your choice of
target determines what happens.Some targets are listed in the
Makefile, but are not meant for you to run.
Instead, they are used by the build process to break out the
steps necessary to rebuild the system into a number of
sub-steps.Most of the time you won't need to pass any parameters to
&man.make.1;, and so your command like will look like
this:&prompt.root; make targetSaving the outputIt's a good idea to save the output you get from running
&man.make.1; to another file. If something goes wrong you will
have a copy of the error message, and a complete list of where
the process had got to. While this might not help you in
diagnosing what has gone wrong, it can help others if you post
your problem to one of the FreeBSD mailing lists.The easiest way to do this is to use the &man.script.1;
command, with a parameter that specifies the name of the file to
save all output to. You would do this immediately before
remaking the world, and then type exit
when the process has finished.&prompt.root; script /var/tmp/mw.out
Script started, output file is /var/tmp/mw.out
&prompt.root; make world… compile, compile, compile …
&prompt.root; exit
Script done, …If you do this, do not save the output
in /tmp. This directory may be cleared
next time you reboot. A better place to store it is in
/var/tmp (as in the previous example) or
in root's home directory.Version 2.2.2 and below/usr/src/Makefile contains the
world target, which will rebuild the
entire system and then install it.Use it like this:&prompt.root; make worldVersion 2.2.5 and aboveBeginning with version 2.2.5 of FreeBSD (actually, it was
first created on the -CURRENT branch, and then retrofitted to
-STABLE midway between 2.2.2 and 2.2.5) the
world target has been split in
two. buildworld and
installworld.As the names imply, buildworld
builds a complete new tree under /usr/obj,
and installworld installs this tree on
the current machine.This is very useful for 2 reasons. First, it allows you to do
the build safe in the knowledge that no components of your running
system will be affected. The build is self hosted.
Because of this, you can safely run
buildworld on a machine running in
multi-user mode with no fear of ill-effects. I still recommend you
run the installworld part in single user
mode though.Secondly, it allows you to use NFS mounts to upgrade
multiple machines on your network. If you have three machines,
A, B and C that you want to upgrade, run make
buildworld and make installworld on
A. B and C should then NFS mount /usr/src
and /usr/obj from A, and you can then run
make installworld to install the results of
the build on B and C.The world target still exists, and
you can use it exactly as shown for version 2.2.2.
make world runs make
buildworld followed by make
installworld.If you do the make buildworld and
make installworld commands separately, you
must pass the same parameters to &man.make.1; each
time.If you run:&prompt.root; make -DNOPROFILE=true buildworldyou must install the results with:&prompt.root; make -DNOPROFILE=true installworldotherwise it would try and install profiled libraries that
had not been built during the make buildworld
phase.-CURRENT and aboveIf you are tracking -CURRENT you can also pass the
-j
option to make. This lets
make spawn several simultaneous processes.This is most useful on true multi-CPU machines. However, since
much of the compiling process is IO bound rather than CPU bound it is
also useful on single CPU machines.On a typical single-CPU machine you would run:&prompt.root; make -j4 target&man.make.1; will then have up to 4 processes running at any one
time. Empirical evidence posted to the mailing lists shows this
generally gives the best performance benefit.If you have a multi-CPU machine and you are using an SMP
configured kernel try values between 6 and 10 and see how they speed
things up.Be aware that (at the time of writing) this is still
experimental, and commits to the source tree may occasionally break
this feature. If the world fails to compile using this parameter
try again without it before you report any problems.TimingsAssuming everything goes well you have anywhere between an hour
and a half and a day or so to wait.As a general rule of thumb, a 200MHz P6 with more than 32MB of
RAM and reasonable SCSI disks will complete make
world in about an hour and a half. A 32MB P133 will
take 5 or 6 hours. Revise these figures down if your machines are
slower…Update /etcRemaking the world will not update certain directories (in
particular, /etc, /var and
/usr) with new or changed configuration files.
This is something you have to do by hand, eyeball, and judicious use
of &man.diff.1;.You cannot just copy over the files from
/usr/src/etc to /etc and
have it work. Some of these files must be installed
first. This is because the /usr/src/etc
directory is not a copy of what your
/etc directory should look like. In addition,
there are files that should be in /etc that are
not in /usr/src/etc.The simplest way to do this is to install the files into a new
directory, and then work through them looking for differences.Backup your existing /etcAlthough, in theory, nothing is going to touch this directory
automatically, it is always better to be sure. So copy your
existing /etc directory somewhere safe.
Something like:&prompt.root; cp -Rp /etc /etc.old
-R
does a recursive copy,
-p
preserves times, ownerships on files and suchlike.You need to build a dummy set of directories to install the new
/etc and other files into. I generally choose to
put this dummy directory in /var/tmp/root, and
there are a number of subdirectories required under this as
well.&prompt.root; mkdir /var/tmp/root
&prompt.root; cd /usr/src/etc
&prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distributionThis will build the necessary directory structure and install the
files. A lot of the subdirectories that have been created under
/var/tmp/root are empty and should be deleted.
The simplest way to do this is to:&prompt.root; cd /var/tmp/root
&prompt.root; find -d . -type d | /usr/bin/perl -lne \
'opendir(D,$_);@f=readdir(D);rmdir if $#f == 1;closedir(D);'This does a depth first search, examines each directory, and if
the number of files in that directory is 2 (/var/tmp/root now contains all the files that
should be placed in appropriate locations below
/. You now have to go through each of these
files, determining how they differ with your existing files.Note that some of the files that will have been installed in
/var/tmp/root have a leading /var/tmp/root/ and
/var/tmp/root/root/, although there may be others
(depending on when you are reading this. Make sure you use
The simplest way to do this is to use &man.diff.1; to compare the
two files.&prompt.root; diff /etc/shells /var/tmp/root/etc/shellsThis will show you the differences between your
/etc/shells file and the new
/etc/shells file. Use these to decide whether to
merge in changes that you have made or whether to copy over your old
file.Name the new root directory
(/var/tmp/root)with a timestamp, so you can
easily compare differences between versionsFrequently remaking the world means that you have to update
/etc frequently as well, which can be a bit of
a chore.You can speed this process up by keeping a copy of the last set
of changed files that you merged into /etc.
The following procedure gives one idea of how to do this.Make the world as normal. When you want to update
/etc and the other directories, give the
target directory a name based on the current date. If you were
doing this on the 14th of February 1998 you could do the
following.&prompt.root; mkdir /var/tmp/root-19980214
&prompt.root; cd /usr/src/etc
&prompt.root; make DESTDIR=/var/tmp/root-19980214 \
distrib-dirs distributionMerge in the changes from this directory as outlined
above.Do not remove the
/var/tmp/root-19980214 directory when you
have finished.When you have downloaded the latest version of the source
and remade it, follow step 1. This will give you a new
directory, which might be called
/var/tmp/root-19980221 (if you wait a week
between doing updates).You can now see the differences that have been made in the
intervening week using &man.diff.1; to create a recursive diff
between the two directories.&prompt.root; cd /var/tmp
&prompt.root; diff -r root-19980214 root-19980221Typically, this will be a much smaller set of differences
than those between
/var/tmp/root-19980221/etc and
/etc. Because the set of differences is
smaller, it is easier to migrate those changes across into your
/etc directory.You can now remove the older of the two
/var/tmp/root-* directories.&prompt.root; rm -rf /var/tmp/root-19980214Repeat this process every time you need to merge in changes
to /etc.You can use &man.date.1; to automate the generation of the
directory names.&prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"`Update /devDEVFSIf you are using DEVFS then this is probably unnecessary.For safety's sake, this is a multistep process.Copy /var/tmp/root/dev/MAKEDEV to
/dev.&prompt.root; cp /var/tmp/root/dev/MAKEDEV /devNow, take a snapshot of your current
/dev. This snapshot needs to contain the
permissions, ownerships, major and minor numbers of each filename,
but it should not contain the timestamps. The easiest way to do
this is to use &man.awk.1; to strip out some of the
information.&prompt.root; cd /dev
&prompt.root; ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.outRemake all the devices.&prompt.root; Write another snapshot of the directory, this time to
/var/tmp/dev2.out. Now look through these
two files for any devices that you missed creating. There should
not be any, but it is better to be safe than sorry.&prompt.root; diff /var/tmp/dev.out /var/tmp/dev2.outYou are most likely to notice disk slice discrepancies which
will involve commands such as
&prompt.root; sh MAKEDEV sd0s1
to recreate the slice entries. Your precise circumstances may
vary.Update /standThis step is included only for completeness, it can safely be
omitted.For completenesses sake you may want to update the files in
/stand as well. These files consist of hard
links to the /stand/sysinstall binary. This
binary should be statically linked, so that it can work when no other
filesystems (and in particular /usr) have been
mounted.&prompt.root; cd /usr/src/release/sysinstall
&prompt.root; make all installSource older than 2 April 1998If your source code is older than 2nd April 1998, or the
Makefile version is not 1.68 or higher (for
FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X
systems) you will need to add the
NOSHARED=yes option, like so;&prompt.root; make NOSHARED=yes all installCompile and install a new kernelTo take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.Follow the handbook instructions for compiling a new kernel. If
you have previously built a custom kernel then carefully examine the
LINT config file to see if there are any new
options which you should take advantage of.A previous version of this document suggested rebooting before
rebuilding the kernel. This is wrong because:Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8;
may fail. This could leave your machine unable to connect to the
network.Basic utilities like &man.mount.8; could fail,
making it impossible to mount /,
/usr and so on. This is unlikely if you are
tracking a -STABLE candidate, but more likely if you are tracking
-CURRENT during a large merge.Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X
systems and above) built as part of the world may
crash an older kernel.For these reasons, it is always best to rebuild and install a
new kernel before rebooting.You should build your new kernel after you have completed
make world (or make
installworld). If you do not want to do this (perhaps
you want to confirm that the kernel builds before updating your
system) you may have problems. These may be because your
&man.config.8; command is out of date with respect to your kernel
sources.In this case you could build your kernel with the new version of &man.config.8;&prompt.root; /usr/obj/usr/src/usr.sbin/config/config KERNELNAMEThis may not work in all cases. It is recommended that you
complete make world (or make
installworld) before compiling a new kernel.You are now done. After you have verified that everything appears
to be in the right place you can reboot the system. A simple
&man.fastboot.8; should do it.
&prompt.root; fastbootFinishedYou should now have successfully upgraded your FreeBSD system.
Congratulations.You may notice small problems due to things that you have missed.
For example, I once deleted /etc/magic as part of
the upgrade and merge to /etc, and the
file command stopped working. A moment's thought
meant that
&prompt.root; cd /usr/src/usr.bin/file
&prompt.root;
was sufficient to fix that one.Do I need to re-make the world for every change?There is no easy answer to this one, as it depends on the
nature of the change. For example, I have just run CVSup, and
it has shown the following files as being updated since I last
ran it;src/games/cribbage/instr.csrc/games/sail/pl_main.csrc/release/sysinstall/config.csrc/release/sysinstall/media.csrc/share/mk/bsd.port.mkThere is nothing in there that I would re-make the world
for. I would go to the appropriate sub-directories and
make all install, and that's about it. But
if something major changed, for example
src/lib/libc/stdlib then I would either
re-make the world, or at least those parts of it that are
statically linked (as well as anything else I might have added
that is statically linked).At the end of the day, it is your call. You might be happy
re-making the world every fortnight say, and let changes
accumulate over that fortnight. Or you might want to re-make
just those things that have changed, and are confident you can
spot all the dependencies.And, of course, this all depends on how often you want to
upgrade, and whether you are tracking -STABLE or
-CURRENT.My compile failed with lots of signal 12 (or other signal
number) errors. What has happened?This is normally indicative of hardware problems.
(Re)making the world is an effective way to stress test your
hardware, and will frequently throw up memory problems. These
normally manifest themselves as the compiler mysteriously dying
on receipt of strange signals.A sure indicator of this is if you can restart the make and
it dies at a different point in the process.In this instance there is little you can do except start
swapping around the components in your machine to determine
which one is failing.Can I remove /usr/obj when I have
finished?That depends on how you want to make the world on future
occasions./usr/obj contains all the object files
that were produced during the compilation phase. Normally, one
of the first steps in the /usr/obj around after you have finished
makes little sense, and will free up a large chunk of disk space
(currently about 150MB).However, if you know what you are doing you can have
If you want to live dangerously then make the world, passing
the NOCLEAN definition to make, like
this:&prompt.root; make -DNOCLEAN worldCan interrupted builds be resumed?This depends on how far through the process you got before
you found a problem.In general (and this is not a hard and
fast rule) the make world process builds new
copies of essential tools (such as &man.gcc.1;, and
&man.make.1;>) and the system libraries. These tools and
libraries are then installed. The new tools and libraries are
then used to rebuild themselves, and are installed again. The
entire system (now including regular user programs, such as
&man.ls.1; or &man.grep.1;) is then rebuilt with the new
system files.If you are at the last state, and you know it (because you
have looked through the output that you were storing) then you
can (fairly safely) do… fix the problem …
&prompt.root; cd /usr/src
&prompt.root; make -DNOCLEAN allThis will not undo the work of the previous
make world.If you see the message
--------------------------------------------------------------
Building everything..
--------------------------------------------------------------
in the make world output then it is
probably fairly safe to do so.If you do not see that message, or you are not sure, then it
is always better to be safe than sorry, and restart the build
from scratch.Can I use one machine as a People often ask on the FreeBSD mailing lists whether they
can do all the compiling on one machine, and then use the
results of that compile to make install on to
other machines around the network.This is not something I have done, so the suggestions below
are either from other people, or deduced from the
Makefiles.The precise approach to take depends on your version of
FreeBSDYou must still upgrade /etc and
/dev on the target machines after doing
this.For 2.1.7 and below, Antonio Bemfica
suggested the following approach:Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST)
From: Antonio Bemfica <bemfica@militzer.me.tuns.ca>
To: freebsd-questions@FreeBSD.org
Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca>
Josef Karthauser asked:
> Has anybody got a good method for upgrading machines on a network
First make world, etc. on your main machine
Second, mount / and /usr from the remote machine:
main_machine% mount remote_machine:/ /mnt
main_machine% mount remote_machine:/usr /mnt/usr
Third, do a 'make install' with /mnt as the destination:
main_machine% make install DESTDIR=/mnt
Repeat for every other remote machine on your network. It works fine
for me.
AntonioThis mechanism will only work (to the best of my knowledge)
if you can write to /usr/src on the NFS
server, as the install target in 2.1.7
and below needed to do this.Midway between 2.1.7 and 2.2.0 the reinstall
target was committed. You can use the approach exactly as
outlined above for 2.1.7, but use reinstall
instead of install.This approach does not require write
access to the /usr/src directory on the NFS
server.There was a bug introduced in this target between versions
1.68 and 1.107 of the Makefile, which meant that write access to
the NFS server was required. This bug was
fixed before version 2.2.0 of FreeBSD was released, but may be an
issue of you have an old server still running -STABLE from this
era.For version 2.2.5 and above, you can use the
buildworld and installworld
targets. Use them to build a source tree on one machine, and
then NFS mount /usr/src and
/usr/obj on the remote machine and install
it there.How can I speed up making the world?Run in single user mode.Put the /usr/src and
/usr/obj directories on separate
filesystems held on separate disks. If possible, put these
disks on separate disk controllers.Better still, put these filesystems across separate
disks using the ccd (concatenated disk
driver) device.Turn off profiling (set NOPROFILE=true in
/etc/make.conf). You almost certainly
do not need it.Also in /etc/make.conf, set
CFLAGS to something like -O
-pipe. The optimisation -O2 is much
slower, and the optimisation difference between
-O and -O2 is normally
negligible. -pipe lets the compiler use
pipes rather than temporary files for communication, which
saves disk access (at the expense of memory).Pass the
-j<n>
option to make (if
you are running a sufficiently recent version of FreeBSD) to
run multiple processes in parallel. This helps regardless
of whether you have a single or a multi processor
machine.The filesystem holding
/usr/src can be mounted (or remounted)
with the noatime option. This stops the time
files in the filesystem were last accessed from being
written to the disk. You probably do not need this
information anyway.
noatime is in version 2.2.0 and
above.&prompt.root; mount -u -o noatime /usr/srcThe example assumes /usr/src is
on its own filesystem. If it is not (if it is a part of
/usr for example) then you will
need to use that filesystem mount point, and not
/usr/src.The filesystem holding /usr/obj can
be mounted (or remounted) with the async
option. This causes disk writes to happen asynchronously.
In other words, the write completes immediately, and the
data is written to the disk a few seconds later. This
allows writes to be clustered together, and can be a
dramatic performance boost.Keep in mind that this option makes your filesystem
more fragile. With this option there is an increased
chance that, should power fail, the filesystem will be in
an unrecoverable state when the machine restarts.If /usr/obj is the only thing on
this filesystem then it is not a problem. If you have
other, valuable data on the same filesystem then ensure
your backups are fresh before you enable this
option.&prompt.root; mount -u -o async /usr/objAs above, if /usr/obj is not on
its own filesystem, replace it in the example with the
name of the appropriate mount point.
diff --git a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
index 3503c0ecf1..74c17dcee1 100644
--- a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,3487 +1,3506 @@
The Cutting EdgeRestructured, reorganized, and parts updated by &a.jim;
March 2000. Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik;
with feedback from various others.SynopsisFreeBSD is under constant development between releases. For
people who want to be on the cutting edge, there are several easy
mechanisms for keeping your system in sync with the latest
developments. Be warned—the cutting edge is not for everyone!
This chapter will help you decide if you want to track the
development system, or stick with one of the released
versions.-CURRENT vs. -STABLEThere are two development branches to FreeBSD; -CURRENT and
-STABLE. This section will explain a bit about each and describe
how to keep your system up-to-date with each respective tree.
-CURRENT will be discussed first, then -STABLE.Staying Current with FreeBSDAs you are reading this, keep in mind that -CURRENT is the
“bleeding edge” of FreeBSD development and that if you
are new to FreeBSD, you are most likely going to want to think
twice about running it.What is FreeBSD-CURRENT?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!Who needs FreeBSD-CURRENT?FreeBSD-CURRENT is made generally available for 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.What is FreeBSD-CURRENT not?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.Using FreeBSD-CURRENTJoin 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 &a.cvsall; mailing list will allow you to see the
commit log entry for each change as it is made along with
any pertinent information on possible side-effects.To join these lists, send mail to &a.majordomo; and
specify the following in the body of your message:
subscribe freebsd-current
subscribe cvs-allOptionally, you can also say help
and Majordomo will send you full help on how to subscribe
and unsubscribe to the various other mailing lists we
support.Grab the sources from ftp.FreeBSD.org. You can do this in
one of three ways:Use the CTM facility. Unless
you have a good TCP/IP connection at a flat rate, this
is the way to do it.Use the cvsup program
with this
supfile. This is the second most recommended
method, since it allows you to grab the entire
collection once and then only what has changed from then
on. Many people run cvsup from cron and keep their
sources up-to-date automatically. For a fairly easy
interface to this, simply type:
Use ftp. The source tree for
FreeBSD-CURRENT is always “exported” on:
ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/.
We also use wu-ftpd which allows
compressed/tar'd grabbing of whole trees. e.g. you
see:usr.bin/lexYou can do the following to get the whole directory
as a tar file:ftp>cd usr.binftp>get lex.tarEssentially, if you need rapid on-demand access to the
source and communications bandwidth is not a consideration,
use cvsup or ftp.
Otherwise, use CTM.If you are grabbing the sources to run, and not just
look at, then grab all of current, not
just selected portions. The reason for this is that various
parts of the source depend on updates elsewhere, and trying
to compile just a subset is almost guaranteed to get you
into trouble.Before compiling current, read the
Makefilein /usr/src
carefully. You should at least run a make world the first time through
as part of the upgrading process. Reading the &a.current;
will keep you up-to-date on other bootstrapping procedures
that sometimes become necessary as we move towards the next
release.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!Staying Stable with FreeBSDIf you are using FreeBSD in a production environment and want
to make sure you have the latest fixes from the -CURRENT branch,
you want to be running -STABLE. This is the tree that -RELEASEs
are branched from when we are putting together a new release. For
example, if you have a copy of 3.4-RELEASE, that is really just a
“snapshot” from the -STABLE branch that we put on
CDROM. In order to get any changes merged into -STABLE after the
-RELEASE, you need to “track” the -STABLE
branch.What is FreeBSD-STABLE?FreeBSD-STABLE is our development branch for a more low-key
and conservative set of changes intended for our next mainstream
release. Changes of an experimental or untested nature do not
go into this branch (see FreeBSD-CURRENT).Who needs FreeBSD-STABLE?If you are a commercial user or someone who puts maximum
stability of their FreeBSD system before all other concerns, you
should consider tracking stable. This is
especially true if you have installed the most recent release
(&rel.current;-RELEASE
at the time of this writing) since the
stable branch is effectively a bug-fix
stream relative to the previous release.The stable tree endeavors, above all,
to be fully compilable and stable at all times, but we do
occasionally make mistakes (these are still active sources
with quickly-transmitted updates, after all). We also do our
best to thoroughly test fixes in current
before bringing them into stable, but
sometimes our tests fail to catch every case. If something
breaks for you in stable, please let us
know immediately! (see next
section).Using FreeBSD-STABLEJoin the &a.stable;. This will keep you informed of
build-dependencies that may appear in
stable or any other issues requiring
special attention. Developers will also make announcements
in this mailing list when they are contemplating some
controversial fix or update, giving the users a chance to
respond if they have any issues to raise concerning the
proposed change.The &a.cvsall; mailing list will allow you to see the
commit log entry for each change as it is made along with
any pertinent information on possible side-effects.To join these lists, send mail to &a.majordomo; and
specify the following in the body of your message:
subscribe freebsd-stable
subscribe cvs-allOptionally, you can also say help
and Majordomo will send you full help on how to subscribe
and unsubscribe to the various other mailing lists we
support.If you are installing a new system and want it to be as
stable as possible, you can simply grab the latest dated
branch snapshot from ftp://releng3.FreeBSD.org/pub/FreeBSD/
and install it like any other release.If you are already running a previous release of FreeBSD
and wish to upgrade via sources then you can easily do so
from ftp.FreeBSD.org. This can
be done in one of three ways:Use the CTM facility. Unless
you have a good TCP/IP connection at a flat rate, this
is the way to do it.Use the cvsup program
with this
supfile. This is the second most recommended
method, since it allows you to grab the entire
collection once and then only what has changed from then
on. Many people run cvsup from cron to keep their
sources up-to-date automatically. For a fairly easy
interface to this, simply type:
Use ftp. The source tree for
FreeBSD-STABLE is always “exported” on:
ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/We also use wu-ftpd which allows
compressed/tar'd grabbing of whole trees. e.g. you
see:usr.bin/lexYou can do the following to get the whole directory
for you as a tar file:ftp>cd usr.binftp>get lex.tarEssentially, if you need rapid on-demand access to the
source and communications bandwidth is not a consideration,
use cvsup or ftp.
Otherwise, use CTM.Before compiling stable, read the
Makefile in /usr/src
carefully. You should at least run a make world the first time through
as part of the upgrading process. Reading the &a.stable; will
keep you up-to-date on other bootstrapping procedures that
sometimes become necessary as we move towards the next
release.Synchronizing Your SourceThere are various ways of using an Internet (or email)
connection to stay up-to-date with any given area of the FreeBSD
project sources, or all areas, depending on what interests you. The
primary services we offer are Anonymous
CVS, CVSup, and CTM.Anonymous CVS and
CVSup use the pull
model of updating sources. In the case of
CVSup the user (or a cron script) invokes
the cvsup program, and it interacts with a
cvsupd server somewhere to bring your files
up-to-date. The updates you receive are up-to-the-minute and you
get them when, and only when, you want them. You can easily
restrict your updates to the specific files or directories that are
of interest to you. Updates are generated on the fly by the server,
according to what you have and what you want to have.
Anonymous CVS is quite a bit more
simplistic than CVSup in that it's just an extension to
CVS which allows it to pull changes
directly from a remote CVS repository.
CVSup can do this far more efficiently,
but Anonymous CVS is easier to
use.CTM, on the other hand, does not
interactively compare the sources you have with those on the master
archive or otherwise pull them across.. Instead, a script which
identifies changes in files since its previous run is executed
several times a day on the master CTM machine, any detected changes
being compressed, stamped with a sequence-number and encoded for
transmission over email (in printable ASCII only). Once received,
these “CTM deltas” can then be handed to the
&man.ctm.rmail.1; utility which will automatically decode, verify
and apply the changes to the user's copy of the sources. This
process is far more efficient than CVSup,
and places less strain on our server resources since it is a
push rather than a pull
model.There are other trade-offs, of course. If you inadvertently
wipe out portions of your archive, CVSup
will detect and rebuild the damaged portions for you.
CTM won't do this, and if you wipe some
portion of your source tree out (and don't have it backed up) then
you will have to start from scratch (from the most recent CVS
“base delta”) and rebuild it all with CTM or, with
anoncvs, simply delete the bad bits and resync.More information about Anonymous CVS,
CTM, and
CVSup is available further down in this
section.Anonymous CVSIntroductionAnonymous CVS (or, as it is otherwise known,
anoncvs) is a feature provided by the CVS
utilities bundled with FreeBSD for synchronizing with a remote
CVS repository. Among other things, it allows users of FreeBSD
to perform, with no special privileges, read-only CVS operations
against one of the FreeBSD project's official anoncvs servers.
To use it, one simply sets the CVSROOT
environment variable to point at the appropriate anoncvs server,
provides the well-known password anoncvs with the
cvs login command, and then uses the
&man.cvs.1; command to access it like any local
repository.While it can also be said that the CVSup and anoncvs
services both perform essentially the same function, there are
various trade-offs which can influence the user's choice of
synchronization methods. In a nutshell,
CVSup is much more efficient in its
usage of network resources and is by far the most technically
sophisticated of the two, but at a price. To use
CVSup, a special client must first be
installed and configured before any bits can be grabbed, and
then only in the fairly large chunks which
CVSup calls
collections.Anoncvs, by contrast, can be used
to examine anything from an individual file to a specific
program (like ls or grep)
by referencing the CVS module name. Of course,
anoncvs is also only good for
read-only operations on the CVS repository, so if it's your
intention to support local development in one repository shared
with the FreeBSD project bits then
CVSup is really your only
option.Using Anonymous CVSConfiguring &man.cvs.1; to use an Anonymous CVS repository
is a simple matter of setting the CVSROOT
environment variable to point to one of the FreeBSD project's
anoncvs servers. At the time of this
writing, the following servers are available:USA:
:pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
(Use cvs login and enter the password
anoncvs when prompted.)Since CVS allows one to “check out” virtually
any version of the FreeBSD sources that ever existed (or, in
some cases, will exist :-), you need to be
familiar with the revision (
-r
) flag to
&man.cvs.1; and what some of the permissible values for it in
the FreeBSD Project repository are.There are two kinds of tags, revision tags and branch tags.
A revision tag refers to a specific revision. Its meaning stays
the same from day to day. A branch tag, on the other hand,
refers to the latest revision on a given line of development, at
any given time. Because a branch tag does not refer to a
specific revision, it may mean something different tomorrow than
it means today.Here are the branch tags that users might be interested
in (keep in mind that the only tags valid for the ports collection is
HEAD).HEADSymbolic name for the main line, or FreeBSD-CURRENT.
Also the default when no revision is specified.RELENG_3The line of development for FreeBSD-3.X, also known
as FreeBSD-STABLE.RELENG_2_2The line of development for FreeBSD-2.2.X, also known
as 2.2-STABLE. This branch is mostly obsolete.Here are the revision tags that users might be interested
in. Again, none of these are valid for the ports collection
since the ports collection does not have multiple
revisions.RELENG_3_4_0_RELEASEFreeBSD-3.4.RELENG_3_3_0_RELEASEFreeBSD-3.3.RELENG_3_2_0_RELEASEFreeBSD-3.2.RELENG_3_1_0_RELEASEFreeBSD-3.1.RELENG_3_0_0_RELEASEFreeBSD-3.0.RELENG_2_2_8_RELEASEFreeBSD-2.2.8.RELENG_2_2_7_RELEASEFreeBSD-2.2.7.RELENG_2_2_6_RELEASEFreeBSD-2.2.6.RELENG_2_2_5_RELEASEFreeBSD-2.2.5.RELENG_2_2_2_RELEASEFreeBSD-2.2.2.RELENG_2_2_1_RELEASEFreeBSD-2.2.1.RELENG_2_2_0_RELEASEFreeBSD-2.2.0.When you specify a branch tag, you normally receive the
latest versions of the files on that line of development. If
you wish to receive some past version, you can do so by
specifying a date with the
-D date
flag.
See the &man.cvs.1; man page for more details.ExamplesWhile it really is recommended that you read the manual page
for &man.cvs.1; thoroughly before doing anything, here are some
quick examples which essentially show how to use Anonymous
CVS:Checking out something from -CURRENT (&man.ls.1;) and
deleting it again:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co ls
&prompt.user; cvs release -d ls
&prompt.user; cvs logoutChecking out the version of &man.ls.1; in the 2.2-STABLE
branch:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co -rRELENG_2_2 ls
&prompt.user; cvs release -d ls
&prompt.user; cvs logoutCreating a list of changes (as unidiffs) to &man.ls.1;
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls
&prompt.user; cvs logoutFinding out what other module names can be used:
&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
&prompt.user; cvs loginAt the prompt, enter the passwordanoncvs.
&prompt.user; cvs co modules
&prompt.user; more modules/modules
&prompt.user; cvs release -d modules
&prompt.user; cvs logoutOther ResourcesThe following additional resources may be helpful in learning
CVS:CVS Tutorial from Cal Poly.Cyclic Software,
commercial maintainers of CVS.CVSWeb is
the FreeBSD Project web interface for CVS.CTMCTM is a method for keeping a
remote directory tree in sync with a central one. It has been
developed for usage with FreeBSD's source trees, though other
people may find it useful for other purposes as time goes by.
Little, if any, documentation currently exists at this time on the
process of creating deltas, so talk to &a.phk; for more
information should you wish to use CTM
for other things.Why should I use CTM?CTM will give you a local copy of
the FreeBSD source trees. There are a number of
“flavors” of the tree available. Whether you wish
to track the entire CVS tree or just one of the branches,
CTM can provide you the information.
If you are an active developer on FreeBSD, but have lousy or
non-existent TCP/IP connectivity, or simply wish to have the
changes automatically sent to you,
CTM was made for you. You will need
to obtain up to three deltas per day for the most active
branches. However, you should consider having them sent by
automatic email. The sizes of the updates are always kept as
small as possible. This is typically less than 5K, with an
occasional (one in ten) being 10-50K and every now and then a
biggie of 100K+ or more coming around.You will also need to make yourself aware of the various
caveats related to working directly from the development sources
rather than a pre-packaged release. This is particularly true
if you choose the “current” sources. It is
recommended that you read Staying
current with FreeBSD.What do I need to use
CTM?You will need two things: The CTM
program, and the initial deltas to feed it (to get up to
“current” levels).The CTM program has been part of
FreeBSD ever since version 2.0 was released, and lives in
/usr/src/usr.sbin/CTM if you have a copy
of the source available.If you are running a pre-2.0 version of FreeBSD, you can
fetch the current CTM sources
directly from:ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/The “deltas” you feed
CTM can be had two ways, FTP or
email. If you have general FTP access to the Internet then the
following FTP sites support access to
CTM:ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/or see section mirrors.FTP the relevant directory and fetch the
README file, starting from there.If you wish to get your deltas via email:Send email to &a.majordomo; to subscribe to one of the
CTM distribution lists.
“ctm-cvs-cur” supports the entire cvs tree.
“ctm-src-cur” supports the head of the development
branch. “ctm-src-2_2” supports the 2.2 release
branch, etc.. (If you do not know how to subscribe yourself
using majordomo, send a message first containing the word
help — it will send you back usage
instructions.)When you begin receiving your CTM
updates in the mail, you may use the
ctm_rmail program to unpack and apply them.
You can actually use the ctm_rmail program
directly from a entry in /etc/aliases if
you want to have the process run in a fully automated fashion.
Check the ctm_rmail man page for more
details.No matter what method you use to get the
CTM deltas, you should subscribe to
the ctm-announce@FreeBSD.org mailing list. In
the future, this will be the only place where announcements
concerning the operations of the
CTM system will be posted. Send an
email to &a.majordomo; with a single line of
subscribe ctm-announce to get added to the
list.Using CTM for the first
timeBefore you can start using CTM
deltas, you will need to get to a starting point for the deltas
produced subsequently to it.First you should determine what you already have. Everyone
can start from an “empty” directory. You must use
an initial “Empty” delta to start off your
CTM supported tree. At some point it
is intended that one of these “started” deltas be
distributed on the CD for your convenience, however, this does
not currently happen.Since the trees are many tens of megabytes, you should
prefer to start from something already at hand. If you have a
-RELEASE CD, you can copy or extract an initial source from it.
This will save a significant transfer of data.You can recognize these “starter” deltas by the
X appended to the number
(src-cur.3210XEmpty.gz for instance). The
designation following the X corresponds to
the origin of your initial “seed”.
Empty is an empty directory. As a rule a
base transition from Empty is produced
every 100 deltas. By the way, they are large! 25 to 30
Megabytes of gzip'd data is common for the
XEmpty deltas.Once you've picked a base delta to start from, you will also
need all deltas with higher numbers following it.Using CTM in your daily
lifeTo apply the deltas, simply say:&prompt.root; cd /where/ever/you/want/the/stuff
&prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.*CTM understands deltas which have
been put through gzip, so you do not need to
gunzip them first, this saves disk space.Unless it feels very secure about the entire process,
CTM will not touch your tree. To
verify a delta you can also use the
-c
flag and
CTM will not actually touch your
tree; it will merely verify the integrity of the delta and see
if it would apply cleanly to your current tree.There are other options to CTM
as well, see the manual pages or look in the sources for more
information.I would also be very happy if somebody could help with the
“user interface” portions, as I have realized that I
cannot make up my mind on what options should do what, how and
when...That is really all there is to it. Every time you get a new
delta, just run it through CTM to
keep your sources up to date.Do not remove the deltas if they are hard to download again.
You just might want to keep them around in case something bad
happens. Even if you only have floppy disks, consider using
fdwrite to make a copy.Keeping your local changesAs a developer one would like to experiment with and change
files in the source tree. CTM
supports local modifications in a limited way: before checking
for the presence of a file foo, it first
looks for foo.ctm. If this file exists,
CTM will operate on it instead of
foo.This behaviour gives us a simple way to maintain local
changes: simply copy the files you plan to modify to the
corresponding file names with a .ctm
suffix. Then you can freely hack the code, while CTM keeps the
.ctm file up-to-date.Other interesting CTM optionsFinding out exactly what would be touched by an
updateYou can determine the list of changes that
CTM will make on your source
repository using the
-l
option to
CTM.This is useful if you would like to keep logs of the
changes, pre- or post- process the modified files in any
manner, or just are feeling a tad paranoid
:-).Making backups before updatingSometimes you may want to backup all the files that would
be changed by a CTM update.Specifying the
-B backup-file
option
causes CTM to backup all files that
would be touched by a given CTM
delta to backup-file.Restricting the files touched by an updateSometimes you would be interested in restricting the scope
of a given CTM update, or may be
interested in extracting just a few files from a sequence of
deltas.You can control the list of files that
CTM would operate on by specifying
filtering regular expressions using the
-e
and
-x
options.For example, to extract an up-to-date copy of
lib/libc/Makefile from your collection of
saved CTM deltas, run the commands:&prompt.root; cd /where/ever/you/want/to/extract/it/
&prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*For every file specified in a
CTM delta, the
-e
and
-x
options are applied in the order given
on the command line. The file is processed by
CTM only if it is marked as
eligible after all the
-e
and
-x
options are applied to it.Future plans for CTMTons of them:Use some kind of authentication into the CTM system, so
as to allow detection of spoofed CTM updates.Clean up the options to CTM,
they became confusing and counter intuitive.Miscellaneous stuffAll the “DES infected” (e.g. export controlled)
source is not included. You will get the
“international” version only. If sufficient
interest appears, we will set up a sec-cur
sequence too. There is a sequence of deltas for the
ports collection too, but interest has not
been all that high yet. Tell me if you want an email list for
that too and we will consider setting it up.CVSupIntroductionCVSup 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.InstallationThe easiest way to install CVSup
is to use the net/cvsup-bin port
from the FreeBSD ports collection.
If you prefer to build CVSup from
source, you can use the net/cvsup
port instead. But be forewarned: the
net/cvsup port depends on the Modula-3
system, which takes a substantial amount of time, memory, and
disk space to build.If you do not know anything about cvsup at all and want a
single package which will install it, set up the configuration
file and start the transfer via a pointy-clicky type of
interface, then get the cvsupit
package. Just hand it to &man.pkg.add.1; and it will lead you
through the configuration process in a menu-oriented
fashion.CVSup ConfigurationCVSup's operation is controlled
by a configuration file called the supfile.
There are some sample supfiles in the
directory /usr/share/examples/cvsup/.The information in a supfile answers
the following questions for cvsup:Which files do you
want to receive?Which versions of them
do you want?Where do you want to
get them from?Where do you want to
put them on your own machine?Where do you want to
put your status files?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 FreeBSD-CURRENT.Which files do you want
to receive?The files available via CVSup
are organized into named groups called
“collections”. The collections that are
available are described here. In this example, we
wish to receive the entire main source tree for the FreeBSD
system. There is a single large collection
src-all which will give us all of that,
except the export-controlled cryptography support. Let us
assume for this example that we are in the USA or Canada.
Then we can get the cryptography code with one additional
collection, cvs-crypto. As a first step
toward constructing our supfile, we
simply list these collections, one per line:
src-all
cvs-cryptoWhich version(s) of them
do you want?With CVSup, you can receive
virtually any version of the sources that ever existed.
That is possible because the cvsupd server works directly
from the CVS repository, which contains all of the versions.
You specify which one of them you want using the
tag= and
date=
value
fields.Be very careful to specify any tag=
fields correctly. Some tags are valid only for certain
collections of files. If you specify an incorrect or
misspelled tag, CVSup will delete files which you probably
do not want deleted. In particular, use only
tag=. for the
ports-* collections.The tag= field names a symbolic tag
in the repository. There are two kinds of tags, revision
tags and branch tags. A revision tag refers to a specific
revision. Its meaning stays the same from day to day. A
branch tag, on the other hand, refers to the latest revision
on a given line of development, at any given time. Because
a branch tag does not refer to a specific revision, it may
mean something different tomorrow than it means
today.Here are the branch tags that users might be interested
in. Keep in mind that only the tag=. is
relevant for the ports collection.tag=.The main line of development, also known as
FreeBSD-CURRENT.The . is not punctuation; it
is the name of the tag. Valid for all
collections.RELENG_3The line of development for FreeBSD-3.X, also
known as FreeBSD-STABLE.RELENG_2_2The line of development for FreeBSD-2.2.X, also
known as 2.2-STABLE.Here are the revision tags that users might be interested
in. Again, these are not valid for the ports
collection.RELENG_3_4_0_RELEASEFreeBSD-3.4.tag=RELENG_3_3_0_RELEASEFreeBSD-3.3.tag=RELENG_3_2_0_RELEASEFreeBSD-3.2.tag=RELENG_3_1_0_RELEASEFreeBSD-3.1.tag=RELENG_3_0_0_RELEASEFreeBSD-3.0.tag=RELENG_2_2_8_RELEASEFreeBSD-2.2.8.tag=RELENG_2_2_7_RELEASEFreeBSD-2.2.7.tag=RELENG_2_2_6_RELEASEFreeBSD-2.2.6.tag=RELENG_2_2_5_RELEASEFreeBSD-2.2.5.tag=RELENG_2_2_2_RELEASEFreeBSD-2.2.2.tag=RELENG_2_2_1_RELEASEFreeBSD-2.2.1.tag=RELENG_2_2_0_RELEASEFreeBSD-2.2.0.Be very careful to type the tag name exactly as shown.
CVSup cannot distinguish
between valid and invalid tags. If you misspell the tag,
CVSup will behave as though you
had specified a valid tag which happens to refer to no
files at all. It will delete your existing sources in
that case.When you specify a branch tag, you normally receive the
latest versions of the files on that line of development.
If you wish to receive some past version, you can do so by
specifying a date with the
date=
value
field. The &man.cvsup.1; manual page explains how to do
that.For our example, we wish to receive FreeBSD-CURRENT. We
add this line at the beginning of our
supfile:
*default tag=.There is an important special case that comes into play
if you specify neither a tag= field nor a
date= field. In that case, you receive
the actual RCS files directly from the server's CVS
repository, rather than receiving a particular version.
Developers generally prefer this mode of operation. By
maintaining a copy of the repository itself on their
systems, they gain the ability to browse the revision
histories and examine past versions of files. This gain is
achieved at a large cost in terms of disk space,
however.Where do you want to get
them from?We use the host= field to tell
cvsup where to obtain its updates. Any
of the CVSup mirror
sites will do, though you should try to select one
that is close to you in cyberspace. In this example we will
use a fictional FreeBSD distribution site,
cvsup666.FreeBSD.org:
*default host=cvsup666.FreeBSD.orgYou will need to change the host to one that actually
exists before running CVSup. On any particular run of
cvsup, you can override the host setting
on the command line, with
-h
hostname
.Where do you want to put
them on your own machine?The prefix= field tells
cvsup where to put the files it receives.
In this example, we will put the source files directly into
our main source tree, /usr/src. The
src directory is already implicit in
the collections we have chosen to receive, so this is the
correct specification:
*default prefix=/usrWhere should
cvsup maintain its status files?The cvsup client maintains certain status files in what
is called the “base” directory. These files
help CVSup to work more
efficiently, by keeping track of which updates you have
already received. We will use the standard base directory,
/usr/local/etc/cvsup:
*default base=/usr/local/etc/cvsupThis setting is used by default if it is not specified
in the supfile, so we actually do not
need the above line.If your base directory does not already exist, now would
be a good time to create it. The cvsup
client will refuse to run if the base directory does not
exist.Miscellaneous supfile
settings:There is one more line of boiler plate that normally
needs to be present in the
supfile:
*default release=cvs delete use-rel-suffix compressrelease=cvs indicates that the server
should get its information out of the main FreeBSD CVS
repository. This is virtually always the case, but there
are other possibilities which are beyond the scope of this
discussion.delete gives
CVSup permission to delete files.
You should always specify this, so that
CVSup can keep your source tree
fully up-to-date. CVSup is
careful to delete only those files for which it is
responsible. Any extra files you happen to have will be
left strictly alone.use-rel-suffix is ... arcane. If you
really want to know about it, see the &man.cvsup.1; manual
page. Otherwise, just specify it and do not worry about
it.compress enables the use of
gzip-style compression on the communication channel. If
your network link is T1 speed or faster, you probably should
not use compression. Otherwise, it helps
substantially.Putting it all together:Here is the entire supfile for our
example:
*default tag=.
*default host=cvsup666.FreeBSD.org
*default prefix=/usr
*default base=/usr/local/etc/cvsup
*default release=cvs delete use-rel-suffix compress
src-all
cvs-cryptoRunning CVSupYou are now ready to try an update. The command line for
doing this is quite simple:&prompt.root; cvsup supfilewhere 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:&prompt.root; mkdir /var/tmp/dest
&prompt.root; cvsup supfile /var/tmp/destThe 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:&prompt.root; cvsup -g -L 2 supfileThe
-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 &man.cron.8;.
Obviously, you should not let cvsup use its GUI when running it
from cron.CVSup File CollectionsThe 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
src-all, cvs-crypto, and
ports-all. The other collections are used
only by small groups of people for specialized purposes, and
some mirror sites may not carry all of them.cvs-all release=cvsThe main FreeBSD CVS repository, excluding the
export-restricted cryptography code.distrib release=cvsFiles related to the distribution and mirroring
of FreeBSD.doc-all release=cvsSources for the FreeBSD handbook and other
documentation.ports-all release=cvsThe FreeBSD ports collection.ports-archivers
release=cvsArchiving tools.ports-astro
release=cvsAstronomical ports.ports-audio
release=cvsSound support.ports-base
release=cvsMiscellaneous files at the top of
/usr/ports.ports-benchmarks
release=cvsBenchmarks.ports-biology
release=cvsBiology.ports-cad
release=cvsComputer aided design tools.ports-chinese
release=cvsChinese language support.ports-comms
release=cvsCommunication software.ports-converters
release=cvscharacter code converters.ports-databases
release=cvsDatabases.ports-deskutils
release=cvsThings that used to be on the desktop
before computers were invented.ports-devel
release=cvsDevelopment utilities.ports-editors
release=cvsEditors.ports-emulators
release=cvsEmulators for other operating
systems.ports-ftp
release=cvsFTP client and server utilities.ports-games
release=cvsGames.ports-german
release=cvsGerman language support.ports-graphics
release=cvsGraphics utilities.ports-irc
release=cvsInternet Relay Chat utilities.ports-japanese
release=cvsJapanese language support.ports-java
release=cvsJava utilities.ports-korean
release=cvsKorean language support.ports-lang
release=cvsProgramming languages.ports-mail
release=cvsMail software.ports-math
release=cvsNumerical computation software.ports-mbone
release=cvsMBone applications.ports-misc
release=cvsMiscellaneous utilities.ports-net
release=cvsNetworking software.ports-news
release=cvsUSENET news software.ports-palm
release=cvsSoftware support for 3Com Palm(tm)
series.ports-print
release=cvsPrinting software.ports-russian
release=cvsRussian language support.ports-security
release=cvsSecurity utilities.ports-shells
release=cvsCommand line shells.ports-sysutils
release=cvsSystem utilities.ports-textproc
release=cvstext processing utilities (does not
include desktop publishing).ports-vietnamese
release=cvsVietnamese language support.ports-www
release=cvsSoftware related to the World Wide
Web.ports-x11
release=cvsPorts to support the X window
system.ports-x11-clocks
release=cvsX11 clocks.ports-x11-fm
release=cvsX11 file managers.ports-x11-fonts
release=cvsX11 fonts and font utilities.ports-x11-toolkits
release=cvsX11 toolkits.ports-x11-serversX11 servers.ports-x11-wmX11 window managers.src-all release=cvsThe main FreeBSD sources, excluding the
export-restricted cryptography code.src-base
release=cvsMiscellaneous files at the top of
/usr/src.src-bin
release=cvsUser utilities that may be needed in
single-user mode
(/usr/src/bin).src-contrib
release=cvsUtilities and libraries from outside the
FreeBSD project, used relatively unmodified
(/usr/src/contrib).src-etc
release=cvsSystem configuration files
(/usr/src/etc).src-games
release=cvsGames
(/usr/src/games).src-gnu
release=cvsUtilities covered by the GNU Public
License (/usr/src/gnu).src-include
release=cvsHeader files
(/usr/src/include).src-kerberos5
release=cvsKerberos5 security package
(/usr/src/kerberos5).src-kerberosIV
release=cvsKerberosIV security package
(/usr/src/kerberosIV).src-lib
release=cvsLibraries
(/usr/src/lib).src-libexec
release=cvsSystem programs normally executed by other
programs
(/usr/src/libexec).src-release
release=cvsFiles required to produce a FreeBSD
release
(/usr/src/release).src-sbin
release=cvsSystem utilities for single-user mode
(/usr/src/sbin).src-share
release=cvsFiles that can be shared across multiple
systems
(/usr/src/share).src-sys
release=cvsThe kernel
(/usr/src/sys).src-tools
release=cvsVarious tools for the maintenance of
FreeBSD
(/usr/src/tools).src-usrbin
release=cvsUser utilities
(/usr/src/usr.bin).src-usrsbin
release=cvsSystem utilities
(/usr/src/usr.sbin).www release=cvsThe sources for the World Wide Web data.cvs-crypto release=cvsThe export-restricted cryptography code.src-crypto release=cvsExport-restricted utilities and libraries from
outside the FreeBSD project, used relatively
unmodified
(/usr/src/crypto).src-eBones release=cvsKerberos and DES
(/usr/src/eBones). Not
used in current releases of FreeBSD.src-secure release=cvsDES (/usr/src/secure).src-sys-crypto
release=cvsKernel cryptography code
(/usr/src/sys/crypto).distrib release=selfThe CVSup server's own configuration files. Used by
CVSup mirror sites.gnats release=currentThe GNATS bug-tracking database.mail-archive release=currentFreeBSD mailing list archive.www release=currentThe installed World Wide Web data. Used by WWW mirror
sites.For more informationFor the CVSup FAQ and other information about CVSup, see
The
CVSup Home Page.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 cvsup-bugs@polstra.com.Using make worldOnce you have synchronised your local source tree against a
particular version of FreeBSD (stable,
current and so on) you must then use the source
tree to rebuild the system.Take a backupI cannot stress highly enough how important it is to take a
backup of your system before you do this.
While remaking the world is (as long as you follow these
instructions) an easy task to do, there will inevitably be times
when you make mistakes, or when mistakes made by others in the
source tree render your system unbootable.Make sure you have taken a backup. And have a fixit floppy to
hand. I have never needed to use them, and, touch wood, I never
will, but it is always better to be safe than sorry.Subscribe to the right mailing listThe -STABLE and -CURRENT FreeBSD code branches are, by their
nature, in development. People that
contribute to FreeBSD are human, and mistakes occasionally
happen.Sometimes these mistakes can be quite harmless, just causing
your system to print a new diagnostic warning. Or the change may
be catastrophic, and render your system unbootable or destroy your
filesystems (or worse).If problems like these occur, a heads up is
posted to the appropriate mailing list, explaining the nature of
the problem and which systems it affects. And an all
clear announcement is posted when the problem has been
solved.If you try and track -STABLE or -CURRENT and do not read the
stable@FreeBSD.org or
current@FreeBSD.org mailing lists then you are
asking for trouble.
+
+ Read /usr/src/UPDATING
+
+ Before you do anything else, read
+ /usr/src/UPDATING (or the equivalent file
+ wherever you have a copy of the source code). This file should
+ contain important information about problems you might encounter, or
+ specify the order in which you might have to run certain commands.
+ If UPDATING contradicts something you read here,
+ UPDATING takes precedence.
+
+
+ Reading UPDATING is not an acceptable
+ substitute for subscribing to the correct mailing list, as described
+ previously. The two requirements are complementary, not
+ exclusive.
+
+
+
Check /etc/make.confExamine the file /etc/make.conf. This
contains some default defines for Everything is, by default, commented out. Uncomment those
entries that look useful. For a typical user (not a developer),
you will probably want to uncomment the CFLAGS and NOPROFILE
definitions.If your machine has a floating point unit (386DX, 486DX,
Pentium and up class machines) then you can also uncomment the
HAVE_FPU line.This definition was removed for version 2.2.2 and up of
FreeBSD.Examine the other definitions (COPTFLAGS, NOPORTDOCS and so
on) and decide if they are relevant to you.Update /etc/groupThe /etc directory contains a large part
of your system's configuration information, as well as scripts
that are run at system startup. Some of these scripts change from
version to version of FreeBSD.Some of the configuration files are also used in the day to
day running of the system. In particular,
/etc/group.There have been occasions when the installation part of
make world has expected certain usernames or groups
to exist. When performing an upgrade it is likely that these
groups did not exist. This caused problems when upgrading.The most recent example of this is when the ppp subsystem were installed using a
non-existent (for them) group name.The solution is to examine
/usr/src/etc/group and compare its list of
groups with your own. If they are any groups in the new file that
are not in your file then copy them over. Similarly, you should
rename any groups in /etc/group which have
the same GID but a different name to those in
/usr/src/etc/group.If you are feeling particularly paranoid, you can check your
system to see which files are owned by the group you are
renaming or deleting.&prompt.root; find / -group GID -printwill show all files owned by group
GID (which can be either a group name
or a numeric group ID).You may want to compile the system in single user mode. Apart
from the obvious benefit of making things go slightly faster,
reinstalling the system will touch a lot of important system
files, all the standard system binaries, libraries, include files
and so on. Changing these on a running system (particularly if
you have active users on their at the time) is asking for
trouble.
That said, if you are confident, you can omit this
step.Version 2.2.5 and aboveAs described in more detail below, versions 2.2.5 and above
of FreeBSD have separated the building process from the
installing process. You can therefore
build the new system in multi-user mode,
and then drop to single user mode to do the installation.As the superuser, you can execute&prompt.root; from a running system, which will drop it to single user
mode.Alternatively, reboot the system, and at the boot prompt,
enter the
-s
flag. The system will then boot
single user. At the shell prompt you should then run:&prompt.root; fsck -p
&prompt.root; mount -u /
&prompt.root; mount -a -t ufs
&prompt.root; swapon -aThis checks the filesystems, remounts /
read/write, mounts all the other UFS filesystems referenced in
/etc/fstab and then turns swapping on.Remove /usr/objAs parts of the system are rebuilt they are placed in
directories which (by default) go under
/usr/obj. The directories shadow those under
/usr/src.You can speed up the make world process, and
possibly save yourself some dependency headaches by removing this
directory as well.Some files below /usr/obj will have the
immutable flag set (see &man.chflags.1; for more information)
which must be removed first.&prompt.root; cd /usr/obj
&prompt.root; chflags -R noschg *
&prompt.root; rm -rf *All versionsYou must be in the /usr/src
directory...&prompt.root; cd /usr/src(unless, of course, your source code is elsewhere, in which
case change to that directory instead).To rebuild the world you use the &man.make.1; command. This
command reads instructions from the
Makefile which describes how the programs
that comprise FreeBSD should be rebuilt, the order they should
be built in, and so on.The general format of the command line you will type is as
follows:&prompt.root; make
-
-DVARIABLE
target
In this example,
-x
is an option that you would pass to &man.make.1;. See the
&man.make.1; manual page for an example of the options you can
pass.
-DVARIABLE
passes a variable to the Makefile. The
behavior of the Makefile is controlled by
these variables. These are the same variables as are set in
/etc/make.conf, and this provides another
way of setting them.&prompt.root; make -DNOPROFILE=true targetis another way of specifying that profiled libaries should
not be built, and corresponds with theNOPROFILE= true
# Avoid compiling profiled librarieslines in /etc/make.conf.target tells &man.make.1; what
you want to do. Each Makefile defines a
number of different targets, and your choice of
target determines what happens.Some targets are listed in the
Makefile, but are not meant for you to run.
Instead, they are used by the build process to break out the
steps necessary to rebuild the system into a number of
sub-steps.Most of the time you won't need to pass any parameters to
&man.make.1;, and so your command like will look like
this:&prompt.root; make targetSaving the outputIt's a good idea to save the output you get from running
&man.make.1; to another file. If something goes wrong you will
have a copy of the error message, and a complete list of where
the process had got to. While this might not help you in
diagnosing what has gone wrong, it can help others if you post
your problem to one of the FreeBSD mailing lists.The easiest way to do this is to use the &man.script.1;
command, with a parameter that specifies the name of the file to
save all output to. You would do this immediately before
remaking the world, and then type exit
when the process has finished.&prompt.root; script /var/tmp/mw.out
Script started, output file is /var/tmp/mw.out
&prompt.root; make world… compile, compile, compile …
&prompt.root; exit
Script done, …If you do this, do not save the output
in /tmp. This directory may be cleared
next time you reboot. A better place to store it is in
/var/tmp (as in the previous example) or
in root's home directory.Version 2.2.2 and below/usr/src/Makefile contains the
world target, which will rebuild the
entire system and then install it.Use it like this:&prompt.root; make worldVersion 2.2.5 and aboveBeginning with version 2.2.5 of FreeBSD (actually, it was
first created on the -CURRENT branch, and then retrofitted to
-STABLE midway between 2.2.2 and 2.2.5) the
world target has been split in
two. buildworld and
installworld.As the names imply, buildworld
builds a complete new tree under /usr/obj,
and installworld installs this tree on
the current machine.This is very useful for 2 reasons. First, it allows you to do
the build safe in the knowledge that no components of your running
system will be affected. The build is self hosted.
Because of this, you can safely run
buildworld on a machine running in
multi-user mode with no fear of ill-effects. I still recommend you
run the installworld part in single user
mode though.Secondly, it allows you to use NFS mounts to upgrade
multiple machines on your network. If you have three machines,
A, B and C that you want to upgrade, run make
buildworld and make installworld on
A. B and C should then NFS mount /usr/src
and /usr/obj from A, and you can then run
make installworld to install the results of
the build on B and C.The world target still exists, and
you can use it exactly as shown for version 2.2.2.
make world runs make
buildworld followed by make
installworld.If you do the make buildworld and
make installworld commands separately, you
must pass the same parameters to &man.make.1; each
time.If you run:&prompt.root; make -DNOPROFILE=true buildworldyou must install the results with:&prompt.root; make -DNOPROFILE=true installworldotherwise it would try and install profiled libraries that
had not been built during the make buildworld
phase.-CURRENT and aboveIf you are tracking -CURRENT you can also pass the
-j
option to make. This lets
make spawn several simultaneous processes.This is most useful on true multi-CPU machines. However, since
much of the compiling process is IO bound rather than CPU bound it is
also useful on single CPU machines.On a typical single-CPU machine you would run:&prompt.root; make -j4 target&man.make.1; will then have up to 4 processes running at any one
time. Empirical evidence posted to the mailing lists shows this
generally gives the best performance benefit.If you have a multi-CPU machine and you are using an SMP
configured kernel try values between 6 and 10 and see how they speed
things up.Be aware that (at the time of writing) this is still
experimental, and commits to the source tree may occasionally break
this feature. If the world fails to compile using this parameter
try again without it before you report any problems.TimingsAssuming everything goes well you have anywhere between an hour
and a half and a day or so to wait.As a general rule of thumb, a 200MHz P6 with more than 32MB of
RAM and reasonable SCSI disks will complete make
world in about an hour and a half. A 32MB P133 will
take 5 or 6 hours. Revise these figures down if your machines are
slower…Update /etcRemaking the world will not update certain directories (in
particular, /etc, /var and
/usr) with new or changed configuration files.
This is something you have to do by hand, eyeball, and judicious use
of &man.diff.1;.You cannot just copy over the files from
/usr/src/etc to /etc and
have it work. Some of these files must be installed
first. This is because the /usr/src/etc
directory is not a copy of what your
/etc directory should look like. In addition,
there are files that should be in /etc that are
not in /usr/src/etc.The simplest way to do this is to install the files into a new
directory, and then work through them looking for differences.Backup your existing /etcAlthough, in theory, nothing is going to touch this directory
automatically, it is always better to be sure. So copy your
existing /etc directory somewhere safe.
Something like:&prompt.root; cp -Rp /etc /etc.old
-R
does a recursive copy,
-p
preserves times, ownerships on files and suchlike.You need to build a dummy set of directories to install the new
/etc and other files into. I generally choose to
put this dummy directory in /var/tmp/root, and
there are a number of subdirectories required under this as
well.&prompt.root; mkdir /var/tmp/root
&prompt.root; cd /usr/src/etc
&prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distributionThis will build the necessary directory structure and install the
files. A lot of the subdirectories that have been created under
/var/tmp/root are empty and should be deleted.
The simplest way to do this is to:&prompt.root; cd /var/tmp/root
&prompt.root; find -d . -type d | /usr/bin/perl -lne \
'opendir(D,$_);@f=readdir(D);rmdir if $#f == 1;closedir(D);'This does a depth first search, examines each directory, and if
the number of files in that directory is 2 (/var/tmp/root now contains all the files that
should be placed in appropriate locations below
/. You now have to go through each of these
files, determining how they differ with your existing files.Note that some of the files that will have been installed in
/var/tmp/root have a leading /var/tmp/root/ and
/var/tmp/root/root/, although there may be others
(depending on when you are reading this. Make sure you use
The simplest way to do this is to use &man.diff.1; to compare the
two files.&prompt.root; diff /etc/shells /var/tmp/root/etc/shellsThis will show you the differences between your
/etc/shells file and the new
/etc/shells file. Use these to decide whether to
merge in changes that you have made or whether to copy over your old
file.Name the new root directory
(/var/tmp/root)with a timestamp, so you can
easily compare differences between versionsFrequently remaking the world means that you have to update
/etc frequently as well, which can be a bit of
a chore.You can speed this process up by keeping a copy of the last set
of changed files that you merged into /etc.
The following procedure gives one idea of how to do this.Make the world as normal. When you want to update
/etc and the other directories, give the
target directory a name based on the current date. If you were
doing this on the 14th of February 1998 you could do the
following.&prompt.root; mkdir /var/tmp/root-19980214
&prompt.root; cd /usr/src/etc
&prompt.root; make DESTDIR=/var/tmp/root-19980214 \
distrib-dirs distributionMerge in the changes from this directory as outlined
above.Do not remove the
/var/tmp/root-19980214 directory when you
have finished.When you have downloaded the latest version of the source
and remade it, follow step 1. This will give you a new
directory, which might be called
/var/tmp/root-19980221 (if you wait a week
between doing updates).You can now see the differences that have been made in the
intervening week using &man.diff.1; to create a recursive diff
between the two directories.&prompt.root; cd /var/tmp
&prompt.root; diff -r root-19980214 root-19980221Typically, this will be a much smaller set of differences
than those between
/var/tmp/root-19980221/etc and
/etc. Because the set of differences is
smaller, it is easier to migrate those changes across into your
/etc directory.You can now remove the older of the two
/var/tmp/root-* directories.&prompt.root; rm -rf /var/tmp/root-19980214Repeat this process every time you need to merge in changes
to /etc.You can use &man.date.1; to automate the generation of the
directory names.&prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"`Update /devDEVFSIf you are using DEVFS then this is probably unnecessary.For safety's sake, this is a multistep process.Copy /var/tmp/root/dev/MAKEDEV to
/dev.&prompt.root; cp /var/tmp/root/dev/MAKEDEV /devNow, take a snapshot of your current
/dev. This snapshot needs to contain the
permissions, ownerships, major and minor numbers of each filename,
but it should not contain the timestamps. The easiest way to do
this is to use &man.awk.1; to strip out some of the
information.&prompt.root; cd /dev
&prompt.root; ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.outRemake all the devices.&prompt.root; Write another snapshot of the directory, this time to
/var/tmp/dev2.out. Now look through these
two files for any devices that you missed creating. There should
not be any, but it is better to be safe than sorry.&prompt.root; diff /var/tmp/dev.out /var/tmp/dev2.outYou are most likely to notice disk slice discrepancies which
will involve commands such as
&prompt.root; sh MAKEDEV sd0s1
to recreate the slice entries. Your precise circumstances may
vary.Update /standThis step is included only for completeness, it can safely be
omitted.For completenesses sake you may want to update the files in
/stand as well. These files consist of hard
links to the /stand/sysinstall binary. This
binary should be statically linked, so that it can work when no other
filesystems (and in particular /usr) have been
mounted.&prompt.root; cd /usr/src/release/sysinstall
&prompt.root; make all installSource older than 2 April 1998If your source code is older than 2nd April 1998, or the
Makefile version is not 1.68 or higher (for
FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X
systems) you will need to add the
NOSHARED=yes option, like so;&prompt.root; make NOSHARED=yes all installCompile and install a new kernelTo take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.Follow the handbook instructions for compiling a new kernel. If
you have previously built a custom kernel then carefully examine the
LINT config file to see if there are any new
options which you should take advantage of.A previous version of this document suggested rebooting before
rebuilding the kernel. This is wrong because:Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8;
may fail. This could leave your machine unable to connect to the
network.Basic utilities like &man.mount.8; could fail,
making it impossible to mount /,
/usr and so on. This is unlikely if you are
tracking a -STABLE candidate, but more likely if you are tracking
-CURRENT during a large merge.Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X
systems and above) built as part of the world may
crash an older kernel.For these reasons, it is always best to rebuild and install a
new kernel before rebooting.You should build your new kernel after you have completed
make world (or make
installworld). If you do not want to do this (perhaps
you want to confirm that the kernel builds before updating your
system) you may have problems. These may be because your
&man.config.8; command is out of date with respect to your kernel
sources.In this case you could build your kernel with the new version of &man.config.8;&prompt.root; /usr/obj/usr/src/usr.sbin/config/config KERNELNAMEThis may not work in all cases. It is recommended that you
complete make world (or make
installworld) before compiling a new kernel.You are now done. After you have verified that everything appears
to be in the right place you can reboot the system. A simple
&man.fastboot.8; should do it.
&prompt.root; fastbootFinishedYou should now have successfully upgraded your FreeBSD system.
Congratulations.You may notice small problems due to things that you have missed.
For example, I once deleted /etc/magic as part of
the upgrade and merge to /etc, and the
file command stopped working. A moment's thought
meant that
&prompt.root; cd /usr/src/usr.bin/file
&prompt.root;
was sufficient to fix that one.Do I need to re-make the world for every change?There is no easy answer to this one, as it depends on the
nature of the change. For example, I have just run CVSup, and
it has shown the following files as being updated since I last
ran it;src/games/cribbage/instr.csrc/games/sail/pl_main.csrc/release/sysinstall/config.csrc/release/sysinstall/media.csrc/share/mk/bsd.port.mkThere is nothing in there that I would re-make the world
for. I would go to the appropriate sub-directories and
make all install, and that's about it. But
if something major changed, for example
src/lib/libc/stdlib then I would either
re-make the world, or at least those parts of it that are
statically linked (as well as anything else I might have added
that is statically linked).At the end of the day, it is your call. You might be happy
re-making the world every fortnight say, and let changes
accumulate over that fortnight. Or you might want to re-make
just those things that have changed, and are confident you can
spot all the dependencies.And, of course, this all depends on how often you want to
upgrade, and whether you are tracking -STABLE or
-CURRENT.My compile failed with lots of signal 12 (or other signal
number) errors. What has happened?This is normally indicative of hardware problems.
(Re)making the world is an effective way to stress test your
hardware, and will frequently throw up memory problems. These
normally manifest themselves as the compiler mysteriously dying
on receipt of strange signals.A sure indicator of this is if you can restart the make and
it dies at a different point in the process.In this instance there is little you can do except start
swapping around the components in your machine to determine
which one is failing.Can I remove /usr/obj when I have
finished?That depends on how you want to make the world on future
occasions./usr/obj contains all the object files
that were produced during the compilation phase. Normally, one
of the first steps in the /usr/obj around after you have finished
makes little sense, and will free up a large chunk of disk space
(currently about 150MB).However, if you know what you are doing you can have
If you want to live dangerously then make the world, passing
the NOCLEAN definition to make, like
this:&prompt.root; make -DNOCLEAN worldCan interrupted builds be resumed?This depends on how far through the process you got before
you found a problem.In general (and this is not a hard and
fast rule) the make world process builds new
copies of essential tools (such as &man.gcc.1;, and
&man.make.1;>) and the system libraries. These tools and
libraries are then installed. The new tools and libraries are
then used to rebuild themselves, and are installed again. The
entire system (now including regular user programs, such as
&man.ls.1; or &man.grep.1;) is then rebuilt with the new
system files.If you are at the last state, and you know it (because you
have looked through the output that you were storing) then you
can (fairly safely) do… fix the problem …
&prompt.root; cd /usr/src
&prompt.root; make -DNOCLEAN allThis will not undo the work of the previous
make world.If you see the message
--------------------------------------------------------------
Building everything..
--------------------------------------------------------------
in the make world output then it is
probably fairly safe to do so.If you do not see that message, or you are not sure, then it
is always better to be safe than sorry, and restart the build
from scratch.Can I use one machine as a People often ask on the FreeBSD mailing lists whether they
can do all the compiling on one machine, and then use the
results of that compile to make install on to
other machines around the network.This is not something I have done, so the suggestions below
are either from other people, or deduced from the
Makefiles.The precise approach to take depends on your version of
FreeBSDYou must still upgrade /etc and
/dev on the target machines after doing
this.For 2.1.7 and below, Antonio Bemfica
suggested the following approach:Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST)
From: Antonio Bemfica <bemfica@militzer.me.tuns.ca>
To: freebsd-questions@FreeBSD.org
Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca>
Josef Karthauser asked:
> Has anybody got a good method for upgrading machines on a network
First make world, etc. on your main machine
Second, mount / and /usr from the remote machine:
main_machine% mount remote_machine:/ /mnt
main_machine% mount remote_machine:/usr /mnt/usr
Third, do a 'make install' with /mnt as the destination:
main_machine% make install DESTDIR=/mnt
Repeat for every other remote machine on your network. It works fine
for me.
AntonioThis mechanism will only work (to the best of my knowledge)
if you can write to /usr/src on the NFS
server, as the install target in 2.1.7
and below needed to do this.Midway between 2.1.7 and 2.2.0 the reinstall
target was committed. You can use the approach exactly as
outlined above for 2.1.7, but use reinstall
instead of install.This approach does not require write
access to the /usr/src directory on the NFS
server.There was a bug introduced in this target between versions
1.68 and 1.107 of the Makefile, which meant that write access to
the NFS server was required. This bug was
fixed before version 2.2.0 of FreeBSD was released, but may be an
issue of you have an old server still running -STABLE from this
era.For version 2.2.5 and above, you can use the
buildworld and installworld
targets. Use them to build a source tree on one machine, and
then NFS mount /usr/src and
/usr/obj on the remote machine and install
it there.How can I speed up making the world?Run in single user mode.Put the /usr/src and
/usr/obj directories on separate
filesystems held on separate disks. If possible, put these
disks on separate disk controllers.Better still, put these filesystems across separate
disks using the ccd (concatenated disk
driver) device.Turn off profiling (set NOPROFILE=true in
/etc/make.conf). You almost certainly
do not need it.Also in /etc/make.conf, set
CFLAGS to something like -O
-pipe. The optimisation -O2 is much
slower, and the optimisation difference between
-O and -O2 is normally
negligible. -pipe lets the compiler use
pipes rather than temporary files for communication, which
saves disk access (at the expense of memory).Pass the
-j<n>
option to make (if
you are running a sufficiently recent version of FreeBSD) to
run multiple processes in parallel. This helps regardless
of whether you have a single or a multi processor
machine.The filesystem holding
/usr/src can be mounted (or remounted)
with the noatime option. This stops the time
files in the filesystem were last accessed from being
written to the disk. You probably do not need this
information anyway.
noatime is in version 2.2.0 and
above.&prompt.root; mount -u -o noatime /usr/srcThe example assumes /usr/src is
on its own filesystem. If it is not (if it is a part of
/usr for example) then you will
need to use that filesystem mount point, and not
/usr/src.The filesystem holding /usr/obj can
be mounted (or remounted) with the async
option. This causes disk writes to happen asynchronously.
In other words, the write completes immediately, and the
data is written to the disk a few seconds later. This
allows writes to be clustered together, and can be a
dramatic performance boost.Keep in mind that this option makes your filesystem
more fragile. With this option there is an increased
chance that, should power fail, the filesystem will be in
an unrecoverable state when the machine restarts.If /usr/obj is the only thing on
this filesystem then it is not a problem. If you have
other, valuable data on the same filesystem then ensure
your backups are fresh before you enable this
option.&prompt.root; mount -u -o async /usr/objAs above, if /usr/obj is not on
its own filesystem, replace it in the example with the
name of the appropriate mount point.