Documentation de Cookutils

SliTaz Cook & Cooker

Les Cookutils SliTaz fournissent les outils et utilitaires pour faciliter la construction de paquets SliTaz. Ils sont faciles à utiliser et à apprendre, rapides et légers. Vous pourrez créer des paquets SliTaz avec quelques commandes. Les Cookutils fournissent l'utilitaire 'cook' et le Cooker.

Cook vous permet de créer et de compiler un paquet, fournit un fichier journal et vérifie la qualité du paquet et de la recette. Le Cooker est un robot de fabrication avec plus d'automatismes et peut être utilisé comme outil de fabrication car il fournit une interface CGI/Web qui vous parmet de voir des journaux de cuisson agréables et coloriés. Cook et le Cooker se servent des mêmes wok et base de fichiers, il partagent les paquets bloqués et cassés tout comme leur activité.

Pour toute information technique, par exemple le style de codage, etc, veuillez vous référer au README qui se trouve dans les fichiers source ou dans /usr/share/doc/cookutils.

Usage de Cook

Cook donne une aide intégrée succinte que vous pouvez afficher avec la commande 'usage'. Il a aussi quelques options pour faire des tâches spécifiques avant ou après la cuisson. Pour avoir l'aide et l'usage :

# cook usage

Comment faire

La première chose à faire avant de cuire des paquets est de configurer votre environnement. Les 2 façons recommendées de travailler : cuire directement sur l'hôte ou cuire dans un chroot pour protéger votre hôte. Dans le cas où vous voulez travailler dans un chroot vous pouvez installer et utiliser Tazdev pour en créer un et vous placer à l'intérieur :

# tazdev gen-chroot && tazdev chroot

Par défaut Tazdev crée un chroot dans /home/slitaz/cooking/chroot mais vous pouvez spécifier un chemin quelconque en argument. L'endroit du chroot n'est pas important, lorsque vous serez dans le chroot vous utiliserez des chemins standards de SliTaz comme /home/slitaz/wok pour de répertoire du wok ou /home/slitaz/log pour tous les journaux de cuisson. Comme toujours vous pouvez afficher l'aide de tazdev avec : tazdev usage.

Lorsque vous utilisez un chroot il y a 2 répertoires spéciaux montés avec l'option bind : src et packages. Les sources pour tous les paquets sont stockés par défaut dans /home/slitaz/src, ce répertoire est monté dans le chroot pour que les outils puissient l'utiliser. Cette méthode vous permet de partager les sources avec plusieurs chroots par exemple un pour cooking et un pour stable. Le répertoire par défaut est : /home/slitaz/[version]/packages ainsi ils ne sont pas dans le chroot et ne sont pas affectés si le chroot est effacé par erreur.

Pour commencer

Donc vous avez décidé de la façon dont vous voulez travailler, alors préparons l'environnement de cuisson. Cook se sert du fichier de configuration cook.conf, si vous voulez utiliser des chemins inhabituels pour les répertoires et fichiers SliTaz, vous devez le modifier. Le paramétrage va créer quelques répertoires et fichiers pour garder une trace de la l'activité et des erreurs, tous les fichiers sont des fichiers textes simples que vous pouvez ouvrir dans un éditeur de texte. Pour préparer votre environnement :

# cook setup

La commande de paramétrage à une option --wok qui vous permet de cloner un wok SliTaz pendant la creation de l'environnement de cuisson. Même si vous n'êtes pas un développeur officiel vous pouver le cloner et utiliser les paquets existants comme exemple pour créer le vôtre. Pour paramétrer et cloner le wok cooking ou le wok undisgest par défaut ;

# cook setup --wok
# cook setup --undigest

Testez votre environnement

Cook fournit une commande de test qui crée un paquet et le cuit. Cela vous permet de voir si votre environnement fonctionne et donne un paquet exemple avec une recette. Le paquet s'appelle 'cooktest' et peut être retiré après avoir été testé. Pour cuire le paquet de test :

# cook test

Créer et cuire

Si votre environnement est correctement paramétré vous pouvez commencer à créer et compiler des paquets SliTaz depuis votre wok. Pour créer un nouveau pqauet avec une recette vide (vous pouvez aussi créer une recette interactivement) :

# cook new pkgname
# cook new pkgname --interactive

Si vous venez de créer un nouveau paquet, vous devrez éditer le recette avec votre éditeur de texte favori. Alors la recette est prête ou si vous avez déjà un paquet existant, vous pouvez le cuire :

# cook pkgname

Si tout c'est bien passé vous trouverez votre paquet dans le répertoire $SLITAZ/packages et tous les fichiers produits dans $SLITAZ/wok/pkgname.

