doc/build_system_fr.md

228 lines
12 KiB
Markdown
Raw Normal View History

2016-03-07 12:45:10 +01:00
# Système de construction des paquets
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
## Dépôts
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Tout d'abord, aussi bien au niveau des dépôts que des paquets YunoHost, il faut savoir qu'il y a trois *composants* (`unstable`, `testing` et `stable`) :
2014-10-09 13:10:16 +02:00
2016-03-07 12:45:10 +01:00
* `unstable` correspondent à la dernière version du dépôt git sur la branche `unstable`, et sont reconstruits de façon automatisée toutes les nuits sil y a eu une modification sur la cette branche.
* `testing` permet de mettre en place une nouvelle version dun paquet qui sera ensuite testée.
* `stable` contient la version de production.
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Le terme *composant* vient de la façon dont les dépôts sont configurés. Afin de se rapprocher de la façon dont les dépôts sont structurés dans Debian, l'entrée à ajouter dans les sources APT se construit ainsi :
2014-10-04 13:51:00 +02:00
2016-03-07 13:31:34 +01:00
```bash
2016-03-07 12:45:10 +01:00
deb http://repo.yunohost.org/debian/ nom_de_code composant [composant ...]
```
Avec *nom_de_code* la "version" de Debian installée sur l'hôte (ex. : `jessie`). Pour les composants, il est nécessaire de spécifier au moins `stable`, puis les différents intermédiaires. Par exemple, sur un système sous Debian Jessie, voici les différentes possibilités :
2015-02-04 12:15:45 +01:00
2016-03-07 13:31:34 +01:00
```bash
2016-03-07 12:45:10 +01:00
# composant stable
deb http://repo.yunohost.org/debian/ jessie stable
# composant testing
deb http://repo.yunohost.org/debian/ jessie stable testing
# composant unstable
deb http://repo.yunohost.org/debian/ jessie stable testing unstable
```
## Workflow
2015-02-04 12:15:45 +01:00
2016-03-02 22:27:13 +01:00
Le but du workflow est déviter toute intervention manuelle (lancement dun script, …) sur le serveur, et de maîtriser la gestion des paquets via GitHub uniquement.
2015-02-04 12:15:45 +01:00
2016-03-07 12:45:10 +01:00
Ansi, les dépôts de chaque paquet yunohost possèdent trois branches correspondant aux trois composants (`unstable`, `testing` et `stable`). Le serveur de build construit et déploie **automatiquement** les paquets source et binaires Debian correspondant à létat de ces trois branches sur GitHub.
2015-02-04 12:15:45 +01:00
2015-05-01 17:47:54 +02:00
### Branche unstable
2015-02-04 12:15:45 +01:00
2015-05-01 17:47:54 +02:00
Aucun commit dans la branche unstable ne modifie le fichier `debian/changelog` car celui-ci est modifié automatiquement lors du build quotidien, avec une version correspondant à la date/heure de construction.
2015-02-04 12:22:23 +01:00
2016-01-30 22:00:44 +01:00
Tout commit modifiant fonctionnellement les paquets doit se faire dabord dans cette branche `unstable`.
2015-02-04 12:15:45 +01:00
**TODO** ajouter un pre-commit hook pour éviter les erreurs ?
2015-02-04 12:15:45 +01:00
2015-05-01 17:47:54 +02:00
### Branche testing et stable - workflow standard
2015-02-04 12:15:45 +01:00
2016-01-30 22:00:44 +01:00
Aucun commit fonctionnel nest effectué directement dans ces branches. On ne fait que des merges (merge de `unstable` dans `testing` et merge de `testing` dans `stable`).
2015-02-04 12:15:45 +01:00
2015-05-01 17:47:54 +02:00
Les seules modifications spécifiques à ces dépôts sont les changements de versions (modification de `debian/changelog`, puis tag).
2015-02-04 12:15:45 +01:00
Des outils à destinations des mainteneurs de paquets sont disponibles sur le dépôt [yunohost-debhelper](https://github.com/YunoHost/yunohost-debhelper)
2015-02-04 12:15:45 +01:00
```bash
2015-05-01 17:47:54 +02:00
git clone https://github.com/YunoHost/yunohost-debhelper
yunohost-debhelper/setup_git_alias.sh
2015-02-04 12:15:45 +01:00
```
2016-01-30 22:00:44 +01:00
Ceci va configurer un nouvel alias git nommé `yunobump`, global (stocké dans `~/.gitconfig` et donc accessible depuis nimporte quel dépôt git local).
2015-02-04 12:22:23 +01:00
2015-05-01 17:47:54 +02:00
<div class="alert alert-warning">
2016-03-02 22:27:13 +01:00
**Attention :** pour le moment ce helper `yunobump` ne fonctionne que sous Ubuntu ou Debian Jessie. Vous **devez** installer les paquets `git` et `git-buildpackage` pour que le helper fonctionne correctement.
2015-05-01 17:47:54 +02:00
</div>
#### Sans helper
1. Rendez-vous dans le repo du paquet que vous voulez builder
2. Assurez-vous que la branche `unstable` contient toutes les modifications que vous voulez intégrer dans votre build
3. Récupérez le numéro de version actuel : `head debian/changelog`
4. Rendez-vous sur la branche `testing` ou `stable`
5. Mergez ou cherry-pickez les commits que vous voulez intégrer à la version depuis la branche `unstable`
6. Modifiez le `debian/changelog` en intégrant les messages de commits correspondant aux modifications que vous avez intégré (ou utilisez `git-dch` pour le faire automatiquement)
2016-03-02 22:27:13 +01:00
7. Taguez la branche actuelle (`testing` ou `stable`) du numéro de version juste supérieur à lactuel
2015-05-01 17:47:54 +02:00
8. Pushez vos modifications **ainsi que vos tags** sur le repo GitHub
9. Retournez sur la branche `unstable`
10. Mergez le changelog mis à jour précédemment
11. Pushez la branche `unstable`
#### Avec helper
2015-02-04 12:15:45 +01:00
```bash
2015-05-01 17:47:54 +02:00
# You Only Clone Once
2015-02-04 15:09:01 +01:00
$ git clone git@github.com:YunoHost/yunohost-config-nginx.git
$ cd yunohost-config-nginx
# Be sure to be up-to-date, and don't forget to get the tags !
$ git fetch --tags
2015-04-30 12:59:26 +02:00
# Checkout your branch : stable or testing
$ git checkout testing
2015-02-04 15:09:01 +01:00
2015-05-01 17:47:54 +02:00
# Do your 'functional' modifications: either merge unstable in testing, or merge testing in stable
$ git pull origin unstable
# Or just
$ git merge unstable
2015-02-04 15:09:01 +01:00
# What is the current version number in test ?
$ dpkg-parsechangelog | grep "^Version" | cut -d ' ' -f 2
2015-05-01 17:47:54 +02:00
# Or just
$ head debian/changelog
2015-02-04 15:09:01 +01:00
2015-05-01 17:47:54 +02:00
# Update changelog and do a proper tag (explained below)
2015-02-04 14:50:45 +01:00
$ git yunobump x.y.z-p
2015-02-04 15:09:01 +01:00
2015-05-01 17:47:54 +02:00
# Push the branch state AND the tags to the remote repository
$ git push origin --tags testing:testing
2015-02-04 12:15:45 +01:00
2015-05-01 17:47:54 +02:00
# Merge changelog modifications to the `unstable` branch
$ git checkout unstable
$ git merge testing
$ git push origin unstable
```
2015-02-04 12:22:23 +01:00
**TODO** politique sur les formats de tag, actuellement $branch/$version pour autoriser la même version dans deux branches différentes. est-ce vraiment souhaitable ?
2015-02-04 12:15:45 +01:00
**TODO** normalement à chaque push sur test ou stable, le dernier commit est un commit de changelog et il est taggué proprement. On doit pouvoir implémenter un hook git de pre-push qui empêche de pousser des trucs à moitié fait (une erreur dans git yunobump, un git tag -d, un commit à la main...)
2015-02-04 14:12:02 +01:00
2015-05-01 17:47:54 +02:00
#### Branche test et stable - faire un hotfix
2015-02-04 12:15:45 +01:00
2016-01-30 22:00:44 +01:00
Il peut arriver, de façon exceptionnelle, quon ait besoin de faire un hotfix (de sécurité par exemple) sur les paquets en `stable` ou en `test`, pour lequel le merge de la branche daily nest pas acceptable (car trop de nouvelles fonctionnalités en développement sur daily).
**Cette situation doit rester exceptionnelle**
2015-02-04 12:15:45 +01:00
**TODO** à décrire
2015-02-04 12:22:23 +01:00
**TODO** dev un helper 'git yunohotfix ...' qui commit dans stable et cherry-pick tout de suite dans daily ? ou linverse ?
2014-10-11 13:38:36 +02:00
2014-10-09 13:08:07 +02:00
#### Paquets non YunoHost
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Pour les paquets « non-YunoHost » (par exemple `rspamd`) le paquet ne passe pas par le composant `unstable`, mais uniquement `testing` et `stable` une fois les tests effectués sur ce paquet.
2015-05-01 17:47:54 +02:00
## Numéros de version
2016-03-28 10:47:36 +02:00
La version d'un paquet YunoHost est sous la forme : ``X.x.y[.z]``.
2015-05-01 17:47:54 +02:00
2016-03-28 10:47:36 +02:00
La première partie, ``X``, correspond à la version majeure de YunoHost, actuellement **2**.
2015-05-01 17:47:54 +02:00
2016-03-28 10:47:36 +02:00
La deuxième partie, ``x``, sincrémente lors dun changement fonctionnel important : ajout dune nouvelle fonctionnalité, modification dune façon de fonctionner, ... Les chiffres pairs correspondent à une version ``stable`` (ex. : **2.4.x**), tandis que les chiffres impairs à une version ``testing``.
2015-05-01 17:47:54 +02:00
2016-03-28 10:47:36 +02:00
La troisième partie, ``y``, sincrémente quasi-arbitrairement, lors dun lot de bugfixes ou dun changement fonctionnel mineur. On peut trouver par exemple des paquets en **2.1.3** ou **2.1.5**.
Enfin, une quatrième partie, ``z``, est réservée dans les cas exceptionnels de bugfix. Dans ce cas, on veut faire passer un changement unique, généralement directement dans la branche ``stable`` (voir la partie s'y rapportant). Cela donne, par exemple, **2.1.3.1**.
Note : les paquets de YunoHost étants natfis pour Debian (dans le sens où nous gérons directement le *packaging* Debian avec le paquet), il n'y a pas de révision Debian dans le numéro de version (caractérisé par **-debian_revision**). Pour plus de détails sur les numéros de version, voir le [Debian Policy Manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version).
2014-10-04 13:51:00 +02:00
2015-05-01 17:47:54 +02:00
## Gestion des paquets
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
### Outils et méthode
2014-10-09 13:08:07 +02:00
2016-03-07 12:45:10 +01:00
#### Logiciels et scripts utilisés
2014-10-09 13:08:07 +02:00
2016-03-07 12:45:10 +01:00
Les principaux logiciels utilisés pour la gestion et construction des paquets sont les suivants :
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
* [reprepro](https://mirrorer.alioth.debian.org/) : gérer localement un dépôt de paquets Debian
* [rebuildd](https://julien.danjou.info/projects/rebuildd) : reconstruire des paquets Debian, avec un historique, une interface Web, ...
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Pour plus de flexibilité, *rebuildd* délègue la construction du paquet à [pbuilder](https://pbuilder.alioth.debian.org/). Ce dernier permet notamment d'avoir différents environnements, architectures, ...
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Enfin, pour gérer au mieux ces outils, deux scripts ont été développé, stockés dans `/usr/local/bin` :
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
* `daily_build` : construire un ou tous les paquets YunoHost dans le composant **unstable** uniquement
* `build_deb` : construire un paquet Debian depuis un répertoire, dans un composant et un nom de code donné
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
À noter également que d'autres scripts ont été fait pour *rebuildd* et *reprepro*, afin notamment de faire le pont entre les deux. Ils se trouvent dans `/usr/local/bin/{rebuildd,reprepro}`.
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
#### Déroulement de la construction d'un paquet
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Tout est déclenché par *reprepro*, configuré (voir `/var/www/repo.yunohost.org/debian/conf/distribustion`) pour exécuter le script `/usr/local/bin/repo/process-include` chaque fois qu'un paquet est inclus dans un dépôt (plus précisément, qu'un fichier `.changes` est inclus, via la commande `reprepro include`). Ce dernier va vérifier un certain nombre de chose, dont le fait qu'il s'agit bien d'un paquet source, puis va ajouter une nouvelle tâche pour *rebuildd*, afin que le paquet soit créé.
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Lorsque la tâche est reçue par *rebuildd*, si le paquet correspond bien à une distribution et architecture supportée (voir `/etc/rebuildd/rebuilddrc`), trois scripts seront exécutés les uns après les autres, si aucune erreur n'intervient :
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
1. `/usr/local/bin/rebuildd/get-sources` : récupération des sources depuis le dépôt local pour le paquet et la version demandée
2. `/usr/local/bin/rebuildd/build-binaries` : construction du paquet via *pbuilder* et l'environnement correspondant à la distribution et l'architecture
3. `/usr/local/bin/rebuildd/upload-binaries` : ajout du paquet binaire précédemment créé à *reprepro* dans le bon dépôt et composant
2015-02-17 14:41:18 +01:00
2016-03-07 14:06:07 +01:00
### Utilisation de daily\_build
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Un cron défini pour lutilisateur `pbuilder` se lance **tous les jours à 01:00**, qui exécute le script `daily_build`. Pour chaque paquet (`ssowat`, `yunohost` et `yunohost-admin`), le script met d'abord à jour le dépôt git correspondant depuis la branche *unstable*. Si de nouveaux commits ont été fait depuis la veille, une nouvelle version du paquet sera construit.
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Plus précisément, une nouvelle entrée dans le *changelog* sera d'abord ajoutée, avec une version sous la forme **YYYY.MM.DD+HHMM**. Un paquet source sera ensuite construit, avant de passer le relais au script `/usr/local/bin/repo/include-changes`. Ce dernier va exécuter les bonnes commandes pour *reprepro* afin d'inclure dans le bon dépôt et composant le paquet source fraîchement créé.
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
#### (Re)build dun paquet YunoHost
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Il est possible de relancer manuellement le build dun paquet :
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
```bash
$ daily_build -p <nom_du_paquet>
```
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Il est aussi possible d'utiliser une branche autre que *unstable* :
2014-10-04 13:51:00 +02:00
```bash
2016-03-07 12:45:10 +01:00
$ daily_build -p <nom_du_paquet> -b <branch>
2014-10-04 13:51:00 +02:00
```
2016-03-07 12:45:10 +01:00
*Notez bien que ce script permet uniquement de construire des paquets dans le composant **unstable** !*
2014-10-04 13:51:00 +02:00
2016-03-07 12:58:56 +01:00
### Utilisation de build\_deb
2014-10-04 13:51:00 +02:00
2016-03-07 12:45:10 +01:00
Ce script permet de construire un paquet Debian quelconque, et de l'inclure dans un dépôt donné. Il est notamment utilisé pour construire les paquets `rspamd` et `rmilter`. Une fois le paquet source récupéré et extrait, il suffit de lancer la commande suivante :
2014-10-04 13:51:00 +02:00
2014-10-04 15:16:16 +02:00
```bash
2016-03-07 12:45:10 +01:00
$ build_deb -c distribution -d <composant> /chemin/du/paquet/source
2014-10-04 13:51:00 +02:00
```
2016-03-07 12:45:10 +01:00
### Gestion du dépôt
#### Lister les paquets
2014-10-04 13:51:00 +02:00
```bash
2016-03-07 12:45:10 +01:00
$ reprepro -V -b /var/www/repo.yunohost.org/debian -C <composant> list <nom_de_code>
2014-10-04 13:51:00 +02:00
```
#### Suppression dun paquet
2015-01-06 11:12:49 +01:00
```bash
2016-03-07 12:45:10 +01:00
$ reprepro -V -b /var/www/repo.yunohost.org/debian -C <composant> remove <nom_de_code> nom_du_paquet
2015-01-06 11:12:49 +01:00
```
2016-03-07 12:45:10 +01:00
#### Gestion des backports
Pour la gestion des paquets venant du dépôt backport, il est possible de les intégrer rapidement dans le dépôt de yunohost.
Pour ce faire il faut ajouter le nom du paquet dans le fichier `/var/www/repo.yunohost.org/debian/conf/<nom_de_code>-<composant>.list`, puis exécuter la commande :
```bash
$ reprepro -V -b /var/www/repo.yunohost.org/debian -C <composant> update <nom_de_code>
2016-03-07 12:55:59 +01:00
```