cvs.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->
<!-- SAS : 20070322, PG8.2.3 -->

<appendix id="cvs">
 <appendixinfo>
  <authorgroup>
   <author>
    <firstname>Marc</firstname>
    <surname>Fournier</surname>
   </author>
   <author>
    <firstname>Tom</firstname>
    <surname>Lane</surname>
   </author>
   <author>
    <firstname>Thomas</firstname>
    <surname>Lockhart</surname>
   </author>
   <author>
    <firstname>David</firstname>
    <surname>Fetter</surname>
   </author>
  </authorgroup>
  <date>1999-05-20</date>
 </appendixinfo>

 <title>Dépôt <productname>CVS</productname></title>

 <para>
  Le code source de <productname>PostgreSQL</productname> est stocké et géré à
  l'aide du système de contrôle de version <productname>CVS</productname>
  (<foreignphrase>Concurrent Version Control System</foreignphrase>).
 </para>

 <para>
  Il existe au moins trois méthodes,
  CVS anonyme, <productname>rsync</productname> et <productname>CVSup</productname>,
  pour extraire de <productname>CVS</productname> l'arborescence du
  code source du serveur <productname>PostgreSQL</productname> vers une
  machine locale.
  La <ulink
  url="http://wiki.postgresql.org/index.php/Working_with_CVS">page wiki</ulink>
  contient des informations supplémentaires sur le travail avec CVS.
 </para>

 <sect1 id="anoncvs">
  <title>Obtenir les sources via <productname>CVS</productname> anonyme</title>

  <para>
    Pour conserver une arborescence locale à jour, il suffit de
    descendre les sources depuis le serveur <productname>CVS</productname>, et d'utiliser
    <productname>CVS</productname> pour récupérer les mises à jour de temps
    en temps.
  </para>

  <procedure>
   <title>CVS anonyme</title>

   <step>
    <para>
     Une copie locale de <productname>CVS</productname> est nécessaire. Elle
     peut être récupérée depuis
     <ulink url="http://www.nongnu.org/cvs/"></ulink> (le
     site officiel avec la dernière version) ou depuis n'importe quel site
     d'archive GNU (parfois pas à jour). Différents systèmes proposent une version
     récente de <application>cvs</application> installée par défaut.
    </para>
   </step>

   <step>
    <para>
     Connexion initiale au serveur
     <productname>CVS</productname>&nbsp;:

     <programlisting>cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login</programlisting>

     Un mot de passe est demandé. Cela peut être n'importe quelle chaîne de
     caractères, à l'exception d'une chaîne vide.
    </para>

    <para>
     Il n'est plus nécessaire, alors, de reproduire cette opération, car le
     mot de passe est sauvegardé dans le fichier <filename>.cvspass</filename>
     du répertoire personnel.
    </para>
   </step>

   <step>
    <para>
     Récupération des sources de <productname>PostgreSQL</productname>&nbsp;:
     <programlisting>cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql</programlisting>

     Les sources de <productname>PostgreSQL</productname> sont ainsi copiées dans un 
     sous-répertoire <filename>pgsql</filename> du répertoire courant.

     <note>
      <para>
       Si une connexion rapide à Internet est disponible, il n'est pas
       nécessaire d'utiliser l'option <option>-z3</option>, qui demande à 
       <productname>CVS</productname> de compresser les données à transférer
       avec <command>gzip</command>.
       Mais à la vitesse d'un modem, cela permet un gain de temps substantiel.
      </para>
     </note>
    </para>

    <para>
     Cette extraction initiale est un peu plus lente que le simple
     téléchargement d'un fichier <filename>tar.gz</filename>&nbsp;; il est
     probable que cela prenne
     40 minutes environ avec un modem à 28,8&nbsp;Kbps. L'avantage de
     <productname>CVS</productname> n'apparaît que plus tard, lors de la
     mise à jour des fichiers.
    </para>
   </step>

   <step>
    <para>
     Pour mettre à jour les sources <productname>CVS</productname>
     avec la dernière version, se placer dans le sous-répertoire
    <filename>pgsql</filename> (<command>cd</command>) et lancer la commande
     <programlisting>cvs -z3 update -d -P</programlisting>.

     Seules les modifications qui ont eu lieu depuis la dernière
     mise à jour sont récupérées. La mise à jour ne dure généralement
     que quelques minutes, même avec un simple modem.
    </para>
   </step>

   <step>
    <para>
     La création d'un fichier <filename>.cvsrc</filename> dans le répertoire
     personnel ($HOME) permet d'économiser quelques saisies. Il suffit de lui
     ajouter&nbsp;:
     <programlisting>cvs -z3
