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 5b172dff2a..a25bb012bd 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -1,3504 +1,3487 @@ - 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. + The Cutting Edge + + Restructured, reorganized, and parts updated by &a.jim; + March 2000. Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik; + with feedback from various others. + + + Synopsis + + 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. - + -CURRENT v.s. -STABLE - - 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. - + There are two development branches to FreeBSD; -CURRENT and + -STABLE. This section will explain a bit about each and describe + how to keep your system up-to-date with each respective tree. + -CURRENT will be discussed first, then -STABLE. - - 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. - + Staying Current with FreeBSD - - A quick way of getting bug fixes. - + As you are reading this, keep in mind that -CURRENT is the + “bleeding edge” of FreeBSD development and that if you + are new to FreeBSD, you are most likely going to want to think + twice about running it. - - 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 + + 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 &a.cvsall; mailing list will allow you to see the commit - log entry for each change as it is made along with any pertinent - information on possible side-effects. - - To join these lists, send mail to - &a.majordomo; and specify: + + + 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 &a.cvsall; mailing list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, send mail to &a.majordomo; and + specify the following in the body of your message: subscribe freebsd-current subscribe cvs-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. - + 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 - + Grab the sources from ftp.FreeBSD.org. You can do this in + one of three ways: + + + + Use the CTM facility. Unless + you have a good TCP/IP connection at a flat rate, this + is the way to do it. + + + + Use the cvsup program + with this supfile. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron and keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type: - -
&prompt.root; pkg_add -f \ + 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: + + + 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: - + We also use wu-ftpd which allows + compressed/tar'd grabbing of whole trees. e.g. you + see: + + usr.bin/lex + + You can do the following to get the whole directory + as a tar file: + ftp> cd usr.bin ftp> get lex.tar - - and it will get the whole directory for you as a - 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. - + + 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 + Makefilein /usr/src + carefully. You should at least run a make world the first time through + as part of the upgrading process. Reading the &a.current; + will keep you up-to-date on other bootstrapping procedures + that sometimes become necessary as we move towards the next + release. + - - Be active! If you are running FreeBSD-current, we want to - know what you have to say about it, especially if you have - suggestions for enhancements or bug fixes. Suggestions with - accompanying code are received most enthusiastically! - - + + 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 - - + <anchor id="stable">Staying Stable with FreeBSD + + If you are using FreeBSD in a production environment and want + to make sure you have the latest fixes from the -CURRENT branch, + you want to be running -STABLE. This is the tree that -RELEASEs + are branched from when we are putting together a new release. For + example, if you have a copy of 3.4-RELEASE, that is really just a + “snapshot” from the -STABLE branch that we put on + CDROM. In order to get any changes merged into -STABLE after the + -RELEASE, you need to “track” the -STABLE + branch. - - 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 &a.cvsall; mailing list will allow you to see the commit - log entry for each change as it is made along with any pertinent - information on possible side-effects. + + 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). + - To join these lists, send mail to &a.majordomo; and specify: + + 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 &a.cvsall; mailing list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, send mail to &a.majordomo; and + specify the following in the body of your message: subscribe freebsd-stable subscribe cvs-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. - + 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 + 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. + and install it like any other release. - If you are already running a previous release of FreeBSD and wish - to upgrade via sources then you can easily do so from ftp.FreeBSD.org. This can be done in one - of three ways: - - - - Use the CTM facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it. - - - - Use the cvsup program with - If you are already running a previous release of FreeBSD + and wish to upgrade via sources then you can easily do so + from ftp.FreeBSD.org. This can + be done in one of three ways: + + + + Use the CTM facility. Unless + you have a good TCP/IP connection at a flat rate, this + is the way to do it. + + + + Use the cvsup program + with this supfile. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron to keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type; + 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 \ +
&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: + + + 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: - + We also use wu-ftpd which allows + compressed/tar'd grabbing of whole trees. e.g. you + see: + + usr.bin/lex + + You can do the following to get the whole directory + for you as a tar file: + ftp> cd usr.bin ftp> get lex.tar - - and it will get the whole directory for you as a - 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. - + + 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 + + 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 + Synchronizing Your Source - 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. + 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. + 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 + 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. + 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. + 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: + More information about Anonymous CVS, + CTM, and + CVSup is available further down in this + section. 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, - provides the well-known password anoncvs - with the cvs login command, and then uses - the &man.cvs.1; command to access it like any local + utilities bundled with FreeBSD for synchronizing with a remote + CVS repository. Among other things, it allows users of FreeBSD + to perform, with no special privileges, read-only CVS operations + against one of the FreeBSD project's official anoncvs servers. + To use it, one simply sets the CVSROOT + environment variable to point at the appropriate anoncvs server, + provides the well-known password anoncvs with the + cvs login command, and then uses the + &man.cvs.1; command to access it like any local repository. While it can also be said that the CVSup and anoncvs + linkend="cvsup">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 + 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 + 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. + 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: + 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: - :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs + :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs (Use cvs login and enter the password anoncvs when prompted.) - Since CVS allows one to “check out” virtually any - version of the FreeBSD sources that ever existed (or, in some cases, - will exist :), you need to be familiar with the - revision () flag to &man.cvs.1; and what some of - the permissible values for it in the FreeBSD Project repository - are. - - There are two kinds of tags, revision tags and branch tags. A - revision tag refers to a specific revision. Its meaning stays the - same from day to day. A branch tag, on the other hand, refers to - the latest revision on a given line of development, at any given - time. Because a branch tag does not refer to a specific revision, - it may mean something different tomorrow than it means today. + 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: + in (keep in mind that the only tags valid for the ports collection is + HEAD). HEAD - + - Symbolic name for the main line, or FreeBSD-current. Also - the default when no revision is specified. + 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. + The line of development for FreeBSD-3.X, also known + as FreeBSD-STABLE. - + RELENG_2_2 - + - The line of development for FreeBSD-2.2.x, also known as - 2.2-stable. This branch is mostly obsolete. Not valid for - the ports collection. + The line of development for FreeBSD-2.2.X, also known + as 2.2-STABLE. This branch is mostly obsolete. Here are the revision tags that users might be interested - in: + in. Again, none of these are valid for the ports collection + since the ports collection does not have multiple + revisions. RELENG_3_4_0_RELEASE - FreeBSD-3.4. Not valid for the ports collection. + FreeBSD-3.4. RELENG_3_3_0_RELEASE - FreeBSD-3.3. Not valid for the ports collection. + FreeBSD-3.3. - RELENG_3_2_0_RELEASE - + - FreeBSD-3.2. Not valid for the ports collection. + FreeBSD-3.2. - - + RELENG_3_1_0_RELEASE - + - FreeBSD-3.1. Not valid for the ports collection. + FreeBSD-3.1. RELENG_3_0_0_RELEASE - + - FreeBSD-3.0. Not valid for the ports collection. + FreeBSD-3.0. RELENG_2_2_8_RELEASE - + - FreeBSD-2.2.8. Not valid for the ports collection. + FreeBSD-2.2.8. RELENG_2_2_7_RELEASE - + - FreeBSD-2.2.7. Not valid for the ports collection. + FreeBSD-2.2.7. RELENG_2_2_6_RELEASE - + - FreeBSD-2.2.6. Not valid for the ports collection. + FreeBSD-2.2.6. - + RELENG_2_2_5_RELEASE - + - FreeBSD-2.2.5. Not valid for the ports collection. + FreeBSD-2.2.5. - + RELENG_2_2_2_RELEASE - + - FreeBSD-2.2.2. Not valid for the ports collection. + FreeBSD-2.2.2. - + RELENG_2_2_1_RELEASE - + - FreeBSD-2.2.1. Not valid for the ports collection. + FreeBSD-2.2.1. - + RELENG_2_2_0_RELEASE - + - FreeBSD-2.2.0. Not valid for the ports collection. + FreeBSD-2.2.0. - When you specify a branch tag, you normally receive the latest - versions of the files on that line of development. If you wish to - receive some past version, you can do so by specifying a date with - the flag. See the &man.cvs.1; man page - for more details. + 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 + 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 + <title>Checking out something from -CURRENT (&man.ls.1;) and deleting it again: -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co ls &prompt.user; cvs release -d ls &prompt.user; cvs logout - Checking out the version of &man.ls.1; in the 2.2-stable + <title>Checking out the version of &man.ls.1; in the 2.2-STABLE branch: -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co -rRELENG_2_2 ls &prompt.user; cvs release -d ls &prompt.user; cvs logout Creating a list of changes (as unidiffs) to &man.ls.1; -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls &prompt.user; cvs logout Finding out what other module names can be used: - + -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules &prompt.user; cvs logout - + 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. - + 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. + 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>? + 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 + 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: + /usr/src/usr.sbin/CTM if you have a copy + of the source available. + + If you are running a pre-2.0 version of FreeBSD, you can + fetch the current CTM sources + directly from: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/ - - The “deltas” you feed CTM - can be had two ways, FTP or e-mail. If you have general FTP access - to the Internet then the following FTP sites support access to + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/ + + The “deltas” you feed + CTM can be had two ways, FTP or + email. If you have general FTP access to the Internet then the + following FTP sites support access to CTM: - + ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/ - - or see section mirrors. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/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: - + + If you wish to get your deltas via email: + Send email to &a.majordomo; to subscribe to one of the CTM distribution lists. “ctm-cvs-cur” supports the entire cvs tree. “ctm-src-cur” supports the head of the development - branch. “ctm-src-2_2” supports the 2.2 release branch, - etc. (If you do not know how to subscribe yourself using majordomo, - send a message first containing the word help - — it will send you back usage instructions.) - + 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. + 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 + 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 + <title>Using <application>CTM</application> for the first time - + Before you can start using CTM deltas, you will need to get to a starting point for the deltas produced subsequently to it. - - First you should determine what you already have. Everyone can - start from an “empty” directory. You must use an - initial “Empty&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 + + First you should determine what you already have. Everyone + can start from an “empty” directory. You must use + an initial “Empty” delta to start off your + CTM supported tree. At some point it + is intended that one of these “started” deltas be + distributed on the CD for your convenience, however, this does + not currently happen. + + Since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a - RELEASE CD, you can copy or extract an initial source from it. This - will save a significant transfer of data. - + -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 + designation following the X corresponds to + the origin of your initial “seed”. + Empty is an empty directory. As a rule a + base transition from Empty is produced + every 100 deltas. By the way, they are large! 25 to 30 + Megabytes of gzip'd data is common for the XEmpty deltas. - + Once you've picked a base delta to start from, you will also need all deltas with higher numbers following it. - + - Using <application>CTM</application> in your daily life + 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 + 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 + + That is really all there is to it. Every time you get a new + delta, just run it through CTM to + keep your sources up to date. + + Do not remove the deltas if they are hard to download again. + You just might want to keep them around in case something bad + happens. Even if you only have floppy disks, consider using fdwrite to make a copy. - + Keeping your local 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. + 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 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 :-). + + 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. + + 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 + + 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. - + 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 + + 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. + 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. + 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... - - - + “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. - + <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. - + 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. + 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 + 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. + project, because CVSup is both faster + and more flexible. - + Installation The easiest way to install CVSup is to use the net/cvsup-bin port from the FreeBSD ports collection. If you prefer to build CVSup from source, you can use the net/cvsup - port instead. But be forewarned: the net/cvsup - port depends on the Modula-3 system, which takes a substantial - amount of time, memory, and disk space to build. + port instead. But be forewarned: the + net/cvsup port depends on the Modula-3 + system, which takes a substantial amount of time, memory, and + disk space to build. If you do not know anything about cvsup at all and want a - single package which will install it, set up the configuration file - and start the transfer via a pointy-clicky type of interface, then - get the - cvsupit package. Just hand it to &man.pkg.add.1; and it will - lead you through the configuration process in a menu-oriented fashion. - + single package which will install it, set up the configuration + file and start the transfer via a pointy-clicky type of + interface, then get the cvsupit + package. Just hand it to &man.pkg.add.1; and it will lead you + through the configuration process in a menu-oriented + fashion. - + CVSup Configuration - CVSup's operation is controlled by a - configuration file called the supfile. - There are some sample - supfiles in the directory /usr/share/examples/cvsup/. - + CVSup's operation is controlled + by a configuration file called the supfile. + There are some sample supfiles in the + directory /usr/share/examples/cvsup/. + + The information in a supfile answers + the following questions for cvsup: - The information in a supfile answers the - following questions for cvsup: - - Which files do you want - to receive? + Which files do you + want to receive? - + - Which versions of them do - you want? + Which versions of them + do you want? - + - Where do you want to get - them from? + 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 them on your own machine? - + - Where do you want to put - your status files? + 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. - + 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 + “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 + 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 + 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. - + 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. + linkend="current">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: - + 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? - + 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. + 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 + 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. + + 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: + in. Keep in mind that only the tag=. is + relevant for the ports collection. tag=. The main line of development, also known as - FreeBSD-current. + FreeBSD-CURRENT. - The . is not punctuation; it is - the name of the tag. Valid for all collections. + 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. + The line of development for FreeBSD-3.X, also + known as FreeBSD-STABLE. RELENG_2_2 - The line of development for FreeBSD-2.2.x, also known - as 2.2-stable. Not valid for the ports collection. + The line of development for FreeBSD-2.2.X, also + known as 2.2-STABLE. Here are the revision tags that users might be interested - in: - + in. Again, these are not valid for the ports + collection. + RELENG_3_4_0_RELEASE - FreeBSD-3.4. Not valid for the ports-* - collections. + FreeBSD-3.4. - tag=RELENG_3_3_0_RELEASE - FreeBSD-3.3. Not valid for the ports-* - collections. + FreeBSD-3.3. + tag=RELENG_3_2_0_RELEASE + + + FreeBSD-3.2. + + - tag=RELENG_3_2_0_RELEASE - - - FreeBSD-3.2. Not valid for the ports-* - collections. - - - - + tag=RELENG_3_1_0_RELEASE - + - FreeBSD-3.1. Not valid for the ports-* - collections. + FreeBSD-3.1. - + tag=RELENG_3_0_0_RELEASE - + - FreeBSD-3.0. Not valid for the ports-* - collections. + FreeBSD-3.0. - + tag=RELENG_2_2_8_RELEASE - + - FreeBSD-2.2.8. Not valid for the ports-* - collections. + FreeBSD-2.2.8. - + tag=RELENG_2_2_7_RELEASE - + - FreeBSD-2.2.7. Not valid for the ports-* - collections. + FreeBSD-2.2.7. - + tag=RELENG_2_2_6_RELEASE - FreeBSD-2.2.6. Not valid for the ports-* - collections. + FreeBSD-2.2.6. - + tag=RELENG_2_2_5_RELEASE - + - FreeBSD-2.2.5. Not valid for the ports-* - collections. + FreeBSD-2.2.5. - + tag=RELENG_2_2_2_RELEASE - + - FreeBSD-2.2.2. Not valid for the ports-* - collections. + FreeBSD-2.2.2. - + tag=RELENG_2_2_1_RELEASE - + - FreeBSD-2.2.1. Not valid for the ports-* - collections. + FreeBSD-2.2.1. - + tag=RELENG_2_2_0_RELEASE - + - FreeBSD-2.2.0. Not valid for the ports-* - collections. + FreeBSD-2.2.0. - + Be very careful to type the tag name exactly as shown. - CVSup cannot distinguish between - valid and invalid tags. If you misspell the tag, - CVSup will behave as though you had - specified a valid tag which happens to refer to no files at - all. It will delete your existing sources in that - case. + 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 + 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 + 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. + 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? - + 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: - + 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 . + 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? - + 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: - + 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, + 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. + 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. + 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: - + 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 + 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. + 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. + 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: - + 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 + + 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: - + 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. + 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. - + 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. + 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. + 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 - + 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 - + 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. + Things that used to be on the desktop + before computers were invented. - + ports-devel - release=cvs - + release=cvs + Development utilities. - + ports-editors - release=cvs - + release=cvs + Editors. - + ports-emulators - release=cvs - + release=cvs + - Emulators for other operating systems. + Emulators for other operating + systems. - + ports-ftp - release=cvs - + release=cvs + FTP client and server utilities. - + ports-games - release=cvs - + release=cvs + Games. - + ports-german - release=cvs - + release=cvs + German language support. - + ports-graphics - release=cvs - + release=cvs + Graphics utilities. - + ports-irc - release=cvs - + release=cvs + Internet Relay Chat utilities. - + ports-japanese - release=cvs - + release=cvs + Japanese language support. - + ports-java - release=cvs - + release=cvs + Java utilities. - + ports-korean - release=cvs - + release=cvs + Korean language support. - + - ports-lang release=cvs - + ports-lang + release=cvs + Programming languages. - + - ports-mail release=cvs - + ports-mail + release=cvs + Mail software. - + - ports-math release=cvs - + ports-math + release=cvs + Numerical computation software. - + ports-mbone - release=cvs - + release=cvs + MBone applications. - + - ports-misc release=cvs - + ports-misc + release=cvs + Miscellaneous utilities. - + - ports-net release=cvs - + ports-net + release=cvs + Networking software. - + - ports-news release=cvs - + ports-news + release=cvs + USENET news software. - - ports-palm - release=cvs - - - Software support for 3Com Palm(tm) series. - - - + + ports-palm + release=cvs + + + Software support for 3Com Palm(tm) + series. + + + ports-print - release=cvs - + release=cvs + Printing software. - + ports-russian - release=cvs - + release=cvs + Russian language support. - + - ports-security - release=cvs - + ports-security + release=cvs + Security utilities. - + ports-shells - release=cvs - + release=cvs + Command line shells. - + ports-sysutils - release=cvs + release=cvs System utilities. - + ports-textproc - release=cvs - + release=cvs + - text processing utilities (does not include - desktop publishing). + text processing utilities (does not + include desktop publishing). - + ports-vietnamese - release=cvs - + release=cvs + Vietnamese language support. - + - ports-www release=cvs - + ports-www + release=cvs + - Software related to the World Wide Web. + Software related to the World Wide + Web. - + - ports-x11 release=cvs - + ports-x11 + release=cvs + - Ports to support the X window system. + Ports to support the X window + system. - + ports-x11-clocks - release=cvs - + release=cvs + X11 clocks. - + ports-x11-fm - release=cvs - + release=cvs + X11 file managers. - + ports-x11-fonts - release=cvs - + release=cvs + X11 fonts and font utilities. - + ports-x11-toolkits - release=cvs - + release=cvs + X11 toolkits. - + ports-x11-servers - + X11 servers. - + ports-x11-wm - + X11 window managers. - + src-all release=cvs - + The main FreeBSD sources, excluding the export-restricted cryptography code. - + - src-base release=cvs - + src-base + release=cvs + Miscellaneous files at the top of /usr/src. - + - src-bin release=cvs - + src-bin + release=cvs + User utilities that may be needed in single-user mode (/usr/src/bin). - + src-contrib - release=cvs - + release=cvs + Utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/contrib). - + - src-etc release=cvs - + src-etc + release=cvs + System configuration files (/usr/src/etc). - + - src-games release=cvs - + src-games + release=cvs + Games (/usr/src/games). - + - src-gnu release=cvs - + src-gnu + release=cvs + - Utilities covered by the GNU Public License - (/usr/src/gnu). + Utilities covered by the GNU Public + License (/usr/src/gnu). - + src-include - release=cvs - + release=cvs + Header files (/usr/src/include). - + src-kerberos5 - release=cvs - + release=cvs + Kerberos5 security package (/usr/src/kerberos5). - + src-kerberosIV - release=cvs - + release=cvs + KerberosIV security package (/usr/src/kerberosIV). - + - src-lib release=cvs - + src-lib + release=cvs + Libraries (/usr/src/lib). - + src-libexec - release=cvs - + release=cvs + System programs normally executed by other programs (/usr/src/libexec). - + src-release - release=cvs - + release=cvs + - Files required to produce a FreeBSD release + Files required to produce a FreeBSD + release (/usr/src/release). - + - src-sbin release=cvs - + src-sbin + release=cvs + System utilities for single-user mode (/usr/src/sbin). - + - src-share release=cvs - + src-share + release=cvs + Files that can be shared across multiple systems (/usr/src/share). - + - src-sys release=cvs - + src-sys + release=cvs + The kernel (/usr/src/sys). - + - src-tools release=cvs - + src-tools + release=cvs + - Various tools for the maintenance of FreeBSD + Various tools for the maintenance of + FreeBSD (/usr/src/tools). - + - src-usrbin release=cvs - + src-usrbin + release=cvs + User utilities (/usr/src/usr.bin). - + src-usrsbin - release=cvs - + 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 + outside the FreeBSD project, used relatively + unmodified (/usr/src/crypto). - + src-eBones release=cvs - + Kerberos and DES (/usr/src/eBones). Not used in current releases of FreeBSD. - + src-secure release=cvs - + DES (/usr/src/secure). - + - src-sys-crypto release=cvs - + src-sys-crypto + release=cvs + Kernel cryptography code (/usr/src/sys/crypto). - + distrib release=self - + - The CVSup server's own configuration files. Used by CVSup - mirror sites. + 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. + 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. + 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;. + + Using <command>make world</command> 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. + current and so on) you must then use the source + tree to rebuild the system. Take a backup - - I cannot stress highly enough how important it is to take a backup - of your system before you do this. While - remaking the world is (as long as you follow these instructions) an - easy task to do, there will inevitably be times when you make - mistakes, or when mistakes made by others in the source tree render - your system unbootable. - + + I cannot stress highly enough how important it is to take a + backup of your system before you do this. + While remaking the world is (as long as you follow these + instructions) an easy task to do, there will inevitably be times + when you make mistakes, or when mistakes made by others in the + source tree render your system unbootable. + Make sure you have taken a backup. And have a fixit floppy to - hand. I have never needed to use them, and, touch wood, I never will, - but it is always better to be safe than sorry. + hand. I have never needed to use them, and, touch wood, I never + will, but it is always better to be safe than sorry. Subscribe to the right mailing list - - The -stable and -current FreeBSD code branches are, by their - nature, in development. People that contribute - to FreeBSD are human, and mistakes occasionally happen. - Sometimes these mistakes can be quite harmless, just causing your - system to print a new diagnostic warning. Or the change may be - catastrophic, and render your system unbootable or destroy your + The -STABLE and -CURRENT FreeBSD code branches are, by their + nature, in development. People that + contribute to FreeBSD are human, and mistakes occasionally + happen. + + Sometimes these mistakes can be quite harmless, just causing + your system to print a new diagnostic warning. Or the change may + be catastrophic, and render your system unbootable or destroy your filesystems (or worse). - If problems like these occur, a heads up is posted - to the appropriate mailing list, explaining the nature of the problem - and which systems it affects. And an all clear - announcement is posted when the problem has been solved. + If problems like these occur, a heads up is + posted to the appropriate mailing list, explaining the nature of + the problem and which systems it affects. And an all + clear announcement is posted when the problem has been + solved. - If you try and track -stable or -current and do not read - FreeBSD-stable@FreeBSD.ORG or - FreeBSD-current@FreeBSD.ORG then you are asking for - trouble. + If you try and track -STABLE or -CURRENT and do not read the + stable@FreeBSD.org or + current@FreeBSD.org mailing lists then you are + asking for trouble. - + Check <filename>/etc/make.conf</filename> - + Examine the file /etc/make.conf. This - contains some default defines for - - Everything is, by default, commented out. Uncomment those entries - that look useful. For a typical user (not a developer), you will - probably want to uncomment the CFLAGS and NOPROFILE + contains some default defines for + + Everything is, by default, commented out. Uncomment those + entries that look useful. For a typical user (not a developer), + you will probably want to uncomment the CFLAGS and NOPROFILE definitions. If your machine has a floating point unit (386DX, 486DX, Pentium - and up class machines) then you can also uncomment the HAVE_FPU - line.</para> + <para>If your machine has a floating point unit (386DX, 486DX, + Pentium and up class machines) then you can also uncomment the + HAVE_FPU line.</para> <para>This definition was removed for version 2.2.2 and up of FreeBSD.</para> </note> - - <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so on) - and decide if they are relevant to you.</para> + + <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so + on) and decide if they are relevant to you.</para> </sect2> - - <sect2> + + <sect2> <title>Update <filename>/etc/group</filename> - - The /etc directory contains a large part of - your system's configuration information, as well as scripts that are - run at system startup. Some of these scripts change from version to - version of FreeBSD. - Some of the configuration files are also used in the day to day - running of the system. In particular, + The /etc directory contains a large part + of your system's configuration information, as well as scripts + that are run at system startup. Some of these scripts change from + version to version of FreeBSD. + + Some of the configuration files are also used in the day to + day running of the system. In particular, /etc/group. There have been occasions when the installation part of - make world has expected certain usernames or groups to - exist. When performing an upgrade it is likely that these groups did - not exist. This caused problems when upgrading. + make world has expected certain usernames or groups + to exist. When performing an upgrade it is likely that these + groups did not exist. This caused problems when upgrading. The most recent example of this is when the ppp - subsystem were installed using a non-existent (for them) group - name. - - The solution is to examine /usr/src/etc/group - and compare its list of groups with your own. If they are any groups - in the new file that are not in your file then copy them over. - Similarly, you should rename any groups in - /etc/group which have the same GID but a - different name to those in + (later renamed ppp subsystem were installed using a + non-existent (for them) group name. + + The solution is to examine + /usr/src/etc/group and compare its list of + groups with your own. If they are any groups in the new file that + are not in your file then copy them over. Similarly, you should + rename any groups in /etc/group which have + the same GID but a different name to those in /usr/src/etc/group. If you are feeling particularly paranoid, you can check your - system to see which files are owned by the group you are renaming or - deleting. + system to see which files are owned by the group you are + renaming or deleting. &prompt.root; find / -group GID -print - will show all files owned by group GID - (which can be either a group name or a numeric group ID). + will show all files owned by group + GID (which can be either a group name + or a numeric group ID). - + You may want to compile the system in single user mode. Apart from the obvious benefit of making things go slightly faster, - reinstalling the system will touch a lot of important system files, - all the standard system binaries, libraries, include files and so on. - Changing these on a running system (particularly if you have active - users on their at the time) is asking for trouble.</para> + reinstalling the system will touch a lot of important system + files, all the standard system binaries, libraries, include files + and so on. Changing these on a running system (particularly if + you have active users on their at the time) is asking for + trouble.</para> + + <para>That said, if you are confident, you can omit this + step.</para> - <para>That said, if you are confident, you can omit this step.</para> - <note> <title>Version 2.2.5 and above - As described in more detail below, versions 2.2.5 and above of - FreeBSD have separated the building process from the installing - process. You can therefore build the new - system in multi user mode, and then drop to single user mode to do - the installation. + As described in more detail below, versions 2.2.5 and above + of FreeBSD have separated the building process from the + installing process. You can therefore + build the new system in multi-user mode, + and then drop to single user mode to do the installation. - - As the superuser, you can execute - &prompt.root; + As the superuser, you can execute - from a running system, which will drop it to single user mode. - - Alternatively, reboot the system, and at the boot prompt, enter - the flag. The system will then boot single user. - At the shell prompt you should then run: + &prompt.root; + + from a running system, which will drop it to single user + mode. + + Alternatively, reboot the system, and at the boot prompt, + enter the flag. The system will then boot + single user. At the shell prompt you should then run: &prompt.root; fsck -p &prompt.root; mount -u / &prompt.root; mount -a -t ufs &prompt.root; swapon -a This checks the filesystems, remounts / read/write, mounts all the other UFS filesystems referenced in /etc/fstab and then turns swapping on. - + Remove <filename>/usr/obj</filename> - - As parts of the system are rebuilt they are placed in directories - which (by default) go under /usr/obj. The - directories shadow those under /usr/src. - + + As parts of the system are rebuilt they are placed in + directories which (by default) go under + /usr/obj. The directories shadow those under + /usr/src. + You can speed up the make world process, and possibly save yourself some dependency headaches by removing this directory as well. Some files below /usr/obj will have the - immutable flag set (see &man.chflags.1; for more - information) which must be removed first. + immutable flag set (see &man.chflags.1; for more information) + which must be removed first. &prompt.root; cd /usr/obj &prompt.root; chflags -R noschg * &prompt.root; rm -rf * <title>All versions - You must be in the /usr/src directory, so + You must be in the /usr/src + directory... + + &prompt.root; cd /usr/src + + (unless, of course, your source code is elsewhere, in which + case change to that directory instead). - &prompt.root; cd /usr/src - - (unless, of course, your source code is elsewhere, in which case - change to that directory instead). - To rebuild the world you use the &man.make.1; command. This - command reads instructions from the Makefile - which describes how the programs that comprise FreeBSD should be - rebuilt, the order they should be built in, and so on. + command reads instructions from the + Makefile which describes how the programs + that comprise FreeBSD should be rebuilt, the order they should + be built in, and so on. The general format of the command line you will type is as - follows; + follows: &prompt.root; make In this example, - is an option that you would pass to &man.make.1;. See the manual - page for an example of the options you can pass. + is an option that you would pass to &man.make.1;. See the + &man.make.1; manual page for an example of the options you can + pass. - passes a - variable to the Makefile. The behaviour of the - Makefile is controlled by these variables. - These are the same variables as are set in - /etc/make.conf, and this provides another way - of setting them. + + passes a variable to the Makefile. The + behavior of the Makefile is controlled by + these variables. These are the same variables as are set in + /etc/make.conf, and this provides another + way of setting them. &prompt.root; make -DNOPROFILE=true target - - is another way of specifying that profiled libaries should not be - built, and corresponds with the - NOPROFILE= true + is another way of specifying that profiled libaries should + not be built, and corresponds with the + + NOPROFILE= true # Avoid compiling profiled libraries - lines in /etc/make.conf. + lines in /etc/make.conf. - target tells &man.make.1; what you - want to do. Each Makefile defines a number of - different targets, and your choice of target - determines what happens. + target tells &man.make.1; what + you want to do. Each Makefile defines a + number of different targets, and your choice of + target determines what happens. - Some targets are listed in the Makefile, - but are not meant for you to run. Instead, they are used by the - build process to break out the steps necessary to rebuild the system - into a number of sub-steps. + Some targets are listed in the + Makefile, but are not meant for you to run. + Instead, they are used by the build process to break out the + steps necessary to rebuild the system into a number of + sub-steps. Most of the time you won't need to pass any parameters to - &man.make.1;, and so your command like will look like this. + &man.make.1;, and so your command like will look like + this: &prompt.root; make target Saving the output It's a good idea to save the output you get from running - &man.make.1; to another file. If something goes wrong you will - have a copy of the error message, and a complete list of where the - process had got to. While this might not help you in diagnosing - what has gone wrong, it can help others if you post your problem to - one of the FreeBSD mailing lists. - - The easiest way to do this is to use the &man.script.1; command, - with a parameter that specifies the name of the file to save all - output to. You would do this immediately before remaking the world, - and then type exit when the process has - finished. + &man.make.1; to another file. If something goes wrong you will + have a copy of the error message, and a complete list of where + the process had got to. While this might not help you in + diagnosing what has gone wrong, it can help others if you post + your problem to one of the FreeBSD mailing lists. + + The easiest way to do this is to use the &man.script.1; + command, with a parameter that specifies the name of the file to + save all output to. You would do this immediately before + remaking the world, and then type exit + when the process has finished. &prompt.root; script /var/tmp/mw.out Script started, output file is /var/tmp/mw.out &prompt.root; make world … compile, compile, compile … &prompt.root; exit Script done, … - If you do this, do not save the output in - /tmp. This directory may be cleared next time - you reboot. A better place to store it is in - /var/tmp (as in the previous example) or in - root's home directory. + If you do this, do not save the output + in /tmp. This directory may be cleared + next time you reboot. A better place to store it is in + /var/tmp (as in the previous example) or + in root's home directory. - + Version 2.2.2 and below /usr/src/Makefile contains the - world target, which will rebuild the entire - system and then install it. + world target, which will rebuild the + entire system and then install it. + + Use it like this: - Use it like this. - &prompt.root; make world Version 2.2.5 and above - Beginning with version 2.2.5 of FreeBSD (actually, it was first - created on the -current branch, and then retrofitted to -stable - midway between 2.2.2 and 2.2.5) the world - target has been split in two. buildworld - and installworld. + Beginning with version 2.2.5 of FreeBSD (actually, it was + first created on the -CURRENT branch, and then retrofitted to + -STABLE midway between 2.2.2 and 2.2.5) the + world target has been split in + two. buildworld and + installworld. - As the names imply, buildworld builds a - complete new tree under /usr/obj, and - installworld installs this tree on the - current machine. + As the names imply, buildworld + builds a complete new tree under /usr/obj, + and installworld installs this tree on + the current machine. This is very useful for 2 reasons. First, it allows you to do the build safe in the knowledge that no components of your running system will be affected. The build is self hosted. Because of this, you can safely run buildworld on a machine running in multi-user mode with no fear of ill-effects. I still recommend you run the installworld part in single user mode though. - Secondly, it allows you to use NFS mounts to upgrade multiple - machines on your network. If you have three machines, A, B and C - that you want to upgrade, run make buildworld and - make installworld on A. B and C should then NFS - mount /usr/src and - /usr/obj from A, and you can then run - make installworld to install the results of the - build on B and C. - - The world target still exists, and you - can use it exactly as shown for version 2.2.2. make - world runs make buildworld followed - by make installworld. + Secondly, it allows you to use NFS mounts to upgrade + multiple machines on your network. If you have three machines, + A, B and C that you want to upgrade, run make + buildworld and make installworld on + A. B and C should then NFS mount /usr/src + and /usr/obj from A, and you can then run + make installworld to install the results of + the build on B and C. + + The world target still exists, and + you can use it exactly as shown for version 2.2.2. + make world runs make + buildworld followed by make + installworld. - If you do the make buildworld and - make installworld commands separately, you must - pass the same parameters to &man.make.1; each time. + If you do the make buildworld and + make installworld commands separately, you + must pass the same parameters to &man.make.1; each + time. - If you run + If you run: - &prompt.root; make -DNOPROFILE=true buildworld + &prompt.root; make -DNOPROFILE=true buildworld - you must install the results with + you must install the results with: - &prompt.root; make -DNOPROFILE=true installworld + &prompt.root; make -DNOPROFILE=true installworld - otherwise it would try and install profiled libraries that had not - been built during the make buildworld + otherwise it would try and install profiled libraries that + had not been built during the make buildworld phase. - -current and above + -CURRENT and above - If you are tracking -current you can also pass the + If you are tracking -CURRENT you can also pass the option to make. This lets make spawn several simultaneous processes. This is most useful on true multi-CPU machines. However, since much of the compiling process is IO bound rather than CPU bound it is also useful on single CPU machines. On a typical single-CPU machine you would run: &prompt.root; make -j4 target &man.make.1; will then have up to 4 processes running at any one time. Empirical evidence posted to the mailing lists shows this generally gives the best performance benefit. If you have a multi-CPU machine and you are using an SMP configured kernel try values between 6 and 10 and see how they speed things up. Be aware that (at the time of writing) this is still experimental, and commits to the source tree may occasionally break this feature. If the world fails to compile using this parameter try again without it before you report any problems. Timings Assuming everything goes well you have anywhere between an hour and a half and a day or so to wait. As a general rule of thumb, a 200MHz P6 with more than 32MB of RAM and reasonable SCSI disks will complete make world in about an hour and a half. A 32MB P133 will take 5 or 6 hours. Revise these figures down if your machines are slower… Update <filename>/etc</filename> Remaking the world will not update certain directories (in particular, /etc, /var and /usr) with new or changed configuration files. This is something you have to do by hand, eyeball, and judicious use of &man.diff.1;. You cannot just copy over the files from /usr/src/etc to /etc and have it work. Some of these files must be installed first. This is because the /usr/src/etc directory is not a copy of what your /etc directory should look like. In addition, there are files that should be in /etc that are not in /usr/src/etc. The simplest way to do this is to install the files into a new directory, and then work through them looking for differences. Backup your existing <filename>/etc</filename> Although, in theory, nothing is going to touch this directory automatically, it is always better to be sure. So copy your existing /etc directory somewhere safe. Something like: &prompt.root; cp -Rp /etc /etc.old does a recursive copy, preserves times, ownerships on files and suchlike. You need to build a dummy set of directories to install the new /etc and other files into. I generally choose to put this dummy directory in /var/tmp/root, and there are a number of subdirectories required under this as well. &prompt.root; mkdir /var/tmp/root &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distribution This will build the necessary directory structure and install the files. A lot of the subdirectories that have been created under /var/tmp/root are empty and should be deleted. The simplest way to do this is to: &prompt.root; cd /var/tmp/root &prompt.root; find -d . -type d | /usr/bin/perl -lne \ 'opendir(D,$_);@f=readdir(D);rmdir if $#f == 1;closedir(D);' This does a depth first search, examines each directory, and if the number of files in that directory is 2 ( /var/tmp/root now contains all the files that should be placed in appropriate locations below /. You now have to go through each of these files, determining how they differ with your existing files. Note that some of the files that will have been installed in /var/tmp/root have a leading /var/tmp/root/ and /var/tmp/root/root/, although there may be others (depending on when you are reading this. Make sure you use The simplest way to do this is to use &man.diff.1; to compare the two files. &prompt.root; diff /etc/shells /var/tmp/root/etc/shells This will show you the differences between your /etc/shells file and the new /etc/shells file. Use these to decide whether to merge in changes that you have made or whether to copy over your old file. Name the new root directory (<filename>/var/tmp/root</filename>)with a timestamp, so you can easily compare differences between versions Frequently remaking the world means that you have to update /etc frequently as well, which can be a bit of a chore. You can speed this process up by keeping a copy of the last set of changed files that you merged into /etc. The following procedure gives one idea of how to do this. Make the world as normal. When you want to update /etc and the other directories, give the target directory a name based on the current date. If you were doing this on the 14th of February 1998 you could do the following. &prompt.root; mkdir /var/tmp/root-19980214 &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root-19980214 \ distrib-dirs distribution Merge in the changes from this directory as outlined above. Do not remove the /var/tmp/root-19980214 directory when you have finished. When you have downloaded the latest version of the source and remade it, follow step 1. This will give you a new directory, which might be called /var/tmp/root-19980221 (if you wait a week between doing updates). You can now see the differences that have been made in the intervening week using &man.diff.1; to create a recursive diff between the two directories. &prompt.root; cd /var/tmp &prompt.root; diff -r root-19980214 root-19980221 Typically, this will be a much smaller set of differences than those between /var/tmp/root-19980221/etc and /etc. Because the set of differences is smaller, it is easier to migrate those changes across into your /etc directory. You can now remove the older of the two /var/tmp/root-* directories. &prompt.root; rm -rf /var/tmp/root-19980214 Repeat this process every time you need to merge in changes to /etc. You can use &man.date.1; to automate the generation of the directory names. &prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"` Update <filename>/dev</filename> DEVFS If you are using DEVFS then this is probably unnecessary. For safety's sake, this is a multistep process. Copy /var/tmp/root/dev/MAKEDEV to /dev. &prompt.root; cp /var/tmp/root/dev/MAKEDEV /dev Now, take a snapshot of your current /dev. This snapshot needs to contain the permissions, ownerships, major and minor numbers of each filename, but it should not contain the timestamps. The easiest way to do this is to use &man.awk.1; to strip out some of the information. &prompt.root; cd /dev &prompt.root; ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out Remake all the devices. &prompt.root; Write another snapshot of the directory, this time to /var/tmp/dev2.out. Now look through these two files for any devices that you missed creating. There should not be any, but it is better to be safe than sorry. &prompt.root; diff /var/tmp/dev.out /var/tmp/dev2.out You are most likely to notice disk slice discrepancies which will involve commands such as &prompt.root; sh MAKEDEV sd0s1 to recreate the slice entries. Your precise circumstances may vary. Update <filename>/stand</filename> This step is included only for completeness, it can safely be omitted. For completenesses sake you may want to update the files in /stand as well. These files consist of hard links to the /stand/sysinstall binary. This binary should be statically linked, so that it can work when no other filesystems (and in particular /usr) have been mounted. &prompt.root; cd /usr/src/release/sysinstall &prompt.root; make all install Source older than 2 April 1998 If your source code is older than 2nd April 1998, or the Makefile version is not 1.68 or higher (for - FreeBSD current and 3.x systems) or 1.48.2.21 or higher (for 2.2.x + FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X systems) you will need to add the NOSHARED=yes option, like so; &prompt.root; make NOSHARED=yes all install Compile and install a new kernel To take full advantage of your new system you should recompile the kernel. This is practically a necessity, as certain memory structures may have changed, and programs like &man.ps.1; and &man.top.1; will fail to work until the kernel and source code versions are the same. Follow the handbook instructions for compiling a new kernel. If you have previously built a custom kernel then carefully examine the LINT config file to see if there are any new options which you should take advantage of. A previous version of this document suggested rebooting before rebuilding the kernel. This is wrong because: Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8; may fail. This could leave your machine unable to connect to the network. Basic utilities like &man.mount.8; could fail, making it impossible to mount /, /usr and so on. This is unlikely if you are - tracking a -stable candidate, but more likely if you are tracking - -current during a large merge. + tracking a -STABLE candidate, but more likely if you are tracking + -CURRENT during a large merge. - Loadable kernel modules (LKMs on pre-3.x systems, KLDs on 3.x + Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X systems and above) built as part of the world may crash an older kernel. For these reasons, it is always best to rebuild and install a new kernel before rebooting. You should build your new kernel after you have completed make world (or make installworld). If you do not want to do this (perhaps you want to confirm that the kernel builds before updating your system) you may have problems. These may be because your &man.config.8; command is out of date with respect to your kernel sources. In this case you could build your kernel with the new version of &man.config.8; &prompt.root; /usr/obj/usr/src/usr.sbin/config/config KERNELNAME This may not work in all cases. It is recommended that you complete make world (or make installworld) before compiling a new kernel. You are now done. After you have verified that everything appears to be in the right place you can reboot the system. A simple &man.fastboot.8; should do it.</para> <screen>&prompt.root; <userinput>fastboot</userinput></screen> </sect2> <sect2> <title>Finished You should now have successfully upgraded your FreeBSD system. Congratulations. You may notice small problems due to things that you have missed. For example, I once deleted /etc/magic as part of the upgrade and merge to /etc, and the file command stopped working. A moment's thought meant that &prompt.root; cd /usr/src/usr.bin/file &prompt.root; was sufficient to fix that one. <qandaentry> <question> <para>Do I need to re-make the world for every change?</para> </question> <answer> <para>There is no easy answer to this one, as it depends on the nature of the change. For example, I have just run CVSup, and it has shown the following files as being updated since I last ran it;</para> <screen><filename>src/games/cribbage/instr.c</filename> <filename>src/games/sail/pl_main.c</filename> <filename>src/release/sysinstall/config.c</filename> <filename>src/release/sysinstall/media.c</filename> <filename>src/share/mk/bsd.port.mk</filename></screen> <para>There is nothing in there that I would re-make the world for. I would go to the appropriate sub-directories and <command>make all install</command>, and that's about it. But if something major changed, for example <filename>src/lib/libc/stdlib</filename> then I would either re-make the world, or at least those parts of it that are statically linked (as well as anything else I might have added that is statically linked).</para> <para>At the end of the day, it is your call. You might be happy re-making the world every fortnight say, and let changes accumulate over that fortnight. Or you might want to re-make just those things that have changed, and are confident you can spot all the dependencies.</para> <para>And, of course, this all depends on how often you want to - upgrade, and whether you are tracking -stable or - -current.</para> + upgrade, and whether you are tracking -STABLE or + -CURRENT.</para> </answer> </qandaentry> <qandaentry> <question> <para>My compile failed with lots of signal 12 (or other signal number) errors. What has happened?</para> </question> <answer> <para>This is normally indicative of hardware problems. (Re)making the world is an effective way to stress test your hardware, and will frequently throw up memory problems. These normally manifest themselves as the compiler mysteriously dying on receipt of strange signals.</para> <para>A sure indicator of this is if you can restart the make and it dies at a different point in the process.</para> <para>In this instance there is little you can do except start swapping around the components in your machine to determine which one is failing.</para> </answer> </qandaentry> <qandaentry> <question> <para>Can I remove <filename>/usr/obj</filename> when I have finished?</para> </question> <answer> <para>That depends on how you want to make the world on future occasions.</para> <para><filename>/usr/obj</filename> contains all the object files that were produced during the compilation phase. Normally, one of the first steps in the <quote/make world/ process is to remove this directory and start afresh. In this case, keeping <filename>/usr/obj</filename> around after you have finished makes little sense, and will free up a large chunk of disk space (currently about 150MB).</para> <para>However, if you know what you are doing you can have <quote/make world/ skip this step. This will make subsequent builds run much faster, since most of sources will not need to be recompiled. The flip side of this is that subtle dependency problems can creep in, causing your build to fail in odd ways. This frequently generates noise on the FreeBSD mailing lists, when one person complains that their build has failed, not realising that it is because they have tried to cut corners.</para> <para>If you want to live dangerously then make the world, passing the <makevar>NOCLEAN</makevar> definition to make, like this:</para> <screen>&prompt.root; <userinput>make -DNOCLEAN world</userinput></screen> </answer> </qandaentry> <qandaentry> <question> <para>Can interrupted builds be resumed?</para> </question> <answer> <para>This depends on how far through the process you got before you found a problem.</para> <para><emphasis>In general</emphasis> (and this is not a hard and fast rule) the <quote>make world</quote> process builds new copies of essential tools (such as &man.gcc.1;, and &man.make.1;>) and the system libraries. These tools and libraries are then installed. The new tools and libraries are then used to rebuild themselves, and are installed again. The entire system (now including regular user programs, such as &man.ls.1; or &man.grep.1;) is then rebuilt with the new system files.</para> <para>If you are at the last state, and you know it (because you have looked through the output that you were storing) then you can (fairly safely) do</para> <screen><emphasis>… fix the problem …</emphasis> &prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make -DNOCLEAN all</userinput></screen> <para>This will not undo the work of the previous <quote>make world</quote>.</para> <para>If you see the message <screen>-------------------------------------------------------------- Building everything.. --------------------------------------------------------------</screen> in the <quote>make world</quote> output then it is probably fairly safe to do so.</para> <para>If you do not see that message, or you are not sure, then it is always better to be safe than sorry, and restart the build from scratch.</para> </answer> </qandaentry> <qandaentry> <question> <para>Can I use one machine as a <emphasis/master/ to upgrade lots of machines (NFS)?</para> </question> <answer> <para>People often ask on the FreeBSD mailing lists whether they can do all the compiling on one machine, and then use the results of that compile to <command>make install</command> on to other machines around the network.</para> <para>This is not something I have done, so the suggestions below are either from other people, or deduced from the Makefiles.</para> <para>The precise approach to take depends on your version of FreeBSD</para> <para>You must still upgrade <filename>/etc</filename> and <filename>/dev</filename> on the target machines after doing this.</para> <para>For 2.1.7 and below, Antonio Bemfica suggested the following approach:</para> <screen>Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST) From: Antonio Bemfica <bemfica@militzer.me.tuns.ca> -To: freebsd-questions@freebsd.org +To: freebsd-questions@FreeBSD.org Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca> Josef Karthauser asked: > Has anybody got a good method for upgrading machines on a network First make world, etc. on your main machine Second, mount / and /usr from the remote machine: main_machine% mount remote_machine:/ /mnt main_machine% mount remote_machine:/usr /mnt/usr Third, do a 'make install' with /mnt as the destination: main_machine% make install DESTDIR=/mnt Repeat for every other remote machine on your network. It works fine for me. Antonio</screen> <para>This mechanism will only work (to the best of my knowledge) if you can write to <filename>/usr/src</filename> on the NFS server, as the <maketarget>install</maketarget> target in 2.1.7 and below needed to do this.</para> <para>Midway between 2.1.7 and 2.2.0 the <quote>reinstall</quote> target was committed. You can use the approach exactly as outlined above for 2.1.7, but use <quote>reinstall</quote> instead of <quote>install</quote>.</para> <para>This approach <emphasis>does not</emphasis> require write access to the <filename>/usr/src</filename> directory on the NFS server.</para> <para>There was a bug introduced in this target between versions 1.68 and 1.107 of the Makefile, which meant that write access to the NFS server <emphasis>was</emphasis> required. This bug was fixed before version 2.2.0 of FreeBSD was released, but may be an - issue of you have an old server still running -stable from this + issue of you have an old server still running -STABLE from this era.</para> <para>For version 2.2.5 and above, you can use the <quote>buildworld</quote> and <quote>installworld</quote> targets. Use them to build a source tree on one machine, and then NFS mount <filename>/usr/src</filename> and <filename>/usr/obj</filename> on the remote machine and install it there.</para> </answer> </qandaentry> <qandaentry> <question> <para>How can I speed up making the world?</para> <itemizedlist> <listitem> <para>Run in single user mode.</para> </listitem> <listitem> <para>Put the <filename>/usr/src</filename> and <filename>/usr/obj</filename> directories on separate filesystems held on separate disks. If possible, put these disks on separate disk controllers.</para> </listitem> <listitem> <para>Better still, put these filesystems across separate disks using the <quote>ccd</quote> (concatenated disk driver) device.</para> </listitem> <listitem> <para>Turn off profiling (set <quote>NOPROFILE=true</quote> in <filename>/etc/make.conf</filename>). You almost certainly do not need it.</para> </listitem> <listitem> <para>Also in <filename>/etc/make.conf</filename>, set <quote>CFLAGS</quote> to something like <quote>-O -pipe</quote>. The optimisation <quote>-O2</quote> is much slower, and the optimisation difference between <quote>-O</quote> and <quote>-O2</quote> is normally negligible. <quote>-pipe</quote> lets the compiler use pipes rather than temporary files for communication, which saves disk access (at the expense of memory).</para> </listitem> <listitem> <para>Pass the <option>-j<n></option> option to make (if you are running a sufficiently recent version of FreeBSD) to run multiple processes in parallel. This helps regardless of whether you have a single or a multi processor machine.</para> </listitem> <listitem><para>The filesystem holding <filename>/usr/src</filename> can be mounted (or remounted) with the <quote>noatime</quote> option. This stops the time files in the filesystem were last accessed from being written to the disk. You probably do not need this information anyway. <note> <para><quote>noatime</quote> is in version 2.2.0 and above.</para> </note> <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> <warning> <para>The example assumes <filename>/usr/src</filename> is on its own filesystem. If it is not (if it is a part of <filename>/usr</filename> for example) then you will need to use that filesystem mount point, and not <filename>/usr/src</filename>.</para> </warning> </para> </listitem> <listitem> <para>The filesystem holding <filename>/usr/obj</filename> can be mounted (or remounted) with the <quote>async</quote> option. This causes disk writes to happen asynchronously. In other words, the write completes immediately, and the data is written to the disk a few seconds later. This allows writes to be clustered together, and can be a dramatic performance boost.</para> <warning> <para>Keep in mind that this option makes your filesystem more fragile. With this option there is an increased chance that, should power fail, the filesystem will be in an unrecoverable state when the machine restarts.</para> <para>If <filename>/usr/obj</filename> is the only thing on this filesystem then it is not a problem. If you have other, valuable data on the same filesystem then ensure your backups are fresh before you enable this option.</para> </warning> <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> <warning> <para>As above, if <filename>/usr/obj</filename> is not on its own filesystem, replace it in the example with the name of the appropriate mount point.</para> </warning> </listitem> </itemizedlist> </question> </qandaentry> </qandaset> </sect2> - - <sect2> - <title>Contributors - - The following people have contributed to this document in some - form or another. Either by directly suggesting alterations and - improvements, pointing out errors, or by their messages to the FreeBSD - mailing lists, from which I have shamelessly cribbed information. My - thanks to them. - - - - Antonio Bemfica, - bemfica@militzer.me.tuns.ca - - - - Sue Blake, sue@welearn.com.au - - - - Brian Haskin, haskin@ptway.com - - - - Kees Jan Koster, kjk1@ukc.ac.uk - - - - A Joseph Kosy, koshy@india.hp.com - - - - Greg Lehey, grog@lemis.com - - - - Wes Peters, softweyr@xmission.com - - - - Joseph Stein, joes@wstein.com - - - - Studded, studded@dal.net - - - - Axel Thimm, - Axel.Thimm@physik.fu-berlin.de - - - - Matthew Thyer, - Matthew.Thyer@dsto.defence.gov.au - - - 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 5b172dff2a..a25bb012bd 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,3504 +1,3487 @@ - 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. + The Cutting Edge + + Restructured, reorganized, and parts updated by &a.jim; + March 2000. Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik; + with feedback from various others. + + + Synopsis + + 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. - + -CURRENT v.s. -STABLE - - 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. - + There are two development branches to FreeBSD; -CURRENT and + -STABLE. This section will explain a bit about each and describe + how to keep your system up-to-date with each respective tree. + -CURRENT will be discussed first, then -STABLE. - - 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. - + Staying Current with FreeBSD - - A quick way of getting bug fixes. - + As you are reading this, keep in mind that -CURRENT is the + “bleeding edge” of FreeBSD development and that if you + are new to FreeBSD, you are most likely going to want to think + twice about running it. - - 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 + + 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 &a.cvsall; mailing list will allow you to see the commit - log entry for each change as it is made along with any pertinent - information on possible side-effects. - - To join these lists, send mail to - &a.majordomo; and specify: + + + 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 &a.cvsall; mailing list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, send mail to &a.majordomo; and + specify the following in the body of your message: subscribe freebsd-current subscribe cvs-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. - + 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 - + Grab the sources from ftp.FreeBSD.org. You can do this in + one of three ways: + + + + Use the CTM facility. Unless + you have a good TCP/IP connection at a flat rate, this + is the way to do it. + + + + Use the cvsup program + with this supfile. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron and keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type: - -
&prompt.root; pkg_add -f \ + 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: + + + 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: - + We also use wu-ftpd which allows + compressed/tar'd grabbing of whole trees. e.g. you + see: + + usr.bin/lex + + You can do the following to get the whole directory + as a tar file: + ftp> cd usr.bin ftp> get lex.tar - - and it will get the whole directory for you as a - 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. - + + 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 + Makefilein /usr/src + carefully. You should at least run a make world the first time through + as part of the upgrading process. Reading the &a.current; + will keep you up-to-date on other bootstrapping procedures + that sometimes become necessary as we move towards the next + release. + - - Be active! If you are running FreeBSD-current, we want to - know what you have to say about it, especially if you have - suggestions for enhancements or bug fixes. Suggestions with - accompanying code are received most enthusiastically! - - + + 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 - - + <anchor id="stable">Staying Stable with FreeBSD + + If you are using FreeBSD in a production environment and want + to make sure you have the latest fixes from the -CURRENT branch, + you want to be running -STABLE. This is the tree that -RELEASEs + are branched from when we are putting together a new release. For + example, if you have a copy of 3.4-RELEASE, that is really just a + “snapshot” from the -STABLE branch that we put on + CDROM. In order to get any changes merged into -STABLE after the + -RELEASE, you need to “track” the -STABLE + branch. - - 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 &a.cvsall; mailing list will allow you to see the commit - log entry for each change as it is made along with any pertinent - information on possible side-effects. + + 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). + - To join these lists, send mail to &a.majordomo; and specify: + + 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 &a.cvsall; mailing list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, send mail to &a.majordomo; and + specify the following in the body of your message: subscribe freebsd-stable subscribe cvs-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. - + 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 + 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. + and install it like any other release. - If you are already running a previous release of FreeBSD and wish - to upgrade via sources then you can easily do so from ftp.FreeBSD.org. This can be done in one - of three ways: - - - - Use the CTM facility. Unless - you have a good TCP/IP connection at a flat rate, this is - the way to do it. - - - - Use the cvsup program with - If you are already running a previous release of FreeBSD + and wish to upgrade via sources then you can easily do so + from ftp.FreeBSD.org. This can + be done in one of three ways: + + + + Use the CTM facility. Unless + you have a good TCP/IP connection at a flat rate, this + is the way to do it. + + + + Use the cvsup program + with this supfile. This is the second most recommended - method, since it allows you to grab the entire collection - once and then only what has changed from then on. Many people - run cvsup from cron to keep their sources up-to-date - automatically. For a fairly easy interface to this, simply - type; + 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 \ +
&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: + + + 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: - + We also use wu-ftpd which allows + compressed/tar'd grabbing of whole trees. e.g. you + see: + + usr.bin/lex + + You can do the following to get the whole directory + for you as a tar file: + ftp> cd usr.bin ftp> get lex.tar - - and it will get the whole directory for you as a - 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. - + + 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 + + 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 + Synchronizing Your Source - 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. + 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. + 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 + 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. + 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. + 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: + More information about Anonymous CVS, + CTM, and + CVSup is available further down in this + section. 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, - provides the well-known password anoncvs - with the cvs login command, and then uses - the &man.cvs.1; command to access it like any local + utilities bundled with FreeBSD for synchronizing with a remote + CVS repository. Among other things, it allows users of FreeBSD + to perform, with no special privileges, read-only CVS operations + against one of the FreeBSD project's official anoncvs servers. + To use it, one simply sets the CVSROOT + environment variable to point at the appropriate anoncvs server, + provides the well-known password anoncvs with the + cvs login command, and then uses the + &man.cvs.1; command to access it like any local repository. While it can also be said that the CVSup and anoncvs + linkend="cvsup">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 + 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 + 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. + 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: + 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: - :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs + :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs (Use cvs login and enter the password anoncvs when prompted.) - Since CVS allows one to “check out” virtually any - version of the FreeBSD sources that ever existed (or, in some cases, - will exist :), you need to be familiar with the - revision () flag to &man.cvs.1; and what some of - the permissible values for it in the FreeBSD Project repository - are. - - There are two kinds of tags, revision tags and branch tags. A - revision tag refers to a specific revision. Its meaning stays the - same from day to day. A branch tag, on the other hand, refers to - the latest revision on a given line of development, at any given - time. Because a branch tag does not refer to a specific revision, - it may mean something different tomorrow than it means today. + 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: + in (keep in mind that the only tags valid for the ports collection is + HEAD). HEAD - + - Symbolic name for the main line, or FreeBSD-current. Also - the default when no revision is specified. + 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. + The line of development for FreeBSD-3.X, also known + as FreeBSD-STABLE. - + RELENG_2_2 - + - The line of development for FreeBSD-2.2.x, also known as - 2.2-stable. This branch is mostly obsolete. Not valid for - the ports collection. + The line of development for FreeBSD-2.2.X, also known + as 2.2-STABLE. This branch is mostly obsolete. Here are the revision tags that users might be interested - in: + in. Again, none of these are valid for the ports collection + since the ports collection does not have multiple + revisions. RELENG_3_4_0_RELEASE - FreeBSD-3.4. Not valid for the ports collection. + FreeBSD-3.4. RELENG_3_3_0_RELEASE - FreeBSD-3.3. Not valid for the ports collection. + FreeBSD-3.3. - RELENG_3_2_0_RELEASE - + - FreeBSD-3.2. Not valid for the ports collection. + FreeBSD-3.2. - - + RELENG_3_1_0_RELEASE - + - FreeBSD-3.1. Not valid for the ports collection. + FreeBSD-3.1. RELENG_3_0_0_RELEASE - + - FreeBSD-3.0. Not valid for the ports collection. + FreeBSD-3.0. RELENG_2_2_8_RELEASE - + - FreeBSD-2.2.8. Not valid for the ports collection. + FreeBSD-2.2.8. RELENG_2_2_7_RELEASE - + - FreeBSD-2.2.7. Not valid for the ports collection. + FreeBSD-2.2.7. RELENG_2_2_6_RELEASE - + - FreeBSD-2.2.6. Not valid for the ports collection. + FreeBSD-2.2.6. - + RELENG_2_2_5_RELEASE - + - FreeBSD-2.2.5. Not valid for the ports collection. + FreeBSD-2.2.5. - + RELENG_2_2_2_RELEASE - + - FreeBSD-2.2.2. Not valid for the ports collection. + FreeBSD-2.2.2. - + RELENG_2_2_1_RELEASE - + - FreeBSD-2.2.1. Not valid for the ports collection. + FreeBSD-2.2.1. - + RELENG_2_2_0_RELEASE - + - FreeBSD-2.2.0. Not valid for the ports collection. + FreeBSD-2.2.0. - When you specify a branch tag, you normally receive the latest - versions of the files on that line of development. If you wish to - receive some past version, you can do so by specifying a date with - the flag. See the &man.cvs.1; man page - for more details. + 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 + 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 + <title>Checking out something from -CURRENT (&man.ls.1;) and deleting it again: -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co ls &prompt.user; cvs release -d ls &prompt.user; cvs logout - Checking out the version of &man.ls.1; in the 2.2-stable + <title>Checking out the version of &man.ls.1; in the 2.2-STABLE branch: -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co -rRELENG_2_2 ls &prompt.user; cvs release -d ls &prompt.user; cvs logout Creating a list of changes (as unidiffs) to &man.ls.1; -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls &prompt.user; cvs logout Finding out what other module names can be used: - + -&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.freebsd.org:/home/ncvs +&prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules &prompt.user; cvs logout - + 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. - + 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. + 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>? + 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 + 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: + /usr/src/usr.sbin/CTM if you have a copy + of the source available. + + If you are running a pre-2.0 version of FreeBSD, you can + fetch the current CTM sources + directly from: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/ - - The “deltas” you feed CTM - can be had two ways, FTP or e-mail. If you have general FTP access - to the Internet then the following FTP sites support access to + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/ + + The “deltas” you feed + CTM can be had two ways, FTP or + email. If you have general FTP access to the Internet then the + following FTP sites support access to CTM: - + ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/ - - or see section mirrors. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/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: - + + If you wish to get your deltas via email: + Send email to &a.majordomo; to subscribe to one of the CTM distribution lists. “ctm-cvs-cur” supports the entire cvs tree. “ctm-src-cur” supports the head of the development - branch. “ctm-src-2_2” supports the 2.2 release branch, - etc. (If you do not know how to subscribe yourself using majordomo, - send a message first containing the word help - — it will send you back usage instructions.) - + 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. + 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 + 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 + <title>Using <application>CTM</application> for the first time - + Before you can start using CTM deltas, you will need to get to a starting point for the deltas produced subsequently to it. - - First you should determine what you already have. Everyone can - start from an “empty” directory. You must use an - initial “Empty&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 + + First you should determine what you already have. Everyone + can start from an “empty” directory. You must use + an initial “Empty” delta to start off your + CTM supported tree. At some point it + is intended that one of these “started” deltas be + distributed on the CD for your convenience, however, this does + not currently happen. + + Since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a - RELEASE CD, you can copy or extract an initial source from it. This - will save a significant transfer of data. - + -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 + designation following the X corresponds to + the origin of your initial “seed”. + Empty is an empty directory. As a rule a + base transition from Empty is produced + every 100 deltas. By the way, they are large! 25 to 30 + Megabytes of gzip'd data is common for the XEmpty deltas. - + Once you've picked a base delta to start from, you will also need all deltas with higher numbers following it. - + - Using <application>CTM</application> in your daily life + 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 + 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 + + That is really all there is to it. Every time you get a new + delta, just run it through CTM to + keep your sources up to date. + + Do not remove the deltas if they are hard to download again. + You just might want to keep them around in case something bad + happens. Even if you only have floppy disks, consider using fdwrite to make a copy. - + Keeping your local 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. + 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 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 :-). + + 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. + + 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 + + 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. - + 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 + + 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. + 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. + 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... - - - + “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. - + <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. - + 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. + 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 + 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. + project, because CVSup is both faster + and more flexible. - + Installation The easiest way to install CVSup is to use the net/cvsup-bin port from the FreeBSD ports collection. If you prefer to build CVSup from source, you can use the net/cvsup - port instead. But be forewarned: the net/cvsup - port depends on the Modula-3 system, which takes a substantial - amount of time, memory, and disk space to build. + port instead. But be forewarned: the + net/cvsup port depends on the Modula-3 + system, which takes a substantial amount of time, memory, and + disk space to build. If you do not know anything about cvsup at all and want a - single package which will install it, set up the configuration file - and start the transfer via a pointy-clicky type of interface, then - get the - cvsupit package. Just hand it to &man.pkg.add.1; and it will - lead you through the configuration process in a menu-oriented fashion. - + single package which will install it, set up the configuration + file and start the transfer via a pointy-clicky type of + interface, then get the cvsupit + package. Just hand it to &man.pkg.add.1; and it will lead you + through the configuration process in a menu-oriented + fashion. - + CVSup Configuration - CVSup's operation is controlled by a - configuration file called the supfile. - There are some sample - supfiles in the directory /usr/share/examples/cvsup/. - + CVSup's operation is controlled + by a configuration file called the supfile. + There are some sample supfiles in the + directory /usr/share/examples/cvsup/. + + The information in a supfile answers + the following questions for cvsup: - The information in a supfile answers the - following questions for cvsup: - - Which files do you want - to receive? + Which files do you + want to receive? - + - Which versions of them do - you want? + Which versions of them + do you want? - + - Where do you want to get - them from? + 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 them on your own machine? - + - Where do you want to put - your status files? + 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. - + 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 + “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 + 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 + 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. - + 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. + linkend="current">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: - + 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? - + 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. + 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 + 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. + + 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: + in. Keep in mind that only the tag=. is + relevant for the ports collection. tag=. The main line of development, also known as - FreeBSD-current. + FreeBSD-CURRENT. - The . is not punctuation; it is - the name of the tag. Valid for all collections. + 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. + The line of development for FreeBSD-3.X, also + known as FreeBSD-STABLE. RELENG_2_2 - The line of development for FreeBSD-2.2.x, also known - as 2.2-stable. Not valid for the ports collection. + The line of development for FreeBSD-2.2.X, also + known as 2.2-STABLE. Here are the revision tags that users might be interested - in: - + in. Again, these are not valid for the ports + collection. + RELENG_3_4_0_RELEASE - FreeBSD-3.4. Not valid for the ports-* - collections. + FreeBSD-3.4. - tag=RELENG_3_3_0_RELEASE - FreeBSD-3.3. Not valid for the ports-* - collections. + FreeBSD-3.3. + tag=RELENG_3_2_0_RELEASE + + + FreeBSD-3.2. + + - tag=RELENG_3_2_0_RELEASE - - - FreeBSD-3.2. Not valid for the ports-* - collections. - - - - + tag=RELENG_3_1_0_RELEASE - + - FreeBSD-3.1. Not valid for the ports-* - collections. + FreeBSD-3.1. - + tag=RELENG_3_0_0_RELEASE - + - FreeBSD-3.0. Not valid for the ports-* - collections. + FreeBSD-3.0. - + tag=RELENG_2_2_8_RELEASE - + - FreeBSD-2.2.8. Not valid for the ports-* - collections. + FreeBSD-2.2.8. - + tag=RELENG_2_2_7_RELEASE - + - FreeBSD-2.2.7. Not valid for the ports-* - collections. + FreeBSD-2.2.7. - + tag=RELENG_2_2_6_RELEASE - FreeBSD-2.2.6. Not valid for the ports-* - collections. + FreeBSD-2.2.6. - + tag=RELENG_2_2_5_RELEASE - + - FreeBSD-2.2.5. Not valid for the ports-* - collections. + FreeBSD-2.2.5. - + tag=RELENG_2_2_2_RELEASE - + - FreeBSD-2.2.2. Not valid for the ports-* - collections. + FreeBSD-2.2.2. - + tag=RELENG_2_2_1_RELEASE - + - FreeBSD-2.2.1. Not valid for the ports-* - collections. + FreeBSD-2.2.1. - + tag=RELENG_2_2_0_RELEASE - + - FreeBSD-2.2.0. Not valid for the ports-* - collections. + FreeBSD-2.2.0. - + Be very careful to type the tag name exactly as shown. - CVSup cannot distinguish between - valid and invalid tags. If you misspell the tag, - CVSup will behave as though you had - specified a valid tag which happens to refer to no files at - all. It will delete your existing sources in that - case. + 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 + 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 + 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. + 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? - + 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: - + 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 . + 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? - + 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: - + 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, + 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. + 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. + 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: - + 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 + 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. + 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. + 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: - + 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 + + 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: - + 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. + 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. - + 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. + 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. + 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 - + 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 - + 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. + Things that used to be on the desktop + before computers were invented. - + ports-devel - release=cvs - + release=cvs + Development utilities. - + ports-editors - release=cvs - + release=cvs + Editors. - + ports-emulators - release=cvs - + release=cvs + - Emulators for other operating systems. + Emulators for other operating + systems. - + ports-ftp - release=cvs - + release=cvs + FTP client and server utilities. - + ports-games - release=cvs - + release=cvs + Games. - + ports-german - release=cvs - + release=cvs + German language support. - + ports-graphics - release=cvs - + release=cvs + Graphics utilities. - + ports-irc - release=cvs - + release=cvs + Internet Relay Chat utilities. - + ports-japanese - release=cvs - + release=cvs + Japanese language support. - + ports-java - release=cvs - + release=cvs + Java utilities. - + ports-korean - release=cvs - + release=cvs + Korean language support. - + - ports-lang release=cvs - + ports-lang + release=cvs + Programming languages. - + - ports-mail release=cvs - + ports-mail + release=cvs + Mail software. - + - ports-math release=cvs - + ports-math + release=cvs + Numerical computation software. - + ports-mbone - release=cvs - + release=cvs + MBone applications. - + - ports-misc release=cvs - + ports-misc + release=cvs + Miscellaneous utilities. - + - ports-net release=cvs - + ports-net + release=cvs + Networking software. - + - ports-news release=cvs - + ports-news + release=cvs + USENET news software. - - ports-palm - release=cvs - - - Software support for 3Com Palm(tm) series. - - - + + ports-palm + release=cvs + + + Software support for 3Com Palm(tm) + series. + + + ports-print - release=cvs - + release=cvs + Printing software. - + ports-russian - release=cvs - + release=cvs + Russian language support. - + - ports-security - release=cvs - + ports-security + release=cvs + Security utilities. - + ports-shells - release=cvs - + release=cvs + Command line shells. - + ports-sysutils - release=cvs + release=cvs System utilities. - + ports-textproc - release=cvs - + release=cvs + - text processing utilities (does not include - desktop publishing). + text processing utilities (does not + include desktop publishing). - + ports-vietnamese - release=cvs - + release=cvs + Vietnamese language support. - + - ports-www release=cvs - + ports-www + release=cvs + - Software related to the World Wide Web. + Software related to the World Wide + Web. - + - ports-x11 release=cvs - + ports-x11 + release=cvs + - Ports to support the X window system. + Ports to support the X window + system. - + ports-x11-clocks - release=cvs - + release=cvs + X11 clocks. - + ports-x11-fm - release=cvs - + release=cvs + X11 file managers. - + ports-x11-fonts - release=cvs - + release=cvs + X11 fonts and font utilities. - + ports-x11-toolkits - release=cvs - + release=cvs + X11 toolkits. - + ports-x11-servers - + X11 servers. - + ports-x11-wm - + X11 window managers. - + src-all release=cvs - + The main FreeBSD sources, excluding the export-restricted cryptography code. - + - src-base release=cvs - + src-base + release=cvs + Miscellaneous files at the top of /usr/src. - + - src-bin release=cvs - + src-bin + release=cvs + User utilities that may be needed in single-user mode (/usr/src/bin). - + src-contrib - release=cvs - + release=cvs + Utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/contrib). - + - src-etc release=cvs - + src-etc + release=cvs + System configuration files (/usr/src/etc). - + - src-games release=cvs - + src-games + release=cvs + Games (/usr/src/games). - + - src-gnu release=cvs - + src-gnu + release=cvs + - Utilities covered by the GNU Public License - (/usr/src/gnu). + Utilities covered by the GNU Public + License (/usr/src/gnu). - + src-include - release=cvs - + release=cvs + Header files (/usr/src/include). - + src-kerberos5 - release=cvs - + release=cvs + Kerberos5 security package (/usr/src/kerberos5). - + src-kerberosIV - release=cvs - + release=cvs + KerberosIV security package (/usr/src/kerberosIV). - + - src-lib release=cvs - + src-lib + release=cvs + Libraries (/usr/src/lib). - + src-libexec - release=cvs - + release=cvs + System programs normally executed by other programs (/usr/src/libexec). - + src-release - release=cvs - + release=cvs + - Files required to produce a FreeBSD release + Files required to produce a FreeBSD + release (/usr/src/release). - + - src-sbin release=cvs - + src-sbin + release=cvs + System utilities for single-user mode (/usr/src/sbin). - + - src-share release=cvs - + src-share + release=cvs + Files that can be shared across multiple systems (/usr/src/share). - + - src-sys release=cvs - + src-sys + release=cvs + The kernel (/usr/src/sys). - + - src-tools release=cvs - + src-tools + release=cvs + - Various tools for the maintenance of FreeBSD + Various tools for the maintenance of + FreeBSD (/usr/src/tools). - + - src-usrbin release=cvs - + src-usrbin + release=cvs + User utilities (/usr/src/usr.bin). - + src-usrsbin - release=cvs - + 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 + outside the FreeBSD project, used relatively + unmodified (/usr/src/crypto). - + src-eBones release=cvs - + Kerberos and DES (/usr/src/eBones). Not used in current releases of FreeBSD. - + src-secure release=cvs - + DES (/usr/src/secure). - + - src-sys-crypto release=cvs - + src-sys-crypto + release=cvs + Kernel cryptography code (/usr/src/sys/crypto). - + distrib release=self - + - The CVSup server's own configuration files. Used by CVSup - mirror sites. + 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. + 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. + 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;. + + Using <command>make world</command> 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. + current and so on) you must then use the source + tree to rebuild the system. Take a backup - - I cannot stress highly enough how important it is to take a backup - of your system before you do this. While - remaking the world is (as long as you follow these instructions) an - easy task to do, there will inevitably be times when you make - mistakes, or when mistakes made by others in the source tree render - your system unbootable. - + + I cannot stress highly enough how important it is to take a + backup of your system before you do this. + While remaking the world is (as long as you follow these + instructions) an easy task to do, there will inevitably be times + when you make mistakes, or when mistakes made by others in the + source tree render your system unbootable. + Make sure you have taken a backup. And have a fixit floppy to - hand. I have never needed to use them, and, touch wood, I never will, - but it is always better to be safe than sorry. + hand. I have never needed to use them, and, touch wood, I never + will, but it is always better to be safe than sorry. Subscribe to the right mailing list - - The -stable and -current FreeBSD code branches are, by their - nature, in development. People that contribute - to FreeBSD are human, and mistakes occasionally happen. - Sometimes these mistakes can be quite harmless, just causing your - system to print a new diagnostic warning. Or the change may be - catastrophic, and render your system unbootable or destroy your + The -STABLE and -CURRENT FreeBSD code branches are, by their + nature, in development. People that + contribute to FreeBSD are human, and mistakes occasionally + happen. + + Sometimes these mistakes can be quite harmless, just causing + your system to print a new diagnostic warning. Or the change may + be catastrophic, and render your system unbootable or destroy your filesystems (or worse). - If problems like these occur, a heads up is posted - to the appropriate mailing list, explaining the nature of the problem - and which systems it affects. And an all clear - announcement is posted when the problem has been solved. + If problems like these occur, a heads up is + posted to the appropriate mailing list, explaining the nature of + the problem and which systems it affects. And an all + clear announcement is posted when the problem has been + solved. - If you try and track -stable or -current and do not read - FreeBSD-stable@FreeBSD.ORG or - FreeBSD-current@FreeBSD.ORG then you are asking for - trouble. + If you try and track -STABLE or -CURRENT and do not read the + stable@FreeBSD.org or + current@FreeBSD.org mailing lists then you are + asking for trouble. - + Check <filename>/etc/make.conf</filename> - + Examine the file /etc/make.conf. This - contains some default defines for - - Everything is, by default, commented out. Uncomment those entries - that look useful. For a typical user (not a developer), you will - probably want to uncomment the CFLAGS and NOPROFILE + contains some default defines for + + Everything is, by default, commented out. Uncomment those + entries that look useful. For a typical user (not a developer), + you will probably want to uncomment the CFLAGS and NOPROFILE definitions. If your machine has a floating point unit (386DX, 486DX, Pentium - and up class machines) then you can also uncomment the HAVE_FPU - line.</para> + <para>If your machine has a floating point unit (386DX, 486DX, + Pentium and up class machines) then you can also uncomment the + HAVE_FPU line.</para> <para>This definition was removed for version 2.2.2 and up of FreeBSD.</para> </note> - - <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so on) - and decide if they are relevant to you.</para> + + <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so + on) and decide if they are relevant to you.</para> </sect2> - - <sect2> + + <sect2> <title>Update <filename>/etc/group</filename> - - The /etc directory contains a large part of - your system's configuration information, as well as scripts that are - run at system startup. Some of these scripts change from version to - version of FreeBSD. - Some of the configuration files are also used in the day to day - running of the system. In particular, + The /etc directory contains a large part + of your system's configuration information, as well as scripts + that are run at system startup. Some of these scripts change from + version to version of FreeBSD. + + Some of the configuration files are also used in the day to + day running of the system. In particular, /etc/group. There have been occasions when the installation part of - make world has expected certain usernames or groups to - exist. When performing an upgrade it is likely that these groups did - not exist. This caused problems when upgrading. + make world has expected certain usernames or groups + to exist. When performing an upgrade it is likely that these + groups did not exist. This caused problems when upgrading. The most recent example of this is when the ppp - subsystem were installed using a non-existent (for them) group - name. - - The solution is to examine /usr/src/etc/group - and compare its list of groups with your own. If they are any groups - in the new file that are not in your file then copy them over. - Similarly, you should rename any groups in - /etc/group which have the same GID but a - different name to those in + (later renamed ppp subsystem were installed using a + non-existent (for them) group name. + + The solution is to examine + /usr/src/etc/group and compare its list of + groups with your own. If they are any groups in the new file that + are not in your file then copy them over. Similarly, you should + rename any groups in /etc/group which have + the same GID but a different name to those in /usr/src/etc/group. If you are feeling particularly paranoid, you can check your - system to see which files are owned by the group you are renaming or - deleting. + system to see which files are owned by the group you are + renaming or deleting. &prompt.root; find / -group GID -print - will show all files owned by group GID - (which can be either a group name or a numeric group ID). + will show all files owned by group + GID (which can be either a group name + or a numeric group ID). - + You may want to compile the system in single user mode. Apart from the obvious benefit of making things go slightly faster, - reinstalling the system will touch a lot of important system files, - all the standard system binaries, libraries, include files and so on. - Changing these on a running system (particularly if you have active - users on their at the time) is asking for trouble.</para> + reinstalling the system will touch a lot of important system + files, all the standard system binaries, libraries, include files + and so on. Changing these on a running system (particularly if + you have active users on their at the time) is asking for + trouble.</para> + + <para>That said, if you are confident, you can omit this + step.</para> - <para>That said, if you are confident, you can omit this step.</para> - <note> <title>Version 2.2.5 and above - As described in more detail below, versions 2.2.5 and above of - FreeBSD have separated the building process from the installing - process. You can therefore build the new - system in multi user mode, and then drop to single user mode to do - the installation. + As described in more detail below, versions 2.2.5 and above + of FreeBSD have separated the building process from the + installing process. You can therefore + build the new system in multi-user mode, + and then drop to single user mode to do the installation. - - As the superuser, you can execute - &prompt.root; + As the superuser, you can execute - from a running system, which will drop it to single user mode. - - Alternatively, reboot the system, and at the boot prompt, enter - the flag. The system will then boot single user. - At the shell prompt you should then run: + &prompt.root; + + from a running system, which will drop it to single user + mode. + + Alternatively, reboot the system, and at the boot prompt, + enter the flag. The system will then boot + single user. At the shell prompt you should then run: &prompt.root; fsck -p &prompt.root; mount -u / &prompt.root; mount -a -t ufs &prompt.root; swapon -a This checks the filesystems, remounts / read/write, mounts all the other UFS filesystems referenced in /etc/fstab and then turns swapping on. - + Remove <filename>/usr/obj</filename> - - As parts of the system are rebuilt they are placed in directories - which (by default) go under /usr/obj. The - directories shadow those under /usr/src. - + + As parts of the system are rebuilt they are placed in + directories which (by default) go under + /usr/obj. The directories shadow those under + /usr/src. + You can speed up the make world process, and possibly save yourself some dependency headaches by removing this directory as well. Some files below /usr/obj will have the - immutable flag set (see &man.chflags.1; for more - information) which must be removed first. + immutable flag set (see &man.chflags.1; for more information) + which must be removed first. &prompt.root; cd /usr/obj &prompt.root; chflags -R noschg * &prompt.root; rm -rf * <title>All versions - You must be in the /usr/src directory, so + You must be in the /usr/src + directory... + + &prompt.root; cd /usr/src + + (unless, of course, your source code is elsewhere, in which + case change to that directory instead). - &prompt.root; cd /usr/src - - (unless, of course, your source code is elsewhere, in which case - change to that directory instead). - To rebuild the world you use the &man.make.1; command. This - command reads instructions from the Makefile - which describes how the programs that comprise FreeBSD should be - rebuilt, the order they should be built in, and so on. + command reads instructions from the + Makefile which describes how the programs + that comprise FreeBSD should be rebuilt, the order they should + be built in, and so on. The general format of the command line you will type is as - follows; + follows: &prompt.root; make In this example, - is an option that you would pass to &man.make.1;. See the manual - page for an example of the options you can pass. + is an option that you would pass to &man.make.1;. See the + &man.make.1; manual page for an example of the options you can + pass. - passes a - variable to the Makefile. The behaviour of the - Makefile is controlled by these variables. - These are the same variables as are set in - /etc/make.conf, and this provides another way - of setting them. + + passes a variable to the Makefile. The + behavior of the Makefile is controlled by + these variables. These are the same variables as are set in + /etc/make.conf, and this provides another + way of setting them. &prompt.root; make -DNOPROFILE=true target - - is another way of specifying that profiled libaries should not be - built, and corresponds with the - NOPROFILE= true + is another way of specifying that profiled libaries should + not be built, and corresponds with the + + NOPROFILE= true # Avoid compiling profiled libraries - lines in /etc/make.conf. + lines in /etc/make.conf. - target tells &man.make.1; what you - want to do. Each Makefile defines a number of - different targets, and your choice of target - determines what happens. + target tells &man.make.1; what + you want to do. Each Makefile defines a + number of different targets, and your choice of + target determines what happens. - Some targets are listed in the Makefile, - but are not meant for you to run. Instead, they are used by the - build process to break out the steps necessary to rebuild the system - into a number of sub-steps. + Some targets are listed in the + Makefile, but are not meant for you to run. + Instead, they are used by the build process to break out the + steps necessary to rebuild the system into a number of + sub-steps. Most of the time you won't need to pass any parameters to - &man.make.1;, and so your command like will look like this. + &man.make.1;, and so your command like will look like + this: &prompt.root; make target Saving the output It's a good idea to save the output you get from running - &man.make.1; to another file. If something goes wrong you will - have a copy of the error message, and a complete list of where the - process had got to. While this might not help you in diagnosing - what has gone wrong, it can help others if you post your problem to - one of the FreeBSD mailing lists. - - The easiest way to do this is to use the &man.script.1; command, - with a parameter that specifies the name of the file to save all - output to. You would do this immediately before remaking the world, - and then type exit when the process has - finished. + &man.make.1; to another file. If something goes wrong you will + have a copy of the error message, and a complete list of where + the process had got to. While this might not help you in + diagnosing what has gone wrong, it can help others if you post + your problem to one of the FreeBSD mailing lists. + + The easiest way to do this is to use the &man.script.1; + command, with a parameter that specifies the name of the file to + save all output to. You would do this immediately before + remaking the world, and then type exit + when the process has finished. &prompt.root; script /var/tmp/mw.out Script started, output file is /var/tmp/mw.out &prompt.root; make world … compile, compile, compile … &prompt.root; exit Script done, … - If you do this, do not save the output in - /tmp. This directory may be cleared next time - you reboot. A better place to store it is in - /var/tmp (as in the previous example) or in - root's home directory. + If you do this, do not save the output + in /tmp. This directory may be cleared + next time you reboot. A better place to store it is in + /var/tmp (as in the previous example) or + in root's home directory. - + Version 2.2.2 and below /usr/src/Makefile contains the - world target, which will rebuild the entire - system and then install it. + world target, which will rebuild the + entire system and then install it. + + Use it like this: - Use it like this. - &prompt.root; make world Version 2.2.5 and above - Beginning with version 2.2.5 of FreeBSD (actually, it was first - created on the -current branch, and then retrofitted to -stable - midway between 2.2.2 and 2.2.5) the world - target has been split in two. buildworld - and installworld. + Beginning with version 2.2.5 of FreeBSD (actually, it was + first created on the -CURRENT branch, and then retrofitted to + -STABLE midway between 2.2.2 and 2.2.5) the + world target has been split in + two. buildworld and + installworld. - As the names imply, buildworld builds a - complete new tree under /usr/obj, and - installworld installs this tree on the - current machine. + As the names imply, buildworld + builds a complete new tree under /usr/obj, + and installworld installs this tree on + the current machine. This is very useful for 2 reasons. First, it allows you to do the build safe in the knowledge that no components of your running system will be affected. The build is self hosted. Because of this, you can safely run buildworld on a machine running in multi-user mode with no fear of ill-effects. I still recommend you run the installworld part in single user mode though. - Secondly, it allows you to use NFS mounts to upgrade multiple - machines on your network. If you have three machines, A, B and C - that you want to upgrade, run make buildworld and - make installworld on A. B and C should then NFS - mount /usr/src and - /usr/obj from A, and you can then run - make installworld to install the results of the - build on B and C. - - The world target still exists, and you - can use it exactly as shown for version 2.2.2. make - world runs make buildworld followed - by make installworld. + Secondly, it allows you to use NFS mounts to upgrade + multiple machines on your network. If you have three machines, + A, B and C that you want to upgrade, run make + buildworld and make installworld on + A. B and C should then NFS mount /usr/src + and /usr/obj from A, and you can then run + make installworld to install the results of + the build on B and C. + + The world target still exists, and + you can use it exactly as shown for version 2.2.2. + make world runs make + buildworld followed by make + installworld. - If you do the make buildworld and - make installworld commands separately, you must - pass the same parameters to &man.make.1; each time. + If you do the make buildworld and + make installworld commands separately, you + must pass the same parameters to &man.make.1; each + time. - If you run + If you run: - &prompt.root; make -DNOPROFILE=true buildworld + &prompt.root; make -DNOPROFILE=true buildworld - you must install the results with + you must install the results with: - &prompt.root; make -DNOPROFILE=true installworld + &prompt.root; make -DNOPROFILE=true installworld - otherwise it would try and install profiled libraries that had not - been built during the make buildworld + otherwise it would try and install profiled libraries that + had not been built during the make buildworld phase. - -current and above + -CURRENT and above - If you are tracking -current you can also pass the + If you are tracking -CURRENT you can also pass the option to make. This lets make spawn several simultaneous processes. This is most useful on true multi-CPU machines. However, since much of the compiling process is IO bound rather than CPU bound it is also useful on single CPU machines. On a typical single-CPU machine you would run: &prompt.root; make -j4 target &man.make.1; will then have up to 4 processes running at any one time. Empirical evidence posted to the mailing lists shows this generally gives the best performance benefit. If you have a multi-CPU machine and you are using an SMP configured kernel try values between 6 and 10 and see how they speed things up. Be aware that (at the time of writing) this is still experimental, and commits to the source tree may occasionally break this feature. If the world fails to compile using this parameter try again without it before you report any problems. Timings Assuming everything goes well you have anywhere between an hour and a half and a day or so to wait. As a general rule of thumb, a 200MHz P6 with more than 32MB of RAM and reasonable SCSI disks will complete make world in about an hour and a half. A 32MB P133 will take 5 or 6 hours. Revise these figures down if your machines are slower… Update <filename>/etc</filename> Remaking the world will not update certain directories (in particular, /etc, /var and /usr) with new or changed configuration files. This is something you have to do by hand, eyeball, and judicious use of &man.diff.1;. You cannot just copy over the files from /usr/src/etc to /etc and have it work. Some of these files must be installed first. This is because the /usr/src/etc directory is not a copy of what your /etc directory should look like. In addition, there are files that should be in /etc that are not in /usr/src/etc. The simplest way to do this is to install the files into a new directory, and then work through them looking for differences. Backup your existing <filename>/etc</filename> Although, in theory, nothing is going to touch this directory automatically, it is always better to be sure. So copy your existing /etc directory somewhere safe. Something like: &prompt.root; cp -Rp /etc /etc.old does a recursive copy, preserves times, ownerships on files and suchlike. You need to build a dummy set of directories to install the new /etc and other files into. I generally choose to put this dummy directory in /var/tmp/root, and there are a number of subdirectories required under this as well. &prompt.root; mkdir /var/tmp/root &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distribution This will build the necessary directory structure and install the files. A lot of the subdirectories that have been created under /var/tmp/root are empty and should be deleted. The simplest way to do this is to: &prompt.root; cd /var/tmp/root &prompt.root; find -d . -type d | /usr/bin/perl -lne \ 'opendir(D,$_);@f=readdir(D);rmdir if $#f == 1;closedir(D);' This does a depth first search, examines each directory, and if the number of files in that directory is 2 ( /var/tmp/root now contains all the files that should be placed in appropriate locations below /. You now have to go through each of these files, determining how they differ with your existing files. Note that some of the files that will have been installed in /var/tmp/root have a leading /var/tmp/root/ and /var/tmp/root/root/, although there may be others (depending on when you are reading this. Make sure you use The simplest way to do this is to use &man.diff.1; to compare the two files. &prompt.root; diff /etc/shells /var/tmp/root/etc/shells This will show you the differences between your /etc/shells file and the new /etc/shells file. Use these to decide whether to merge in changes that you have made or whether to copy over your old file. Name the new root directory (<filename>/var/tmp/root</filename>)with a timestamp, so you can easily compare differences between versions Frequently remaking the world means that you have to update /etc frequently as well, which can be a bit of a chore. You can speed this process up by keeping a copy of the last set of changed files that you merged into /etc. The following procedure gives one idea of how to do this. Make the world as normal. When you want to update /etc and the other directories, give the target directory a name based on the current date. If you were doing this on the 14th of February 1998 you could do the following. &prompt.root; mkdir /var/tmp/root-19980214 &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root-19980214 \ distrib-dirs distribution Merge in the changes from this directory as outlined above. Do not remove the /var/tmp/root-19980214 directory when you have finished. When you have downloaded the latest version of the source and remade it, follow step 1. This will give you a new directory, which might be called /var/tmp/root-19980221 (if you wait a week between doing updates). You can now see the differences that have been made in the intervening week using &man.diff.1; to create a recursive diff between the two directories. &prompt.root; cd /var/tmp &prompt.root; diff -r root-19980214 root-19980221 Typically, this will be a much smaller set of differences than those between /var/tmp/root-19980221/etc and /etc. Because the set of differences is smaller, it is easier to migrate those changes across into your /etc directory. You can now remove the older of the two /var/tmp/root-* directories. &prompt.root; rm -rf /var/tmp/root-19980214 Repeat this process every time you need to merge in changes to /etc. You can use &man.date.1; to automate the generation of the directory names. &prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"` Update <filename>/dev</filename> DEVFS If you are using DEVFS then this is probably unnecessary. For safety's sake, this is a multistep process. Copy /var/tmp/root/dev/MAKEDEV to /dev. &prompt.root; cp /var/tmp/root/dev/MAKEDEV /dev Now, take a snapshot of your current /dev. This snapshot needs to contain the permissions, ownerships, major and minor numbers of each filename, but it should not contain the timestamps. The easiest way to do this is to use &man.awk.1; to strip out some of the information. &prompt.root; cd /dev &prompt.root; ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out Remake all the devices. &prompt.root; Write another snapshot of the directory, this time to /var/tmp/dev2.out. Now look through these two files for any devices that you missed creating. There should not be any, but it is better to be safe than sorry. &prompt.root; diff /var/tmp/dev.out /var/tmp/dev2.out You are most likely to notice disk slice discrepancies which will involve commands such as &prompt.root; sh MAKEDEV sd0s1 to recreate the slice entries. Your precise circumstances may vary. Update <filename>/stand</filename> This step is included only for completeness, it can safely be omitted. For completenesses sake you may want to update the files in /stand as well. These files consist of hard links to the /stand/sysinstall binary. This binary should be statically linked, so that it can work when no other filesystems (and in particular /usr) have been mounted. &prompt.root; cd /usr/src/release/sysinstall &prompt.root; make all install Source older than 2 April 1998 If your source code is older than 2nd April 1998, or the Makefile version is not 1.68 or higher (for - FreeBSD current and 3.x systems) or 1.48.2.21 or higher (for 2.2.x + FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X systems) you will need to add the NOSHARED=yes option, like so; &prompt.root; make NOSHARED=yes all install Compile and install a new kernel To take full advantage of your new system you should recompile the kernel. This is practically a necessity, as certain memory structures may have changed, and programs like &man.ps.1; and &man.top.1; will fail to work until the kernel and source code versions are the same. Follow the handbook instructions for compiling a new kernel. If you have previously built a custom kernel then carefully examine the LINT config file to see if there are any new options which you should take advantage of. A previous version of this document suggested rebooting before rebuilding the kernel. This is wrong because: Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8; may fail. This could leave your machine unable to connect to the network. Basic utilities like &man.mount.8; could fail, making it impossible to mount /, /usr and so on. This is unlikely if you are - tracking a -stable candidate, but more likely if you are tracking - -current during a large merge. + tracking a -STABLE candidate, but more likely if you are tracking + -CURRENT during a large merge. - Loadable kernel modules (LKMs on pre-3.x systems, KLDs on 3.x + Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X systems and above) built as part of the world may crash an older kernel. For these reasons, it is always best to rebuild and install a new kernel before rebooting. You should build your new kernel after you have completed make world (or make installworld). If you do not want to do this (perhaps you want to confirm that the kernel builds before updating your system) you may have problems. These may be because your &man.config.8; command is out of date with respect to your kernel sources. In this case you could build your kernel with the new version of &man.config.8; &prompt.root; /usr/obj/usr/src/usr.sbin/config/config KERNELNAME This may not work in all cases. It is recommended that you complete make world (or make installworld) before compiling a new kernel. You are now done. After you have verified that everything appears to be in the right place you can reboot the system. A simple &man.fastboot.8; should do it.</para> <screen>&prompt.root; <userinput>fastboot</userinput></screen> </sect2> <sect2> <title>Finished You should now have successfully upgraded your FreeBSD system. Congratulations. You may notice small problems due to things that you have missed. For example, I once deleted /etc/magic as part of the upgrade and merge to /etc, and the file command stopped working. A moment's thought meant that &prompt.root; cd /usr/src/usr.bin/file &prompt.root; was sufficient to fix that one. <qandaentry> <question> <para>Do I need to re-make the world for every change?</para> </question> <answer> <para>There is no easy answer to this one, as it depends on the nature of the change. For example, I have just run CVSup, and it has shown the following files as being updated since I last ran it;</para> <screen><filename>src/games/cribbage/instr.c</filename> <filename>src/games/sail/pl_main.c</filename> <filename>src/release/sysinstall/config.c</filename> <filename>src/release/sysinstall/media.c</filename> <filename>src/share/mk/bsd.port.mk</filename></screen> <para>There is nothing in there that I would re-make the world for. I would go to the appropriate sub-directories and <command>make all install</command>, and that's about it. But if something major changed, for example <filename>src/lib/libc/stdlib</filename> then I would either re-make the world, or at least those parts of it that are statically linked (as well as anything else I might have added that is statically linked).</para> <para>At the end of the day, it is your call. You might be happy re-making the world every fortnight say, and let changes accumulate over that fortnight. Or you might want to re-make just those things that have changed, and are confident you can spot all the dependencies.</para> <para>And, of course, this all depends on how often you want to - upgrade, and whether you are tracking -stable or - -current.</para> + upgrade, and whether you are tracking -STABLE or + -CURRENT.</para> </answer> </qandaentry> <qandaentry> <question> <para>My compile failed with lots of signal 12 (or other signal number) errors. What has happened?</para> </question> <answer> <para>This is normally indicative of hardware problems. (Re)making the world is an effective way to stress test your hardware, and will frequently throw up memory problems. These normally manifest themselves as the compiler mysteriously dying on receipt of strange signals.</para> <para>A sure indicator of this is if you can restart the make and it dies at a different point in the process.</para> <para>In this instance there is little you can do except start swapping around the components in your machine to determine which one is failing.</para> </answer> </qandaentry> <qandaentry> <question> <para>Can I remove <filename>/usr/obj</filename> when I have finished?</para> </question> <answer> <para>That depends on how you want to make the world on future occasions.</para> <para><filename>/usr/obj</filename> contains all the object files that were produced during the compilation phase. Normally, one of the first steps in the <quote/make world/ process is to remove this directory and start afresh. In this case, keeping <filename>/usr/obj</filename> around after you have finished makes little sense, and will free up a large chunk of disk space (currently about 150MB).</para> <para>However, if you know what you are doing you can have <quote/make world/ skip this step. This will make subsequent builds run much faster, since most of sources will not need to be recompiled. The flip side of this is that subtle dependency problems can creep in, causing your build to fail in odd ways. This frequently generates noise on the FreeBSD mailing lists, when one person complains that their build has failed, not realising that it is because they have tried to cut corners.</para> <para>If you want to live dangerously then make the world, passing the <makevar>NOCLEAN</makevar> definition to make, like this:</para> <screen>&prompt.root; <userinput>make -DNOCLEAN world</userinput></screen> </answer> </qandaentry> <qandaentry> <question> <para>Can interrupted builds be resumed?</para> </question> <answer> <para>This depends on how far through the process you got before you found a problem.</para> <para><emphasis>In general</emphasis> (and this is not a hard and fast rule) the <quote>make world</quote> process builds new copies of essential tools (such as &man.gcc.1;, and &man.make.1;>) and the system libraries. These tools and libraries are then installed. The new tools and libraries are then used to rebuild themselves, and are installed again. The entire system (now including regular user programs, such as &man.ls.1; or &man.grep.1;) is then rebuilt with the new system files.</para> <para>If you are at the last state, and you know it (because you have looked through the output that you were storing) then you can (fairly safely) do</para> <screen><emphasis>… fix the problem …</emphasis> &prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make -DNOCLEAN all</userinput></screen> <para>This will not undo the work of the previous <quote>make world</quote>.</para> <para>If you see the message <screen>-------------------------------------------------------------- Building everything.. --------------------------------------------------------------</screen> in the <quote>make world</quote> output then it is probably fairly safe to do so.</para> <para>If you do not see that message, or you are not sure, then it is always better to be safe than sorry, and restart the build from scratch.</para> </answer> </qandaentry> <qandaentry> <question> <para>Can I use one machine as a <emphasis/master/ to upgrade lots of machines (NFS)?</para> </question> <answer> <para>People often ask on the FreeBSD mailing lists whether they can do all the compiling on one machine, and then use the results of that compile to <command>make install</command> on to other machines around the network.</para> <para>This is not something I have done, so the suggestions below are either from other people, or deduced from the Makefiles.</para> <para>The precise approach to take depends on your version of FreeBSD</para> <para>You must still upgrade <filename>/etc</filename> and <filename>/dev</filename> on the target machines after doing this.</para> <para>For 2.1.7 and below, Antonio Bemfica suggested the following approach:</para> <screen>Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST) From: Antonio Bemfica <bemfica@militzer.me.tuns.ca> -To: freebsd-questions@freebsd.org +To: freebsd-questions@FreeBSD.org Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca> Josef Karthauser asked: > Has anybody got a good method for upgrading machines on a network First make world, etc. on your main machine Second, mount / and /usr from the remote machine: main_machine% mount remote_machine:/ /mnt main_machine% mount remote_machine:/usr /mnt/usr Third, do a 'make install' with /mnt as the destination: main_machine% make install DESTDIR=/mnt Repeat for every other remote machine on your network. It works fine for me. Antonio</screen> <para>This mechanism will only work (to the best of my knowledge) if you can write to <filename>/usr/src</filename> on the NFS server, as the <maketarget>install</maketarget> target in 2.1.7 and below needed to do this.</para> <para>Midway between 2.1.7 and 2.2.0 the <quote>reinstall</quote> target was committed. You can use the approach exactly as outlined above for 2.1.7, but use <quote>reinstall</quote> instead of <quote>install</quote>.</para> <para>This approach <emphasis>does not</emphasis> require write access to the <filename>/usr/src</filename> directory on the NFS server.</para> <para>There was a bug introduced in this target between versions 1.68 and 1.107 of the Makefile, which meant that write access to the NFS server <emphasis>was</emphasis> required. This bug was fixed before version 2.2.0 of FreeBSD was released, but may be an - issue of you have an old server still running -stable from this + issue of you have an old server still running -STABLE from this era.</para> <para>For version 2.2.5 and above, you can use the <quote>buildworld</quote> and <quote>installworld</quote> targets. Use them to build a source tree on one machine, and then NFS mount <filename>/usr/src</filename> and <filename>/usr/obj</filename> on the remote machine and install it there.</para> </answer> </qandaentry> <qandaentry> <question> <para>How can I speed up making the world?</para> <itemizedlist> <listitem> <para>Run in single user mode.</para> </listitem> <listitem> <para>Put the <filename>/usr/src</filename> and <filename>/usr/obj</filename> directories on separate filesystems held on separate disks. If possible, put these disks on separate disk controllers.</para> </listitem> <listitem> <para>Better still, put these filesystems across separate disks using the <quote>ccd</quote> (concatenated disk driver) device.</para> </listitem> <listitem> <para>Turn off profiling (set <quote>NOPROFILE=true</quote> in <filename>/etc/make.conf</filename>). You almost certainly do not need it.</para> </listitem> <listitem> <para>Also in <filename>/etc/make.conf</filename>, set <quote>CFLAGS</quote> to something like <quote>-O -pipe</quote>. The optimisation <quote>-O2</quote> is much slower, and the optimisation difference between <quote>-O</quote> and <quote>-O2</quote> is normally negligible. <quote>-pipe</quote> lets the compiler use pipes rather than temporary files for communication, which saves disk access (at the expense of memory).</para> </listitem> <listitem> <para>Pass the <option>-j<n></option> option to make (if you are running a sufficiently recent version of FreeBSD) to run multiple processes in parallel. This helps regardless of whether you have a single or a multi processor machine.</para> </listitem> <listitem><para>The filesystem holding <filename>/usr/src</filename> can be mounted (or remounted) with the <quote>noatime</quote> option. This stops the time files in the filesystem were last accessed from being written to the disk. You probably do not need this information anyway. <note> <para><quote>noatime</quote> is in version 2.2.0 and above.</para> </note> <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> <warning> <para>The example assumes <filename>/usr/src</filename> is on its own filesystem. If it is not (if it is a part of <filename>/usr</filename> for example) then you will need to use that filesystem mount point, and not <filename>/usr/src</filename>.</para> </warning> </para> </listitem> <listitem> <para>The filesystem holding <filename>/usr/obj</filename> can be mounted (or remounted) with the <quote>async</quote> option. This causes disk writes to happen asynchronously. In other words, the write completes immediately, and the data is written to the disk a few seconds later. This allows writes to be clustered together, and can be a dramatic performance boost.</para> <warning> <para>Keep in mind that this option makes your filesystem more fragile. With this option there is an increased chance that, should power fail, the filesystem will be in an unrecoverable state when the machine restarts.</para> <para>If <filename>/usr/obj</filename> is the only thing on this filesystem then it is not a problem. If you have other, valuable data on the same filesystem then ensure your backups are fresh before you enable this option.</para> </warning> <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> <warning> <para>As above, if <filename>/usr/obj</filename> is not on its own filesystem, replace it in the example with the name of the appropriate mount point.</para> </warning> </listitem> </itemizedlist> </question> </qandaentry> </qandaset> </sect2> - - <sect2> - <title>Contributors - - The following people have contributed to this document in some - form or another. Either by directly suggesting alterations and - improvements, pointing out errors, or by their messages to the FreeBSD - mailing lists, from which I have shamelessly cribbed information. My - thanks to them. - - - - Antonio Bemfica, - bemfica@militzer.me.tuns.ca - - - - Sue Blake, sue@welearn.com.au - - - - Brian Haskin, haskin@ptway.com - - - - Kees Jan Koster, kjk1@ukc.ac.uk - - - - A Joseph Kosy, koshy@india.hp.com - - - - Greg Lehey, grog@lemis.com - - - - Wes Peters, softweyr@xmission.com - - - - Joseph Stein, joes@wstein.com - - - - Studded, studded@dal.net - - - - Axel Thimm, - Axel.Thimm@physik.fu-berlin.de - - - - Matthew Thyer, - Matthew.Thyer@dsto.defence.gov.au - - -