A.7. CVSup gebruiken

A.7.1. Inleiding

CVSup is een softwarepakket voor het verspreiden en bijwerken van broncodestructuren vanaf een master CVS depot op een andere server. De FreeBSD broncode wordt beheerd in een broncode depot op een centrale ontwikkelmachine in Californië. Met CVSup kunnen FreeBSD gebruikers op eenvoudige wijze hun broncode bijwerken.

CVSup gebruikt een zogenaamd pull model voor het bijwerken. In het pull-model vraagt iedere client de server om updates als die nodig zijn. De server wacht passief op een verzoek om updates van zijn clients. Alle updates worden dus op initiatief van de client gedaan. De server stuurt nooit ongevraagde updates. Gebruikers moeten de CVSup client handmatig draaien om te updaten of een cron taak instellen om op regelmatige basis bij te werken.

De term CVSup, op de gegeven wijze geschreven, doelt op het complete softwarepakket. De belangrijkste componenten zijn de client cvsup, die op de machine van een gebruiker draait, en de server cvsupd, die op alle FreeBSD mirrorsites draait.

In de FreeBSD documentatie en op de mailinglijsten zijn referenties aan sup te vinden. Sup was de voorloper van CVSup en diende hetzelfde doel. CVSup wordt op dezelfde manier gebruikt als sup en gebruikt zelfs bestanden met instellingen die ook te gebruiken zijn met sup. Sup wordt niet langer gebruikt in het FreeBSD project omdat CVSup sneller en flexibeler is.

A.7.2. Installatie

De meest eenvoudige wijze van installatie van CVSup is met het voorgecompileerde pakket net/cvsup uit de FreeBSD pakkettencollectie. Als het gewenst is, kan CVSup ook uit de broncode gebouwd worden in net/cvsup. De port net/cvsup is afhankelijk van het Modula-3 systeem en dat kan wel even duren en er is ook nogal wat schijfruimte voor nodig om het te downloaden en te bouwen.

A.7.3. CVSup instellingen

De werking van CVSup wordt gestuurd door een bestand met instellingen met de naam supfile. Er staan een aantal supfiles als voorbeeld in de map /usr/share/examples/cvsup/.

De informatie in een supfile beantwoordt de volgende vragen voor CVSup:

• Welke bestanden moeten ontvangen worden?

• Welke versies daarvan moeten ontvangen worden?

• Waar moeten ze vandaan komen?

• Waar moeten ze komen te staan?

• Waar moet cvsup zijn statusbestanden bijhouden?

In de volgende paragrafen wordt een supfile bestand opgebouwd door achtereenvolgens alle gestelde vragen te beantwoorden. Als eerste wordt de algemene structuur van een supfile beschreven.

Een supfile is een tekstbestand. Commentaar begint met een # en loopt tot het einde van de regel. Lege regels en regels die alleen commentaar bevatten worden genegeerd.

Iedere regel die overblijft slaat op een groep bestanden die ontvangen moet worden. De regel begint met de naam van een “collectie”, een logische groep bestanden op de server. De naam van de collectie geeft de server aan welke bestanden er gestuurd moeten worden. Na de naam van de collectie komen er geen of meer velden die gescheiden worden door witruimte. Die velden beantwoorden de hierboven gestelde vragen. Er zijn twee soorten velden: vlagvelden en waardevelden. Een vlagveld bestaat uit een alleenstaand sleutelwoord, bijvoorbeeld delete of compress. Een waardeveld begint ook met een sleutelwoord, maar het sleutelwoord wordt direct (zonder witruimte) gevolgd door = en een tweede woord. release=cvs is bijvoorbeeld een waardeveld.

In een supfile wordt meestal aangegeven dat er meerdere collecties ontvangen moeten worden. Het is mogelijk om een supfile te structureren door expliciet alle relevante velden aan te geven voor iedere collectie, maar dat maakt de regels in de supfile nogal lang en het is onhandig omdat de meeste velden hetzelfde zijn voor alle collecties in een supfile. CVSup biedt een systeem met standaardinstellingen om dit probleem te omzeilen. Regels die beginnen met de speciale pseudo-collectienaam *default kunnen gebruikt worden om standaarden in te stellen voor de collecties die er in de supfile achteraan komen. Een standaardwaarde kan voor individuele collecties overschreven worden door een andere waarde in de collectie zelf aan te geven. Standaarden kunnen ook middenin het bestand gewijzigd of aangevuld worden met extra *default regels.

