720d4d69c8
* Correct some broken links * Use relative links for freebsd.org documents PR: docs/31447 Submitted by: Cyrille Lefevre <clefevre@citeweb.net> Found by: linbot
264 lines
10 KiB
Text
264 lines
10 KiB
Text
<!--
|
|
The FreeBSD Documentation Project
|
|
-->
|
|
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
|
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
|
%man;
|
|
]>
|
|
|
|
<article>
|
|
<articleinfo>
|
|
<title>CVSup Advanced Points</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Salvo</firstname>
|
|
<surname>Bartolotta</surname>
|
|
|
|
<affiliation>
|
|
<address><email>bartequi@neomedia.it</email></address>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<abstract>
|
|
<para>The present article assumes a basic understanding of CVSup
|
|
operation. It documents several delicate issues connected with
|
|
source synchronization via CVSup, viz. effective solutions to
|
|
the problem of stale files as well as special source updating
|
|
cases; which issues are likely to cause apparently inexplicable
|
|
troubles.</para>
|
|
</abstract>
|
|
</articleinfo>
|
|
|
|
<sect1 id="preface">
|
|
<title>Preface</title>
|
|
|
|
<para>This document is the fruit of the author's attempts to
|
|
fully understand the niceties of cvsup & source updating. :-)
|
|
While the author has made every effort to make these pages
|
|
as informative and correct as possible, he is only human and
|
|
may have made all sorts of typos, mistakes, etc. He will be
|
|
very grateful for any comments and/or suggestions you send to
|
|
his e-mail address, <email>bartequi@neomedia.it</email>.</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="introduction">
|
|
<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 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. They 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); in subsequent sections, you
|
|
will be given interesting and instructive concrete examples.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="script">
|
|
<title>A 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>
|
|
</sect1>
|
|
|
|
<sect1 id="examples">
|
|
<title>Examples of more advanced source management</title>
|
|
|
|
<sect2>
|
|
<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 information
|
|
identifying 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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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 sync
|
|
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>
|
|
|
|
<note><para>The format of a date is rigid. You have to specify
|
|
all the components of the date: century (20, ie the 20th
|
|
century, must be supplied whereas 19, the past century, can
|
|
be omitted), year, month, day, hour, minutes, seconds -- as
|
|
shown in the above example. For more information, please
|
|
see &man.cvsup.1;.</para></note>
|
|
|
|
<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>
|
|
</sect2>
|
|
|
|
|
|
<sect2>
|
|
<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 sync 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>
|
|
</sect2>
|
|
</sect1>
|
|
</article>
|