Portal:Build Service/Tutoriel

Ce document devrait vous donner un aperçu de Build Service et un tutoriel pour compiler des paquets pour différentes distributions utilisant ce fabuleux outil.

Nous essaierons de montrer toutes les actions dans un exemple d'application, pour que vous puissiez vous sentir capable de produire vos propres paquets.

Modèle:Buildservice Content

Prérequis

Vous devriez être en mesure de comprendre plus ou moins bien les RPMs et comment les créer (voir aussi conventions de paquets pour SuSE), ou tout autre compréhension de compilation de paquet similaire à dpkg. Ce document n'est pas un remplaçant de la documentation de l'empaquetage qui se trouve dans les liens précédents.

Vous devriez être familié à l'environnement du code source de votre projet. Build Service peut arranger les erreurs communes et vous alerte normalement aux problèmes liés à votre code source via des fichiers log and de simples échecs de compilation. Nous avons un mailing de compilation buildservice-mailinglist qui peut vous servir d'aide. Toutefois, vous décidez vous-même des modifications et améliorations à apporter à votre projet source.

Requis

Pour utiliser Build Service, vous devez au préalable créer un compte login. ;-)

Votre compte buildservice est le même que votre compte wiki/bugzilla. Si vous n'avez pas de compte, suivez le lien en haut de la page pour en créer un.

Après avoir créé votre login wiki/bugzilla, allez sur http://build.opensuse.org/ et loggez-vous là-bas ! La première fois, vous devez remplir le formulaire et expliquer pourquoi vous avez besoin d'un compte et que voulez-vous empaqueter. Ensuite, vous devez attendre jusqu'à ce que votre compte soit garanti. Pendant ce temps, vous pouvez vous inscrire à la mailinglist de opensuse-buildservice pour nous donner une brève introduction. Dites-nous simplement votre nom et quelque chose à propos du projet dont vous êtes responsable (quelques mots au sujet du paquet lui-même sont les bienvenus) !

Si vous avez envie de tester et/ou de compiler vos paquets à la maison (quelle bonne idée !), vous devriez regarder la page SUSE Build Tutorial pour avoir un premier aperçu des requis pour un environnement de compilation locale.

Terminologie

Build Service contient des projets (vous pouvez consulter une liste de ceux-ci (login requis)). Chaque projet contient les ressources nécessaires à la compilation de un ou plusieurs paquets (i.e. RPMs). Ces ressources incluent des archives sources, des fichiers .spec, etc. La sortie d'un projet est un ou plusieurs dépôts. Un dépôt est un vieux concept familier : un paquet de RPMs est organisé en une hiérarchie de répertoires avec quelques fichiers index/meta-data facilitant l'accès à des outils tels que zypper pour résoudre les dépendances. Les dépôts qu'un projet produit correspondent aux différentes versions de systèmes telles que SuSE 10.3, etc.

Alors que les projets existent, il y a des projets SuSE "officiels" qui compilent les RPMs fournis dans les distributions standards de SuSE. Le projet "factory" est le projet "en cours de développement" qui deviendra la prochaine version de SuSE. Il existe aussi une quantité de projets spécifiques tels que Apache et network:telephony. Finalement, chaque utillisateur obtient son propre "terrain de jeu" pour son projet : home:utilisateur.

Les RPMs ont tendance à avoir des quantités de dépendances à d'autres RPMs, et souvent celles-ci viennent de différents projets du Build Service. Ceci a deux conséquences importantes.

Premièrement, si votre paquet dépend d'un quelconque paquet comme exécutant ("Requires"), il va généralement en dépendre au moment de la compilation aussi (i.e. "Build-Requires"). Build Service ne va pas automatiquement chercher et rapporter les dépendances pour vous (pour tout autre paquet qui n'est pas inclu dans la distribution standard cible). Donc, d'une manière ou d'une autre, vous devez indiquer à Build Service où trouver les paquets.

Deuxièmement, le but idéal pour un dépôt est d'être fermé transitivement, i.e. toute dépendance de tout paquet dans le dépôt est aussi dans le dépôt (les paquets de la distribution standard cible exceptés). Cela facilite l'installation de RPMs que votre projet fournit. Mais cela n'est pas obligatoire : les utilisateurs peuvent toujours trouver ces dépendances manuellement en utilisant l'interface de recherche.

