5fa082b1f8
Currently we have articles.ent and books.ent, and
for example, articles.ent can be used by putting the
following lines in the doctype declaration:
<!ENTITY % articles.ent PUBLIC
"-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
This pulls all of the necessary entities via share/sgml/articles.ent.
The translation teams can customize these entities by redefining
the articles.ent file in <langcode>/share/sgml. See
ja_JP.eucJP/share/sgml for example.
270 lines
11 KiB
Text
270 lines
11 KiB
Text
<!--
|
|
The FreeBSD Documentation Project
|
|
-->
|
|
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
|
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
|
|
%articles.ent;
|
|
]>
|
|
|
|
<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>
|
|
|
|
<legalnotice id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.cvsup;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<abstract>
|
|
<para>The present article assumes a basic understanding of <application>CVSup</application>
|
|
operation. It documents several delicate issues connected with
|
|
source synchronization via <application>CVSup</application>, 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 <application>CVSup</application> & 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 <quote>photograph</quote>. This
|
|
significant information enables <command>cvsup</command> to retrieve updates most
|
|
effectively. Further, and maybe more important, it enables <command>cvsup</command>
|
|
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, <command>cvsup</command> would
|
|
<emphasis>not</emphasis> 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
|
|
got your installation CD-ROMs.</para>
|
|
|
|
<para>It is therefore recommended that you adopt the two-step procedure
|
|
outlined in the <application>CVSup</application> 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: <command>cvsupchk</command></title>
|
|
|
|
<para>Alternatively, in order to examine your sources for
|
|
inconsistencies, you may wish to utilize the <command>cvsupchk</command> 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, <command>cvsupchk</command> 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 <literal>tag=A</literal> in your <filename>supfile</filename>, <command>cvsup</command> will create
|
|
a checkouts file called <filename>checkouts.cvs:A</filename>:
|
|
for instance, if <literal>tag=RELENG_4</literal>, 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 <literal>tag=A</literal> to <literal>tag=B</literal> (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 <filename>supfile</filename> whose collection line reads:</para>
|
|
<programlisting>src-all tag=B</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>cvsup your sources using the new <filename>supfile</filename>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The <command>cvsup</command> utility will look for <filename>checkouts.cvs:B</filename>—in
|
|
that the target is B; that is, <command>cvsup</command> 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 <command>cvsup</command>
|
|
operates in the most efficient way.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
|
|
<para>For example, <literal>A=RELENG_4</literal>, <literal>B=.</literal>. The period in <literal>B=.</literal> means
|
|
-CURRENT. This is a rather typical update, from 4-STABLE
|
|
to -CURRENT. While it is straightforward to <quote>downgrade</quote> 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 <literal>tag=A</literal> to <literal>tag=A</literal> as of a
|
|
different GMT date (say, <literal>date=D</literal>), you will execute the
|
|
following:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>write a <filename>supfile</filename> whose collection line reads:</para>
|
|
<programlisting>src-all tag=A date=D</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>update your sources using the new <filename>supfile</filename></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Whether the new date precedes that of the last sync
|
|
operation with <literal>tag=A</literal> or not, it is immaterial. For example,
|
|
in order to specify the date <quote>August 27, 2000, 10:00:00 GMT</quote>
|
|
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 (<quote>20</quote>, ie the 21st
|
|
century, must be supplied whereas <quote>19</quote>, 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 <filename>supfile</filename>,
|
|
and run <command>csvup</command> again.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2>
|
|
<title>Updating your ports collection for the first time</title>
|
|
|
|
<para>Since ports are tagged <quote>.</quote> (ie -CURRENT), you can
|
|
correctly <quote>sync</quote> 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 <quote>shipping</quote> of
|
|
your ports tree. After <command>cvsup</command> 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 trouble in a source updating process.
|
|
A number of people have actually run into problems. You have
|
|
been warned. :-)</para>
|
|
</sect2>
|
|
</sect1>
|
|
</article>
|