diff --git a/handbook/anoncvs.sgml b/handbook/anoncvs.sgml index be8c7d821f..4d6691b771 100644 --- a/handbook/anoncvs.sgml +++ b/handbook/anoncvs.sgml @@ -1,166 +1,170 @@ - + Anonymous CVS

Contributed by &a.jkh; Introduction

Anonymous 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 and then uses the cvs(1) command to access it like any local repository.

While it can also be said that the 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 CVS

Configuring 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: anoncvs@anoncvs.freebsd.org:/cvs

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 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:

Here are the revision tags that users might be interested in:

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 cvs(1) man page for more details. Examples

While it really is recommended that you read the manual page for cvs(1) thoroughly before doing anything, here are some quick examples which essentially show how to use Anonymous CVS:

Checking out something from -current (ls(1)) and deleting it again: % setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs % cvs co ls % cvs release -d ls

Checking out the version of ls(1) in the 2.2-stable branch: % setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs % cvs co -rRELENG_2_2 ls % cvs release -d ls

Creating a list of changes (as unidiffs) to ls(1) between FreeBSD 2.2.2 and FreeBSD 2.2.6: % setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs % cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls

Finding out what other module names can be used: % setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs % cvs co modules % more modules/modules % cvs release -d modules Other Resources

The following additional resources may be helpful in learning CVS: from Cal Poly. , commercial maintainers of CVS. is the FreeBSD Project web interface for CVS. diff --git a/handbook/cvsup.sgml b/handbook/cvsup.sgml index f66c0b9f85..d4b30406a4 100644 --- a/handbook/cvsup.sgml +++ b/handbook/cvsup.sgml @@ -1,618 +1,622 @@ - + CVSup

Contributed by &a.jdp;. Introduction

CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date.

CVSup uses the so-called pull model of updating. Under the pull model, each client asks the server for updates, if and when they are wanted. The server waits passively for update requests from its clients. Thus all updates are instigated by the client. The server never sends unsolicited updates. Users must either run the CVSup client manually to get an update, or they must set up a cron job to run it automatically on a regular basis.

The term "CVSup", capitalized just so, refers to the entire software package. Its main components are the client "cvsup" which runs on each user's machine, and the server "cvsupd" which runs at each of the FreeBSD mirror sites.

As you read the FreeBSD documentation and mailing lists, you may see references to sup. Sup was the predecessor of CVSup, and it served a similar purpose. CVSup is in used in much the same way as sup and, in fact, uses configuration files which are backward-compatible with sup's. Sup is no longer used in the FreeBSD project, because CVSup is both faster and more flexible. Installation

The easiest way to install CVSup if you are running FreeBSD 2.2 or later is to use either from the FreeBSD or the corresponding , depending on whether you prefer to roll your own or not.

If you are running FreeBSD-2.1.6 or 2.1.7, you unfortunately cannot use the binary package versions due to the fact that it requires a version of the C library that does not yet exist in FreeBSD-2.1.{6,7}. You can easily use , however, just as with FreeBSD 2.2. Simply unpack the tar file, cd to the cvsup subdirectory and type "make install".

Because CVSup is written in , both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the port and the package. If you follow the same directions as for cvsup, these libraries will be compiled and/or installed automatically when you install the CVSup port or package.

The Modula-3 libraries are rather large, and fetching and compiling them is not an instantaneous process. For that reason, a third option is provided. You can get statically linked FreeBSD executables for CVSup from the USA distribution site: (client including GUI). (client without GUI). (server). as well as from the many FreeBSD around the world.

Most users will need only the client. These executables are entirely self-contained, and they will run on any version of FreeBSD from FreeBSD-2.1.0 to FreeBSD-current.

In summary, your options for installing CVSup are: FreeBSD-2.2 or later: static binary, port, or package FreeBSD-2.1.6, 2.1.7: static binary or port FreeBSD-2.1.5 or earlier: static binary Configuration