Build Service propose quelques manières différentes de gérer ces dépendances.

Premièrement, vous pouvez directement ajouter les paquet(s) requis à votre dépôt. C'est certainement l'approche que vous devez faire si aucun autre projet ne compile les paquets requis. En général, ces paquets sont déjà compilés par un autre projet. Comment ré-utiliser ce travail ?

La seconde option est de lier les autres projets du dépôt à votre dépôt. Cela se fait en éditant les données meta (meta-data) de votre projet. Cela ajoute simplement l'autre dépôt à la liste des dépôts dans lesquels Build Service recherchera les dépendances "Build-Requires" au moment de la compilation. Cela permet à la compilation de réussir, inhibant le premier problème, mais sans inhiber du tout l'idée "fermé transitivement" : les utilisateurs doivent acquérir les paquets requis eux-mêmes. Toutefois, ce choix est le bon quand il s'agit de multiples dépendances de votre projet dans un autre projet et/ou que les utilisateurs sont enclins à télécharger depuis les deux dépôts unilatéralement.

La troisième option est appelée liaison (linking) et est un moyen d'autoriser votre projet à ré-utiliser un paquet qui existe déjà dans un autre projet. Lorsque vous lier (link) un paquet dans votre projet, les paquets dépendant de lui pourront être compilés, et le paquet apparaîtra dans le dépôt de votre projet, en solutionnant les deux problèmes sans dupliquer le travail.

Il existe deux types de liaisons (linking) : lier et agréger. Lorsque vous liez, vous pouvez optionnellement modifier la façon dont le paquet est compilé. Votre compilation RPM aura un numéro de compilation différent de celui du projet original. Remarquez que ceci peut provoquer la confusion chez les utilisateurs. Concrètement, vous êtes en train de compiler une version différente d'un paquet du même nom.

À moins que vous ne deviez modifier les paquet requis, vous devriez plutôt agréger que lier. Lorsque vous agréger, vous fabriquez un lien en "lecture seule". Ce paquet n'est pas compilé dans votre projet; au lieu de cela, le paquet compilé est copié dans votre projet depuis le projet original. Ainsi le même RPM (avec le même numéro de compilation) apparaîtra dans les deux projets. Pour l'utilisateur, il y a moins de confusion puisque les RPMs sont identiques.

Build Service détecte automatiquement les changements dans les paquets liés et déclenche une recompilation de tout paquet dépendant.

Workflow

Les étapes suivantes couvrent un processus normal pour créer un projet et y ajouter des paquets. Bien sûr, dans un exemple concret, vous pourriez échouer à certaines étapes et répéter jusqu'à ce que cela fonctionne. Ce survol est simplement donné pour vous donner une impression juste de ce que essayez d'accomplir.

Nous vous montrons deux manières différentes :

la manière Client web
la manière Ligne de commande en client (nous utilisons osc dans nos exemples)
Une troisième méthode alternative, mais non détailler ici, c'est le client MonoOSC, en effet un tutoriel existe déjà ici, donc pas la peine de dupliquer.

Étape une - Login et installation unique d'un projet local

Si vous avez déjà un compte Build Service, c'est l'étape la plus facile.

Client web : Chaque fois que vous voulez intéragir avec votre projet via le Client web, vous devez vous authentifier.

Pour cela, ouvrez http://build.opensuse.org/ et cliquez un des liens "Lister tous les projets" ou "Projets suivis". Vous serez amené à entrer votre nom d'utilisateur et votre mot de passe de openSuSE Build Service. Après quoi, vous verrez la liste de tous les projets et dans le coin haut-droit vous trouverez un lien vers votre "Home Project". Cliquez dessus sîl-vous-plaît !

Ligne de commande : Si vous pensez éventuellement intéragir avec votre projet via CLI, vous devez installer les outils logiciels et créer votre répertoire local de travail.

Tout d'abord, vous devez installer le Client de Ligne de commande sur votre Client local. Vous pouvez trouver les paquets osc pour différentes distributions dans le dépôt openSUSE-Tools (oui, c'est aussi un projet Build Service). Utilisez votre gestionnaire de paquets favori pour installer le paquet osc. Remarque : pour SuSE Linux 9.3 ou plus ancien vous avez besoin de python-elementtree et python-urlgrabber de ce dépôt python.