update -d -P</programlisting>

     Ceci ajoute l'option <option>-z3</option> à toutes les commandes
     <command>cvs</command>, et les options <option>-d</option> et
     <option>-P</option> aux commandes <command>cvs update</command>. Il
     suffit désormais de lancer <programlisting>cvs update</programlisting>
     pour actualiser les fichiers.
    </para>
   </step>
  </procedure>

  <para>
   <productname>CVS</productname> peut faire de nombreuses autres
   choses, comme retrouver des versions antérieures des sources de
   <productname>PostgreSQL</productname> plutôt que les dernières
   versions de développement.
   Pour plus d'informations, consulter le manuel de
   <productname>CVS</productname> ou lire la documentation en
   ligne à <ulink url="http://www.nongnu.org/cvs/"></ulink>.
  </para>

  <para>
   <productname>CVS</productname> a des inconvénients. Par exemple, la
   génération de fichiers diff qui ajoutent ou suppriment des fichiers requière un
   accès en écriture au dépôt CVS. Pour contourner ce problème, on peut utiliser
   <productname>cvsutils</productname> qui est disponible sur plusieurs
   systèmes d'exploitation et au format source sur <ulink
   url="http://www.red-bean.com/cvsutils/"></ulink>.
  </para>

  <para>
   La construction de <productname>PostgreSQL</productname> à partir
   de la version CVS nécessite des versions à jour de
   <application>bison</application> et <application>flex</application>, versions
   qui ne sont pas nécessaire pour la contruction des sources à partir d'une
   archive tar car les fichiers qu'ils créent sont pré-construits dans une
   archive tar. Pour le reste, les outils nécessaires sont identiques.
  </para>
 </sect1>

 <sect1 id="cvs-tree">
  <title>Organisation de l'arbre <productname>CVS</productname></title>

  <para>
   <note>
    <title>Auteur</title>
    <para>
     Écrit par Marc G. Fournier (<email>scrappy@hub.org</email>) 
     le 05/11/1998.
    </para>
   </note>
  </para>

  <para>
   La commande <command>cvs checkout</command> accepte un paramètre, <option>-r</option>,
   qui permet d'obtenir une révision particulière d'un module. Il est
   possible, par exemple, de retrouver les fichiers sources de la
   version 6_4 du module 'tc'.

   <programlisting>cvs checkout -r REL6_4 tc</programlisting>
   C'est en particulier utile si quelqu'un pense qu'il y a un bogue
   dans cette version, mais qu'il n'apparaît pas dans
   la version courante.

   <tip>
    <para>
     Un module peut également être extrait tel qu'il était à une date
     donnée en utilisant l'option <option>-D</option>.
    </para>
   </tip>
  </para>

  <para>
   Lorsqu'une même marque est utilisée sur plusieurs fichiers,
   celle-ci peut être vue comme 
   <quote>une courbe tracée dans la matrice des noms de fichiers et
   des numéros de révision</quote>. Soient 5 fichiers avec
   les révisions suivantes&nbsp;:

   <programlisting>             fichier1 fichier2 fichier3 fichier4 fichier5

             1.1      1.1      1.1      1.1  /---1.1*    &lt;-*-  MARQUE
             1.2*-    1.2      1.2    --1.2*-
             1.3  \-- 1.3*-    1.3   /  1.3
             1.4           \   1.4  /   1.4
                            \--1.5*-    1.5
                               1.6</programlisting>

   alors la marque <literal>MARQUE</literal> référence
   fichier1-1.2, fichier2-1.3, etc.

   <note>
    <para>
     Pour créer une branche de version, à part l'option <literal>-b</literal>
     ajoutée sur la ligne de commande, c'est la même chose.</para>
    </note>
  </para>

  <para>
   Ainsi, pour créer la version 6.4&nbsp;:

   <programlisting>cd pgsql
cvs tag -b REL6_4</programlisting>
   ce qui crée la marque et la branche pour l'arbre de VERSION.
  </para>

  <para>
   Pour ceux qui disposent d'un accès <productname>CVS</productname>, il est
   facile de créer des répertoires séparés pour chaque version.
   D'abord, on crée deux répertoires, VERSION et COURANT, afin de ne
   pas les mélanger. Puis&nbsp;:

   <programlisting>cd VERSION
