Date: Fri, 7 Sep 2001 18:40:03 -0700 (PDT) From: Salvo Bartolotta <bartequi@neomedia.it> To: freebsd-doc@freebsd.org Subject: Re: docs/24662: too many questions about source management bloat freebsd lists Message-ID: <200109080140.f881e3N80802@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/24662; it has been noted by GNATS.
From: Salvo Bartolotta <bartequi@neomedia.it>
To: Murray Stokely <murray.stokely@windriver.com>
Cc: freebsd-gnats-submit@FreeBSD.org, cvsupbugs@polstra.com
Subject: Re: docs/24662: too many questions about source management bloat freebsd lists
Date: Sat, 08 Sep 2001 03:30:17 +0200 (CEST)
This message is in MIME format.
---MOQ999912617bf28d22212d6ba57727d5d15660290b8
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit
Here is a patch, as promised.
I exchanged a couple of e-mail messages with John Polstra on this subject
a few months ago; I am sending him the draft so that he may also be able to
spot any bugs and give suggestions.
-- Salvo
---MOQ999912617bf28d22212d6ba57727d5d15660290b8
Content-Type: text/plain; name="patch"; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit
Content-Disposition: inline; filename="patch"
===================================================================
RCS file: /myjunk/home/ncvs/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml,v
retrieving revision 1.153
diff -u -r1.153 chapter.sgml
--- chapter.sgml 2001/09/05 00:29:19 1.153
+++ chapter.sgml 2001/09/08 00:22:40
@@ -3910,6 +3910,213 @@
</varlistentry>
</variablelist>
</sect2>
+
+ <sect2>
+ <sect2info>
+ <authorgroup>
+ <author>
+ <firstname>Salvo</firstname>
+ <surname>Bartolotta</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </sect2info>
+
+ <title>Advanced Points</title>
+
+ <sect3>
+ <title>Introduction</title>
+
+ <para>If you have visited <ulink url="http://www.polstra.com">John Polstra's site</ulink>
+ and read
+ <ulink url="http://www.polstra.com/projects/freeware/CVSup/faq.html">his FAQ</ulink>,
+ you may probably have noticed Question 12 & 13.</para>
+
+ <para>When updating any collection of sources (eg <filename>/usr/ports</filename>),
+ &man.cvsup.1; makes use of the related checkouts file in order to
+ perform the updating process in the most efficient and correct way.
+ In this example (<filename>/usr/ports</filename>), the related checkouts
+ file is <filename>/usr/sup/ports-all/checkouts.cvs:.</filename> if
+ your base is <filename>/usr</filename>.</para>
+
+ <para>A checkouts file contains information on the current status of your
+ sources -- in a way, a sort of "photograph". This significant information
+ enables cvsup to retrieve updates most effectively. Further, and maybe
+ more important, it enables cvsup to correctly manage your sources by
+ locally deleting any files no longer present in the repository, thus
+ leaving no stale files on your system. In fact, without a checkouts file,
+ cvsup would NOT know which files your collection was composed of (cf
+ &man.cvsup.1; and the fallback method for details); as a result, it
+ could NOT delete on your system those files no longer present in the
+ repository. These files would remain on your system (stale files), and
+ might cause you subtle build failures or other trouble. For example,
+ this problem is likely to occur if you first update your ports
+ collection several weeks after you have got(ten) your installation
+ CDs.</para>
+
+ <para>It is therefore recommended that you adopt the two-step procedure
+ outlined in the Cvsup FAQ (cf Q12, Q13); later, you will be given
+ interesting and instructive concrete examples.</para>
+ </sect3>
+ <sect3>
+ <title>An useful python script: cvsupchk</title>
+
+ <para>Alternatively, in order to examine your sources for inconsistencies,
+ you may wish to utilize the cvsupchk python script; which script is
+ currently found in <filename>/usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk</filename>,
+ together with a nice <filename>README</filename>. Prerequisites:</para>
+
+ <orderedlist>
+ <listitem>
+ <para><literal>/usr/ports/net/cvsup</literal> &prompt.root; <userinput> make extract</userinput></para>
+ </listitem>
+
+ <listitem>
+ <para>python (also found in the ports collection :-))</para>
+ </listitem>
+
+ <listitem>
+ <para>a checkouts file for your collection of sources.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>If you are updating your sources for the very first time, of course
+ you do not have a checkouts file. After installing python and updating
+ your sources (eg <filename>/usr/ports</filename>), you can check them
+ thus:</para>
+
+ <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more</userinput></screen>
+
+ <para>If you want to check your RELENG_4 sources:</para>
+
+ <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more</userinput></screen>
+
+ <para>In each case, cvsupchk will inspect your sources for inconsistencies
+ by utilizing the information contained in the related checkouts file.
+ Such anomalies as deleted files being present (aka stale files), missing
+ checked out files, extra RCS files, and dead directories, will be
+ printed to standard output.</para>
+
+ <para>In the next section, we will provide important, typical examples of
+ source updating; which examples will show you the role of checkouts
+ files and the dangers of negligent source management.</para>
+ </sect3>
+
+ <sect3>
+ <title>Examples of more advanced source management</title>
+
+ <sect4>
+ <title>How to safely change tags when updating <literal>src-all.</literal></title>
+
+ <para>If you specify eg tag=A in your supfile, cvsup will create a
+ checkouts file called <filename>checkouts.cvs:A</filename>: for
+ instance, if tag=RELENG_4, a checkouts file called
+ <filename>checkouts.cvs:RELENG_4</filename> is generated. This file
+ will be used to retrieve and/or store identification information
+ on your 4-STABLE sources.</para>
+
+ <para>When tracking <literal>src-all</literal>, if you wish to pass from tag=A to tag=B
+ (A less/greater than B not making any difference) and if your
+ checkouts file is <filename>checkouts.cvs:A</filename>, the
+ following actions should be performed:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>&prompt.root; <userinput>mv checkouts.cvs:A checkouts.cvs:B</userinput>
+ (This provides the subsequent step with the appropriate
+ checkouts file)</para>
+ </listitem>
+
+ <listitem>
+ <para>write a supfile whose collection line reads:</para>
+ <programlisting>src-all tag=B</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>cvsup your sources using the new supfile.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Cvsup will look for <filename>checkouts.cvs:B</filename> -- in
+ that the target is B; that is, cvsup will make use of the information
+ contained therein to correctly manage your sources.</para>
+
+ <para>The benefits:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the sources are dealt with correctly (in particular, no
+ stale files)</para>
+ </listitem>
+
+ <listitem>
+ <para>less load is placed on the server, in that cvsup operates
+ in the most efficient way.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For example, A=RELENG_4, B=. The period in "B=." means -CURRENT.
+ This is a rather typical update, from 4-STABLE to -CURRENT. While it
+ is straightforward to "downgrade" your sources (eg from -CURRENT to
+ -STABLE), downgrading a system is quite another matter. You are
+ STRONGLY advised not to attempt such an operation, unless you know
+ exactly what you are doing.</para>
+ </sect4>
+
+ <sect4>
+ <title>Updating to the same tag as of a different date</title>
+
+ <para>If you wish to switch from "tag=A" to "tag=A" as of a different
+ GMT date (say, "date=D"), you will execute the following:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>write a supfile whose collection line reads:</para>
+ <programlisting>src-all tag=A date=D</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>update your sources using the new supfile</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Whether the new date precedes that of the last synch operation
+ with tag=A or not, it is immaterial. For example, in order to
+ specify the date "August 27, 2000, 10:00:00 GMT" you write the
+ line:</para>
+
+ <programlisting>src-all tag=RELENG_4 date=2000.08.27.10.00.00</programlisting>
+
+ <para>N.B. The format of a date is rigid. You have to specify all
+ the components of the date: century (19 for the 19th or 20 for the
+ 20th), year, month, day, hour, minutes, seconds -- as shown in the
+ above example. For more information, please see &man.cvsup.1;.</para>
+
+ <para>Whether or not a date is specified, the checkouts file is called
+ <filename>checkouts.cvs:A</filename> (eg
+ <filename>checkouts.cvs:RELENG_4</filename>). As a result, no
+ particular action is needed in order to revert to the previous state:
+ you have to modify the date in the supfile, and csvup again.</para>
+ </sect4>
+
+ <sect4>
+ <title>Updating your ports collection for the first time</title>
+
+ <para>Since ports are tagged "." (ie -CURRENT), you can correctly "sync"
+ them for the first time by adding the date keyword (cf &man.cvsup.1;
+ for the exact format): you should specify a date as close as possible
+ to that of "shipping" of your ports tree. After cvsup has correctly
+ created the ports checkouts file, which is precisely the goal of
+ this first special synch operation, the date field must be removed;
+ all subsequent updates will be carried out smoothly.</para>
+
+ <para>If you have been reading the apparently nit-picking remarks in
+ these sections, you will probably have recognized the potential for
+ scr^Wtrouble in a source updating process. A number of people have
+ actually run into problems. You have been warned. :-)</para>
+ </sect4>
+ </sect3>
+ </sect2>
</sect1>
<sect1 id="mirrors-afs">
---MOQ999912617bf28d22212d6ba57727d5d15660290b8--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200109080140.f881e3N80802>