Ensuite, "cd" vers le répertoire que vous voulez utiliser pour vos fichiers de projet. Maintenant les habitués de SVN se sentirons "à la maison" : essayez de faire un checkout de votre projet avec

 cd <répertoire_pour_contenir_la_racine_du_projet>
 osc checkout home:<utilisateur>
 cd home:<utilisateur>

(svp remplacez <utilisateur> avec votre login). Vous serez amené à entrer votre nom d'utilisateur et votre mot de passe - après osc essayera de faire un checkout des paquets dans votre projet et de créer un nouveau répertoire nommé home:<utilisateur>. Vous pouvez éditer votre configuration dans le fichier ~/.oscrc.

Étape deux - Créer & télécharger des paquets

Il n'est pas vraiment nécessaire de démarrer dans votre propre projet - vous pouvez en effet télécharger des paquest vers un projet existant - mais il est toujours de bon ton de le faire et personne ne devrait utiliser le projet d'un autre comme dépendance de compilation. Vous pouvez donc utiliser votre propre projet comme "terrain de jeu" pour tester les paquets qui doivent être transférés à d'autres projets quand tout est ok.

'PARTAGE DEBIAN : Avant de partager votre archive, quels sont les conditions requises pour les paquets Debian ?

Client web : cliquez simplement sur le lien ajouter un paquet. Vous devez ensuite remplir trois champs texte : "Nom", "Titre" et "Description". Utilisez simplement le nom du paquet comme "Nom", le résumé du paquet comme "Titre" et la description du paquet comme "Desctiption".

Ensuite, cliquez sur le lien [ajouter un fichier] pour ajouter les fichiers de votre paquet. Vous devez télécharger le code source (compressé) de votre paquet et au moins un fichier .spec.

Ligne de commande:

osc meta pkg -e home:<utilisateur> <nomDuPaquet>