cvs checkout -P -r REL6_4 pgsql
cd ../COURANT
cvs checkout -P pgsql</programlisting>

   Cela crée deux arbres de répertoires, <filename>VERSION/pgsql</filename> et
   <filename>COURANT/pgsql</filename>. À partir de ce moment,
   <productname>CVS</productname> sait quel arbre de
   référence est dans quel répertoire, et permet des mises à jour
   indépendantes de chaque arbre.
  </para>

  <para>
   Pour ne travailler <emphasis>que</emphasis> sur l'arbre
   <literal>COURANT</literal>, il suffit de suivre ce qui est indiqué jusqu'à
   la partie traitant du marquage des branches de versions.
  </para>

  <para>
   Après avoir fait l'extraction initiale d'une branche&nbsp;:

   <programlisting>cvs checkout -r REL6_4</programlisting>

   tout ce qui est fait dans ce répertoire est limité à cette branche.
   Un correctif appliquée à cette structure de répertoires
   suivi d'un&nbsp;:

   <programlisting>cvs commit</programlisting>

   dans ce répertoire, n'applique le correctif qu'à cette branche et
   <emphasis>uniquement</emphasis> à cette branche.
  </para>
 </sect1>

 <sect1 id="rsync">
  <title>Obtenir les sources via <productname>rsync</productname></title>

  <para>
   Une autre façon d'utiliser le CVS anonyme pour récupérer les sources de
   <productname>PostgreSQL</productname> est
   <productname>rsync</productname>, un outil de transfert incrémental de
   fichiers. Un avantage majeur à utiliser
   <productname>rsync</productname> est qu'il peut répliquer de façon fiable
   le dépôt CVS <emphasis>complet</emphasis> sur le système local, permettant
   ainsi un accès local rapide aux opérations <command>cvs</command> telles que
   <option>log</option> et <option>diff</option>. Un autre avantage est la
   synchronisation rapide avec le serveur
   <productname>PostgreSQL</productname> grâce à un protocole de transfert
   efficace qui n'envoie que les modifications depuis la dernière mise à jour.
  </para>

  <para>
   Le dépôt CVS peut être récupéré à l'aide de la commande&nbsp;:
<programlisting>
rsync -avzH --delete anoncvs.postgresql.org::pgsql-cvs cvsroot/
</programlisting>
   Pour des instructions complètes, lire la section «&nbsp;rsync&nbsp;» dans
   les
   <ulink url="http://pgfoundry.org/docman/view.php/1000040/4/PGBuildFarm-HOWTO.txt">
   instructions de pgbuildfarm</ulink>.
  </para>
 </sect1>

 <sect1 id="cvsup">
  <title>Obtenir les sources via <productname>CVSup</productname></title>

  <para>
   Une alternative au CVS anonyme pour obtenir l'arbre source de 
   <productname>PostgreSQL</productname> est
   <productname>CVSup</productname>.
   <productname>CVSup</productname> a été développé par John Polstra
   (<email>jdp@polstra.com</email>) pour distribuer des arbres de
   référence CVS et autres arborescences de fichiers pour le
   <ulink url="http://www.freebsd.org">projet FreeBSD</ulink>.
  </para>

  <sect2>
   <title>Préparer un système client <productname>CVSup</productname></title>

   <para>
    Deux groupes de répertoires sont nécessaires à
    <productname>CVSup</productname>&nbsp;: un entrepôt contenant le
    référentiel <productname>CVS</productname> local (ou simplement
    un groupe de répertoires si seul un extrait est récupéré et non
    le référentiel complet&nbsp;; voir plus loin) et une zone de stockage
    propre à <productname>CVSup</productname>. Ces deux groupes de
    répertoires peuvent coexister dans la même arborescence.
   </para>

   <para>
    Il faut alors décider de l'emplacement de la copie locale du référentiel
    <productname>CVS</productname>. Sur un de ses systèmes, l'auteur
    a créé un référentiel dans
    <filename>/home/cvs/</filename>, mais utilisait jusque-là
    <filename>/opt/postgres/cvs/</filename> comme arbre de développement
    pour <productname>PostgreSQL</productname>. Pour
    placer le référentiel dans <filename>/home/cvs/</filename>,
    ajouter&nbsp;:

    <programlisting>setenv CVSROOT /home/cvs</programlisting>

    dans le fichier <filename>.cshrc</filename>, <filename>.bashrc</filename>
    ou dans <filename>.profile</filename>, en fonction de l'interpréteur
    de commandes (shell).
   </para>

   <para>
    Le dépôt <application>cvs</application> doit
    être initialisé. Une fois <envar>CVSROOT</envar>
    initialisée, il suffit de faire&nbsp;:

    <programlisting>cvs init</programlisting>

    après quoi devrait au moins exister un répertoire
    <filename>CVSROOT</filename>&nbsp;:

    <programlisting>$ ls $CVSROOT