Cuire et installer

Si vous voulez cuire et installer le paquet en une commande :

# cook pkgname --install

Obtenir les sources

Si vous voulez ou avez besion de seulement télécharger les sources d'un paquet sans le fabriquer, vous pouvez utiliser l'option --getsrc comme suit :

# cook pkgname --getsrc

Nettoyer les paquets

Après compilation et empaquetage il y a plusieurs fichiers dans le wok qui prennent de la place disque. Pour nettoyer un pqauet unique :

# cook pkgname --clean

Vous pouvez aussi nettoyer le wok en entier ou vous pouvez choisir de garder les fichiers SliTaz et seulement retirer les sources :

# cook clean-wok
# cook clean-src

Recherche

Cook fournit une fonction de recherche simple pour trouver rapidement un paquet dans le wok. Elle utilise grep et supporte des expressions régulières :

# cook search busybox

Functions de la recette

Beaucoup de paquets fournissent le même genre de fichiers comme les paquets *-dev avec les librairies statiques, les fichiers pkgconfig et les entêtes pour includes. Alors cook fournit une fonction à utiliser dans la recette :

get_dev_files     : Install /usr/lib/{lib.*a,pkgconfig} /usr/include

Liste de paquets

Cook peut lister les paquets dans le wok et ainsi créer une liste de paquets adaptée pour Tazpkg. Cela vous permet de créer votre dépôt de paquets assez facilement et c'est utiilisé pour créer la liste offcielle des paquets Slitaz sur les miroirs. Pour lister le wok actuellement utilisé par cook (il n'est pas nécessaire d'être root) :

$ cook list-wok

En créant la base (ou liste) de paquets, cook va vérifier si vous avez un dépôt de saveurs dans /home/slitaz/flavors ; si c'est la cas il va emballer toutes les saveurs en utilisant la dernière liste de paquets disponible. Pour créer une liste de paquets et les fichers de saveurs :

# cook pkgdb

Le Cooker

Le Cooker est un robot de compilation, sa première fonction est de rechercher les commits dans le wok, créer une liste ordonnée et cuire tous les paquets modifiés. Il peut aussi être utilisé comme interface pour cook car ils utilisent les mêmes fichiers. Le Cooker peut aussi être utilisé pour cuire une longue liste de paquets en une fois comme tous les paquets d'une saveur. Le cooker fournit une interface CGI/Web agréable qui fonctionne par défaut sur n'importe quel système SliTaz car il fournit le support CGI via le serveur httpd de busybox.

Le Cooker fournit une aide intégrée succinte et quelques commandes. Par exemple pour afficher l'usage vous pouvez faire :

# cooker usage
# cooker -u

Paramétrage du Cooker

Tout comme cook, le Cooker a besoin d'un environnement fonctionnel avant de commencer à l'utiliser. Le principale différence avec l'environnement de cook est que le Cooker a besoin de 2 woks. Un wok Hg propre comme référence et un wok de fabrication. De cette façon il est facile de comparer les 2 woks et d'obtenir les modifications. SI vous avez déjà un environnement pour cook, vous devez déplacer votre wok avant de paramétrer le Cooker ou il s'en plaindra. Le paramétrage installera aussi un ensemble de paquets de développement qui peuvent être définis dans le fichiers de configuration cook.conf avec la variable SETUP_PKGS. Pour paramétrer votre environnement cooker :

# cooker setup

Si tout ce passe correctement vous avez maintenant 2 woks, les paquets de developpement de base installés et tous les fichiers nécessaires créés. Le comportement par défaut est de rechercher les commits, vous pouvez lancer un test :

# cooker

Cuire avec le Cooker

Encore 2 façons de travailler maintenant : faire des modifications dans le nouveau wok Hg et lancer le cooker sans arguments ou cuire les paquets manuellement. Le cooker vous permet de cuire un paquet unique ou tous les paquets d'un catégorie ou d'une saveur. Vous pouvez aussi essayer de fabriquer tous les paquets non construits, mais sachez que le Cooker n'a pas été fait pour gérer des milliers de paquets.

Pour cuire un paquet unique comme 'cook pkgname' mais avec un journal en plus :

# cooker pkg pkgname

Pour cuire plus d'un paquet vous avez différentes possibilités. Vous pouvez utiliser un paquet existant comme ceux des saveurs live, vous pouvez aussi utiliser une liste personnelle avec des noms de paquet à chaque ligne. Enfin vous pouvez construire tous les paquets d'un catégorie.

# cooker flavor [name]
# cooker list [/path/to/cooklist]
# cooker cat [category]