osc ouvre un modèle de fichier xml dans votre éditeur favori (basé sur la variable d'environnement EDITOR, mais traditionnellement "vi") et vous pouvez simplement ajouter les même renseignements (Nom, Titre, Description) décrits plus haut.

Maintenant tapez

osc up

et vous obtiendrez un nouveau répertoire du nom de votre paquet. Pour ajouter des fichiers via la ligne de commande, 'cd' dans le nouveau répertoire, copiez les fichiers concernés (typiquement un fichier .tar.gz et les fichiers de support) et typez

osc add *

cela va marquer les fichiers dans le répertoire pour le prochain envoi (submit). Pour envoyer les fichiers, tapez

osc commit

Étape trois - Ajouter des dépôts

Retournez à votre page d'accueil OBS. Maintenant vous devez faire un choix : pour quels dépôts de distribution voulez-vous compiler votre paquet ?

Client web: Cliquez simplement sur ajouter un dépôt et choisissez un dépôt de distribution cible et son/ses architecture/s.

Ligne de commande: d'abord, prenez une liste des dépôts accessibles

osc ls

ensuite, éditez les méta-données (metadata) de votre projet

osc meta prj -e home:<utilisateur>

et ajouter le dépôt comme ceci :

 <repository name="SUSE_Linux_Factory">
   <path project="openSUSE:Factory" repository="standard" />
   <arch>x86_64</arch>
   <arch>i586</arch>
 </repository>

Remarque : repository="standard" est pour de futures extensions (p.ex. une autre branche d'un dépôt).

Étape quatre : compiler votre paquet

Normalement votre paquet est programmé pour être compilé après qu'il soit envoyé ou que des fichiers aient changé. Si un paquet requis est recompilé, votre paquet est automatiquement recompilé, cela va de soit. Vous pouvez aussi enclencher manuellement une recompilation si vous en avez le besoin (mais s'il-vous-plaît ne le faites pas trop souvent au risque de consommer de l'énergie à d'autres paquets).

Compiler votre paquet localement

Parfois il peut être plus rapide de compiler votre paquet sur votre machine locale que d'attendre les résultat de Build Service. osc supporte les compilations locales de votre paquet, pour autant que votre matériel le supporte (sur x86_64 on peut compiler pour i586 et x86_64, mais sur i586 seul i586 est possible).

 osc build <platforme> <architecture> <fichier.spec> [--clean|--noinit]

SI vous démarrez la compilation en tant qu'utilisateur normal (bonne idée !), il vous sera demandé votre mot de passe root de la machine locale. Vous pouvez éviter cela si vous ajoutez votre utilisateur à '/etc/sudoers et éditez votre ~/.oscrc :

su-wrapper = sudo

et avec visudo ajoutez la ligne (en tant que root) :

<utilisateur> ALL = NOPASSWD: /usr/bin/build

à la configuration sudo (bien sûr sans '<' et '>'). osc se connectera au serveur-dépôt et téléchargera tous les RPMs nécessaires dans /var/tmp/osbuild-packagecache/<plattforme>/<dépôt>/<architecture> comme répertoire de cache. (Donc si vous possédez déjà un dépôt complet, vous pouvez lier les RPMs vers ce répertoire afin d'éviter un trafic de téléchargement énorme.)

Par exemple, pour le dépôt openSUSE_10.2 vous pouvez utiliser le fichier iso Retail Box DVD comme ci-dessous :

 mount openSUSE-10.2.iso /mnt/openSUSE-10.2 -o loop
 mkdir -p /var/tmp/osbuild-packagecache/openSUSE\:10.2
 ln -s /mnt/openSUSE-10.2/suse/* /var/tmp/osbuild-packagecache/openSUSE:10.2/standard

Cela vous donne les dépôts pour x86 et x86_64 aussi.

Les paquets peuvent dorénavant être compilés comme suit :

 osc build openSUSE_10.2 i586 beryl-core-snapshot.spec

osc créera un environnement chroot dans /var/tmp/osc-build-root/ et démarrera la compilation de votre paquet. Si vous n'avez que des changements mineurs, vous pouvez éviter la re-création de l'environnement de compilation avec l'option --noinit. Si vous suspectez que votre environnement chroot est cassé, vous pouvez enclencher une recompilation complète avec l'option --clean. Vous pouvez configurer le répertoire chroot; voir les commentaires dans votre fichier ~/.oscrc .

Après que vos paquets soient compilés dans cet environnement chroot, vous pouvez trouver les paquets résultant dans /var/tmp/osc-build-root/usr/src/packages/RPMS/.

Le fichier journal (log) complet de votre compilation locale est stocké dans /var/tmp/osc-build-root/.build.log.

Compiler votre paquet dans Build Service

Compiler dans Build Serviĉe est plus facile que compiler localement - mais prend peut-être plus de temps.

Client web : Si vous voulez enclencher une recompilation manuellement, cliquez simplement sur [enclencher une recompilation] au bas de la page de chaque paquet.

Ligne de commande : Avec les arguments optionnels <repo> (dépôt) et <arch> (architecture), la recompilation peut être limitée à un certain dépôt ou une certaine architecture.

osc rebuildpac <projet> <paquet> [<repo> [<arch>]]

Pour écrire votre propre fichier .spec, vous devriez d'abord lire le HOWTO correspondant. Ensuite, il faut télécharger le .spec.

Attention : Remarquez qu'il n'est normalement PAS nécessaire de lancer des recompilations comme cela, parce qu'elles interviennent en principe automatiquement, par le biais de contrôle des téléchargements. En particulier, l'ordre dans lequel les paquets sont compilés est géré par Build Service.

Étape cinq : contrôler les fichiers journaux

Build Service produit un seul large fichier journal pour chaque compilation de paquet.

Client web : Cliquez simplement sur le lien [Journal de compilation] dans la fenêtre du paquet.

Ligne de commande : Vous avez quelques choix dépendant de vos besoins (repDuPaquet est optionnel si vous êtes dans le répertoire du paquet) :

osc prjresults [repDuPaquet]

Montre les résultats agrégés de compilation du projet entier. Ou vous pouvez taper :

osc results [repDuPaquet]

Montre les résultats de compilation d'un seul paquet.

osc buildlog <platforme> <architecture>

Montre le fichier journal d'un paquet (vous avez besoin d'être dans le répertoire du paquet).

Créer des Modèles (Patterns)

Les modèles sont des fichiers qui contiennent une liste de paquets ensemble avec une description de leur utilité. (À l'avenir, Build Service exportera les modèles vers les dépôts pour les rendre visible à YaST.) Additionnellement, Build Service crée des fichiers .ymp pour chaque modèle de dépôt généré. Ces fichiers .ymp peuvent être utilisés pour une installation En Un Clic par l'utilisateur.

En bref, les modèles sont utiles pour l'installation d'un set de logiciels destinés à une application typique sans créer des dépendances entre les paquets.

Envoyer des modèles est possible en utilisant directement l'api, ou en utilisant osc :

pour ouvrir un modèle dans $EDITOR (en en créant un s'il n'existe pas déjà)

osc meta pattern -e <projet> <modèle>

pour ouvrir des modèles existant

osc meta pattern <projet>

obtenir un modèle existant

osc meta pattern <projet> <modèle>

Vous pouvez aussi envoyer un fichier existant comme suit :

osc meta pattern --file <fichier_local> <projet> <modèle>

Pour tester : en cliquant sur le .ymp dans Konqueror vous devriez lancer l'assistant d'installation. Si vous n'avez pas Konqueror, vous pouvez essayer de lancer par le shell en tant qu'utilisateur normal :

/sbin/yast2 MetaPackageHandler http://download.opensuse.org/repositories/<projet>/<SUSE_Factory or openSUSE_10.2>/<modèle>.ymp

Le fichier suivant est un exemplaire de modèle du projet KDE:KDE4 . Vous pouvez voir le fichier .ymp généré ici.

<pattern
 xmlns="http://novell.com/package/metadata/suse/pattern"
 xmlns:rpm="http://linux.duke.edu/metadata/rpm"
>
    <name>KDE 4 Games</name>
    <summary>KDE 4 Games</summary>
    <description>A number of games for KDE 4.</description>
    <uservisible/>
    <category lang="en">Desktop Functions</category>
    <rpm:recommends>
      <rpm:entry name="kde4-kpat"/>
      <rpm:entry name="kde4-kmahjongg"/>
      <rpm:entry name="kde4-kmines"/>
      <rpm:entry name="kde4-kreversi"/>
      <rpm:entry name="kde4-ksudoku"/>
    </rpm:recommends>
    <rpm:suggests>
      <rpm:entry name="kde4-katomic"/>
      <rpm:entry name="kde4-kbattleship"/>
      <rpm:entry name="kde4-ksquares"/>
      <rpm:entry name="kde4-bovo"/>
      <rpm:entry name="kde4-kiriki"/>
      <rpm:entry name="kde4-kwin4"/>
      <rpm:entry name="kde4-kolf"/>
      <rpm:entry name="kde4-klines"/>
      <rpm:entry name="kde4-ksame"/>
      <rpm:entry name="kde4-lskat"/>
      <rpm:entry name="kde4-kgoldrunner"/>
      <rpm:entry name="kde4-kblackbox"/>
      <rpm:entry name="kde4-kbounce"/>
      <rpm:entry name="kde4-ktuberling"/>
      <rpm:entry name="kde4-knetwalk"/>
      <rpm:entry name="kde4-kjumpingcube"/>
      <rpm:entry name="kde4-kspaceduel"/>
      <rpm:entry name="kde4-konquest"/>
      <rpm:entry name="kde4-kshisen"/>
    </rpm:suggests>
</pattern>

Quelques descriptions de tags :

Tag	Description
<rpm:requires> <rpm:entry name="exemple" /> </rpm:requires>	Requires RPM exemple: ce paquet doit être insallé - autrement le modèle est incomplet.
<rpm:recommends> <rpm:entry name="exemple" /> </rpm:recommends>	Recommends RPM exemple: s'il est disponible et que toute les dépendances de ce paquet sont vérifiées, le paquet devrait être installé. Si le paquet n'est pas disponible, il n'y aura pas de message d'erreur. Si les dépendances de paquet ne sont pas vérifiées, le paquet serait visible mais pas installé.
<rpm:suggests> <rpm:entry name="exemple" /> </rpm:suggests>	Suggests RPM exemple: par défaut, le paquet est montré dans le modèle mais pas installé