diff options
Diffstat (limited to 'en/handbook/cutting-edge/chapter.sgml')
| -rw-r--r-- | en/handbook/cutting-edge/chapter.sgml | 2528 |
1 files changed, 0 insertions, 2528 deletions
diff --git a/en/handbook/cutting-edge/chapter.sgml b/en/handbook/cutting-edge/chapter.sgml deleted file mode 100644 index e06beb5775..0000000000 --- a/en/handbook/cutting-edge/chapter.sgml +++ /dev/null @@ -1,2528 +0,0 @@ - <chapter id="cutting-edge"> - <title>The Cutting Edge: FreeBSD-current and FreeBSD-stable</title> - - <para>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.</para> - - - <sect1 id="current"> - <title>Staying Current with FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - - <sect2> - <title>What is FreeBSD-current?</title> - - <para>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!</para> - - </sect2> - - <sect2> - <title>Who needs FreeBSD-current?</title> - - <para>FreeBSD-current is made generally available for 3 primary - interest groups:</para> - - <orderedlist> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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 - <emphasis>reading</emphasis>, not running). These people - also make the occasional comment or contribute code.</para> - </listitem> - - </orderedlist> - - </sect2> - - <sect2> - <title>What is FreeBSD-current <emphasis>not</emphasis>?</title> - - - <orderedlist> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>A quick way of getting bug fixes.</para> - </listitem> - - <listitem> - <para>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 <emphasis>do not - have the time</emphasis> 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 <emphasis>and</emphasis> 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.</para> - </listitem> - - </orderedlist> - - - </sect2> - - <sect2> - <title>Using FreeBSD-current</title> - - - <orderedlist> - - <listitem> - <para>Join the &a.current; and the &a.cvsall; . This is not - just a good idea, it is <emphasis>essential</emphasis>. If - you are not on the <emphasis>FreeBSD-current</emphasis> - 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.</para> - - <para>The <email>cvs-all</email> 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.</para> - - <para>To join these lists, send mail to - &a.majordomo; and specify: - - <programlisting> -subscribe freebsd-current -subscribe cvs-all</programlisting> - - in the - body of your message. Optionally, you can also say <literal>help</literal> - and Majordomo will send you full help on how to subscribe - and unsubscribe to the various other mailing lists we - support.</para> - </listitem> - - <listitem> - <para>Grab the sources from <hostid role="fqdn">ftp.FreeBSD.ORG</hostid>. You can do - this in three ways:</para> - - <orderedlist> - - <listitem> - <para>Use the <application><link linkend="ctm">CTM</link></application> - facility. Unless you have a good TCP/IP connection - at a flat rate, this is the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> - program with <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this supfile</ulink>. 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:</para> - - - <screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</userinput></screen> - - - - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for FreeBSD-current is - always “exported” on: <ulink - URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current</ulink> We also use <command>wu-ftpd</command> which allows compressed/tar'd grabbing of whole trees. e.g. you see:</para> - - - <screen>usr.bin/lex</screen> - - - <para>You can do: - - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar.Z</userinput></screen> - - - and it will get the whole directory for you as a compressed tar file.</para> - </listitem> - - </orderedlist> - - - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the - source and communications bandwidth is not a consideration, - use <command>cvsup</command> or <command>ftp</command>. Otherwise, use <application>CTM</application>.</para> - - <para>If you are grabbing the sources to run, and not just - look at, then grab <emphasis>all</emphasis> 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.</para> - - <para>Before compiling current, read the Makefile in - <filename>/usr/src</filename> carefully. You should at - least run a <link - linkend="makeworld">make world</link> 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.</para> - </listitem> - - <listitem> - <para>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!</para> - </listitem> - - </orderedlist> - - </sect2> - </sect1> - - <sect1 id="stable"> - <title>Staying Stable with FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - - <sect2> - <title>What is FreeBSD-stable?</title> - - <para>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 <link linkend="current">FreeBSD-current</link>).</para> - - </sect2> - - <sect2> - <title>Who needs FreeBSD-stable?</title> - - <para>If you are a commercial user or someone who puts maximum - stability of their FreeBSD system before all other concerns, you - should consider tracking <emphasis>stable</emphasis>. This is - especially true if you have installed the most recent release - (<ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/&rel.current;-RELEASE">&rel.current;-RELEASE</ulink> at the time of this writing) since the <emphasis>stable</emphasis> branch is effectively a bug-fix stream relative to the previous release.</para> - - <warning> - <para>The <emphasis>stable</emphasis> 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 <emphasis>current</emphasis> before - bringing them into <emphasis>stable</emphasis>, but sometimes - our tests fail to catch every case. If something breaks for you - in <emphasis>stable</emphasis>, please let us know - <emphasis>immediately!</emphasis> (see next section).</para> - </warning> - </sect2> - - <sect2> - <title>Using FreeBSD-stable</title> - - - <orderedlist> - - <listitem> - <para>Join the &a.stable; . This will keep you informed of - build-dependencies that may appear in - <emphasis>stable</emphasis> 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.</para> - - <para>The <email>cvs-all</email> 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.</para> - - <para>To join these lists, send mail to - &a.majordomo; and specify: - - <programlisting> -subscribe freebsd-stable -subscribe cvs-all</programlisting> - - in the - body of your message. Optionally, you can also say <literal>help</literal> - and Majordomo will send you full help on how to subscribe - and unsubscribe to the various other mailing lists we - support.</para> - </listitem> - - <listitem> - <para>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 <ulink - url="ftp://releng22.freebsd.org/pub/FreeBSD/">ftp://releng22.freebsd.org/pub/FreeBSD/</ulink> and install it like any other release.</para> - - <para>If you are already running a previous release of 2.2 and wish - to upgrade via sources then you can easily do so from <hostid - role="fqdn">ftp.FreeBSD.ORG</hostid>. This can be done in one of - three ways:</para> - - <orderedlist> - - <listitem> - <para>Use the <application><link linkend="ctm">CTM</link></application> - facility. Unless you have a good TCP/IP connection - at a flat rate, this is the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> - program with <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. 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;</para> - - - <screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</userinput></screen> - - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for FreeBSD-stable is - always “exported” on: <ulink - URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable</ulink></para> - - <para>We also use <command>wu-ftpd</command> which allows - compressed/tar'd grabbing of whole trees. e.g. you - see:</para> - - - <screen>usr.bin/lex</screen> - - - <para>You can do: - - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar.Z</userinput></screen> - - - and it will get the - whole directory for you as a compressed tar - file.</para> - </listitem> - - </orderedlist> - - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the - source and communications bandwidth is not a consideration, - use <command>cvsup</command> or <command>ftp</command>. Otherwise, use <application>CTM</application>.</para> - </listitem> - - <listitem> - <para>Before compiling stable, read the Makefile in - <filename>/usr/src</filename> carefully. You should at - least run a <link - linkend="makeworld">make world</link> 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.</para> - </listitem> - - </orderedlist> - - - - </sect2> - </sect1> - - <sect1 id="synching"> - <title>Synchronizing Source Trees over the Internet</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>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 <link linkend="anoncvs">Anonymous - CVS</link>, <link linkend="cvsup">CVSup</link>, and - <link linkend="ctm">CTM</link>.</para> - - <para><application>Anonymous CVS</application> and <application>CVSup</application> use the - <emphasis>pull</emphasis> model of updating sources. In the case of - <application>CVSup</application> the user (or a cron - script) invokes the <command>cvsup</command> program, and - it interacts with a <command>cvsupd</command> 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. <application>Anonymous CVS</application> is quite a bit more simplistic - than CVSup in that it's just an extension to - <application>CVS</application> which allows it to pull changes - directly from a remote CVS - repository. <application>CVSup</application> can do this far more - efficiently, but <application>Anonymous CVS</application> is easier to - use.</para> - - <para><application>CTM</application>, 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 <citerefentry><refentrytitle>ctm_rmail</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 <application>CVSup</application>, and places less strain on - our server resources since it is a <emphasis>push</emphasis> rather - than a <emphasis>pull</emphasis> model.</para> - - <para>There are other trade-offs, of course. If you inadvertently - wipe out portions of your archive, <application>CVSup</application> will detect and rebuild the - damaged portions for you. <application>CTM</application> 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.</para> - - <para>For more information on <application>Anonymous CVS</application>, <application>CTM</application>, and <application>CVSup</application>, please see one of the - following sections:</para> - - <sect2 id="anoncvs"> - <title>Anonymous CVS</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis></para> - - <sect3> - <title><anchor id="anoncvs-intro">Introduction</title> - - <para>Anonymous CVS (or, as it is otherwise known, - <emphasis>anoncvs</emphasis>) 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 <envar>CVSROOT</envar> environment - variable to point at the appropriate anoncvs server and then uses - the <citerefentry> - <refentrytitle>cvs</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> command to access it like any local - repository.</para> - - <para>While it can also be said that the <link - linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis> - 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, - <application>CVSup</application> 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 - <application>CVSup</application>, a special client must first be - installed and configured before any bits can be grabbed, and then - only in the fairly large chunks which - <application>CVSup</application> calls - <emphasis>collections</emphasis>.</para> - - <para><application>Anoncvs</application>, by contrast, can be used - to examine anything from an individual file to a specific program - (like <command>ls</command> or <command>grep</command>) by - referencing the CVS module name. Of course, - <application>anoncvs</application> 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 <application>CVSup</application> is - really your only option.</para> - </sect3> - - <sect3> - <title><anchor id="anoncvs-usage">Using Anonymous CVS</title> - - <para>Configuring <citerefentry> - <refentrytitle>cvs</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> to use an Anonymous CVS repository is a simple - matter of setting the <envar>CVSROOT</envar> environment variable - to point to one of the FreeBSD project's - <emphasis>anoncvs</emphasis> servers. At the time of this writing, - the following servers are available:</para> - - <itemizedlist> - <listitem> - <para><emphasis>USA</emphasis>: - anoncvs@anoncvs.freebsd.org:/cvs</para> - </listitem> - </itemizedlist> - - <para>Since CVS allows one to “check out” virtually any - version of the FreeBSD sources that ever existed (or, in some - cases, will exist <!-- smiley -->:), you need to be familiar with - the revision (<option>-r</option>) flag to <citerefentry> - <refentrytitle>cvs</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> and what some of the permissible values for it in - the FreeBSD Project repository are.</para> - - <para>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.</para> - - <para>Here are the branch tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - <term>HEAD</term> - - <listitem> - <para>Symbolic name for the main line, or FreeBSD-current. - Also the default when no revision is - specified.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.x, also known as - 2.2-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_0</term> - - <listitem> - <para>The line of development for FreeBSD-2.1.x - this branch - is largely obsolete. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here are the revision tags that users might be interested - in:</para> - - <variablelist> - <varlistentry> - <term>RELENG_2_2_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.6. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.7. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_6_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6.1. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.5. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.0. Not valid for the ports - collection.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>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 <option>-D date</option> flag. See the <citerefentry> - <refentrytitle>cvs</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> man page for more details.</para> - </sect3> - - <sect3> - <title>Examples</title> - - <para>While it really is recommended that you read the manual page - for <citerefentry> - <refentrytitle>cvs</refentrytitle> - <manvolnum>1</manvolnum></citerefentry> thoroughly before doing - anything, here are some quick examples which essentially show how - to use Anonymous CVS:</para> - - <example> - <title>Checking out something from -current (<citerefentry> - <refentrytitle>ls</refentrytitle> - <manvolnum>1</manvolnum></citerefentry>) and deleting it - again:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs</userinput> -&prompt.user; <userinput>cvs co ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput></screen> - </example> - - <example> - <title>Checking out the version of ls(1) in the 2.2-stable - branch:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs</userinput> -&prompt.user; <userinput>cvs co -rRELENG_2_2 ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput></screen> - </example> - - <example> - <title>Creating a list of changes (as unidiffs) to <citerefentry> - <refentrytitle>ls</refentrytitle> - <manvolnum>1</manvolnum></citerefentry> between FreeBSD 2.2.2 - and FreeBSD 2.2.6:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs</userinput> -&prompt.user; <userinput>cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls</userinput></screen> - </example> - - <example> - <title>Finding out what other module names can be used:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.freebsd.org:/cvs</userinput> -&prompt.user; <userinput>cvs co modules</userinput> -&prompt.user; <userinput>more modules/modules</userinput> -&prompt.user; <userinput>cvs release -d modules</userinput></screen> - </example> - </sect3> - - <sect3> - <title>Other Resources</title> - - <para>The following additional resources may be helpful in learning - CVS:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.cyclic.com">Cyclic - Software</ulink>, commercial maintainers of CVS.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.freebsd.org/cgi/cvsweb.cgi">CVSWeb</ulink> - is the FreeBSD Project web interface for CVS.</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2 id="ctm"> - <title><application>CTM</application></title> - - <para><emphasis>Contributed by &a.phk;. Updated - 19-October-1997.</emphasis></para> - - <para><application>CTM</application> 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 <application>CTM</application> for other things.</para> - - - <sect3> - <title>Why should I use <application>CTM</application>?</title> - - <para><application>CTM</application> 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, <application>CTM</application> 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, - <application>CTM</application> 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.</para> - - <para>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 <link linkend="current">Staying current - with - FreeBSD</link>.</para> - - </sect3> - - <sect3> - <title>What do I need to use <application>CTM</application>?</title> - - <para>You will need two things: The <application>CTM</application> - program and the initial deltas to feed it (to get up to - “current” levels).</para> - - <para>The <application>CTM</application> program has been part of FreeBSD - ever since version 2.0 was released, and lives in - <filename>/usr/src/usr.sbin/CTM</filename> if - you have a copy of the source online.</para> - - <para>If you are running a pre-2.0 version of FreeBSD, you can - fetch the current <application>CTM</application> sources directly - from:</para> - - <para><ulink - 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</ulink></para> - - <para>The “deltas” you feed <application>CTM</application> 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 - <application>CTM</application>:</para> - - <para><ulink - URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/CTM">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/CTM</ulink></para> - - <para>or see section <link linkend="mirrors-ctm">mirrors</link>.</para> - - <para>FTP the relevant directory and fetch the - <filename>README</filename> file, starting from there.</para> - - <para>If you may wish to get your deltas via email:</para> - - <para>Send email to &a.majordomo; to subscribe to one of the - <application>CTM</application> 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 <literal>help</literal> — it will send you back usage - instructions.)</para> - - <para>When you begin receiving your <application>CTM</application> updates - in the mail, you may use the <command>ctm_rmail</command> program - to unpack and apply them. You can actually use the - <command>ctm_rmail</command> program directly from a entry in - <filename>/etc/aliases</filename> if you want to have the - process run in a fully automated fashion. Check the - <command>ctm_rmail</command> man page for more details.</para> - - <note> - <para>No matter what method you use to get the - <application>CTM</application> deltas, you should subscribe to the - <email>ctm-announce@FreeBSD.ORG</email> mailing list. In the - future, this will be the only place where announcements - concerning the operations of the <application>CTM</application> system - will be posted. Send an email to &a.majordomo; with a single - line of <literal>subscribe - ctm-announce</literal> to get added to the list.</para> - </note> - </sect3> - - <sect3> - <title>Starting off with <application>CTM</application> for the first - time</title> - - <para>Before you can start using <application>CTM</application> deltas, - you will need to get a to a starting point for the deltas - produced subsequently to it.</para> - - <para>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 - <application>CTM</application> 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.</para> - - <para>You can recognize -However, since the trees - are many tens of megabytes, you should prefer to start from - something already at hand. If you have a RELEASE CD, you can - copy or extract an initial source from it. This will save a - significant transfer of data.</para> - - <para>You can recognize these “starter” deltas by the - <literal>X</literal> appended to the number - (<filename>src-cur.3210XEmpty.gz</filename> for instance). The - designation following the <filename>X</filename> - corresponds to the origin of your initial “seed”. <filename>Empty</filename> is - an empty directory. As a rule a base transition from - <filename>Empty</filename> is produced - every 100 deltas. By the way, they are large! 25 to 30 - Megabytes of <command>gzip</command>'ed data is - common for the <filename>XEmpty</filename> deltas.</para> - - <para>Once you've picked a base delta to start from, you will also - need all deltas with higher numbers following it.</para> - - </sect3> - - <sect3> - <title>Using <application>CTM</application> in your daily life</title> - - <para>To apply the deltas, simply say:</para> - - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput> -&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen> - - - <para><application>CTM</application> understands deltas which have been - put through <command>gzip</command>, so you do not - need to gunzip them first, this saves disk space.</para> - - <para>Unless it feels very secure about the entire process, - <application>CTM</application> will not touch your tree. To verify a - delta you can also use the <option>-c</option> flag and - <application>CTM</application> 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.</para> - - <para>There are other options to <application>CTM</application> as well, - see the manual pages or look in the sources for more - information.</para> - - <para>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...</para> - - <para>That's really all there is to it. Every time you get a new - delta, just run it through <application>CTM</application> to keep your - sources up to date.</para> - - <para>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 - <command>fdwrite</command> to make a copy.</para> - - </sect3> - - <sect3> - <title>Keeping your local changes</title> - - <para>As a developer one would like to experiment with and change - files in the source tree. <application>CTM</application> supports local modifications in a - limited way: before checking for the presence of a file - <filename>foo</filename>, it first looks for - <filename>foo.ctm</filename>. If this file exists, CTM will - operate on it instead of <filename>foo</filename>.</para> - - <para>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 <filename>.ctm</filename> - suffix. Then you can freely hack the code, while CTM keeps the - <filename>.ctm</filename> file up-to-date.</para> - - </sect3> - - <sect3> - <title>Other interesting <application>CTM</application> options</title> - - - <sect4> - <title>Finding out exactly what would be touched by an - update</title> - - <para>You can determine the list of changes that <application>CTM</application> will make - on your source repository using the <option>-l</option> - option to <application>CTM</application>.</para> - - <para>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 <!-- smiley -->:-).</para> - - </sect4> - - <sect4> - <title>Making backups before updating</title> - - <para>Sometimes you may want to backup all the files that would - be changed by a <application>CTM</application> update.</para> - - <para>Specifying the <option>-B backup-file</option> option - causes <application>CTM</application> to backup all files that would be touched by a - given <application>CTM</application> delta to <filename>backup-file</filename>.</para> - - </sect4> - - <sect4> - <title>Restricting the files touched by an update</title> - - <para>Sometimes you would be interested in restricting the scope - of a given <application>CTM</application> update, or may be interested in extracting just - a few files from a sequence of deltas.</para> - - <para>You can control the list of files that <application>CTM</application> would operate - on by specifying filtering regular expressions using the - <option>-e</option> and <option>-x</option> - options.</para> - - <para>For example, to extract an up-to-date copy of - <filename>lib/libc/Makefile</filename> from your collection of - saved CTM deltas, run the commands:</para> - - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput> -&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen> - - - <para>For every file specified in a <application>CTM</application> delta, the - <option>-e</option> and <option>-x</option> options - are applied in the order given on the command line. The file - is processed by <application>CTM</application> only if it is marked as eligible after all - the <option>-e</option> and <option>-x</option> - options are applied to it.</para> - - </sect4> - </sect3> - - <sect3> - <title>Future plans for <application>CTM</application></title> - - <para>Tons of them:</para> - - <itemizedlist> - - <listitem> - <para>Use some kind of authentication into the CTM system, - so as to allow detection of spoofed CTM updates.</para> - </listitem> - - <listitem> - <para>Clean up the options to <application>CTM</application>, they - became confusing and counter intuitive.</para> - </listitem> - - </itemizedlist> - - <para>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...</para> - - </sect3> - - <sect3> - <title>Miscellaneous stuff</title> - - <para>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 <literal>sec-cur</literal> sequence too. There is a - sequence of deltas for the <literal>ports</literal> - 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.</para> - - </sect3> - - <sect3> - <title>Thanks!</title> - - - <variablelist> - <varlistentry><term>&a.bde;</term> - <listitem> - <para>for his pointed pen and invaluable comments.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>&a.sos;</term> - - <listitem> - <para>for patience.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>Stephen McKay</term> - - <listitem> - <para>wrote <command>ctm_[rs]mail</command>, - much appreciated.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>&a.jkh;</term> - - <listitem> - <para>for being so stubborn that I had to make it - better.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>All the users</term> - - <listitem> - <para>I hope you like it...</para> - - </listitem> - </varlistentry> - </variablelist> - - - </sect3> - </sect2> - - <sect2 id="cvsup"> - <title><application>CVSup</application></title> - - <para><emphasis>Contributed by &a.jdp;</emphasis>.</para> - - - <sect3 id="cvsup-intro"> - <title>Introduction</title> - - <para><application>CVSup</application> 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 <application>CVSup</application>, - FreeBSD users can easily keep their own source trees up to - date.</para> - - <para><application>CVSup</application> uses the so-called <emphasis>pull</emphasis> 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 <application>CVSup</application> client - manually to get an update, or they must set up a <command>cron</command> job to run - it automatically on a regular basis.</para> - - <para>The term <application>CVSup</application>, capitalized just so, refers to the entire - software package. Its main components are the client <command>cvsup</command> - which runs on each user's machine, and the server <command>cvsupd</command> which - runs at each of the FreeBSD mirror sites.</para> - - <para>As you read the FreeBSD documentation and mailing lists, you - may see references to <application>sup</application>. <application>Sup</application> was the - predecessor of <application>CVSup</application>, and it served a similar purpose. <application>CVSup</application> is - in used in much the same way as sup and, in fact, uses - configuration files which are backward-compatible with <command>sup</command>'s. - <application>Sup</application> is no longer used in the FreeBSD project, because <application>CVSup</application> is - both faster and more flexible.</para> - - </sect3> - - <sect3 id="cvsup-install"> - <title>Installation</title> - - <para>The easiest way to install <application>CVSup</application> if you are running FreeBSD - 2.2 or later is to use either <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports-current/net/cvsup.tar">the port</ulink> from the FreeBSD <link linkend="ports">ports collection</link> or the corresponding <ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/packages-current/net/cvsup-15.4.2.tgz">binary package</ulink>, depending on whether you prefer to roll your own or not.</para> - - <para>If you are running FreeBSD-2.1.6 or 2.1.7, you unfortunately - cannot use the binary package versions due to the fact that it - requires a version of the C library that does not yet exist in - FreeBSD-2.1.{6,7}. You can easily use <ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports-current/net/cvsup.tar">the port</ulink>, however, just as with FreeBSD 2.2. Simply unpack the tar file, cd to the cvsup subdirectory and type <command>make install</command>.</para> - - <para>Because <application>CVSup</application> is written in <ulink - URL="http://www.research.digital.com/SRC/modula-3/html/home.html">Modula-3</ulink>, both the package and the port require that the Modula-3 runtime libraries be installed. These are available as the <ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports-current/lang/modula-3-lib.tar">lang/modula-3-lib</ulink> port and the <ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/packages-current/lang/modula-3-lib-3.6.tgz">lang/modula-3-lib-3.6</ulink> package. If you follow the same directions as for <command>cvsup</command>, these libraries will be compiled and/or installed automatically when you install the <application>CVSup</application> port or package.</para> - - <para>The Modula-3 libraries are rather large, and fetching and - compiling them is not an instantaneous process. For that - reason, a third option is provided. You can get - <emphasis>statically linked</emphasis> FreeBSD executables for - <application>CVSup</application> from either the USA distribution site:</para> - - - <itemizedlist> - - <listitem> - <para><ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsup-bin-15.4.2.tar.gz">ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsup-bin-15.4.2.tar.gz</ulink> (client including GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsup.nogui-bin-15.4.2.tar.gz">ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsup.nogui-bin-15.4.2.tar.gz</ulink> (client without GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupd-bin-15.4.2.tar.gz">ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupd-bin-15.4.2.tar.gz</ulink> (server).</para> - </listitem> - - </itemizedlist> - - - <para>as well as from the many FreeBSD <link - linkend="mirrors-ftp">FTP mirror sites</link> around the - world.</para> - - <itemizedlist> - - <listitem> - <para><ulink - URL="ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsup-bin-15.3.tar.gz">ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsup-bin-15.3.tar.gz</ulink> (client including GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsup.nogui-bin-15.3.tar.gz">ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsup.nogui-bin-15.3.tar.gz</ulink> (client without GUI).</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsupd-bin-15.3.tar.gz">ftp://ftp.cs.tu-berlin.de/pub/FreeBSD/CVSup/cvsupd-bin-15.3.tar.gz</ulink> (server).</para> - </listitem> - - </itemizedlist> - - - <para>Most users will need only the client. These executables are - entirely self-contained, and they will run on any version of - FreeBSD from FreeBSD-2.1.0 to FreeBSD-current.</para> - - <para>In summary, your options for installing CVSup are:</para> - - - <itemizedlist> - - <listitem> - <para>FreeBSD-2.2 or later: static binary, port, - or package</para> - </listitem> - - <listitem> - <para>FreeBSD-2.1.6, 2.1.7: static binary or - port</para> - </listitem> - - <listitem> - <para>FreeBSD-2.1.5 or earlier: static binary</para> - </listitem> - - </itemizedlist> - - - </sect3> - - <sect3 id="cvsup-config"> - <title>Configuration</title> - - <para><application>CVSup</application>'s operation is controlled by a configuration file - called the <filename>supfile</filename>. Beginning with - FreeBSD-2.2, there are some sample <filename>supfiles</filename> - in the directory <ulink - URL="file:/usr/share/examples/cvsup">/usr/share/examples/cvsup</ulink>. These examples are also available from <ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/</ulink> if you are on a pre-2.2 system.</para> - - <para>The information in a <filename>supfile</filename> answers - the following questions for cvsup:</para> - - - <itemizedlist> - - <listitem> - <para><link linkend="cvsup-config-files">Which files - do you want to receive?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-vers">Which - versions of them do you want?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-where">Where do you - want to get them from?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-dest">Where do you - want to put them on your own machine?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-status">Where do - you want to put your status files?</link></para> - </listitem> - - </itemizedlist> - - - <para>In the following sections, we will construct a typical - <filename>supfile</filename> by answering each of these - questions in turn. First, we describe the overall structure of - a <filename>supfile</filename>.</para> - - <para>A <filename>supfile</filename> is a text file. Comments - begin with <literal>#</literal> and extend to the end of the line. Lines that - are blank and lines that contain only comments are - ignored.</para> - - <para>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., <literal>delete</literal> or <literal>compress</literal>. A value field also begins - with a keyword, but the keyword is followed without intervening - white space by <literal>=</literal> and a second word. For example, - <literal>release=cvs</literal> is a value field.</para> - - <para>A <filename>supfile</filename> typically specifies more than - one collection to receive. One way to structure a - <filename>supfile</filename> is to specify all of the relevant - fields explicitly for each collection. However, that tends to - make the <filename>supfile</filename> lines quite long, and it - is inconvenient because most fields are the same for all of the - collections in a <filename>supfile</filename>. <application>CVSup</application> provides a - defaulting mechanism to avoid these problems. Lines beginning - with the special pseudo-collection name <literal>*default</literal> can be used - to set flags and values which will be used as defaults for the - subsequent collections in the <filename>supfile</filename>. 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 <literal>*default</literal> lines.</para> - - <para>With this background, we will now proceed to construct a - <filename>supfile</filename> for receiving and updating the main - source tree of <link - linkend="current">FreeBSD-current</link>.</para> - - - <itemizedlist> - - <listitem> - <para>Which files do you want to receive?<anchor id="cvsup-config-files"></para> - - <para>The files available via <application>CVSup</application> are organized into named - groups called “collections”. The collections that are - available are described <link - linkend="cvsup-collec">here</link>. In this example, we wish to receive the - entire main source tree for the FreeBSD system. There is - a single large collection <literal>src-all</literal> 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, <literal>cvs-crypto</literal>. As a first - step toward constructing our <filename>supfile</filename>, - we simply list these collections, one per line:</para> - - <programlisting> -src-all -cvs-crypto</programlisting> - </listitem> - - <listitem> - <para>Which version(s) of them do you want?<anchor id="cvsup-config-vers"></para> - - <para>With <application>CVSup</application>, 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 <literal>tag=</literal> and <option>date=</option> value - fields.</para> - - <warning> - <para>Be very - careful to specify any <literal>tag=</literal> 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 <emphasis>only - </emphasis> <literal>tag=.</literal> for the <literal>ports-*</literal> - collections.</para> - </warning> - - <para>The <literal>tag=</literal> 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.</para> - - <para>Here are the branch tags that users might be - interested in:</para> - - - <variablelist> - <varlistentry><term>tag=.</term> - <listitem> - <para>The main line of development, also known as - FreeBSD-current.</para> - - <note> - <para>The <literal>.</literal> is not punctuation; it is the name - of the tag. Valid for all collections.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.x, also known as - FreeBSD-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.x, also known as - 2.2-stable. Not valid for the ports collection.</para> - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_0</term> - - <listitem> - <para>The line of development for FreeBSD-2.1.x - - this branch is largely obsolete. Not valid for the - ports-* collections.</para> - - </listitem> - </varlistentry> - </variablelist> - - - <para>Here are the revision tags that users might be - interested in:</para> - - - <variablelist> - <varlistentry> - <term>tag=RELENG_3_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.0. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.7. Not valid for the ports-* - collections.</para> - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_2_6_RELEASE</term> - <listitem> - <para>FreeBSD-2.2.6. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.7. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_6_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6.1. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.6. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.5. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - - <varlistentry><term>tag=RELENG_2_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.1.0. Not valid for the ports-* - collections.</para> - - </listitem> - </varlistentry> - </variablelist> - - - <warning> - <para>Be very - careful to type the tag name exactly as shown. <application>CVSup</application> - cannot distinguish between valid and invalid tags. If you - misspell the tag, <application>CVSup</application> 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.</para> - </warning> - - <para>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 <option>date=</option> value - field. The <citerefentry><refentrytitle>cvsup</refentrytitle><manvolnum>1</manvolnum></citerefentry> manual page explains how to do - that.</para> - - <para>For our example, we wish to receive FreeBSD-current. - We add this line at the beginning of our - <filename>supfile</filename>:</para> - - <programlisting> -*default tag=.</programlisting> - - <para>There is an important special case that comes into - play if you specify neither a <literal>tag=</literal> - field nor a <literal>date=</literal> - 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.</para> - </listitem> - - <listitem> - <para>Where do you want to get them from?<anchor id="cvsup-config-where"></para> - - <para>We use the <literal>host=</literal> field to tell <command>cvsup</command> where to obtain - its updates. Any of the <link - linkend="mirrors-cvsup">CVSup - mirror sites</link> will do, though you should try to select - one that's near to you. In this example, we'll use the - primary FreeBSD distribution site, - <hostid role="fqdn">cvsup.FreeBSD.org</hostid>:</para> - - <programlisting> -*default host=cvsup.FreeBSD.org</programlisting> - - <para>On any particular run of <command>cvsup</command>, you can override this - setting on the command line, with <option>-h <replaceable>hostname</replaceable></option>.</para> - </listitem> - - <listitem> - <para>Where do you want to put them on your own - machine?<anchor id="cvsup-config-dest"></para> - - <para>The <literal>prefix=</literal> field tells <command>cvsup</command> where to put the files - it receives. In this example, we will put the source files - directly into our main source tree, <filename>/usr/src</filename>. The <filename>src</filename> - directory is already implicit in the collections we have - chosen to receive, so this is the correct - specification:</para> - - <programlisting> -*default prefix=/usr</programlisting> - </listitem> - - <listitem> - <para>Where should <command>cvsup</command> maintain its status files?<anchor id="cvsup-config-status"></para> - - <para>The cvsup client maintains certain status files in - what is called the “base” directory. These files help - <application>CVSup</application> to work more efficiently, by keeping track of which - updates you have already received. We will use the - standard base directory, <filename>/usr/local/etc/cvsup</filename>:</para> - - <programlisting> -*default base=/usr/local/etc/cvsup</programlisting> - - <para>This setting is used by default if it is not specified - in the <filename>supfile</filename>, so we actually do not - need the above line.</para> - - <para>If your base directory does not already exist, now - would be a good time to create it. The <command>cvsup</command> client will - refuse to run if the base directory does not exist.</para> - </listitem> - - <listitem> - <para>Miscellaneous <filename>supfile</filename> settings:</para> - - <para>There is one more line of boiler plate that normally - needs to be present in the <filename>supfile</filename>:</para> - - <programlisting> -*default release=cvs delete use-rel-suffix compress</programlisting> - - <para><literal>release=cvs</literal> indicates that the server should get its - information out of the main FreeBSD CVS repository. This - is virtually always the case, but there are other - possibilities which are beyond the scope of this - discussion.</para> - - <para><literal>delete</literal> gives <application>CVSup</application> permission to delete files. You - should always specify this, so that <application>CVSup</application> can keep your - source tree fully up to date. <application>CVSup</application> is careful to delete - only those files for which it is responsible. Any extra - files you happen to have will be left strictly - alone.</para> - - <para><literal>use-rel-suffix</literal> is ... arcane. If you really want to - know about it, see the <citerefentry><refentrytitle>cvsup</refentrytitle><manvolnum>1</manvolnum></citerefentry> manual page. Otherwise, - just specify it and do not worry about it.</para> - - <para><literal>compress</literal> 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.</para> - </listitem> - - <listitem> - <para>Putting it all together:</para> - - <para>Here is the entire <filename>supfile</filename> for - our example:</para> - - <programlisting> -*default tag=. -*default host=cvsup.FreeBSD.org -*default prefix=/usr -*default base=/usr/local/etc/cvsup -*default release=cvs delete use-rel-suffix compress - -src-all -cvs-crypto</programlisting> - </listitem> - - </itemizedlist> - - - </sect3> - - <sect3> - <title>Running <application>CVSup</application></title> - - <para>You are now ready to try an update. The command line for - doing this is quite simple:</para> - - - <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen> - - - <para>where <filename><replaceable>supfile</replaceable></filename> is of course the name of the supfile you - have just created. Assuming you are running under X11, <command>cvsup</command> - will display a GUI window with some buttons to do the usual - things. Press the “go” button, and watch it run.</para> - - <para>Since you are updating your actual <filename>/usr/src</filename> tree in this - example, you will need to run the program as <username>root</username> so that <command>cvsup</command> - 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:</para> - - - <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput> -&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen> - - - <para>The directory you specify will be used as the destination - directory for all file updates. <application>CVSup</application> will examine your usual - files in <filename>/usr/src</filename>, but it will not modify - or delete any of them. Any file updates will instead land in - <filename>/var/tmp/dest/usr/src</filename>. <application>CVSup</application> 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 - <filename>/usr/src</filename>, you do not even need to be root - to perform this kind of trial run.</para> - - <para>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:</para> - - - <screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen> - - - <para>The <option>-g</option> tells cvsup not to use its GUI. This is automatic - if you are not running X11, but otherwise you have to specify - it.</para> - - <para>The <option>-L 2</option> tells cvsup to print out the details of all the - file updates it is doing. There are three levels of verbosity, - from <option>-L 0</option> to <option>-L 2</option>. The default is 0, which means total - silence except for error messages.</para> - - <para>There are plenty of other options available. For a brief - list of them, type <command>cvsup -H</command>. For more detailed descriptions, - see the manual page.</para> - - <para>Once you are satisfied with the way updates are working, you - can arrange for regular runs of cvsup using <citerefentry><refentrytitle>cron</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Obviously, - you should not let cvsup use its GUI when running it from - cron.</para> - - </sect3> - - <sect3 id="cvsup-collec"> - <title><application>CVSup</application> File Collections</title> - - <para>The file collections available via <application>CVSup</application> 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.</para> - - <para>The most commonly used collections are <literal>src-all</literal>, <literal>cvs-crypto</literal>, and <literal>ports-all</literal>. The other collections are used - only by small groups of people for specialized purposes, and - some mirror sites may not carry all of them.</para> - - - <variablelist> - <varlistentry><term><literal>cvs-all - release=cvs</literal></term> - <listitem> - <para>The main FreeBSD CVS repository, excluding the - export-restricted cryptography code.</para> - - - <variablelist> - <varlistentry><term><literal>distrib - release=cvs</literal></term> - <listitem> - <para>Files related to the distribution and - mirroring of FreeBSD.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>doc-all - release=cvs</literal></term> - - <listitem> - <para>Sources for the FreeBSD handbook and other - documentation.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-all - release=cvs</literal></term> - - <listitem> - <para>The FreeBSD ports collection.</para> - - - <variablelist> - <varlistentry><term><literal>ports-archivers - release=cvs</literal></term> - <listitem> - <para>Archiving tools.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-astro - release=cvs</literal></term> - - <listitem> - <para>Astronomical ports.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-audio - release=cvs</literal></term> - - <listitem> - <para>Sound support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-base - release=cvs</literal></term> - - <listitem> - <para>Miscellaneous files at the top of - /usr/ports.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-benchmarks - release=cvs</literal></term> - - <listitem> - <para>Benchmarks.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-biology - release=cvs</literal></term> - - <listitem> - <para>Biology.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-cad - release=cvs</literal></term> - - <listitem> - <para>Computer aided design tools.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-chinese - release=cvs</literal></term> - - <listitem> - <para>Chinese language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-comms - release=cvs</literal></term> - - <listitem> - <para>Communication software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-converters - release=cvs</literal></term> - - <listitem> - <para>character code converters.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-databases - release=cvs</literal></term> - - <listitem> - <para>Databases.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><literal></literal>ports-deskutils - release=cvs</term> - - <listitem> - <para>Things that used to be on the desktop before - computers were invented.</para> - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-devel - release=cvs</literal></term> - - <listitem> - <para>Development utilities.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-editors - release=cvs</literal></term> - - <listitem> - <para>Editors.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-emulators - release=cvs</literal></term> - - <listitem> - <para>Emulators for other operating - systems.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-games - release=cvs</literal></term> - - <listitem> - <para>Games.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-german - release=cvs</literal></term> - - <listitem> - <para>German language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-graphics - release=cvs</literal></term> - - <listitem> - <para>Graphics utilities.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-japanese - release=cvs</literal></term> - - <listitem> - <para>Japanese language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-korean - release=cvs</literal></term> - - <listitem> - <para>Korean language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-lang - release=cvs</literal></term> - - <listitem> - <para>Programming languages.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-mail - release=cvs</literal></term> - - <listitem> - <para>Mail software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-math - release=cvs</literal></term> - - <listitem> - <para>Numerical computation - software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-mbone - release=cvs</literal></term> - - <listitem> - <para>MBone applications.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-misc - release=cvs</literal></term> - - <listitem> - <para>Miscellaneous utilities.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-net - release=cvs</literal></term> - - <listitem> - <para>Networking software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-news - release=cvs</literal></term> - - <listitem> - <para>USENET news software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-plan9 - release=cvs</literal></term> - - <listitem> - <para>Various programs from Plan9.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-print - release=cvs</literal></term> - - <listitem> - <para>Printing software.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-russian - release=cvs</literal></term> - - <listitem> - <para>Russian language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-security - release=cvs</literal></term> - - <listitem> - <para>Security utilities.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-shells - release=cvs</literal></term> - - <listitem> - <para>Command line shells.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-sysutils - release=cvs</literal></term> - - <listitem> - <para>System utilities.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-textproc - release=cvs</literal></term> - - <listitem> - <para>text processing utilities (does not - include desktop publishing).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-vietnamese - release=cvs</literal></term> - - <listitem> - <para>Vietnamese language support.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-www - release=cvs</literal></term> - - <listitem> - <para>Software related to the World Wide - Web.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>ports-x11 - release=cvs</literal></term> - - <listitem> - <para>Ports to support the X window - system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-clocks - release=cvs</literal></term> - - <listitem> - <para>X11 clocks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fm - release=cvs</literal></term> - - <listitem> - <para>X11 file managers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fonts - release=cvs</literal></term> - - <listitem> - <para>X11 fonts and font utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-toolkits - release=cvs</literal></term> - - <listitem> - <para>X11 toolkits.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-wm</literal></term> - - <listitem> - <para>X11 window managers.</para> - </listitem> - </varlistentry> - </variablelist> - - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-all - release=cvs</literal></term> - - <listitem> - <para>The main FreeBSD sources, excluding the - export-restricted cryptography code.</para> - - - <variablelist> - <varlistentry><term><literal>src-base - release=cvs</literal></term> - <listitem> - <para>Miscellaneous files at the top of - <filename>/usr/src</filename>.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-bin - release=cvs</literal></term> - - <listitem> - <para>User utilities that may be needed in - single-user mode - (<filename>/usr/src/bin</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-contrib - release=cvs</literal></term> - - <listitem> - <para>Utilities and libraries from outside - the FreeBSD project, used relatively - unmodified - (<filename>/usr/src/contrib</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-etc - release=cvs</literal></term> - - <listitem> - <para>System configuration files - (<filename>/usr/src/etc</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-games - release=cvs</literal></term> - - <listitem> - <para>Games - (<filename>/usr/src/games</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-gnu - release=cvs</literal></term> - - <listitem> - <para>Utilities covered by the GNU Public - License - (<filename>/usr/src/gnu</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-include - release=cvs</literal></term> - - <listitem> - <para>Header files - (<filename>/usr/src/include</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-kerberosIV - release=cvs</literal></term> - - <listitem> - <para>KerberosIV security package - (<filename>/usr/src/kerberosIV</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-lib - release=cvs</literal></term> - - <listitem> - <para>Libraries - (<filename>/usr/src/lib</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-libexec - release=cvs</literal></term> - - <listitem> - <para>System programs normally executed by - other programs - (<filename>/usr/src/libexec</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-release - release=cvs</literal></term> - - <listitem> - <para>Files required to produce a FreeBSD - release - (<filename>/usr/src/release</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-sbin - release=cvs</literal></term> - - <listitem> - <para>System utilities for single-user - mode - (<filename>/usr/src/sbin</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-share - release=cvs</literal></term> - - <listitem> - <para>Files that can be shared across - multiple systems - (<filename>/usr/src/share</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-sys - release=cvs</literal></term> - - <listitem> - <para>The kernel - (<filename>/usr/src/sys</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-tools - release=cvs</literal></term> - - <listitem> - <para>Various tools for the maintenance of - FreeBSD - (<filename>/usr/src/tools</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-usrbin - release=cvs</literal></term> - - <listitem> - <para>User utilities - (<filename>/usr/src/usr.bin</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-usrsbin - release=cvs</literal></term> - - <listitem> - <para>System utilities - (<filename>/usr/src/usr.sbin</filename>).</para> - - </listitem> - </varlistentry> - </variablelist> - - - </listitem> - </varlistentry> - - <varlistentry><term><literal>www - release=cvs</literal></term> - - <listitem> - <para>The sources for the World Wide Web - data.</para> - - </listitem> - </varlistentry> - </variablelist> - - - </listitem> - </varlistentry> - - <varlistentry><term><literal>cvs-crypto - release=cvs</literal></term> - - <listitem> - <para>The export-restricted cryptography code.</para> - - - <variablelist> - <varlistentry><term><literal>src-crypto - release=cvs</literal></term> - <listitem> - <para>Export-restricted utilities and libraries - from outside the FreeBSD project, used - relatively unmodified - (<filename>/usr/src/crypto</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-eBones - release=cvs</literal></term> - - <listitem> - <para>Kerberos and DES - (<filename>/usr/src/eBones</filename>).</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>src-secure - release=cvs</literal></term> - - <listitem> - <para>DES - (<filename>/usr/src/secure</filename>).</para> - - </listitem> - </varlistentry> - </variablelist> - - - </listitem> - </varlistentry> - - <varlistentry><term><literal>distrib - release=self</literal></term> - - <listitem> - <para>The CVSup server's own configuration files. Used by - CVSup mirror sites.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>gnats - release=current</literal></term> - - <listitem> - <para>The GNATS bug-tracking database.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>mail-archive - release=current</literal></term> - - <listitem> - <para>FreeBSD mailing list archive.</para> - - </listitem> - </varlistentry> - - <varlistentry><term><literal>www - release=current</literal></term> - - <listitem> - <para>The installed World Wide Web data. Used by WWW - mirror sites.</para> - - </listitem> - </varlistentry> - </variablelist> - - - </sect3> - - <sect3> - <title>Announcements, Questions, and Bug Reports</title> - - <para>Most FreeBSD-related discussion of <application>CVSup</application> takes place on the - &a.hackers;. New versions of the software are announced there, - as well as on the &a.announce;.</para> - - <para>Questions and bug reports should be addressed to the author - of the program at <email>cvsup-bugs@polstra.com</email>.</para> - - </sect3> - </sect2> - </sect1> - - <sect1 id="makeworld"> - <title>Using <command>make world</command> to rebuild your - system</title> - - <para><emphasis>Contributed by &a.nik;.</emphasis></para> - - <para>Once you have synchronised your local source tree against a - particular version of FreeBSD (<literal>stable</literal>, - <literal>current</literal> and so on) you must then use - the source tree to rebuild the system.</para> - - <para>Currently, the best source of information on how to do that is a - tutorial available from <ulink - URL="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html</ulink>.</para> - - <para>A successor to this tutorial will be integrated into the - handbook.</para> - - </sect1> - </chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - |