SUBDIR+= cvsup-advanced

#                                                                               

#    The FreeBSD Documentation Project                                          

#    The FreeBSD French Documentation Project                                   

#                                                                               

#    $FreeBSD: doc/en_US.ISO8859-1/articles/cvsup-advanced/Makefile,v 1.1 2001/10/10 21:38:30 murray Exp $

#    Original revision: 1.1                                                     

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"

<!--

      The FreeBSD Documentation Project

      The FreeBSD French Documentation Project

      $FreeBSD$

      $Id$

      Original revision: 1.4

-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">

%man;

<!ENTITY % abstract PUBLIC "-//FreeBSD//ENTITIES DocBook Abstract Entities//FR"> %abstract;

<!ENTITY % artheader PUBLIC "-//FreeBSD//ENTITIES DocBook ArtHeader Entities//FR"> %artheader;

<!ENTITY % translators PUBLIC "-//FreeBSD//ENTITIES DocBook Translator Entities//FR"> %translators;

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man;

]>

<article>

  <articleinfo>

    <title>Utilisation avanc&eacute;e de cvsup</title>

    <authorgroup>

      <author>

	<firstname>Salvo</firstname>

	<surname>Bartolotta</surname>

	<affiliation>

	  <address><email>bartequi@neomedia.it</email></address>

	</affiliation>

      </author>

    </authorgroup>

    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml,v 1.4 2001/10/23 21:31:18 murray Exp $</pubdate>

    <abstract>

      <para>Le pr&eacute;sent article suppose une compr&eacute;hension 

	de base de l'utilisation de <application>cvsup</application>.  

	Il expose plusieurs problèmes délicats  

        liés à la synchronisation des sources à 

	l'aide de <application>cvsup</application>, c'est &agrave;

	dire des solutions efficaces aux problèmes des fichiers

	obsolètes aussi bien qu'aux cas spéciaux de mise 

	à jour des sources, ces problèmes sont susceptibles 

	de causer des désagréments apparamment 

	inexplicables.</para>

	&abstract.license;

        &abstract.disclaimer;

        &trans.a.fonvieille;

    </abstract>

  </articleinfo>

  <sect1 id="preface">

    <title>Pr&eacute;face</title>

      <para>Ce document est le fruit des tentatives de l'auteur de

	comprendre les finesses de <application>cvsup</application> et 

	de la mise à jour des sources. :-)

	Bien que l'auteur ait fait de nombreux efforts pour

	rendre ces pages aussi instructives et correctes que possible,

	il n'est qu'un être humain et a pu avoir commis toutes sortes

	de coquilles, d'erreurs, etc...  Il sera vraiment reconnaissant 

	pour tous les commentaires et/ou suggestions que vous enverrez 

	à son adresse électronique 

	<email>bartequi@neomedia.it</email>.</para>

  </sect1>

  <sect1 id="introduction">

    <title>Introduction</title>

      <para>Si vous avez consult&eacute; le <ulink

	url="http://www.polstra.com/">site de John Polstra</ulink> et lu

	sa <ulink

	url="http://www.polstra.com/projects/freeware/CVSup/faq.html">FAQ</ulink>,

	vous avez pu avoir remarqu&eacute; les questions 12 et 13.</para>

      <para>En mettant &agrave; jour n'importe quelle &ldquo;catalogue&rdquo; 

	- collection de sources (e.g. <filename>/usr/ports</filename>), 

	&man.cvsup.1; se sert des fichiers de “checkouts” 

	relatifs afin d'effectuer le processus de mise à jour de la 

	manière la plus efficace et la plus correcte possible.  Dans cet 

	exemple (<filename>/usr/ports</filename>), le fichiers de

	“checkouts” relatif est

	<filename>/usr/sup/ports-all/checkouts.cvs:.</filename> si votre

	r&eacute;pertoire de base est <filename>/usr</filename>.</para>

      <para>Un fichier &ldquo;checkouts&rdquo; contient l'information

	sur l'état actuel de vos sources -- d'une certaine 

	manière, une sorte de “photographie”.  Cette 

	information permet &agrave; <application>cvsup</application> de 

	rechercher les mises à jour le plus efficacement.  De 

	plus, et c'est peut-être plus important, il permet 

	&agrave; <application>cvsup</application> de g&eacute;rer 

	correctement vos sources en effaçant localement tout

	fichier qui n'est plus présent sur l'archive centrale, 

	et de ce fait ne pas laisser de fichiers obsolètes sur 

	votre système.  En fait, sans un fichier 

	&ldquo;checkouts&rdquo;, <application>cvsup</application> ne

	saurait PAS de quels fichiers votre catalogue est composé 

	(Cf &man.cvsup.1; pour plus de détails), et en 

	conséquence, il ne pourrait PAS effacer de votre 

	système ces fichiers qui ne sont plus présents sur 

	l'archive centrale.  Ils resteraient sur votre système 

	(les fichiers obsolètes), et pourraient vous causer de 

	subtiles échecs de compilation ou tout autre 

	désagrément.  Par exemple, ce problème est 

	susceptible de se produire si vous mettez à jour votre 

	catalogue de logiciels portés plusieurs semaines 

	apr&egrave;s que vous ayez eu vos CDROMs d'installation.</para>

     <para>Il est donc recommand&eacute; que vous adoptiez la 

       procédure en deux temps décrite dans la FAQ de 

       CVSup (Cf Q12, Q13); dans les sections suivantes, on vous 

       présentera des exemples concrets intéressant et 

       instructifs.</para>

  </sect1>

  <sect1 id="script">

    <title>Une proc&eacute;dure python utile: cvsupchk</title>

      <para>Alternativement, afin d'examiner les sources pour les

	inconsistences, vous pouvez souhaiter utiliser la procédure

	python <application>cvsupchk</application>, proc&eacute;dure qui se 

	trouve actuellement dans

	<filename>/usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk</filename>,

	avec un sympathique <filename>README</filename>.

	Pr&eacute;requis:</para>

        <orderedlist>

           <listitem>

             <para><literal>/usr/ports/net/cvsup</literal> &prompt.root;