Na deze achtergronden wordt er nu een supfile samengesteld voor het ontvangen en bijwerken van de hoofd broncodestructuur van FreeBSD-CURRENT.

• Welke bestanden moeten ontvangen worden?

  De bestanden die via CVSup beschikbaar zijn, zijn beschikbaar in groepen die “collecties” heten. De beschikbare collecties staan beschreven in de volgende paragraaf. In dit voorbeeld is het de bedoeling dat de hele hoofd broncodestructuur voor FreeBSD wordt ontvangen. Daar is één grote collectie voor: src-all. De eerste stap in het maken van een supfile is het opsommen van de gewenste collecties, één per regel (in dit geval maar één regel):

  src-all
  

• Welke versies daarvan moeten ontvangen worden?

  Met CVSup kan vrijwel iedere versie van de broncode die ooit heeft bestaan opgehaald worden. Dat kan omdat de cvsupd server direct vanaf het CVS depot werkt, dat alle versies bevat. Er kan aangegeven welke ontvangen moeten worden met de waardevelden tag= en date=.

  WaarschuwingVoorzichtigheid is geboden bij het correct aangeven van velden met tag=. Sommige labels zijn alleen geldig voor bepaalde collecties of bestanden. Als ze incorrect worden aangeven of als er een spelfout wordt gemaakt in een label, verwijdert CVSup bestanden waarvan dat waarschijnlijk niet de bedoeling is. Het label tag=. dient eigenlijk alleen gebruikt te worden voor de ports-* collecties.

  Het veld tag= benoemt een symbolisch label in het depot. Er zijn twee soorten labels: revisielabels en taklabels. Een revisielabel refereert aan een specifieke revisie. De betekenis blijft altijd hetzelfde. Een taklabel refereert echter aan de laatste revisie van een gegeven ontwikkellijn op een gegeven moment. Omdat een taklabel niet refereert aan een specifieke revisie, kan het morgen iets anders betekenen dan vandaag.

  Paragraaf A.8 beschrijft de meest interessante taklabels. Als er in het instellingenbestand van CVSup een label wordt aangegeven, moet dat vooraf gegaan worden door tag= (RELENG_8 zal tag=RELENG_8 worden). Voor de Portscollectie is alleen tag=. relevant.

  WaarschuwingLabels dienen exact zo ingegeven te worden als ze staan beschreven. CVSup kan geen onderscheid maken tussen geldige en ongeldige labels. Als er een spelfout in een label wordt gemaakt, doet CVSup alsof er een geldig label is ingegeven dat aan geen enkel bestand refereert. Dan zal CVSup de bestaande broncode wissen.

  Bij het aangeven van een taklabel wordt meestal de laatste versie van de bestanden voor een bepaalde ontwikkellijn ontvangen. Om een oudere versie te ontvangen kan in het veld date= een datum opgegeven worden. In cvsup(1) staat hoe dat werkt.

  Om bijvoorbeeld FreeBSD-CURRENT te ontvangen dient het volgende aan het begin van supfile toegevoegd te worden:

  *default tag=.
  

  Er ontstaat een belangrijk speciaal geval als er geen velden met tag= of date= worden aangegeven. In dat geval worden de eigenlijke RCS bestanden direct uit het CVS depot van de server ontvangen in plaats van dat een bepaalde versie wordt ontvangen. Ontwikkelaars geven in het algemeen de voorkeur aan deze optie. Door zelf een kopie van de broncode op hun systeem te hebben, krijgen ze de mogelijkheid om zelf door eerdere versies van bestanden te bladeren en de geschiedenis ervan te bekijken. Dit voordeel kost wel veel schijfruimte.