CVSROOT/</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Utiliser un client <productname>CVSup</productname></title>

   <para>
    Vérifier que <application>cvsup</application> est dans le
    chemin (<foreignphrase>path</foreignphrase>). Sur la plupart des systèmes,
    cela se fait en tapant&nbsp;:

    <programlisting>which cvsup</programlisting>

    Lancer alors
    <application>cvsup</application>&nbsp;:

    <programlisting>cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable></programlisting>

    où <option>-L 2</option> active certains messages de statut pour
    suivre la progression de la mise à jour et
    <replaceable class="parameter">postgres.cvsup</replaceable> représente
    la chemin et le nom donnés au fichier de
    configuration <productname>CVSup</productname>.
   </para>

   <para>
    Un fichier de configuration <productname>CVSup</productname>
    modifié pour une installation spécifique, qui maintient un
    référentiel <productname>CVS</productname> local complet est présenté
    ci-après.

    <programlisting># Ce fichier représente le fichier de distribution CVSup standard
# pour le projet de SGBDRO <productname>PostgreSQL</productname>
# Modifié par lockart@fourpalms.org 1997-08-28
# - Pointe vers mon arborescence locale
# - Extrait le référentiel CVS complet, pas seulement la
#   dernière version
#
#Valeurs par défaut qui s'appliquent à toutes les collections
*default host=cvsup.postgresql.org
*default compress
*default release=cvs
*default delete use-rel-suffix
# Activer la ligne suivante pour récupérer la dernière version
#*default tag=.
# Activer la ligne suivante pour récupérer ce qui est précisé ci-dessus ou 
# par défaut à la date précisée ci-dessous
#*default date=97.08.29.00.00.00

# répertoire de base où CVSup stocke ses fichiers 'marque page'
# créera un sous répertoire sup/
#*default base=/opt/postgres # /usr/local/pgsql
*default base=/home/cvs

# répertoire préfixe où CVSup stocke les distributions
*default prefix=/home/cvs

# Distribution complète, avec tout ce qui est en dessous
pgsql

# distributions partielles
# pgsql-doc
# pgsql-perl5
# pgsql-src</programlisting>
   </para>

   <para>
    Si <option>repository</option> est indiqué à la place de <option>pgsql</option> dans la
    configuration précédente, une copie complète du dépôt 
    cvsup.postgresql.org est récupérée. Ce qui inclut le répertoire <filename>CVSROOT</filename>.
    Il faut alors probablement exclure du
    répertoire les fichiers qui seront modifiés localement. Pour cela,
    on utilise un fichier de refus. Par exemple, pour la configuration
    précédente, on peut avoir dans le fichier 
    <filename>/home/cvs/sup/repository/refuse</filename>&nbsp;:
<programlisting>CVSROOT/config*
CVSROOT/commitinfo*
CVSROOT/loginfo*</programlisting>
    Voir les pages man de <productname>CVSup</productname> pour savoir comment utiliser
    les fichiers de refus.
</para>

   <para>
    Ce qui suit est une suggestion de fichier de configuration 
    <productname>CVSup</productname> issue du
    <ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
    site FTP</ulink> de <productname>PostgreSQL</productname>, qui
    ne récupère que la version courante&nbsp;:

    <programlisting># Ce fichier représente la distribution CVSup standard pour le
# projet de SGBDRO <productname>PostgreSQL</productname>.
#
# Valeurs par défaut qui s'appliquent à toutes les collections.
*default host=cvsup.postgresql.org
*default compress
*default release=cvs
*default delete use-rel-suffix
*default tag=.

# répertoire de base où CVSup stocke ses fichiers 'marque page'
*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>

# répertoire préfixe où CVSup stocke les distributions
*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>

# Distribution complète, avec tout ce qui est en dessous
pgsql

# distributions partielles
# pgsql-doc
# pgsql-perl5
# pgsql-src</programlisting>
   </para>
  </sect2>
 </sect1>
</appendix>