<userinput> make extract</userinput></para>

           </listitem>

           <listitem>

             <para>python (que l'on trouve &eacute;galement dans le catalogue

	       des logiciels port&eacute;s :-)).</para>

           </listitem>

           <listitem>

             <para>Un fichier &ldquo;checkouts&rdquo; pour votre

	       catalogue des sources.</para>

           </listitem>

         </orderedlist>

      <para>Si vous mettez &agrave; jour vos sources pour la toute 

	première fois, naturellement vous n'avez pas de fichier

	“checkouts”.  Après l'installation de python 

	et la mise à jour de vos sources (e.g.

	<filename>/usr/ports</filename>), vous pouvez les v&eacute;rifier

	ainsi:</para>

        <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more</userinput></screen>

      <para>Si vous d&eacute;sirez v&eacute;rifier vos sources RELENG_4:</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>Dans chaque cas, <application>cvsupchk</application> 

	inspectera vos sources à la

	recherche d'inconsistences en utilisant les informations

	contenues dans le fichier de “checkouts” relatif.

	Des anomalies comme des fichiers effacés, encore 

	présents (aka fichiers obsolètes), fichiers 

	récupérés absents, fichiers RCS

	supplémentaires, et répertoires vides seront 

	affich&eacute;s sur la sortie standard.</para>

      <para>Dans la section suivante, nous pr&eacute;senterons des exemples

	typiques de la mise à jour de source, exemples qui vous

	montreront le rôle des fichiers de “checkouts” 

	et les dangers d'une gestion n&eacute;glig&eacute;e des sources.</para>

  </sect1>

  <sect1 id="examples">

    <title>Exemples avanc&eacute;s de gestion des sources</title>

      <sect2>

        <title>Comment modifier sans risques le champ tag quand vous

	  mettez &agrave; jour <literal>src-all</literal></title>

        <para>Si vous sp&eacute;cifiez par exemple <literal>tag=A</literal>

	  dans votre fichier <filename>supfile</filename>,

	  <application>cvsup</application> cr&eacute;era

	  un fichier “checkouts” appelé

	  <filename>checkouts.cvs:A</filename>, par exemple avec le

	  champ <literal>tag=RELENG_4</literal>, un fichier de

	  “checkouts”

	  <filename>checkouts.cvs:RELENG_4</filename> est 

	  généré.  Ce fichier sera utilisé 

	  pour récupérer et/ou stocker

	  l'information identifiant vos sources 4-STABLE.</para>

         <para>En suivant le catalogue <literal>src-all</literal>, si

	   vous souhaitez passer de <literal>tag=A</literal> &agrave;

	   <literal>tag=B</literal> (A inf&eacute;rieur/sup&eacute;rieur 

	   à B important peu) et si votre fichier 

	   “checkouts” est

	   <filename>checkouts.cvs:A</filename>, les op&eacute;rations

	   suivantes devront &ecirc;tre effectu&eacute;es:</para>

            <orderedlist>

              <listitem>

                <para>&prompt.root; <userinput>mv checkouts.cvs:A