• Waar moeten ze vandaan komen?

  Het veld host= wordt gebruikt om cvsup aan te geven waar de updates vandaan moeten komen. Dat kan van elke CVSup mirrorsite, hoewel er wordt aangeraden een site die geografisch dichtbij ligt te kiezen. In dit voorbeeld wordt een fictieve FreeBSD distributiesite gebruikt, cvsup99.FreeBSD.org:

  *default host=cvsup99.FreeBSD.org
  

  In een werkelijke situatie dient de hostnaam gewijzigd te worden in een host die echt bestaat voordat CVSup gaat draaien. Iedere keer dat cvsup wordt gestart, kan er een andere host op de commandoregel opgegeven worden met de optie -hhostname.

• Waar moeten ze komen te staan?

  Het veld prefix= geeft cvsup aan waar de ontvangen bestanden terecht moeten komen. In dit voorbeeld worden de bestanden direct in de hoofd broncodestructuur /usr/src geplaatst. De map src is al impliciet in de gekozen collecties, vandaar dat het onderstaande de juiste instelling is:

  *default prefix=/usr
  

• Waar moet cvsup zijn statusbestanden bijhouden?

  De CVSup client houdt statusbestanden bij in een map die “base” wordt genoemd. Die bestanden helpen CVSup efficiënter te werken door bij te houden welke updates al eerder zijn ontvangen. Hier wordt de standaard basemap gebruikt, /var/db:

  *default base=/var/db
  

  De bovenstaande instelling wordt standaard gebruikt als die niet wordt aangegeven in de supfile, dus hij is eigenlijk niet nodig.

  Als de basemap niet al bestaat, moet die gemaakt worden. De cvsup client weigert te draaien als de basemap niet bestaat.

• Allerlei supfile instellingen:

  Er is nog een regel die in een supfile moet staan:

  *default release=cvs delete use-rel-suffix compress
  

  release=cvs geeft de server aan dat de informatie uit het FreeBSD hoofd CVS depot moet komen. Dat is eigenlijk altijd het geval, maar er zijn mogelijkheden die buiten het bereik van dit handboek vallen.

  delete geeft CVSup het recht om bestanden te verwijderen. Dit moet altijd aangegeven worden zodat CVSup de broncode altijd kan bijwerken. CVSup gaat voorzichtig om met het verwijderen van bestanden waar het verantwoordelijk voor is. Extra bestanden in de structuur worden met rust gelaten.

  use-rel-suffix is nogal geheimzinnig. Voor de nieuwsgierigen staat er meer over in cvsup(1). Anders kan het gewoon ingesteld worden zonder erover na te denken.

  compress schakelt het gebruikt van gzip compressie in voor het communicatiekanaal. Als de verbinding een E1 of sneller is, hoeft er geen compressie gebruikt te worden. Anders helpt het aanzienlijk.

• Alles combinerend:

  Hieronder staat de hele supfile uit het voorbeeld:

  *default tag=.
  *default host=cvsup99.FreeBSD.org
  *default prefix=/usr
  *default base=/var/db
  *default release=cvs delete use-rel-suffix compress
  
  src-all
  

doc/bn_*
doc/da_*
doc/de_*
doc/el_*
doc/es_*
doc/fr_*
doc/hu_*
doc/it_*
doc/ja_*
doc/mn_*
doc/nl_*
doc/no_*
doc/pl_*
doc/pt_*
doc/ru_*
doc/sr_*
doc/tr_*
doc/zh_*

A.7.4. CVSup draaien

Nu kan het bijwerken beginnen. Het commando is best wel eenvoudig:

# cvsup supfile

De supfile is de naam van het supfile bestand dat gebruikt moet worden. Aangenomen dat er X11 draait op een machine, toont cvsup een GUI venster met wat knoppen om de bekende acties uit te voeren. Het proces start na het klikken op de knop go.

