Commit | Line | Data |
---|---|---|
bf5c74e7 JL |
1 | @node Contribuer |
2 | @chapter Contribuer | |
3 | ||
4 | Ce projet est un effort coopératif et nous avons besoin de votre aide pour | |
5 | le faire grandir ! Contactez-nous sur @email{guix-devel@@gnu.org} et | |
3cacfa9e LC |
6 | @code{#guix} sur le réseau IRC Freenode. Nous accueillons les idées, les |
7 | rapports de bogues, les correctifs et tout ce qui pourrait aider le projet. | |
8 | Nous apprécions particulièrement toute aide sur la création de paquets | |
9 | (@pxref{Consignes d'empaquetage}). | |
bf5c74e7 JL |
10 | |
11 | @cindex code de conduite, des contributeurs | |
12 | @cindex convention de contribution | |
13 | Nous souhaitons fournir un environnement chaleureux, amical et sans | |
14 | harcèlement pour que tout le monde puisse contribuer au mieux de ses | |
3cacfa9e LC |
15 | capacités. Pour cela notre projet a une « Convention de contribution » |
16 | adaptée de @url{http://contributor-covenant.org/}. Vous pouvez trouver une | |
bf5c74e7 JL |
17 | version locale dans le fichier @file{CODE-OF-CONDUCT} dans l'arborescence |
18 | des sources. | |
19 | ||
20 | Les contributeurs n'ont pas besoin d'utiliser leur nom légal dans leurs | |
21 | correctifs et leurs communications en ligne ; ils peuvent utiliser n'importe | |
22 | quel nom ou pseudonyme de leur choix. | |
23 | ||
24 | @menu | |
3cacfa9e | 25 | * Construire depuis Git:: toujours le plus récent. |
bf5c74e7 JL |
26 | * Lancer Guix avant qu'il ne soit installé:: Astuces pour les hackers. |
27 | * La configuration parfaite:: Les bons outils. | |
15f1bff4 | 28 | * Consignes d'empaquetage:: Faire grandir la distribution. |
bf5c74e7 JL |
29 | * Style de code:: Hygiène du contributeur. |
30 | * Envoyer des correctifs:: Partager votre travail. | |
31 | @end menu | |
32 | ||
33 | @node Construire depuis Git | |
34 | @section Construire depuis Git | |
35 | ||
36 | Si vous souhaitez travailler sur Guix lui-même, il est recommandé d'utiliser | |
37 | la dernière version du dépôt Git : | |
38 | ||
39 | @example | |
40 | git clone https://git.savannah.gnu.org/git/guix.git | |
41 | @end example | |
42 | ||
43 | Lors de la construction de Guix depuis un extrait, les paquets suivants sont | |
44 | requis en plus de ceux mentionnés dans les instructions d'installation | |
45 | (@pxref{Prérequis}). | |
46 | ||
47 | @itemize | |
48 | @item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; | |
49 | @item @url{http://gnu.org/software/automake/, GNU Automake}; | |
50 | @item @url{http://gnu.org/software/gettext/, GNU Gettext}; | |
51 | @item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; | |
52 | @item @url{http://www.graphviz.org/, Graphviz}; | |
53 | @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (facultatif)}. | |
54 | @end itemize | |
55 | ||
56 | La manière la plus simple de configurer un environnement de développement | |
57 | pour Guix est, bien sûr, d'utiliser Guix ! La commande suivante démarre un | |
58 | nouveau shell où toutes les dépendances et les variables d'environnements | |
59 | appropriées sont configurés pour travailler sur Guix : | |
60 | ||
61 | @example | |
62 | guix environment guix | |
63 | @end example | |
64 | ||
65 | @xref{Invoquer guix environment}, pour plus d'information sur cette | |
3cacfa9e | 66 | commande. On peut ajouter des dépendances supplémentaires avec |
bf5c74e7 JL |
67 | @option{--ad-hoc} : |
68 | ||
69 | @example | |
70 | guix environment guix --ad-hoc help2man git strace | |
71 | @end example | |
72 | ||
73 | Lancez @command{./bootstrap} pour générer l'infrastructure du système de | |
3cacfa9e | 74 | construction avec Autoconf et Automake. Si vous avez une erreur comme : |
bf5c74e7 JL |
75 | |
76 | @example | |
77 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES | |
78 | @end example | |
79 | ||
80 | @noindent | |
81 | cela signifie probablement qu'Autoconf n'a pas pu trouver @file{pkg.m4} qui | |
3cacfa9e LC |
82 | est fournit par pkg-config. Assurez-vous que @file{pkg.m4} est disponible. |
83 | C'est aussi vrai pour l'ensemble de macros de @file{guile.m4} fournies par | |
84 | Guile. Par exemple, si vous avez installé Automake dans @file{/usr/local}, | |
85 | il ne cherchera pas les fichiers @file{.m4} dans @file{/usr/share}. Dans ce | |
86 | case vous devez invoquer la commande suivante : | |
bf5c74e7 JL |
87 | |
88 | @example | |
89 | export ACLOCAL_PATH=/usr/share/aclocal | |
90 | @end example | |
91 | ||
92 | @xref{Macro Search Path,,, automake, The GNU Automake Manual}, pour plus | |
93 | d'information. | |
94 | ||
3cacfa9e | 95 | Ensuite, lancez @command{./configure} comme d'habitude. Assurez-vous de |
bf5c74e7 JL |
96 | passer @code{--localstatedir=@var{directory}} où @var{directory} est la |
97 | valeur @code{localstatedir} utilisée par votre installation actuelle | |
98 | (@pxref{Le dépôt} pour plus d'informations à ce propos). | |
99 | ||
100 | Finalement, vous devez invoquer @code{make check} pour lancer les tests | |
3cacfa9e | 101 | (@pxref{Lancer la suite de tests}). Si quelque chose échoue, jetez un œil |
bf5c74e7 | 102 | aux instructions d'installation (@pxref{Installation}) ou envoyez un message |
15f1bff4 | 103 | à la liste @email{guix-devel@@gnu.org}. |
bf5c74e7 JL |
104 | |
105 | ||
106 | @node Lancer Guix avant qu'il ne soit installé | |
107 | @section Lancer Guix avant qu'il ne soit installé | |
108 | ||
109 | Pour garder un environnement de travail sain, il est utile de tester les | |
3cacfa9e | 110 | changement localement sans les installer pour de vrai. Pour pouvoir |
bf5c74e7 JL |
111 | distinguer votre rôle « d'utilisateur final » de celui parfois haut en |
112 | couleur de « développeur ». | |
113 | ||
adfb167f JL |
114 | Pour cela, tous les outils en ligne de commande sont utilisables même sans |
115 | avoir lancé @code{make install}. Pour cela, vous devez d'abord avoir un | |
116 | environnement avec toutes les dépendances disponibles (@pxref{Construire depuis Git}), puis préfixer chaque commande par @command{./pre-inst-env} (le script | |
117 | @file{pre-inst-env} se trouve dans le répertoire de plus haut niveau de | |
118 | l'arborescence des sources de Guix ; il est généré par | |
119 | @command{./configure}) comme cela@footnote{L'option @option{-E} de | |
120 | @command{sudo} garantie que @code{GUILE_LOAD_PATH} est bien paramétré pour | |
121 | @command{guix-daemon} et pour que les outils qu'il utilise puissent trouver | |
122 | les modules Guile dont ils ont besoin.} : | |
bf5c74e7 JL |
123 | |
124 | @example | |
125 | $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild | |
126 | $ ./pre-inst-env guix build hello | |
127 | @end example | |
128 | ||
129 | @noindent | |
130 | De même, pour une session Guile qui utilise les modules Guix : | |
131 | ||
132 | @example | |
133 | $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' | |
134 | ||
135 | ;;; ("x86_64-linux") | |
136 | @end example | |
137 | ||
138 | @noindent | |
139 | @cindex REPL | |
140 | @cindex read-eval-print loop | |
141 | @dots{} et pour un REPL (@pxref{Using Guile Interactively,,, guile, Guile | |
142 | Reference Manual}) | |
143 | ||
144 | @example | |
145 | $ ./pre-inst-env guile | |
146 | scheme@@(guile-user)> ,use(guix) | |
147 | scheme@@(guile-user)> ,use(gnu) | |
148 | scheme@@(guile-user)> (define snakes | |
149 | (fold-packages | |
150 | (lambda (package lst) | |
151 | (if (string-prefix? "python" | |
152 | (package-name package)) | |
153 | (cons package lst) | |
154 | lst)) | |
155 | '())) | |
156 | scheme@@(guile-user)> (length snakes) | |
157 | $1 = 361 | |
158 | @end example | |
159 | ||
160 | Le script @command{pre-inst-env} paramètre toutes les variables | |
161 | d'environnement nécessaires, dont @env{PATH} et @env{GUILE_LOAD_PATH}. | |
162 | ||
163 | Remarquez que @command{./pre-inst-env guix pull} ne met @emph{pas} à jour | |
2cf2c778 JL |
164 | l'arborescence des sources locale ; cela met seulement à jour le lien |
165 | symbolique de @file{~/.config/guix/current} (@pxref{Invoquer guix pull}). | |
3cacfa9e | 166 | Lancez @command{git pull} à la place si vous voulez mettre à jour votre |
2cf2c778 | 167 | arborescence des source locale. |
bf5c74e7 JL |
168 | |
169 | ||
170 | @node La configuration parfaite | |
171 | @section La configuration parfaite | |
172 | ||
15f1bff4 JL |
173 | The Perfect Setup to hack on Guix is basically the perfect setup used for |
174 | Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference | |
175 | Manual}). First, you need more than an editor, you need | |
176 | @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful | |
177 | @url{http://nongnu.org/geiser/, Geiser}. To set that up, run: | |
178 | ||
179 | @example | |
180 | guix package -i emacs guile emacs-geiser | |
181 | @end example | |
bf5c74e7 JL |
182 | |
183 | Geiser permet le développement interactif et incrémental depuis Emacs : la | |
184 | compilation du code et son évaluation depuis les buffers, l'accès à la | |
185 | documentation en ligne (docstrings), la complétion sensible au contexte, | |
186 | @kbd{M-.} pour sauter à la définition d'un objet, un REPL pour tester votre | |
3cacfa9e LC |
187 | code, et bien plus (@pxref{Introduction,,, geiser, Geiser User Manual}). |
188 | Pour travailler confortablement sur Guix, assurez-vous de modifier le chemin | |
189 | de chargement de Guile pour qu'il trouve les fichiers source de votre dépôt | |
190 | : | |
bf5c74e7 JL |
191 | |
192 | @lisp | |
193 | ;; @r{Si l'extrait est dans ~/src/guix.} | |
194 | (with-eval-after-load 'geiser-guile | |
195 | (add-to-list 'geiser-guile-load-path "~/src/guix")) | |
196 | @end lisp | |
197 | ||
3cacfa9e LC |
198 | Pour effectivement éditer le code, Emacs a déjà un très bon mode Scheme. |
199 | Mais en plus de ça, vous ne devez pas rater | |
200 | @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Il fournit des | |
201 | fonctionnalités pour opérer directement sur l'arbre de syntaxe, comme | |
202 | relever une s-expression ou l'envelopper, absorber ou rejeter la | |
203 | s-expression suivante, etc. | |
bf5c74e7 JL |
204 | |
205 | @cindex extraits de code | |
206 | @cindex modèles | |
207 | @cindex réduire la quantité de code commun | |
208 | Nous fournissons aussi des modèles pour les messages de commit git communs | |
3cacfa9e | 209 | et les définitions de paquets dans le répertoire @file{etc/snippets}. Ces |
bf5c74e7 JL |
210 | modèles s'utilisent avec @url{http://joaotavora.github.io/yasnippet/, |
211 | YASnippet} pour développer des chaînes courtes de déclenchement en extraits | |
3cacfa9e | 212 | de texte interactifs. Vous pouvez ajouter le répertoire des modèles dans la |
bf5c74e7 JL |
213 | variables @var{yas-snippet-dirs} d'Emacs. |
214 | ||
215 | @lisp | |
216 | ;; @r{Si l'extrait est dans ~/src/guix.} | |
217 | (with-eval-after-load 'yasnippet | |
218 | (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) | |
219 | @end lisp | |
220 | ||
adfb167f JL |
221 | Les extraits de messages de commit dépendent de @url{https://magit.vc/, |
222 | Magit} pour afficher les fichiers sélectionnés. Lors de la modification | |
223 | d'un message de commit, tapez @code{add} suivi de @kbd{TAB} pour insérer un | |
224 | modèle de message de commit pour ajouter un paquet ; tapez @code{update} | |
225 | suivi de @kbd{TAB} pour insérer un modèle pour la mise à jour d'un paquet ; | |
226 | tapez @code{https} suivi de @kbd{TAB} pour insérer un modèle pour le | |
227 | changement à HTTPS de l'URI de la page d'accueil. | |
bf5c74e7 JL |
228 | |
229 | L'extrait principal pour @code{scheme-mode} est lancé en tapant | |
3cacfa9e LC |
230 | @code{package…} suivi par @kbd{TAB}. Cet extrait insère aussi la chaîne de |
231 | déclenchement @code{origin…}, qui peut aussi être étendue. L'extrait | |
bf5c74e7 JL |
232 | @code{origin} lui-même peut aussi insérer des chaînes de déclenchement qui |
233 | finissent sur @code{…}, qui peuvent aussi être étendues. | |
234 | ||
235 | ||
15f1bff4 JL |
236 | @node Consignes d'empaquetage |
237 | @section Consignes d'empaquetage | |
238 | ||
239 | @cindex paquets, création | |
240 | The GNU distribution is nascent and may well lack some of your favorite | |
241 | packages. This section describes how you can help make the distribution | |
242 | grow. | |
243 | ||
244 | Les paquets de logiciels libres sont habituellement distribués sous forme | |
245 | @dfn{d'archives de sources} — typiquement des fichiers @file{.tar.gz} | |
246 | contenant tous les fichiers sources. Ajouter un paquet à la distribution | |
247 | signifie essentiellement deux choses : ajouter une @dfn{recette} qui décrit | |
248 | comment construire le paquet, avec une liste d'autres paquets requis pour le | |
249 | construire, et ajouter des @dfn{métadonnées de paquet} avec la recette, | |
250 | comme une description et une licence. | |
251 | ||
252 | Dans Guix, toutes ces informations sont incorporées dans les | |
253 | @dfn{définitions de paquets}. Les définitions de paquets fournissent une | |
254 | vue de haut-niveau du paquet. Elles sont écrites avec la syntaxe du langage | |
255 | de programmation Scheme ; en fait, pour chaque paquet nous définissons une | |
256 | variable liée à la définition et exportons cette variable à partir d'un | |
257 | module (@pxref{Modules de paquets}). Cependant, il n'est @emph{pas} nécessaire | |
258 | d'avoir une connaissance approfondie du Scheme pour créer des paquets. Pour | |
259 | plus d'informations sur les définitions des paquets, @pxref{Définition des paquets}. | |
260 | ||
261 | Une fois une définition de paquet en place, stocké dans un fichier de | |
262 | l'arborescence des sources de Guix, il peut être testé avec la commande | |
263 | @command{guix build} (@pxref{Invoquer guix build}). Par exemple, en | |
264 | supposant que le nouveau paquet s'appelle @code{gnew}, vous pouvez lancer | |
265 | cette commande depuis l'arborescence de construction de Guix (@pxref{Lancer Guix avant qu'il ne soit installé}) : | |
266 | ||
267 | @example | |
268 | ./pre-inst-env guix build gnew --keep-failed | |
269 | @end example | |
270 | ||
271 | Utiliser @code{--keep-failed} rend facile le débogage des échecs car il | |
272 | fournit l'accès à l'arborescence de construction qui a échouée. Une autre | |
273 | sous-commande utile pour le débogage est @code{--log-file}, pour accéder au | |
274 | journal de construction. | |
275 | ||
276 | Si le paquet n'est pas connu de la commande @command{guix}, il se peut que | |
277 | le fichier source ait une erreur de syntaxe, ou qu'il manque une clause | |
278 | @code{define-public} pour exporter la variable du paquet. Pour comprendre | |
279 | cela, vous pouvez charger le module depuis Guile pour avoir plus | |
280 | d'informations sur la véritable erreur : | |
281 | ||
282 | @example | |
283 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' | |
284 | @end example | |
285 | ||
286 | Once your package builds correctly, please send us a patch | |
287 | (@pxref{Envoyer des correctifs}). Well, if you need help, we will be happy to | |
288 | help you too. Once the patch is committed in the Guix repository, the new | |
289 | package automatically gets built on the supported platforms by | |
290 | @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration | |
291 | system}. | |
292 | ||
293 | @cindex substitution | |
294 | Users can obtain the new package definition simply by running @command{guix | |
295 | pull} (@pxref{Invoquer guix pull}). When @code{@value{SUBSTITUTE-SERVER}} | |
296 | is done building the package, installing the package automatically downloads | |
297 | binaries from there (@pxref{Substituts}). The only place where human | |
298 | intervention is needed is to review and apply the patch. | |
299 | ||
300 | ||
301 | @menu | |
302 | * Liberté logiciel:: Ce que la distribution peut contenir. | |
303 | * Conventions de nommage:: Qu'est-ce qu'un bon nom ? | |
304 | * Numéros de version:: Lorsque le nom n'est pas suffisant. | |
305 | * Synopsis et descriptions:: Aider les utilisateurs à trouver le bon | |
306 | paquet. | |
307 | * Modules python:: Un peu de comédie anglaise. | |
308 | * Modules perl:: Petites perles. | |
309 | * Paquets java:: Pause café. | |
310 | * Polices de caractères:: À fond les fontes. | |
311 | @end menu | |
312 | ||
313 | @node Liberté logiciel | |
314 | @subsection Liberté logiciel | |
315 | ||
316 | @c =========================================================================== | |
317 | @c | |
318 | @c This file was generated with po4a. Translate the source file. | |
319 | @c | |
320 | @c =========================================================================== | |
321 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. | |
322 | @cindex logiciel libre | |
323 | Le système d'exploitation GNU a été développé pour que les utilisateurs | |
324 | puissent utiliser leur ordinateur en toute liberté. GNU est un | |
325 | @dfn{logiciel libre}, ce qui signifie que les utilisateur ont les | |
326 | @url{http://www.gnu.org/philosophy/free-sw.fr.html,quatre libertés | |
327 | essentielles} : exécuter le programmer, étudier et modifier le programme | |
328 | sous sa forme source, redistribuer des copies exactes et distribuer les | |
329 | versions modifiées. Les paquets qui se trouvent dans la distribution GNU ne | |
330 | fournissent que des logiciels qui respectent ces quatre libertés. | |
331 | ||
332 | En plus, la distribution GNU suit les | |
333 | @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,recommandations | |
334 | pour les distributions systèmes libres}. Entre autres choses, ces | |
335 | recommandations rejettent les microgiciels non libres, les recommandations | |
336 | de logiciels non libres et discute des façon de gérer les marques et les | |
337 | brevets. | |
338 | ||
339 | Certaines sources amont autrement parfaitement libres contiennent une petite | |
340 | partie facultative qui viole les recommandations ci-dessus, par exemple car | |
341 | cette partie est du code non-libre. Lorsque cela arrive, les éléments en | |
342 | question sont supprimés avec des correctifs ou des bouts de codes appropriés | |
343 | dans la forme @code{origin} du paquet (@pxref{Définition des paquets}). De cette | |
344 | manière, @code{guix build --source} renvoie la source « libérée » plutôt que | |
345 | la source amont sans modification. | |
346 | ||
347 | ||
348 | @node Conventions de nommage | |
349 | @subsection Conventions de nommage | |
350 | ||
351 | @cindex nom du paquet | |
352 | Un paquet a en fait deux noms qui lui sont associés : d'abord il y a le nom | |
353 | de la @emph{variable Scheme}, celui qui suit @code{define-public}. Par ce | |
354 | nom, le paquet peut se faire connaître par le code Scheme, par exemple comme | |
355 | entrée d'un autre paquet. Deuxièmement, il y a la chaîne dans le champ | |
356 | @code{name} d'une définition de paquet. Ce nom est utilisé par les | |
357 | commandes de gestion des paquets comme @command{guix package} et | |
358 | @command{guix build}. | |
359 | ||
360 | Les deux sont habituellement les mêmes et correspondent à la conversion en | |
361 | minuscule du nom du projet choisi en amont, où les underscores sont | |
362 | remplacés par des tirets. Par exemple, GNUnet est disponible en tant que | |
363 | @code{gnunet} et SDL_net en tant que @code{sdl-net}. | |
364 | ||
365 | Nous n'ajoutons pas de préfixe @code{lib} au bibliothèques de paquets, à | |
366 | moins qu'il ne fasse partie du nom officiel du projet. Mais @pxref{Modules python} et @ref{Modules perl} pour des règles spéciales concernant les | |
367 | modules pour les langages Python et Perl. | |
368 | ||
369 | Les noms de paquets de polices sont gérés différemment, @pxref{Polices de caractères}. | |
370 | ||
371 | ||
372 | @node Numéros de version | |
373 | @subsection Numéros de version | |
374 | ||
375 | @cindex version du paquet | |
376 | Nous n'incluons en général que la dernière version d'un projet de logiciel | |
377 | libre donné. Mais parfois, par exemple pour des versions incompatibles de | |
378 | bibliothèques, deux (ou plus) versions du même paquet sont requises. Elles | |
379 | ont besoin d'un nom de variable Scheme différent. Nous utilisons le nom | |
380 | défini dans @ref{Conventions de nommage} pour la version la plus récente ; les | |
381 | versions précédentes utilisent le même nom, suffixé par @code{-} et le plus | |
382 | petit préfixe du numéro de version qui permet de distinguer deux versions. | |
383 | ||
384 | Le nom dans la définition du paquet est le même pour toutes les versions | |
385 | d'un paquet et ne contient pas de numéro de version. | |
386 | ||
387 | Par exemple, les version 2.24.20 et 3.9.12 de GTK+ peuvent être inclus de | |
388 | cette manière : | |
389 | ||
390 | @example | |
391 | (define-public gtk+ | |
392 | (package | |
393 | (name "gtk+") | |
394 | (version "3.9.12") | |
395 | ...)) | |
396 | (define-public gtk+-2 | |
397 | (package | |
398 | (name "gtk+") | |
399 | (version "2.24.20") | |
400 | ...)) | |
401 | @end example | |
402 | Si nous voulons aussi GTK+ 3.8.2, cela serait inclus de cette manière : | |
403 | @example | |
404 | (define-public gtk+-3.8 | |
405 | (package | |
406 | (name "gtk+") | |
407 | (version "3.8.2") | |
408 | ...)) | |
409 | @end example | |
410 | ||
411 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, | |
412 | @c for a discussion of what follows. | |
413 | @cindex numéro de version, pour les instantanés des systèmes de contrôle de version | |
414 | Parfois, nous incluons des paquets provenant d'instantanés de systèmes de | |
415 | contrôle de version (VCS) au lieu de versions publiées formellement. Cela | |
416 | devrait rester exceptionnel, car c'est le rôle des développeurs amont de | |
417 | spécifier quel est la version stable. Cependant, c'est parfois nécessaire. | |
418 | Donc, que faut-il mettre dans le champ @code{version} ? | |
419 | ||
420 | Clairement, nous devons rendre l'identifiant de commit de l'instantané du | |
421 | VCS visible dans la version, mais nous devons aussi nous assurer que la | |
422 | version augmente de manière monotone pour que @command{guix package | |
423 | --upgrade} puisse déterminer quelle version est la plus récente. Comme les | |
424 | identifiants de commits, notamment avec Git, n'augmentent pas, nous ajoutons | |
425 | un numéro de révision qui nous augmentons à chaque fois que nous mettons à | |
426 | jour vers un nouvel instantané. La chaîne qui en résulte ressemble à cela : | |
427 | ||
428 | @example | |
429 | 2.0.11-3.cabba9e | |
430 | ^ ^ ^ | |
431 | | | `-- ID du commit en amont | |
432 | | | | |
433 | | `--- révision du paquet Guix | |
434 | | | |
435 | dernière version en amont | |
436 | @end example | |
437 | ||
438 | C'est une bonne idée de tronquer les identifiants dans le champ | |
439 | @code{version} à disons 7 caractères. Cela évite un problème esthétique (en | |
440 | supposant que l'esthétique ait un rôle à jouer ici) et des problèmes avec | |
441 | les limites de l'OS comme la longueur maximale d'un shebang (127 octets pour | |
442 | le noyau Linux). Il vaut mieux utilise l'identifiant de commit complet dans | |
443 | @code{origin} cependant, pour éviter les ambiguïtés. Une définition de | |
444 | paquet peut ressembler à ceci : | |
445 | ||
446 | @example | |
447 | (define my-package | |
448 | (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") | |
449 | (revision "1")) ;révision du paquet Guix | |
450 | (package | |
451 | (version (git-version "0.9" revision commit)) | |
452 | (source (origin | |
453 | (method git-fetch) | |
454 | (uri (git-reference | |
455 | (url "git://example.org/my-package.git") | |
456 | (commit commit))) | |
457 | (sha256 (base32 "1mbikn@dots{}")) | |
458 | (file-name (git-file-name name version)))) | |
459 | ;; @dots{} | |
460 | ))) | |
461 | @end example | |
462 | ||
463 | @node Synopsis et descriptions | |
464 | @subsection Synopsis et descriptions | |
465 | ||
466 | @cindex description du paquet | |
467 | @cindex résumé du paquet | |
468 | Comme nous l'avons vu avant, chaque paquet dans GNU@tie{}Guix contient un | |
469 | résumé et une description (@pxref{Définition des paquets}). Les résumés et les | |
470 | descriptions sont importants : ce sont eux que recherche @command{guix | |
471 | package --search}, et c'est une source d'informations cruciale pour aider | |
472 | les utilisateurs à déterminer si un paquet donner correspond à leurs | |
473 | besoins. En conséquence, les mainteneurs doivent prêter attention à leur | |
474 | contenu. | |
475 | ||
476 | Les résumés doivent commencer par une lettre capitale et ne doit pas finir | |
477 | par un point. Ils ne doivent pas commencer par « a » ou « the » (« un » ou | |
478 | « le/la »), ce qui n'apporte généralement rien ; par exemple, préférez « | |
479 | File-frobbing tool » (« Outil de frobage de fichier ») à « A tool that frobs | |
480 | file » (« Un outil qui frobe les fichiers »). Le résumé devrait dire ce que | |
481 | le paquet est — p.@: ex.@: « Utilitaire du cœur de GNU (fichier, text, | |
482 | shell) » — ou ce à quoi il sert — p.@: ex.@: le résumé de grep est « Affiche | |
483 | des lignes correspondant à un motif ». | |
484 | ||
485 | Gardez à l'esprit que le résumé doit avoir un sens pour une large audience. | |
486 | Par exemple « Manipulation d'alignements au format SAM » peut avoir du sens | |
487 | pour un bioinformaticien chevronné, mais n'aidera pas ou pourra perdre une | |
488 | audience de non-spécialistes. C'est une bonne idée de créer un résumé qui | |
489 | donne une idée du domaine d'application du paquet. Dans cet exemple, cela | |
490 | donnerait « Manipulation d'alignements de séquences de nucléotides », ce qui | |
491 | devrait donner une meilleure idée à l'utilisateur pour savoir si c'est ce | |
492 | qu'il recherche. | |
493 | ||
494 | Les descriptions devraient faire entre cinq et dix lignes. Utilisez des | |
495 | phrases complètes, et évitez d'utiliser des acronymes sans les introduire | |
496 | d'abord. Évitez les phrases marketings comme « world-leading », « | |
497 | industrial-strength » et « next-generation » et évitez les superlatifs comme | |
498 | « the most advanced » — ils ne sont pas utiles pour les utilisateurs qui | |
499 | cherchent un paquet et semblent même un peu suspects. À la place, essayez | |
500 | d'être factuels, en mentionnant les cas d'utilisation et les | |
501 | fonctionnalités. | |
502 | ||
503 | @cindex balisage texinfo, dans les descriptions de paquets | |
504 | Les descriptions peuvent inclure du balisage Texinfo, ce qui est utile pour | |
505 | introduire des ornements comme @code{@@code} ou @code{@@dfn}, des listes à | |
506 | points ou des hyperliens (@pxref{Overview,,, texinfo, GNU Texinfo}). | |
507 | Cependant soyez prudents lorsque vous utilisez certains symboles, par | |
508 | exemple @samp{@@} et les accolades qui sont les caractères spéciaux de base | |
509 | en Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). Les | |
510 | interfaces utilisateurs comme @command{guix package --show} prennent en | |
511 | charge le rendu. | |
512 | ||
513 | Les résumés et les descriptions sont traduits par des volontaires | |
514 | @uref{http://translationproject.org/domain/guix-packages.html, sur le projet | |
515 | de traduction} pour que le plus d'utilisateurs possible puissent les lire | |
516 | dans leur langue natale. Les interfaces utilisateurs les recherchent et les | |
517 | affichent dans la langue spécifiée par le paramètre de régionalisation | |
518 | actuel. | |
519 | ||
520 | Pour permettre à @command{xgettext} de les extraire comme des chaînes | |
521 | traduisibles, les résumés et les descriptions @emph{doivent être des chaînes | |
522 | litérales}. Cela signifie que vous ne pouvez pas utiliser | |
523 | @code{string-append} ou @code{format} pour construire ces chaînes : | |
524 | ||
525 | @lisp | |
526 | (package | |
527 | ;; @dots{} | |
528 | (synopsis "Ceci est traduisible") | |
529 | (description (string-append "Ceci n'est " "*pas*" " traduisible."))) | |
530 | @end lisp | |
531 | ||
532 | La traduction demande beaucoup de travail, donc en tant que packageur, | |
533 | faîtes encore plus attention à vos résumés et descriptions car chaque | |
534 | changement peut demander d'autant plus de travail de la part des | |
535 | traducteurs. Pour les aider, il est possible de donner des recommandations | |
536 | ou des instructions qu'ils pourront voir en insérant des commentaires | |
537 | spéciaux comme ceci (@pxref{xgettext Invocation,,, gettext, GNU Gettext}) : | |
538 | ||
539 | @example | |
540 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. | |
541 | (description "ARandR is designed to provide a simple visual front end | |
542 | for the X11 resize-and-rotate (RandR) extension. @dots{}") | |
543 | @end example | |
544 | ||
545 | ||
546 | @node Modules python | |
547 | @subsection Modules python | |
548 | ||
549 | @cindex python | |
550 | Nous incluons actuellement Python 2 et Python 3, sous les noms de variables | |
551 | Scheme @code{python-2} et @code{python} comme expliqué dans @ref{Numéros de version}. Pour éviter la confusion et les problèmes de noms avec d'autres | |
552 | langages de programmation, il semble désirable que le nom d'un paquet pour | |
553 | un module Python contienne le mot @code{python}. | |
554 | ||
555 | Certains modules ne sont compatibles qu'avec une version de Python, d'autres | |
556 | avec les deux. Si le paquet Foo ne compile qu'avec Ptyhon 3, on le nomme | |
557 | @code{python-foo} ; s'il ne compile qu'avec Python 2, on le nome | |
558 | @code{python2-foo}. S'il est compatible avec les deux versions, nous créons | |
559 | deux paquets avec les noms correspondant. | |
560 | ||
561 | If a project already contains the word @code{python}, we drop this; for | |
562 | instance, the module python-dateutil is packaged under the names | |
563 | @code{python-dateutil} and @code{python2-dateutil}. If the project name | |
564 | starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as | |
565 | described above. | |
566 | ||
567 | @subsubsection Spécifier les dépendances | |
568 | @cindex entrées, pour les paquets Python | |
569 | ||
570 | Les informations de dépendances pour les paquets Python se trouvent | |
571 | généralement dans l'arborescence des source du paquet, avec plus ou moins de | |
572 | précision : dans le fichier @file{setup.py}, dans @file{requirements.txt} ou | |
573 | dans @file{tox.ini}. | |
574 | ||
575 | Votre mission, lorsque vous écrivez une recette pour un paquet Python, est | |
576 | de faire correspondre ces dépendances au bon type « d'entrée » | |
577 | (@pxref{Référence de paquet, inputs}). Bien que l'importeur @code{pypi} fasse | |
578 | du bon boulot (@pxref{Invoquer guix import}), vous devriez vérifier la liste | |
579 | suivant pour déterminer où va telle dépendance. | |
580 | ||
581 | @itemize | |
582 | ||
583 | @item | |
584 | Nous empaquetons Python 2 avec @code{setuptools} et @code{pip} installé | |
585 | comme Python 3.4 par défaut. Ainsi, vous n'avez pas à spécifié ces | |
586 | entrées. @command{guix lint} vous avertira si vous faîtes cela. | |
587 | ||
588 | @item | |
589 | Les dépendances Python requises à l'exécutions vont dans | |
590 | @code{propagated-inputs}. Elles sont typiquement définies dans le mot-clef | |
591 | @code{install_requires} dans @file{setup.py} ou dans le fichier | |
592 | @file{requirements.txt}. | |
593 | ||
594 | @item | |
595 | Les paquets Python requis uniquement à la construction — p.@: ex.@: ceux | |
596 | listés dans le mot-clef @code{setup_requires} de @file{setup.py} — ou | |
597 | seulement pour les tests — p.@: ex.@: ceux dans @code{tests_require} — vont | |
598 | dans @code{native-inputs}. La raison est qu'ils n'ont pas besoin d'être | |
599 | propagés car ils ne sont pas requis à l'exécution et dans le cas d'une | |
600 | compilation croisée, c'est l'entrée « native » qu'il nous faut. | |
601 | ||
602 | Les cadriciels de tests @code{pytest}, @code{mock} et @code{nose} sont des | |
603 | exemples. Bien sûr si l'un de ces paquets est aussi requis à l'exécution, | |
604 | il doit aller dans @code{propagated-inputs}. | |
605 | ||
606 | @item | |
607 | Tout ce qui ne tombe pas dans les catégories précédentes va dans | |
608 | @code{inputs}, par exemple des programmes pour des bibliothèques C requises | |
609 | pour construire des paquets Python avec des extensions C. | |
610 | ||
611 | @item | |
612 | Si un paquet Python a des dépendances facultatives (@code{extras_require}), | |
613 | c'est à vous de décider de les ajouter ou non, en fonction du ratio entre | |
614 | utilité et complexité (@pxref{Envoyer des correctifs, @command{guix size}}). | |
615 | ||
616 | @end itemize | |
617 | ||
618 | ||
619 | @node Modules perl | |
620 | @subsection Modules perl | |
621 | ||
622 | @cindex perl | |
623 | Les programmes Perl utiles en soit sont nommés comme les autres paquets, | |
624 | avec le nom amont en minuscule. Pour les paquets Perl contenant une seule | |
625 | classe, nous utilisons le nom de la classe en minuscule, en remplaçant les | |
626 | occurrences de @code{::} par des tirets et en préfixant le tout par | |
627 | @code{perl-}. Donc la classe @code{XML::Parser} devient | |
628 | @code{perl-xml-parser}. Les modules contenant plusieurs classes gardent | |
629 | leur nom amont en minuscule et sont aussi préfixés par @code{perl-}. Ces | |
630 | modules tendent à avoir le mot @code{perl} quelque part dans leur nom, que | |
631 | nous supprimons en faveur du préfixe. Par exemple, @code{libwww-perl} | |
632 | devient @code{perl-libwww}. | |
633 | ||
634 | ||
635 | @node Paquets java | |
636 | @subsection Paquets java | |
637 | ||
638 | @cindex java | |
639 | Le programmes Java utiles en soit sont nommés comme les autres paquets, avec | |
640 | le nom amont en minuscule. | |
641 | ||
642 | Pour éviter les confusions et les problèmes de nom avec d'autres langages de | |
643 | programmation, il est désirable que le nom d'un paquet Java soit préfixé par | |
644 | @code{java-}. Si un projet contient déjà le mot @code{java}, nous le | |
645 | supprimons, par exemple le paquet @code{ngsjava} est empaqueté sous le nom | |
646 | @code{java-ngs}. | |
647 | ||
648 | Pour les paquets java contenant une seul classe ou une petite hiérarchie de | |
649 | classes, nous utilisons le nom de la classe en minuscule, en remplaçant les | |
650 | occurrences de @code{.} par des tirets et en préfixant le tout par | |
651 | @code{java-}. Donc la classe @code{apache.commons.cli} devient | |
652 | @code{java-apache-commons-cli}. | |
653 | ||
654 | ||
655 | @node Polices de caractères | |
656 | @subsection Polices de caractères | |
657 | ||
658 | @cindex polices | |
659 | Pour les polices qui n esont en général par installées par un utilisateurs | |
660 | pour du traitement de texte, ou qui sont distribuées en tant que partie d'un | |
661 | paquet logiciel plus gros, nous nous appuyons sur les règles générales pour | |
662 | les logiciels ; par exemple, cela s'applique aux polices livrées avec le | |
663 | système X.Org ou les polices qui font partie de TeX Live. | |
664 | ||
665 | Pour rendre plus facile la recherche par l'utilisateur, les noms des autres | |
666 | paquets contenant seulement des polices sont construits ainsi, | |
667 | indépendamment du nom du paquet en amont. | |
668 | ||
669 | Le nom d'un paquet contenant une unique famille de polices commence par | |
670 | @code{font-} ; il est suivi du nom du fondeur et d'un tiret @code{-} si le | |
671 | fondeur est connu, et du nom de la police, dont les espaces sont remplacés | |
672 | par des tirets (et comme d'habitude, toutes les lettres majuscules sont | |
673 | transformées en minuscules). Par exemple, la famille de polices Gentium de | |
674 | SIL est empaqueté sous le nom @code{font-sil-gentium}. | |
675 | ||
676 | Pour un paquet contenant plusieurs familles de polices, le nom de la | |
677 | collection est utilisée à la place du nom de la famille. Par exemple les | |
678 | polices Liberation consistent en trois familles, Liberation Sans, Liberation | |
679 | Serif et Liberation Mono. Elles pourraient être empaquetées séparément sous | |
680 | les noms @code{font-liberation-sans} etc, mais comme elles sont distribuées | |
681 | ensemble sous un nom commun, nous préférons les empaqueter ensemble en tant | |
682 | que @code{font-liberation}. | |
683 | ||
684 | Dans le cas où plusieurs formats de la même famille ou collection sont | |
685 | empaquetés séparément, une forme courte du format, préfixé d'un tiret est | |
686 | ajouté au nom du paquet. Nous utilisont @code{-ttf} pour les polices | |
687 | TrueType, @code{-otf} pour les polices OpenType et @code{-type1} pour les | |
688 | polices Type 1 de PostScript. | |
689 | ||
690 | ||
bf5c74e7 JL |
691 | @node Style de code |
692 | @section Style de code | |
693 | ||
694 | En général notre code suit le Standard de Code GNU (@pxref{Top,,, standards, | |
3cacfa9e | 695 | GNU Coding Standards}). Cependant, il ne parle pas beaucoup de Scheme, donc |
bf5c74e7 JL |
696 | voici quelques règles supplémentaires. |
697 | ||
698 | @menu | |
699 | * Paradigme de programmation:: Comment composer vos éléments. | |
700 | * Modules:: Où stocker votre code ? | |
701 | * Types de données et reconnaissance de motif:: Implémenter des | |
702 | structures de données. | |
703 | * Formatage du code:: Conventions d'écriture. | |
704 | @end menu | |
705 | ||
706 | @node Paradigme de programmation | |
707 | @subsection Paradigme de programmation | |
708 | ||
3cacfa9e | 709 | Le code Scheme dans Guix est écrit dans un style purement fonctionnel. Le |
bf5c74e7 JL |
710 | code qui s'occupe des entrées-sorties est une exception ainsi que les |
711 | procédures qui implémentent des concepts bas-niveau comme la procédure | |
712 | @code{memoize}. | |
713 | ||
714 | @node Modules | |
715 | @subsection Modules | |
716 | ||
717 | Les modules Guile qui sont sensés être utilisés du côté de la construction | |
3cacfa9e LC |
718 | doivent se trouver dans l'espace de nom @code{(guix build @dots{})}. Ils ne |
719 | doivent pas se référer à d'autres modules Guix ou GNU@. Cependant il est | |
bf5c74e7 JL |
720 | correct pour un module « côté hôte » de dépendre d'un module coté |
721 | construction. | |
722 | ||
723 | Les modules qui s'occupent du système GNU général devraient se trouver dans | |
724 | l'espace de nom @code{(gnu @dots{})} plutôt que @code{(guix @dots{})}. | |
725 | ||
726 | @node Types de données et reconnaissance de motif | |
727 | @subsection Types de données et reconnaissance de motif | |
728 | ||
729 | La tendance en Lisp classique est d'utiliser des listes pour tout | |
730 | représenter et de naviguer dedans « à la main ( avec @code{car}, @code{cdr}, | |
3cacfa9e | 731 | @code{cadr} et compagnie. Il y a plusieurs problèmes avec ce style, |
bf5c74e7 JL |
732 | notamment le fait qu'il soit dur à lire, source d'erreur et un obstacle aux |
733 | rapports d'erreur bien typés. | |
734 | ||
735 | Le code de Guix devrait définir des types de données appropriées (par | |
3cacfa9e LC |
736 | exemple, avec @code{define-record-type*}) plutôt que d'abuser des listes. |
737 | En plus, il devrait utiliser la recherche de motifs, via le module Guile | |
bf5c74e7 JL |
738 | @code{(ice-9 match)}, surtout pour rechercher dans des listes. |
739 | ||
740 | @node Formatage du code | |
741 | @subsection Formatage du code | |
742 | ||
743 | @cindex formater le code | |
744 | @cindex style de code | |
745 | Lorsque nous écrivons du code Scheme, nous suivons la sagesse commune aux | |
3cacfa9e | 746 | programmeurs Scheme. En général, nous suivons les |
bf5c74e7 | 747 | @url{http://mumble.net/~campbell/scheme/style.txt, règles de style de |
3cacfa9e LC |
748 | Riastradh}. Ce document décrit aussi les conventions utilisées dans le code |
749 | de Guile. Il est bien pensé et bien écrit, alors n'hésitez pas à le lire. | |
bf5c74e7 JL |
750 | |
751 | Certaines formes spéciales introduites dans Guix comme la macro | |
3cacfa9e | 752 | @code{substitute*} ont des règles d'indentation spécifiques. Elles sont |
bf5c74e7 | 753 | définies dans le fichier @file{.dir-locals.el} qu'Emacs utilise |
3cacfa9e | 754 | automatiquement. Remarquez aussi qu'Emacs-Guix fournit le mode |
bf5c74e7 JL |
755 | @code{guix-devel-mode} qui indente et colore le code Guix correctement |
756 | (@pxref{Development,,, emacs-guix, The Emacs-Guix Reference Manual}). | |
757 | ||
758 | @cindex indentation, du code | |
759 | @cindex formatage, du code | |
760 | Si vous n'utilisez pas Emacs, assurez-vous que votre éditeur connaisse ces | |
3cacfa9e | 761 | règles. Pour indenter automatiquement une définition de paquet, vous pouvez |
bf5c74e7 JL |
762 | aussi lancer : |
763 | ||
764 | @example | |
765 | ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} | |
766 | @end example | |
767 | ||
768 | @noindent | |
769 | Cela indente automatiquement la définition de @var{package} dans | |
3cacfa9e | 770 | @file{gnu/packages/@var{file}.scm} en lançant Emacs en mode commande. Pour |
bf5c74e7 JL |
771 | indenter un fichier complet, n'indiquez pas de second argument : |
772 | ||
773 | @example | |
774 | ./etc/indent-code.el gnu/services/@var{file}.scm | |
775 | @end example | |
776 | ||
3cacfa9e LC |
777 | @cindex Vim, édition de code Scheme |
778 | Si vous éditez du code avec Vim, nous recommandons de lancer @code{:set | |
779 | autoindent} pour que votre code soit automatiquement indenté au moment où | |
780 | vous l'entrez. En plus, | |
781 | @uref{https://www.vim.org/scripts/script.php?script_id=3998, | |
782 | @code{paredit.vim}} peut vous aider à gérer toutes ces parenthèses. | |
783 | ||
bf5c74e7 | 784 | Nous demandons que toutes les procédure de premier niveau contiennent une |
15f1bff4 JL |
785 | chaîne de documentation. Ce prérequis peut être relâché pour les procédures |
786 | privées simples dans l'espace de nom @code{(guix build @dots{})} cependant. | |
bf5c74e7 JL |
787 | |
788 | Les procédures ne devraient pas avoir plus de quatre paramètres | |
789 | positionnés. Utilisez des paramètres par mot-clefs pour les procédures qui | |
790 | prennent plus de quatre paramètres. | |
791 | ||
792 | ||
793 | @node Envoyer des correctifs | |
794 | @section Envoyer des correctifs | |
795 | ||
3cacfa9e LC |
796 | Le développement se fait avec le système de contrôle de version Git. Ainsi, |
797 | l'accès au dépôt n'est pas strictement nécessaire. Nous accueillons les | |
bf5c74e7 JL |
798 | contributions sous forme de correctifs produits par @code{git format-patch} |
799 | envoyés sur la liste de diffusion @email{guix-patches@@gnu.org}. | |
800 | ||
801 | Cette liste de diffusion est gérée par une instance Debbugs accessible à | |
802 | l'adresse @uref{https://bugs.gnu.org/guix-patches}, qui nous permet de | |
3cacfa9e | 803 | suivre les soumissions. Chaque message envoyé à cette liste se voit |
bf5c74e7 JL |
804 | attribuer un numéro de suivi ; les gens peuvent ensuite répondre à cette |
805 | soumission en envoyant un courriel à @code{@var{NNN}@@debbugs.gnu.org}, où | |
806 | @var{NNN} est le numéro de suivi (@pxref{Envoyer une série de correctifs}). | |
807 | ||
808 | Veuillez écrire les messages de commit dans le format ChangeLog | |
809 | (@pxref{Change Logs,,, standards, GNU Coding Standards}) ; vous pouvez | |
810 | regarder l'historique des commits pour trouver des exemples. | |
811 | ||
812 | Avant de soumettre un correctif qui ajoute ou modifie la définition d'un | |
813 | paquet, veuillez vérifier cette check-list : | |
814 | ||
815 | @enumerate | |
816 | @item | |
817 | Si les auteurs du paquet logiciel fournissent une signature cryptographique | |
3cacfa9e LC |
818 | pour l'archive, faîtes un effort pour vérifier l'authenticité de l'archive. |
819 | Pour un fichier de signature GPG détaché, cela se fait avec la commande | |
820 | @code{gpg --verify}. | |
bf5c74e7 JL |
821 | |
822 | @item | |
823 | Prenez un peu de temps pour fournir un synopsis et une description adéquats | |
3cacfa9e | 824 | pour le paquet. Voir @xref{Synopsis et descriptions} pour quelques lignes |
bf5c74e7 JL |
825 | directrices. |
826 | ||
827 | @item | |
828 | Lancez @code{guix lint @var{paquet}}, où @var{paquet} est le nom du nouveau | |
829 | paquet ou du paquet modifié, et corrigez les erreurs qu'il rapporte | |
830 | (@pxref{Invoquer guix lint}). | |
831 | ||
832 | @item | |
833 | Assurez-vous que le paquet se construise sur votre plate-forme avec | |
834 | @code{guix build @var{paquet}}. | |
835 | ||
15f1bff4 JL |
836 | @item |
837 | We recommend you also try building the package on other supported | |
838 | platforms. As you may not have access to actual hardware platforms, we | |
839 | recommend using the @code{qemu-binfmt-service-type} to emulate them. In | |
840 | order to enable it, add the following service to the list of services in | |
841 | your @code{operating-system} configuration: | |
842 | ||
843 | @example | |
844 | (service qemu-binfmt-service-type | |
845 | (qemu-binfmt-configuration | |
846 | (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc" "mips64el")) | |
847 | (guix-support? #t))) | |
848 | @end example | |
849 | ||
850 | Then reconfigure your system. | |
851 | ||
852 | You can then build packages for different platforms by specifying the | |
853 | @code{--system} option. For example, to build the "hello" package for the | |
854 | armhf, aarch64, powerpc, or mips64 architectures, you would run the | |
855 | following commands, respectively: | |
856 | @example | |
857 | guix build --system=armhf-linux --rounds=2 hello | |
858 | guix build --system=aarch64-linux --rounds=2 hello | |
859 | guix build --system=powerpc-linux --rounds=2 hello | |
860 | guix build --system=mips64el-linux --rounds=2 hello | |
861 | @end example | |
862 | ||
bf5c74e7 JL |
863 | @item |
864 | @cindex construction groupée | |
865 | Assurez-vous que le paquet n'utilise pas de copie groupée d'un logiciel déjà | |
866 | disponible dans un paquet séparé. | |
867 | ||
868 | Parfois, les paquets incluent des copie du code source de leurs dépendances | |
3cacfa9e | 869 | pour le confort de leurs utilisateurs. Cependant, en tant que distribution, |
bf5c74e7 | 870 | nous voulons nous assurer que ces paquets utilisent bien les copient que |
3cacfa9e | 871 | nous avons déjà dans la distribution si elles existent. Cela améliore |
bf5c74e7 JL |
872 | l'utilisation des ressources (la dépendance n'est construite et stockée |
873 | qu'une seule fois) et permet à la distribution de faire des changements | |
874 | transversaux comme appliquer des correctifs de sécurité pour un paquet donné | |
875 | depuis un unique emplacement et qu'ils affectent tout le système, ce | |
876 | qu'empêchent les copies groupées. | |
877 | ||
878 | @item | |
15f1bff4 JL |
879 | Take a look at the profile reported by @command{guix size} (@pxref{Invoquer guix size}). This will allow you to notice references to other packages |
880 | unwillingly retained. It may also help determine whether to split the | |
881 | package (@pxref{Des paquets avec plusieurs résultats}), and which optional | |
882 | dependencies should be used. In particular, avoid adding @code{texlive} as | |
883 | a dependency: because of its extreme size, use @code{texlive-tiny} or | |
884 | @code{texlive-union} instead. | |
bf5c74e7 JL |
885 | |
886 | @item | |
887 | Pour les changements important, vérifiez que les paquets qui en dépendent | |
888 | (s'ils existent) ne sont pas affectés par le changement ; @code{guix refresh | |
889 | --list-dependant @var{paquet}} vous aidera (@pxref{Invoquer guix refresh}). | |
890 | ||
bf5c74e7 JL |
891 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. |
892 | @cindex stratégie de branche | |
893 | @cindex stratégie de planification des reconstructions | |
894 | Suivant le nombre de paquets dépendants et donc le nombre de reconstruction | |
895 | induites, les commits vont vers des branches différentes, suivant ces | |
896 | principes : | |
897 | ||
898 | @table @asis | |
899 | @item 300 paquets dépendants ou moins | |
900 | branche @code{master} (changements non-disruptifs). | |
901 | ||
902 | @item entre 300 et 1 200 paquets dépendants | |
15f1bff4 | 903 | branche @code{staging} (changements non-disruptifs). Cette branche devrait |
3cacfa9e | 904 | être fusionnées dans @code{master} tous les 3 semaines. Les changements par |
bf5c74e7 JL |
905 | thèmes (par exemple une mise à jour de la pile GNOME) peuvent aller dans une |
906 | branche spécifique (disons, @code{gnome-updates}). | |
907 | ||
908 | @item plus de 1 200 paquets dépendants | |
909 | branche @code{core-updates} (peut inclure des changements majeurs et | |
3cacfa9e | 910 | potentiellement disruptifs). Cette branche devrait être fusionnée dans |
bf5c74e7 JL |
911 | @code{master} tous les 2,5 mois environ. |
912 | @end table | |
913 | ||
2cf2c778 JL |
914 | Toutes ces branches sont @uref{https://hydra.gnu.org/project/gnu, gérées par |
915 | notre ferme de construction} et fusionnées dans @code{master} une fois que | |
916 | tout a été construit correctement. Cela nous permet de corriger des | |
917 | problèmes avant qu'ils n'atteignent les utilisateurs et réduit la fenêtre | |
918 | pendant laquelle les binaires pré-construits ne sont pas disponibles. | |
919 | ||
920 | @c TODO: It would be good with badges on the website that tracks these | |
921 | @c branches. Or maybe even a status page. | |
922 | Généralement les autres branches que @code{master} sont considérées comme | |
923 | @emph{gelées} s'il y a eu une évaluation récente ou qu'il y a une branche | |
924 | @code{-next} correspondante. Demandez sur la liste de diffusion ou sur IRC | |
925 | si vous n'êtes pas sûr de savoir où pousser votre correctif. | |
bf5c74e7 JL |
926 | |
927 | @item | |
928 | @cindex déterminisme, du processus de construction | |
929 | @cindex construction reproductibles, vérification | |
3cacfa9e | 930 | Vérifiez si le processus de construction du paquet est déterministe. Cela |
bf5c74e7 JL |
931 | signifie typiquement vérifier qu'une construction indépendante du paquet |
932 | renvoie exactement le même résultat que vous avez obtenu, bit à bit. | |
933 | ||
934 | Une manière simple de le faire est de reconstruire le paquet plusieurs fois | |
935 | à la suite sur votre machine (@pxref{Invoquer guix build}) : | |
936 | ||
937 | @example | |
938 | guix build --rounds=2 mon-paquet | |
939 | @end example | |
940 | ||
941 | Cela est suffisant pour trouver une classe de non-déterminisme commune, | |
942 | comme l'horodatage ou des sorties générées aléatoirement dans le résultat de | |
943 | la construction. | |
944 | ||
15f1bff4 JL |
945 | Another option is to use @command{guix challenge} (@pxref{Invoquer guix challenge}). You may run it once the package has been committed and built |
946 | by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same | |
947 | result as you did. Better yet: Find another machine that can build it and | |
948 | run @command{guix publish}. Since the remote build machine is likely | |
949 | different from yours, this can catch non-determinism issues related to the | |
950 | hardware---e.g., use of different instruction set extensions---or to the | |
951 | operating system kernel---e.g., reliance on @code{uname} or @file{/proc} | |
952 | files. | |
bf5c74e7 JL |
953 | |
954 | @item | |
955 | Lorsque vous écrivez de la documentation, utilisez une formulation au genre | |
956 | neutre lorsque vous vous référez à des personnes, comme le | |
957 | @uref{https://fr.wikipedia.org/wiki/They_singulier, ``they''@comma{} | |
958 | ``their''@comma{} ``them'' singulier} (en anglais). | |
959 | ||
960 | @item | |
961 | Vérifiez que votre correctif contienne seulement un ensemble de changements | |
3cacfa9e LC |
962 | liés. Grouper des changements non liés ensemble rend la revue plus |
963 | difficile et plus lente. | |
bf5c74e7 JL |
964 | |
965 | Ajouter plusieurs paquet ou une mise à jour d'un paquet avec des corrections | |
966 | dans ce paquet sont des exemples de changements sans rapport. | |
967 | ||
968 | @item | |
969 | Suivez nos règles de formatage de code, éventuellement en lançant le script | |
970 | @command{et/indent-code.el} pour le faire automatiquement (@pxref{Formatage | |
971 | du code}). | |
972 | ||
adfb167f JL |
973 | @item |
974 | Si possible, utilisez des miroirs dans l'URL des sources (@pxref{Invoquer guix download}). Utilisez des URL stable, pas des URL générées. Par | |
975 | exemple, les archives GitHub ne sont pas nécessairement identiques d'une | |
976 | génération à la suivante, donc il vaut mieux dans ce cas cloner le dépôt. | |
977 | N'utilisez pas le champ @command{name} dans l'URL : ce n'est pas très utile | |
978 | et si le nom change, l'URL sera probablement erronée. | |
979 | ||
bf5c74e7 JL |
980 | @end enumerate |
981 | ||
982 | Lorsque vous envoyez un correctif à la liste de diffusion, utilisez | |
3cacfa9e | 983 | @samp{[PATCH] @dots{}} comme sujet. Vous pouvez utiliser votre client de |
bf5c74e7 | 984 | courriel ou la commande @command{git send-email} (@pxref{Envoyer une série |
3cacfa9e LC |
985 | de correctifs}). Nous préférons recevoir des correctifs en texte brut, soit |
986 | en ligne, soit en pièce-jointe MIME@. Nous vous conseillons de faire | |
bf5c74e7 JL |
987 | attention si votre client de courriel change par exemple les retours à la |
988 | ligne ou l'indentation, ce qui peut casser les correctifs. | |
989 | ||
990 | Lorsqu'un bogue est résolu, veuillez fermer le fil en envoyant un courriel à | |
991 | @email{@var{NNN}-done@@debbugs.gnu.org}. | |
992 | ||
993 | @unnumberedsubsec Envoyer une série de correctifs | |
994 | @anchor{Envoyer une série de correctifs} | |
995 | @cindex série de correctifs | |
996 | @cindex @code{git send-email} | |
997 | @cindex @code{git-send-email} | |
998 | ||
999 | @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html | |
3cacfa9e | 1000 | Lorsque vous envoyez une série de correctifs (p.@@:: ex.@: avec @code{git |
bf5c74e7 JL |
1001 | send-email}), envoyez d'abord une premier message à |
1002 | @email{guix-patches@@gnu.org} puis envoyez le reste des correctifs à | |
1003 | @email{@var{NNN}@@debbugs.gnu.org} pour vous assurer qu'ils seront groupés | |
3cacfa9e | 1004 | ensemble. Voyez @uref{https://debbugs.gnu.org/Advanced.html, la |
bf5c74e7 | 1005 | documentation de Debbugs} pour plus d'informations. |