Le cooker vous permet de recuire une révision spécifique de Hg. C'est utile en production ainsi si le robot de fabrication est interrompu pendant des commits en cooking, vous pouvez cuire les paquets à la main :

# cooker rev 9496

Le paquets bloqués

Cook et le Cooker gèrent un fichier contenant la liste des paquets bloqués afin de ne pas les cuire lors de commits ou si une liste de cuission est utilisée. C"est très utile pour un Robot de fabrication en production. Lorsque vous bloquez ou débloquez un paquet vous pouvez ajouter une note dans les cooknotes. Exemple de blocage de paquet :

# cook pkgname --block
# cooker block pkgname
# cooker -n "Blocked pkgname note"

La liste des paquets bloqués est affichée dans l'interface Web du Cooker. Pour débloquer un paquet vous devez utiliser la commande unblock ou l'option cook --unblock :

# cook pkgname --unblock
# cooker unblock pkgname

Cooker CGI/Web

Pour que vous puissiez voir les journaux de façon agréable, garder une trace de l'activité et vous aider à trouver les erreurs, vous pouvez utiliser l'interface Web du Cooker qui se trouve par défaut dans le dossier /var/www/cooker. Si vous n'utilisez pas un chroot et que le démon httpd de Busybox est lancé, l'interface Web fonctionnera sans configuration et sera visible en http://localhost/cooker/cooker.cgi

Si vous utilisez un environnement de chroot, vous devriez aussi installer cookutils sur votre hôte et modifier la variable de chemin SLITAZ. Une façon standard est d'avoir un chroot dans :

/home/slitaz/cooking/chroot

Avec /etc/slitaz/cook.conf modifié comme suit :

SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"

Note : il n'est pas obligatoire d'installer les cookutils sur votre hôte pour utiliser l'interface Web. Si vous utilisez Lighttpd vous pouvez aussi copier les fichiers cooker.cgi et style.css par exemple dans votre dossier ~/Public et utiliser un cook.conf perso avec. L'avantage d'installer cookutils sur l'hôte est d'avoir des mise à jour régulières par le gestionnaire de paquets Tazpkg. Disons que vous avez cloné ou téléchargé les cookutils :

$ cp -a cookutils/web ~/Public/cgi-bin/cooker
$ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker

Editez le fichier de configuration : ~/Public/cgi-bin/cooker/cook.conf pour mettre votre chemin SLITAZ et c'est tout !

Cooknotes

Le fonction cooknotes vous permet d'écrire de courtes notes personnelles au sujet de l'emballage et est utile pour travailler en groupe. Les cooknotes ont été codées pour que les mainteneur du Robot de fabrication de SliTaz partagent des informations avec les autres contributeurs. Les cooker peut bloquer la fabrication d'un paquet et recuire des paquets à la main, par exemple il est commode de faire une note si un paquet est bloqué afin que le mainteneur sache pourquoi l'administrateur a fait cela. Les cooknotes sont affichées dans l'interface Web et peuvent être vérifiées depuis la ligne de commande :

# cooker note "Blocked pkgname due to heavy CPU load"
# cooker notes

Le Cooker comme robot de fabrication

Le Cooker est conçu pour être le robot de fabrication de SliTaz, c'est à dire qu'il contrôle 2 woks, met à jour le wok Hg, obtient les différences et cuit tous les paquets qui ont été commités. La façon la plus sûre et la plus propre de lancer le Cooker comme robot de fabrication avec cron est d'utiliser un environnement de chroot, mais il peut tourner directement sur l'hôte si vous le voulez.

Pour lance de Cooker automatiquement vous devez utiliser crom depuis le chroot et ajouter un ligne dans le crontab de root dans /var/spool/cron/crontabs. Disons que vous souhaitez lancer le Cooker toutes les 2 heures :

* */2 * * * /usr/bin/cooker

Lancer le Robot Cooker au boot

L'environnement du Cooker et la tâche cron peut être automatiquement lancée au démarrage. Vous devez avoir installé le paquet cookutils-daemon sur l'hôte et utiliser une installation standard SliTaz pour qu'il fonctionne correctement (la cooking se trouve dans /home/slitaz/cooking). Ce script va monter les systèmes de fichiers virtuels nécessaires pour les sources et les paquets. Les fichiers sources se trouvent dans /home/slitaz/src et sont reliés au chroot pour que vous puissiez les partager entre plusieurs version (stable, cooking, undigest). Si ce paquet n'est pas encore installé :

# tazpkg get-install cookutils-daemon

Pour lancer le daemon vous devez avoir une définition de ficher cron pour root dans le chroot, le script daemon fonctionne comme tous les autres daemons système et peut être controllé avec :

# /etc/init.d/cooker [start|stop|restart]