diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile index 57e2e14184..233345a467 100644 --- a/en_US.ISO8859-1/articles/Makefile +++ b/en_US.ISO8859-1/articles/Makefile @@ -1,30 +1,31 @@ -# $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 SUBDIR+= filtering-bridges SUBDIR+= freebsd-questions SUBDIR+= fonts SUBDIR+= formatting-media SUBDIR+= ipsec-must SUBDIR+= laptop SUBDIR+= mh SUBDIR+= multi-os SUBDIR+= new-users SUBDIR+= programming-tools SUBDIR+= pxe SUBDIR+= serial-uart SUBDIR+= solid-state SUBDIR+= storage-devices SUBDIR+= vm-design SUBDIR+= zip-drive # ROOT_SYMLINKS+= new-users DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/cvsup-advanced/Makefile b/en_US.ISO8859-1/articles/cvsup-advanced/Makefile new file mode 100644 index 0000000000..27aeb7f607 --- /dev/null +++ b/en_US.ISO8859-1/articles/cvsup-advanced/Makefile @@ -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" diff --git a/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml b/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml new file mode 100644 index 0000000000..2502d1fefe --- /dev/null +++ b/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml @@ -0,0 +1,267 @@ + + + +%man; +]> + +
+ + CVSup Advanced Points + + + + Salvo + Bartolotta + + +
bartequi@neomedia.it
+ + + + + $FreeBSD$ + + + 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. + + + + + Preface + + 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, bartequi@neomedia.it. + + + + + Introduction + + If you have visited + John Polstra's site + and read + his +FAQ, + you may have noticed Question 12 & 13. + + When updating any collection of sources (eg + /usr/ports), &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 + (/usr/ports), the related checkouts file + is /usr/sup/ports-all/checkouts.cvs:. if + your base is /usr. + + 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. + + 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. + + + + A useful python script: cvsupchk + + Alternatively, in order to examine your sources for + inconsistencies, you may wish to utilize the cvsupchk python + script; which script is currently found in + /usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk, + together with a nice README. Prerequisites: + + + + /usr/ports/net/cvsup &prompt.root; + make extract + + + + python (also found in the ports collection :-)) + + + + a checkouts file for your collection of sources. + + + + 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 /usr/ports), + you can check them thus: + + &prompt.user; /path/to/cvsupchk +-d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more + + If you want to check your RELENG_4 sources: + + &prompt.user; /path/to/cvsupchk +-d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more + + 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. + + 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. + + + + Examples of more advanced source management + + + How to safely change tags when updating +<literal>src-all.</literal> + + If you specify eg tag=A in your supfile, cvsup will create + a checkouts file called checkouts.cvs:A: + for instance, if tag=RELENG_4, a checkouts file called + checkouts.cvs:RELENG_4 is generated. + This file will be used to retrieve and/or store identification + information on your 4-STABLE sources. + + When tracking src-all, 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 + checkouts.cvs:A, the following actions + should be performed: + + + + &prompt.root; mv checkouts.cvs:A +checkouts.cvs:B + (This provides the subsequent step with the appropriate + checkouts file) + + + + write a supfile whose collection line reads: + src-all tag=B + + + + cvsup your sources using the new supfile. + + + + Cvsup will look for checkouts.cvs:B + -- in that the target is B; that is, cvsup will make use of + the information contained therein to correctly manage your + sources. + + The benefits: + + + + the sources are dealt with correctly (in particular, + no stale files) + + + + less load is placed on the server, in that cvsup + operates in the most efficient way. + + + + + 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. + + + + Updating to the same tag as of a different date + + 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: + + + + write a supfile whose collection line reads: + src-all tag=A date=D + + + + update your sources using the new supfile + + + + 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: + + + src-all tag=RELENG_4 +date=2000.08.27.10.00.00 + + 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;. + + Whether or not a date is specified, the checkouts file + is called checkouts.cvs:A (eg + checkouts.cvs:RELENG_4). 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. + + + + + Updating your ports collection for the first time + + 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. + + 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. :-) + + +