CVSup's operation is controlled by a configuration file called the "supfile". Beginning with FreeBSD-2.2, there are some sample supfiles in the directory . These examples are also available from if you are on a pre-2.2 system.

The information in a supfile answers the following questions for cvsup:

In the following sections, we will construct a typical supfile by answering each of these questions in turn. First, we describe the overall structure of a supfile.

A supfile is a text file. Comments begin with "#" and extend to the end of the line. Lines that are blank and lines that contain only comments are ignored.

Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a "collection", a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing alone, e.g., "delete" or "compress". A value field also begins with a keyword, but the keyword is followed without intervening white space by "=" and a second word. For example, "release=cvs" is a value field.

A supfile typically specifies more than one collection to receive. One way to structure a supfile is to specify all of the relevant fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning with the special pseudo-collection name "*default" can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by additional "*default" lines.

With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of . 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 . 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-crypto

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

WARNING: 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:

Here are the revision tags that users might be interested in:

WARNING: 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 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 will do, though you should try to select one that's near to you. In this example, we'll use the primary FreeBSD distribution site, "cvsup.FreeBSD.org": *default host=cvsup.FreeBSD.org

On any particular run of cvsup, you can override this 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=/usr

Where 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/cvsup

This 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 compress

"release=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 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=cvsup.FreeBSD.org *default prefix=/usr *default base=/usr/local/etc/cvsup *default release=cvs delete use-rel-suffix compress src-all cvs-crypto Running CVSup

You are now ready to try an update. The command line for doing this is quite simple: cvsup supfile

where "supfile" is of course the name of the supfile you have just created. Assuming you are running under X11, cvsup will display a GUI window with some buttons to do the usual things. Press the "go" button, and watch it run.

Since you are updating your actual "/usr/src" tree in this example, you will need to run the program as root so that cvsup has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might understandably make you nervous. There is an easy way to do a trial run without touching your precious files. Just create an empty directory somewhere convenient, and name it as an extra argument on the command line: mkdir /var/tmp/dest cvsup supfile /var/tmp/dest

The directory you specify will be used as the destination directory for all file updates. CVSup will examine your usual files in "/usr/src", but it will not modify or delete any of them. Any file updates will instead land in "/var/tmp/dest/usr/src". CVSup will also leave its base directory status files untouched when run this way. The new versions of those files will be written into the specified directory. As long as you have read access to "/usr/src", you do not even need to be root to perform this kind of trial run.

If you are not running X11 or if you just do not like GUIs, you should add a couple of options to the command line when you run cvsup: cvsup -g -L 2 supfile

The "-g" tells cvsup not to use its GUI. This is automatic if you are not running X11, but otherwise you have to specify it.

The "-L 2" tells cvsup to print out the details of all the file updates it is doing. There are three levels of verbosity, from "-L 0" to "-L 2". The default is 0, which means total silence except for error messages.

There are plenty of other options available. For a brief list of them, type "cvsup -H". For more detailed descriptions, see the manual page.

Once you are satisfied with the way updates are working, you can arrange for regular runs of cvsup using cron(8). Obviously, you should not let cvsup use its GUI when running it from cron. CVSup File Collections

The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its sub-collections. The hierarchical relationships among collections are reflected by the use of indentation in the list below.

The most commonly used collections are cvs-all release=cvs The main FreeBSD CVS repository, excluding the export-restricted cryptography code.

distrib release=cvs Files related to the distribution and mirroring of FreeBSD. doc-all release=cvs Sources for the FreeBSD handbook and other documentation. ports-all release=cvs The FreeBSD ports collection.

