diff --git a/en/handbook/cutting-edge/chapter.sgml b/en/handbook/cutting-edge/chapter.sgml index bef7b8a9af..3cdf0f1a9a 100644 --- a/en/handbook/cutting-edge/chapter.sgml +++ b/en/handbook/cutting-edge/chapter.sgml @@ -1,2419 +1,2428 @@ The Cutting Edge: FreeBSD-current and FreeBSD-stable FreeBSD 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. Staying Current with FreeBSD Contributed by &a.jkh;. 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 <emphasis>not</emphasis>? 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-current Join the &a.current; and the &a.cvsall; . This is not just a good idea, it is essential. If you are not on the FreeBSD-current mailing list, you will not see the comments that people are making about the current state of the system and thus will probably end up stumbling over a lot of problems that others have already found and solved. Even more importantly, you will miss out on important bulletins which may be critical to your system's continued health. The cvs-all mailing list 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: subscribe freebsd-current subscribe cvs-all in the body of your message. Optionally, 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 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:
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 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.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 FreeBSD Contributed by &a.jkh;. 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-stable Join 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 cvs-all 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: subscribe freebsd-stable subscribe cvs-all in the body of your message. Optionally, 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 2.2 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;
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 Source Trees over the Internet Contributed by &a.jkh;. There 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. For more information on Anonymous CVS, CTM, and CVSup, please see one of the following sections: Anonymous CVS Contributed by &a.jkh; <anchor id="anoncvs-intro">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 &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. <anchor id="anoncvs-usage">Using Anonymous CVS Configuring &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: 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 () 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: HEAD Symbolic name for the main line, or FreeBSD-current. Also the default when no revision is specified. RELENG_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports collection. Here are the revision tags that users might be interested in: RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports collection. RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports collection. RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports collection. RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports collection. RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports collection. RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports collection. RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports collection. RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports collection. RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports collection. RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports collection. 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. Examples While 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 anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co ls &prompt.user; cvs release -d ls Checking out the version of ls(1) in the 2.2-stable branch: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co -rRELENG_2_2 ls &prompt.user; cvs release -d ls Creating a list of changes (as unidiffs) to &man.ls.1; &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls Finding out what other module names can be used: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules Other Resources The 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. <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. CTM 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 <application>CTM</application>? 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 <application>CTM</application>? 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 online. 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 e-mail. 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 may 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. Starting off with <application>CTM</application> for the first time Before you can start using CTM deltas, you will need to get a 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&rdquo 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. This does not currently happen however. However, 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'ed 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 <application>CTM</application> in your daily life To 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's 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 changes As 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 <application>CTM</application> options Finding out exactly what would be touched by an update You 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 updating Sometimes 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 update Sometimes 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 <application>CTM</application> Tons 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. The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what you want also... Miscellaneous stuff All 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. Thanks! &a.bde; for his pointed pen and invaluable comments. &a.sos; for patience. Stephen McKay wrote ctm_[rs]mail, much appreciated. &a.jkh; for being so stubborn that I had to make it better. All the users I hope you like it... <application>CVSup</application> 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 the port from the FreeBSD ports collection or the corresponding binary package, 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 they require a version of the C library that does not yet exist in FreeBSD-2.1.{6,7}. You can easily use the port, 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 Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 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 either the USA distribution site: ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz (client including GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz (client without GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz (server). as well as from the many FreeBSD FTP mirror sites around the world. ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup-bin-15.3.tar.gz (client including GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-15.3.tar.gz (client without GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsupd-bin-15.3.tar.gz (server). 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 /usr/share/examples/cvsup. These examples are also available from ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/ if you are on a pre-2.2 system. 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-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 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: 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_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. tag=RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports-* collections. Here are the revision tags that users might be interested in: + + tag=RELENG_3_1_0_RELEASE + + + FreeBSD-3.1. Not valid for the ports-* + collections. + + + tag=RELENG_3_0_0_RELEASE FreeBSD-3.0. Not valid for the ports-* collections. tag=RELENG_2_2_8_RELEASE FreeBSD-2.2.8. Not valid for the ports-* collections. tag=RELENG_2_2_7_RELEASE FreeBSD-2.2.7. Not valid for the ports-* collections. tag=RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports-* collections. tag=RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports-* collections. tag=RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports-* collections. tag=RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports-* collections. tag=RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports-* collections. tag=RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports-* collections. tag=RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports-* collections. tag=RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports-* collections. tag=RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports-* collections. tag=RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports-* collections. 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.org You 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=/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 &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-crypto Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: &prompt.root; 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: &prompt.root; mkdir /var/tmp/dest &prompt.root; 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: &prompt.root; cvsup -g -L 2 supfile The 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. <application>CVSup</application> 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 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=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 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. For more information For 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 <command>make world</command> to rebuild your system Contributed by &a.nik;. Once 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. Currently, the best source of information on how to do that is a tutorial available from http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html. A successor to this tutorial will be integrated into the handbook. 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 bef7b8a9af..3cdf0f1a9a 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -1,2419 +1,2428 @@ The Cutting Edge: FreeBSD-current and FreeBSD-stable FreeBSD 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. Staying Current with FreeBSD Contributed by &a.jkh;. 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 <emphasis>not</emphasis>? 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-current Join the &a.current; and the &a.cvsall; . This is not just a good idea, it is essential. If you are not on the FreeBSD-current mailing list, you will not see the comments that people are making about the current state of the system and thus will probably end up stumbling over a lot of problems that others have already found and solved. Even more importantly, you will miss out on important bulletins which may be critical to your system's continued health. The cvs-all mailing list 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: subscribe freebsd-current subscribe cvs-all in the body of your message. Optionally, 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 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:
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 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.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 FreeBSD Contributed by &a.jkh;. 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-stable Join 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 cvs-all 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: subscribe freebsd-stable subscribe cvs-all in the body of your message. Optionally, 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 2.2 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;
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 Source Trees over the Internet Contributed by &a.jkh;. There 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. For more information on Anonymous CVS, CTM, and CVSup, please see one of the following sections: Anonymous CVS Contributed by &a.jkh; <anchor id="anoncvs-intro">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 &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. <anchor id="anoncvs-usage">Using Anonymous CVS Configuring &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: 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 () 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: HEAD Symbolic name for the main line, or FreeBSD-current. Also the default when no revision is specified. RELENG_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports collection. Here are the revision tags that users might be interested in: RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports collection. RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports collection. RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports collection. RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports collection. RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports collection. RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports collection. RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports collection. RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports collection. RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports collection. RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports collection. 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. Examples While 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 anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co ls &prompt.user; cvs release -d ls Checking out the version of ls(1) in the 2.2-stable branch: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co -rRELENG_2_2 ls &prompt.user; cvs release -d ls Creating a list of changes (as unidiffs) to &man.ls.1; &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls Finding out what other module names can be used: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules Other Resources The 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. <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. CTM 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 <application>CTM</application>? 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 <application>CTM</application>? 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 online. 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 e-mail. 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 may 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. Starting off with <application>CTM</application> for the first time Before you can start using CTM deltas, you will need to get a 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&rdquo 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. This does not currently happen however. However, 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'ed 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 <application>CTM</application> in your daily life To 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's 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 changes As 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 <application>CTM</application> options Finding out exactly what would be touched by an update You 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 updating Sometimes 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 update Sometimes 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 <application>CTM</application> Tons 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. The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what you want also... Miscellaneous stuff All 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. Thanks! &a.bde; for his pointed pen and invaluable comments. &a.sos; for patience. Stephen McKay wrote ctm_[rs]mail, much appreciated. &a.jkh; for being so stubborn that I had to make it better. All the users I hope you like it... <application>CVSup</application> 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 the port from the FreeBSD ports collection or the corresponding binary package, 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 they require a version of the C library that does not yet exist in FreeBSD-2.1.{6,7}. You can easily use the port, 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 Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 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 either the USA distribution site: ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz (client including GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz (client without GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz (server). as well as from the many FreeBSD FTP mirror sites around the world. ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup-bin-15.3.tar.gz (client including GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-15.3.tar.gz (client without GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsupd-bin-15.3.tar.gz (server). 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 /usr/share/examples/cvsup. These examples are also available from ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/ if you are on a pre-2.2 system. 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-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 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: 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_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. tag=RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports-* collections. Here are the revision tags that users might be interested in: + + tag=RELENG_3_1_0_RELEASE + + + FreeBSD-3.1. Not valid for the ports-* + collections. + + + tag=RELENG_3_0_0_RELEASE FreeBSD-3.0. Not valid for the ports-* collections. tag=RELENG_2_2_8_RELEASE FreeBSD-2.2.8. Not valid for the ports-* collections. tag=RELENG_2_2_7_RELEASE FreeBSD-2.2.7. Not valid for the ports-* collections. tag=RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports-* collections. tag=RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports-* collections. tag=RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports-* collections. tag=RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports-* collections. tag=RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports-* collections. tag=RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports-* collections. tag=RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports-* collections. tag=RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports-* collections. tag=RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports-* collections. tag=RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports-* collections. 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.org You 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=/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 &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-crypto Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: &prompt.root; 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: &prompt.root; mkdir /var/tmp/dest &prompt.root; 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: &prompt.root; cvsup -g -L 2 supfile The 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. <application>CVSup</application> 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 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=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 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. For more information For 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 <command>make world</command> to rebuild your system Contributed by &a.nik;. Once 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. Currently, the best source of information on how to do that is a tutorial available from http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html. A successor to this tutorial will be integrated into the handbook. 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 bef7b8a9af..3cdf0f1a9a 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,2419 +1,2428 @@ The Cutting Edge: FreeBSD-current and FreeBSD-stable FreeBSD 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. Staying Current with FreeBSD Contributed by &a.jkh;. 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 <emphasis>not</emphasis>? 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-current Join the &a.current; and the &a.cvsall; . This is not just a good idea, it is essential. If you are not on the FreeBSD-current mailing list, you will not see the comments that people are making about the current state of the system and thus will probably end up stumbling over a lot of problems that others have already found and solved. Even more importantly, you will miss out on important bulletins which may be critical to your system's continued health. The cvs-all mailing list 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: subscribe freebsd-current subscribe cvs-all in the body of your message. Optionally, 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 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:
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 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.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 FreeBSD Contributed by &a.jkh;. 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-stable Join 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 cvs-all 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: subscribe freebsd-stable subscribe cvs-all in the body of your message. Optionally, 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 2.2 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;
&prompt.root; pkg_add -f \ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz
 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/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z and it will get the whole directory for you as a compressed tar file. Essentially, 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 Source Trees over the Internet Contributed by &a.jkh;. There 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. For more information on Anonymous CVS, CTM, and CVSup, please see one of the following sections: Anonymous CVS Contributed by &a.jkh; <anchor id="anoncvs-intro">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 &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. <anchor id="anoncvs-usage">Using Anonymous CVS Configuring &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: 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 () 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: HEAD Symbolic name for the main line, or FreeBSD-current. Also the default when no revision is specified. RELENG_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports collection. Here are the revision tags that users might be interested in: RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports collection. RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports collection. RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports collection. RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports collection. RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports collection. RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports collection. RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports collection. RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports collection. RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports collection. RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports collection. 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. Examples While 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 anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co ls &prompt.user; cvs release -d ls Checking out the version of ls(1) in the 2.2-stable branch: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co -rRELENG_2_2 ls &prompt.user; cvs release -d ls Creating a list of changes (as unidiffs) to &man.ls.1; &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls Finding out what other module names can be used: &prompt.user; setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules Other Resources The 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. <application>CTM</application> Contributed by &a.phk;. Updated 19-October-1997. CTM 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 <application>CTM</application>? 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 <application>CTM</application>? 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 online. 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 e-mail. 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 may 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. Starting off with <application>CTM</application> for the first time Before you can start using CTM deltas, you will need to get a 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&rdquo 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. This does not currently happen however. However, 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'ed 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 <application>CTM</application> in your daily life To 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's 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 changes As 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 <application>CTM</application> options Finding out exactly what would be touched by an update You 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 updating Sometimes 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 update Sometimes 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 <application>CTM</application> Tons 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. The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what you want also... Miscellaneous stuff All 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. Thanks! &a.bde; for his pointed pen and invaluable comments. &a.sos; for patience. Stephen McKay wrote ctm_[rs]mail, much appreciated. &a.jkh; for being so stubborn that I had to make it better. All the users I hope you like it... <application>CVSup</application> 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 the port from the FreeBSD ports collection or the corresponding binary package, 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 they require a version of the C library that does not yet exist in FreeBSD-2.1.{6,7}. You can easily use the port, 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 Modula-3, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the lang/modula-3-lib port and the lang/modula-3-lib-3.6 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 either the USA distribution site: ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz (client including GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz (client without GUI). ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz (server). as well as from the many FreeBSD FTP mirror sites around the world. ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup-bin-15.3.tar.gz (client including GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-15.3.tar.gz (client without GUI). ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/development/CVSup/cvsupd-bin-15.3.tar.gz (server). 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 /usr/share/examples/cvsup. These examples are also available from ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/ if you are on a pre-2.2 system. 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-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 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: 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_3 The line of development for FreeBSD-3.x, also known as FreeBSD-stable. Not valid for the ports collection. RELENG_2_2 The line of development for FreeBSD-2.2.x, also known as 2.2-stable. Not valid for the ports collection. tag=RELENG_2_1_0 The line of development for FreeBSD-2.1.x - this branch is largely obsolete. Not valid for the ports-* collections. Here are the revision tags that users might be interested in: + + tag=RELENG_3_1_0_RELEASE + + + FreeBSD-3.1. Not valid for the ports-* + collections. + + + tag=RELENG_3_0_0_RELEASE FreeBSD-3.0. Not valid for the ports-* collections. tag=RELENG_2_2_8_RELEASE FreeBSD-2.2.8. Not valid for the ports-* collections. tag=RELENG_2_2_7_RELEASE FreeBSD-2.2.7. Not valid for the ports-* collections. tag=RELENG_2_2_6_RELEASE FreeBSD-2.2.6. Not valid for the ports-* collections. tag=RELENG_2_2_5_RELEASE FreeBSD-2.2.5. Not valid for the ports-* collections. tag=RELENG_2_2_2_RELEASE FreeBSD-2.2.2. Not valid for the ports-* collections. tag=RELENG_2_2_1_RELEASE FreeBSD-2.2.1. Not valid for the ports-* collections. tag=RELENG_2_2_0_RELEASE FreeBSD-2.2.0. Not valid for the ports-* collections. tag=RELENG_2_1_7_RELEASE FreeBSD-2.1.7. Not valid for the ports-* collections. tag=RELENG_2_1_6_1_RELEASE FreeBSD-2.1.6.1. Not valid for the ports-* collections. tag=RELENG_2_1_6_RELEASE FreeBSD-2.1.6. Not valid for the ports-* collections. tag=RELENG_2_1_5_RELEASE FreeBSD-2.1.5. Not valid for the ports-* collections. tag=RELENG_2_1_0_RELEASE FreeBSD-2.1.0. Not valid for the ports-* collections. 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.org You 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=/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 &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-crypto Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: &prompt.root; 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: &prompt.root; mkdir /var/tmp/dest &prompt.root; 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: &prompt.root; cvsup -g -L 2 supfile The 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. <application>CVSup</application> 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 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=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 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. For more information For 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 <command>make world</command> to rebuild your system Contributed by &a.nik;. Once 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. Currently, the best source of information on how to do that is a tutorial available from http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html. A successor to this tutorial will be integrated into the handbook.