Omdat in dit voorbeeld de werkelijke structuur in /usr/src wordt bijgewerkt, moet het programma als root uitgevoerd worden, zodat cvsup de rechten heeft die het nodig heeft om de bestanden bij te werken. Het is voorstelbaar dat de benodigde rechten, het net gemaakte bestand met instellingen en het voor de eerste keer draaien van een programma zorgt voor wat onrust. Daarom is het mogelijk proef te draaien zonder dat er bestanden gewijzigd worden. Dat kan door ergens een lege map te maken en een extra argument mee te geven op de commandoregel:

# mkdir /var/tmp/dest
# cvsup supfile /var/tmp/dest

De opgegeven map is de bestemming voor alle bestandsupdates. CVSup bekijkt wel de bestanden in /usr/src, maar wijzigt ze niet. Alle updates belanden in /var/tmp/dest/usr/src. CVSup werkt ook de statusbestanden niet bij als het op deze wijze wordt uitgevoerd. De nieuwe versies van de bestanden worden naar de aangegeven map geschreven. Als er maar leestoegang is tot /usr/src, hoeft een gebruiker zelfs geen root te zijn bij het uitvoeren van dit experiment.

Als er geen X11 draait of als het niet wenselijk is een GUI te gebruiken, dan kunnen daarvoor opties op de commandoregel meegegeven worden bij het draaien van cvsup:

# cvsup -g -L 2 supfile

De optie -g geeft CVSup aan dat de GUI niet gebruikt hoeft te worden. Dit gebeurt automatisch als X11 niet draait, maar anders moet het aangegeven worden.

De optie -L 2 geeft CVSup aan dat details getoond moeten worden over alle bestanden die bijgewerkt worden. Er zijn drie niveaus van uitvoerigheid, van -L 0 tot -L 2. Standaard is het 0, wat betekent dat er geen enkel bericht wordt getoond, met uitzondering van foutmeldingen.

Er zijn nog veel andere opties beschikbaar. Met cvsup -H wordt een lijst met korte uitleg getoond. Beschrijvingen met meer details staan in de handleiding.

Als het bijwerken op de gewenste manier loopt, kan het regulier draaien van CVSup met cron(8) ingesteld worden. Natuurlijk hoort CVSup zonder GUI te draaien als het programma vanuit de cron(8) draait.

A.7.5. CVSup bestandscollecties

De via CVSup beschikbare bestandscollecties zijn hiërarchisch georganiseerd. Er zijn een paar grote collecties en die zijn opgedeeld in kleinere subcollecties. Het ontvangen van een collectie is hetzelfde als het ontvangen van alle subcollecties. De hiërarchische relatie tussen de collecties wordt hieronder aangegeven door het niveau van inspringen.

De meest gebruikte collecties zijn src-all en ports-all. De andere collecties worden door kleine groepen mensen gebruikt voor bijzondere doeleinden en sommige mirrorsites hebben ze niet allemaal.

A.7.6. Voor meer informatie

De CVSup FAQ en andere informatie over CVSup is te vinden op De CVSup Homepage.

De meeste FreeBSD–gerelateerde discussie over CVSup vindt plaats op de FreeBSD technische discussie mailinglijst. Daar worden nieuwe versies van de software aangekondigd, net als op de FreeBSD aankondigingen mailinglijst.

Voor vragen en foutrapporten moet een kijkje genomen worden op de CVSup FAQ

A.7.7. CVSup sites

CVSup servers voor FreeBSD draaien op de onderstaande sites.

Centrale servers, Primaire spiegelsites, Armenië, Australië, Brazilië, Canada, China, Costa Rica, Denemarken, Duitsland, Estland, Filipijnen, Finland, Frankrijk, Griekenland, Hongarije, Ierland, Ijsland, Israël, Italië, Japan, Kirghizistan, Koeweit, Korea, Letland, Litouwen, Nederland, Nieuw-Zeeland, Noorwegen, Oekraïne, Oostenrijk, Polen, Portugal, Roemenië, Rusland, San Marino, Slovenië, Slowakije, Spanje, Taiwan, Thailand, Tsjechië, Turkije, Verenigd Koninkrijk, Verenigde Staten van Amerika, Zuid-Afrika, Zweden, Zwitserland.

(bijgewerkt op: UTC)