ports-archivers release=cvs Archiving tools. ports-astro release=cvs Astronomical ports. ports-audio release=cvs Sound support. ports-base release=cvs Miscellaneous files at the top of /usr/ports. ports-benchmarks release=cvs Benchmarks. ports-biology release=cvs Biology. ports-cad release=cvs Computer aided design tools. ports-chinese release=cvs Chinese language support. ports-comms release=cvs Communication software. ports-converters release=cvs character code converters. ports-databases release=cvs Databases. ports-deskutils release=cvs Things that used to be on the desktop before computers were invented. ports-devel release=cvs Development utilities. ports-editors release=cvs Editors. ports-emulators release=cvs Emulators for other operating systems. ports-games release=cvs Games. ports-german release=cvs German language support. ports-graphics release=cvs Graphics utilities. ports-japanese release=cvs Japanese language support. ports-korean release=cvs Korean language support. ports-lang release=cvs Programming languages. ports-mail release=cvs Mail software. ports-math release=cvs Numerical computation software. ports-mbone release=cvs MBone applications. ports-misc release=cvs Miscellaneous utilities. ports-net release=cvs Networking software. ports-news release=cvs USENET news software. ports-plan9 release=cvs Various programs from Plan9. ports-print release=cvs Printing software. ports-russian release=cvs Russian language support. ports-security release=cvs Security utilities. ports-shells release=cvs Command line shells. ports-sysutils release=cvs System utilities. ports-textproc release=cvs text processing utilities (does not include desktop publishing). ports-vietnamese release=cvs Vietnamese language support. ports-www release=cvs Software related to the World Wide Web. ports-x11 release=cvs Ports to support the X window system. ports-x11-clocks release=cvs X11 clocks. ports-x11-fm release=cvs X11 file managers. ports-x11-fonts release=cvs X11 fonts and font utilities. ports-x11-toolkits release=cvs X11 toolkits. ports-x11-wm release=cvs X11 window managers. src-all release=cvs The main FreeBSD sources, excluding the export-restricted cryptography code.

src-base release=cvs Miscellaneous files at the top of /usr/src. src-bin release=cvs User utilities that may be needed in single-user mode (/usr/src/bin). src-contrib release=cvs Utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/contrib). src-etc release=cvs System configuration files (/usr/src/etc). src-games release=cvs Games (/usr/src/games). src-gnu release=cvs Utilities covered by the GNU Public License (/usr/src/gnu). src-include release=cvs Header files (/usr/src/include). src-kerberosIV release=cvs KerberosIV security package (/usr/src/kerberosIV). src-lib release=cvs Libraries (/usr/src/lib). src-libexec release=cvs System programs normally executed by other programs (/usr/src/libexec). src-release release=cvs Files required to produce a FreeBSD release (/usr/src/release). src-sbin release=cvs System utilities for single-user mode (/usr/src/sbin). src-share release=cvs Files that can be shared across multiple systems (/usr/src/share). src-sys release=cvs The kernel (/usr/src/sys). src-tools release=cvs Various tools for the maintenance of FreeBSD (/usr/src/tools). src-usrbin release=cvs User utilities (/usr/src/usr.bin). src-usrsbin release=cvs System utilities (/usr/src/usr.sbin). www release=cvs The sources for the World Wide Web data. cvs-crypto release=cvs The export-restricted cryptography code.

src-crypto release=cvs Export-restricted utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/crypto). src-eBones release=cvs Kerberos and DES (/usr/src/eBones). src-secure release=cvs DES (/usr/src/secure). distrib release=self The CVSup server's own configuration files. Used by CVSup mirror sites. gnats release=current The GNATS bug-tracking database. mail-archive release=current FreeBSD mailing list archive. www release=current The installed World Wide Web data. Used by WWW mirror sites. Announcements, Questions, and Bug Reports

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 . diff --git a/handbook/history.sgml b/handbook/history.sgml index 4aac3169d2..13a7227007 100644 --- a/handbook/history.sgml +++ b/handbook/history.sgml @@ -1,93 +1,93 @@ - + A Brief History of FreeBSD