checkouts.cvs:B</userinput>

                  (ceci fournit à l'étape suivante le fichier

		  &ldquo;checkouts&rdquo; appropri&eacute;)</para>

              </listitem>

              <listitem>

                <para>Ecrivez un fichier <filename>supfile</filename>

		  dont la ligne d&eacute;signant le catalogue est:</para>

                  <programlisting>src-all tag=B</programlisting>

              </listitem>

              <listitem>

                <para>Cvsupez vos sources en utilisant le nouveau

		<filename>supfile</filename>.</para>

              </listitem>

            </orderedlist>

         <para>Cvsup recherchera <filename>checkouts.cvs:B</filename> 

	   -- dans ce cas la cible est B, c'est à dire que

	   <application>cvsup</application> se 

	   servira des informations contenus dans ce fichier pour gérer

	   correctement vos sources.</para>

         <para>Les avantages:</para>

           <itemizedlist>

              <listitem>

                <para>Les sources sont trait&eacute;es correctement (en

		  particulier aucun fichiers obsol&egrave;tes).</para>

              </listitem>

              <listitem>

                <para>Moins de charge sur le serveur, dans ce cas

		<application>cvsup</application>

		  agit de la mani&egrave;re la plus efficace.</para>

              </listitem>

           </itemizedlist>

         <para>Par exemple, <literal>A=RELENG_4</literal>,

	   <literal>B=.</literal>, le point dans <literal>B=.</literal>

	   signifie -CURRENT.  C'est une mise à jour plutôt 

	   typique de la branche 4-STABLE vers la branche -CURRENT.  

	   Alors qu'il est simple de revenir à une ancienne 

	   version de sources (e.g. -CURRENT vers -STABLE), il n'en va 

	   pas de même avec le système.  Vous êtes 

	   FORTEMENT déconseillé de tenter une telle

	   opération, à moins que vous ne sachiez 

	   exactement ce que vous faites.</para>

       </sect2>

       <sect2>

         <title>Mettre &agrave; jour en conservant le m&ecirc;me champ 

	   tag mais pour une date diff&eacute;rente</title>

         <para>Si vous souhaitez basculer du champ <literal>tag=A</literal> 

	   au champ <literal>tag=A</literal> avec une date GMT

	   diff&eacute;rente (disons <literal>date=D</literal>) vous 

	   ex&eacute;cuterez ce qui suit:</para>

           <orderedlist>

             <listitem>

               <para>Ecrivez un <filename>supfile</filename> dont la

		 ligne d&eacute;signant le catalogue est:</para>

                 <programlisting>src-all tag=A date=D</programlisting>

             </listitem>

             <listitem>

               <para>Mettez &agrave; jour vos sources en utilisant le nouveau

		 <filename>supfile</filename>.</para>

             </listitem>

           </orderedlist>

         <para>Que la nouvelle date pr&eacute;c&egrave;de ou non celle 

	   de la dernière synchronisation avec le champ 

	   <literal>tag=A</literal> est peu important.  Par exemple, 

	   afin d'indiquer la date du “27 Août 2000 à 

	   10h00s00 GMT&rdquo; vous &eacute;crirez la ligne:</para>

         <programlisting>src-all tag=RELENG_4 date=2000.08.27.10.00.00</programlisting>

         <note><para>Le format de la date est rigide.  Vous devez

	   indiquer toutes les composantes de la date: le siècle 

	   (20, i.e. le vingtième siècle, doit être 

	   fourni tandis que 19, le siècle passé peut 

	   être omis), l'année, le mois, le jour, l'heure, 

	   les minutes et les secondes -- comme montré dans

	   l'exemple ci-dessus.  Pour plus d'information, veuillez

	   consulter la page de manuel &man.cvsup.1;.</para></note>

         <para>Qu'une date soit sp&eacute;cifi&eacute;e ou non, le fichier

	   “checkouts” est appelé

	   <filename>checkouts.cvs:A</filename> (e.g.

	   <filename>checkouts.cvs:RELENG_4</filename>).  Comme

	   conséquence, aucune action particulière n'est 

	   nécessaire afin de retourner à l'état 

	   précédent: vous devez modifier la date

	   dans le <filename>supfile</filename> et remettre &agrave; 

	   jour &agrave; nouveau.</para>

       </sect2>

       <sect2>

         <title>Mise &agrave; jour de votre catalogue des logiciels 

	   port&eacute;s pour la premi&egrave;re fois</title>

         <para>Comme les logiciels port&eacute;s sont 

	   étiquetés “.” (i.e. -CURRENT), 

	   vous pouvez correctement les synchroniser en

	   ajoutant le mot-cl&eacute; <literal>date</literal> (Cf 

	   &man.cvsup.1; pour le format exact), vous devriez 

	   spécifier une date aussi proche que possible que celle 

	   de “l'expédition” de votre catalogue de 

	   logiciel porté.  Après que cvsup ait

	   crée le fichier “checkouts” du catalogue des

	   logiciels portés, qui est précisément le 

	   but de cette première opération de synchronisation, 

	   le champ <literal>date</literal> doit &ecirc;tre retir&eacute;, 

	   toutes les mises à jour suivantes seront faites en 

	   douceur.</para>

         <para>Si vous avez voulu chercher la petite b&ecirc;te dans ce texte,

	   vous vous êtes probablement aperçu des 

	   problèmes potentiels du processus de mise à jour des 

	   sources.  Un certain nombre de personnes ont eu réellement 

	   des problèmes.  Vous avez été

	   avertis. :-)</para>

      </sect2>

   </sect1>

</article>