os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add article on advanced CVSup usage.

Browse source 
PR:		docs/31169
Submitted by:	Salvo Bartolotta <bartequi@neomedia.it>
This commit is contained in:
Murray Stokely 2001-10-10 21:38:30 +00:00
parent ffb6aa551a
commit a70a4d71d7
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=10914
3 changed files with 285 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
en_US.ISO8859-1/articles/Makefile
View file

@ -1,9 +1,10 @@
# $FreeBSD: doc/en_US.ISO8859-1/articles/Makefile,v 1.18 2001/09/17 03:25:05 murray Exp $
# $FreeBSD: doc/en_US.ISO8859-1/articles/Makefile,v 1.19 2001/10/08 06:19:13 murray Exp $
SUBDIR = committers-guide
SUBDIR+= console-server
SUBDIR+= contributing
SUBDIR+= contributors
SUBDIR+= cvsup-advanced
SUBDIR+= dialup-firewall
SUBDIR+= diskless-x
SUBDIR+= explaining-bsd

16
en_US.ISO8859-1/articles/cvsup-advanced/Makefile Normal file
View file

@ -0,0 +1,16 @@
# $FreeBSD$
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
JADEFLAGS+= -V %generate-article-toc%
SRCS= article.sgml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

267
en_US.ISO8859-1/articles/cvsup-advanced/article.sgml Normal file
View file

@ -0,0 +1,267 @@
<!--
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.&nbsp;:-)
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 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>
</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>
<para>N.B. 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>
<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>