Contributed by &a.jkh;. The FreeBSD project had its genesis in the early part of 1993, partially as an outgrowth of the "Unofficial 386BSD Patchkit" by the patchkit's last 3 coordinators: Nate Williams, Rod Grimes and myself. Our original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems with it that the patchkit mechanism just was not capable of solving. Some of you may remember the early working title for the project being "386BSD 0.5" or "386BSD Interim" in reference to that fact. 386BSD was Bill Jolitz's operating system, which had been up to that point suffering rather severely from almost a year's worth of neglect. As the patchkit swelled ever more uncomfortably with each passing day, we were in unanimous agreement that something had to be done and decided to try and assist Bill by providing this interim "cleanup" snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project and without any clear indication of what would be done instead. It did not take us long to decide that the goal remained worthwhile, even without Bill's support, and so we adopted the name "FreeBSD", coined by David Greenman. Our initial objectives were set after consulting with the system's current users and, once it became clear that the project was on the road to perhaps even becoming a reality, I contacted Walnut Creek CDROM with an eye towards improving FreeBSD's distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported the idea of distributing FreeBSD on CD but went so far as to provide the project with a machine to work on and a fast Internet connection. Without Walnut Creek CDROM's almost unprecedented degree of faith in what was, at the time, a completely unknown project, it is quite unlikely that FreeBSD would have gotten as far, as fast, as it has today. The first CDROM (and general net-wide) distribution was FreeBSD 1.0, released in December of 1993. This was based on the 4.3BSD-Lite ("Net/2") tape from U.C. Berkeley, with many components also provided by 386BSD and the Free Software Foundation. It was a fairly reasonable success for a first offering, and we followed it with the highly successful FreeBSD 1.1 release in May of 1994. Around this time, some rather unexpected storm clouds formed on the horizon as Novell and U.C. Berkeley settled their long-running lawsuit over the legal status of the Berkeley Net/2 tape. A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were "encumbered" code and the property of Novell, who had in turn acquired it from AT&T some time previously. What Berkeley got in return was Novell's "blessing" that the 4.4BSD-Lite release, when it was finally released, would be declared unencumbered and all existing Net/2 users would be strongly encouraged to switch. This included FreeBSD, and the project was given until the end of July 1994 to stop shipping its own Net/2 based product. Under the terms of that agreement, the project was allowed one last release before the deadline, that release being FreeBSD 1.1.5.1. FreeBSD then set about the arduous task of literally re-inventing itself from a completely new and rather incomplete set of 4.4BSD-Lite bits. The "Lite" releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until December of 1994 to make this transition, and in January of 1995 it released FreeBSD 2.0 to the net and on CDROM. Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install FreeBSD 2.0.5 release in June of 1995. We released FreeBSD 2.1.5 in August of 1996, and it appeared to be popular enough among the ISP and commercial communities that another release along the 2.1-stable branch was merited. This was FreeBSD 2.1.7.1, released in February 1997 and capping the end of mainstream development on 2.1-stable. Now in maintenance mode, only security enhancements and other critical bug fixes will be done on this branch (RELENG_2_1_0). FreeBSD 2.2 was branched from the development mainline ("-current") in November 1996 as the RELENG_2_2 branch, and the first full release (2.2.1) was released in April, 1997. Further releases along the 2.2 branch were done in the Summer and Fall of '97, the latest being 2.2.7 which -appeared in late July of '98. The first official 3.0 release will appear -in October, 1998 and the last release on the 2.2 branch, 2.2.8, will -appear in November. +appeared in late July of '98. The first official 3.0 release appeared +in October, 1998 and the last release on the 2.2 branch, 2.2.8, +appeared in November, 1998. The tree branched again on Jan 20, 1999. This led to 4.0-current and a 3.x-stable branch, from which 3.1 will be released on Feb 15th, 1999. Long term development projects will continue to take place in the 4.0-current branch and SNAPshot releases of 4.0 on CDROM (and, of course, on the net).