Commit | Line | Data |
---|---|---|
1e40e70b JL |
1 | @node Mitwirken |
2 | @chapter Mitwirken | |
3 | ||
4 | Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um | |
5 | es wachsen zu lassen! Bitte kontaktieren Sie uns auf | |
6 | @email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir | |
7 | freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich | |
793dcd8c LC |
8 | für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der |
9 | Erstellung von Paketen (@pxref{Paketrichtlinien}). | |
1e40e70b JL |
10 | |
11 | @cindex Verhaltensregeln, für Mitwirkende | |
12 | @cindex Verhaltenskodex für Mitwirkende | |
13 | Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung | |
14 | bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten | |
15 | kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für | |
16 | Mitwirkende«, der von @url{http://contributor-covenant.org/} übernommen | |
17 | wurde. Eine übersetzte Fassung finden Sie auf | |
18 | @url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct} | |
19 | sowie eine mitgelieferte, englische Fassung in der Datei | |
20 | @file{CODE-OF-CONDUCT} im Quellbaum. | |
21 | ||
22 | Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der | |
23 | Online-Kommunikation ihre echten Namen preisgeben. Sie können einen | |
24 | beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden. | |
25 | ||
26 | @menu | |
27 | * Erstellung aus dem Git:: Das Neueste und Beste. | |
28 | * Guix vor der Installation ausführen:: Hacker-Tricks. | |
29 | * Perfekt eingerichtet:: Die richtigen Werkzeuge. | |
61ce2e77 | 30 | * Paketrichtlinien:: Die Distribution wachsen lassen. |
1e40e70b JL |
31 | * Code-Stil:: Wie Mitwirkende hygienisch arbeiten. |
32 | * Einreichen von Patches:: Teilen Sie Ihre Arbeit. | |
33 | @end menu | |
34 | ||
35 | @node Erstellung aus dem Git | |
36 | @section Erstellung aus dem Git | |
37 | ||
38 | Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die | |
39 | neueste Version aus dem Git-Softwarebestand verwenden: | |
40 | ||
41 | @example | |
42 | git clone https://git.savannah.gnu.org/git/guix.git | |
43 | @end example | |
44 | ||
45 | Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den | |
46 | Installationsanweisungen genannten Paketen weitere nötig | |
47 | (@pxref{Voraussetzungen}). | |
48 | ||
49 | @itemize | |
50 | @item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; | |
51 | @item @url{http://gnu.org/software/automake/, GNU Automake}; | |
52 | @item @url{http://gnu.org/software/gettext/, GNU Gettext}; | |
53 | @item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; | |
54 | @item @url{http://www.graphviz.org/, Graphviz}; | |
55 | @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}. | |
56 | @end itemize | |
57 | ||
58 | Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist | |
59 | natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in | |
60 | der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um | |
61 | an Guix zu arbeiten: | |
62 | ||
63 | @example | |
64 | guix environment guix | |
65 | @end example | |
66 | ||
67 | In @xref{Aufruf von guix environment} finden Sie weitere Informationen zu | |
68 | diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc} | |
69 | hinzugefügt werden: | |
70 | ||
71 | @example | |
72 | guix environment guix --ad-hoc help2man git strace | |
73 | @end example | |
74 | ||
75 | Führen Sie @command{./bootstrap} aus, um die Infrastruktur des | |
76 | Erstellungssystems mit Autoconf und Automake zu erstellen. Möglicherweise | |
77 | erhalten Sie eine Fehlermeldung wie diese: | |
78 | ||
79 | @example | |
80 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES | |
81 | @end example | |
82 | ||
83 | @noindent | |
84 | Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden | |
85 | konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass | |
86 | @file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile | |
87 | bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake | |
88 | in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht | |
89 | nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden | |
90 | Befehl aufrufen: | |
91 | ||
92 | @example | |
93 | export ACLOCAL_PATH=/usr/share/aclocal | |
94 | @end example | |
95 | ||
96 | In @xref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie | |
97 | weitere Informationen. | |
98 | ||
99 | Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf, | |
100 | @code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei | |
101 | @var{Verzeichnis} der von Ihrer aktuellen Installation verwendete | |
102 | @code{localstatedir}-Wert ist (weitere Informationen auf @pxref{Der Store}). | |
103 | ||
104 | Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen | |
105 | (@pxref{Die Testsuite laufen lassen}). Falls etwas fehlschlägt, werfen Sie einen | |
106 | Blick auf die Installationsanweisungen (@pxref{Installation}) oder senden | |
793dcd8c | 107 | Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}. |
1e40e70b JL |
108 | |
109 | ||
110 | @node Guix vor der Installation ausführen | |
111 | @section Guix vor der Installation ausführen | |
112 | ||
793dcd8c | 113 | Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im |
1e40e70b JL |
114 | lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie |
115 | tatsächlich zu installieren. So können Sie zwischen Ihrem | |
116 | Endnutzer-»Straßenanzug« und Ihrem »Faschingskostüm« unterscheiden. | |
117 | ||
61ce2e77 JL |
118 | Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt |
119 | werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie | |
120 | sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix | |
121 | verfügbar sind (@pxref{Erstellung aus dem Git}) und darin einfach vor jeden | |
122 | Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env} | |
123 | befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo | |
124 | es durch @command{./configure} erzeugt wird), zum Beispiel so@footnote{Die | |
125 | Befehlszeilenoption @option{-E} von @command{sudo} stellt sicher, dass | |
126 | @code{GUILE_LOAD_PATH} richtig gesetzt wird, damit @command{guix-daemon} und | |
127 | die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden | |
128 | können.}: | |
1e40e70b JL |
129 | |
130 | @example | |
131 | $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild | |
132 | $ ./pre-inst-env guix build hello | |
133 | @end example | |
134 | ||
135 | @noindent | |
136 | Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt: | |
137 | ||
138 | @example | |
139 | $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' | |
140 | ||
141 | ;;; ("x86_64-linux") | |
142 | @end example | |
143 | ||
144 | @noindent | |
145 | @cindex REPL | |
146 | @cindex Lese-Auswerten-Schreiben-Schleife | |
147 | @dots{} und auf einer REPL (@pxref{Using Guile Interactively,,, guile, Guile | |
148 | Reference Manual}): | |
149 | ||
150 | @example | |
151 | $ ./pre-inst-env guile | |
152 | scheme@@(guile-user)> ,use(guix) | |
153 | scheme@@(guile-user)> ,use(gnu) | |
154 | scheme@@(guile-user)> (define snakes | |
155 | (fold-packages | |
156 | (lambda (package lst) | |
157 | (if (string-prefix? "python" | |
158 | (package-name package)) | |
159 | (cons package lst) | |
160 | lst)) | |
161 | '())) | |
162 | scheme@@(guile-user)> (length snakes) | |
163 | $1 = 361 | |
164 | @end example | |
165 | ||
166 | Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die | |
167 | nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und | |
168 | @env{GUILE_LOAD_PATH}. | |
169 | ||
61ce2e77 JL |
170 | Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum |
171 | @emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische | |
172 | Verknüpfung @file{~/.config/guix/current} (@pxref{Aufruf von guix pull}). Um | |
173 | Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen | |
174 | @command{git pull} benutzen. | |
1e40e70b JL |
175 | |
176 | ||
177 | @node Perfekt eingerichtet | |
178 | @section Perfekt eingerichtet | |
179 | ||
61ce2e77 JL |
180 | The Perfect Setup to hack on Guix is basically the perfect setup used for |
181 | Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference | |
182 | Manual}). First, you need more than an editor, you need | |
183 | @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful | |
184 | @url{http://nongnu.org/geiser/, Geiser}. To set that up, run: | |
185 | ||
186 | @example | |
187 | guix package -i emacs guile emacs-geiser | |
188 | @end example | |
1e40e70b JL |
189 | |
190 | Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs | |
191 | heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu | |
192 | Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie | |
193 | kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition | |
194 | zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr | |
195 | (@pxref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen | |
196 | Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die | |
197 | Quelldateien in Ihrem Checkout gefunden werden. | |
198 | ||
199 | @lisp | |
200 | ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} | |
201 | (with-eval-after-load 'geiser-guile | |
202 | (add-to-list 'geiser-guile-load-path "~/src/guix")) | |
203 | @end lisp | |
204 | ||
205 | Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten | |
206 | Scheme-Modus. Aber Sie dürfen auch | |
207 | @url{http://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es | |
208 | bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so | |
209 | zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken | |
210 | oder den nachfolgenden S-Ausdruck verwerfen, etc. | |
211 | ||
212 | @cindex Code-Schnipsel | |
213 | @cindex Vorlagen | |
214 | @cindex Tipparbeit sparen | |
215 | Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und | |
216 | Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können | |
217 | mit @url{http://joaotavora.github.io/yasnippet/, YASnippet} zusammen benutzt | |
218 | werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln | |
219 | umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer | |
220 | @var{yas-snippet-dirs}-Variablen in Emacs hinzufügen. | |
221 | ||
222 | @lisp | |
223 | ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} | |
224 | (with-eval-after-load 'yasnippet | |
225 | (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) | |
226 | @end lisp | |
227 | ||
61ce2e77 JL |
228 | Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit} |
229 | voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine | |
230 | Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB} | |
231 | eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines | |
232 | Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um | |
233 | eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie | |
234 | @code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der | |
235 | Homepage-URI eines Pakets auf HTTPS einzufügen. | |
1e40e70b JL |
236 | |
237 | Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie | |
238 | @code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch | |
239 | die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter | |
240 | umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere | |
241 | Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst | |
242 | wieder weiter umgeschrieben werden kann. | |
243 | ||
244 | ||
61ce2e77 JL |
245 | @node Paketrichtlinien |
246 | @section Paketrichtlinien | |
247 | ||
248 | @cindex packages, creating | |
249 | The GNU distribution is nascent and may well lack some of your favorite | |
250 | packages. This section describes how you can help make the distribution | |
251 | grow. | |
252 | ||
253 | Free software packages are usually distributed in the form of @dfn{source | |
254 | code tarballs}---typically @file{tar.gz} files that contain all the source | |
255 | files. Adding a package to the distribution means essentially two things: | |
256 | adding a @dfn{recipe} that describes how to build the package, including a | |
257 | list of other packages required to build it, and adding @dfn{package | |
258 | metadata} along with that recipe, such as a description and licensing | |
259 | information. | |
260 | ||
261 | In Guix all this information is embodied in @dfn{package definitions}. | |
262 | Package definitions provide a high-level view of the package. They are | |
263 | written using the syntax of the Scheme programming language; in fact, for | |
264 | each package we define a variable bound to the package definition, and | |
265 | export that variable from a module (@pxref{Paketmodule}). However, | |
266 | in-depth Scheme knowledge is @emph{not} a prerequisite for creating | |
267 | packages. For more information on package definitions, @pxref{Pakete definieren}. | |
268 | ||
269 | Once a package definition is in place, stored in a file in the Guix source | |
270 | tree, it can be tested using the @command{guix build} command | |
271 | (@pxref{Aufruf von guix build}). For example, assuming the new package is | |
272 | called @code{gnew}, you may run this command from the Guix build tree | |
273 | (@pxref{Guix vor der Installation ausführen}): | |
274 | ||
275 | @example | |
276 | ./pre-inst-env guix build gnew --keep-failed | |
277 | @end example | |
278 | ||
279 | Using @code{--keep-failed} makes it easier to debug build failures since it | |
280 | provides access to the failed build tree. Another useful command-line | |
281 | option when debugging is @code{--log-file}, to access the build log. | |
282 | ||
283 | If the package is unknown to the @command{guix} command, it may be that the | |
284 | source file contains a syntax error, or lacks a @code{define-public} clause | |
285 | to export the package variable. To figure it out, you may load the module | |
286 | from Guile to get more information about the actual error: | |
287 | ||
288 | @example | |
289 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' | |
290 | @end example | |
291 | ||
292 | Once your package builds correctly, please send us a patch | |
293 | (@pxref{Einreichen von Patches}). Well, if you need help, we will be happy to | |
294 | help you too. Once the patch is committed in the Guix repository, the new | |
295 | package automatically gets built on the supported platforms by | |
296 | @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration | |
297 | system}. | |
298 | ||
299 | @cindex substituter | |
300 | Users can obtain the new package definition simply by running @command{guix | |
301 | pull} (@pxref{Aufruf von guix pull}). When @code{@value{SUBSTITUTE-SERVER}} | |
302 | is done building the package, installing the package automatically downloads | |
303 | binaries from there (@pxref{Substitute}). The only place where human | |
304 | intervention is needed is to review and apply the patch. | |
305 | ||
306 | ||
307 | @menu | |
308 | * Software-Freiheit:: Was in die Distribution aufgenommen werden | |
309 | darf. | |
310 | * Paketbenennung:: Was macht einen Namen aus? | |
311 | * Versionsnummern:: Wenn der Name noch nicht genug ist. | |
312 | * Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige | |
313 | Paket zu finden. | |
314 | * Python-Module:: Ein Touch britischer Comedy. | |
315 | * Perl-Module:: Kleine Perlen. | |
316 | * Java-Pakete:: Kaffeepause. | |
317 | * Schriftarten:: Schriften verschriftlicht. | |
318 | @end menu | |
319 | ||
320 | @node Software-Freiheit | |
321 | @subsection Software-Freiheit | |
322 | ||
323 | @c =========================================================================== | |
324 | @c | |
325 | @c This file was generated with po4a. Translate the source file. | |
326 | @c | |
327 | @c =========================================================================== | |
328 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. | |
329 | @cindex free software | |
330 | The GNU operating system has been developed so that users can have freedom | |
331 | in their computing. GNU is @dfn{free software}, meaning that users have the | |
332 | @url{http://www.gnu.org/philosophy/free-sw.html,four essential freedoms}: to | |
333 | run the program, to study and change the program in source code form, to | |
334 | redistribute exact copies, and to distribute modified versions. Packages | |
335 | found in the GNU distribution provide only software that conveys these four | |
336 | freedoms. | |
337 | ||
338 | In addition, the GNU distribution follow the | |
339 | @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free | |
340 | software distribution guidelines}. Among other things, these guidelines | |
341 | reject non-free firmware, recommendations of non-free software, and discuss | |
342 | ways to deal with trademarks and patents. | |
343 | ||
344 | Some otherwise free upstream package sources contain a small and optional | |
345 | subset that violates the above guidelines, for instance because this subset | |
346 | is itself non-free code. When that happens, the offending items are removed | |
347 | with appropriate patches or code snippets in the @code{origin} form of the | |
348 | package (@pxref{Pakete definieren}). This way, @code{guix build --source} | |
349 | returns the ``freed'' source rather than the unmodified upstream source. | |
350 | ||
351 | ||
352 | @node Paketbenennung | |
353 | @subsection Paketbenennung | |
354 | ||
355 | @cindex package name | |
356 | A package has actually two names associated with it: First, there is the | |
357 | name of the @emph{Scheme variable}, the one following @code{define-public}. | |
358 | By this name, the package can be made known in the Scheme code, for instance | |
359 | as input to another package. Second, there is the string in the @code{name} | |
360 | field of a package definition. This name is used by package management | |
361 | commands such as @command{guix package} and @command{guix build}. | |
362 | ||
363 | Both are usually the same and correspond to the lowercase conversion of the | |
364 | project name chosen upstream, with underscores replaced with hyphens. For | |
365 | instance, GNUnet is available as @code{gnunet}, and SDL_net as | |
366 | @code{sdl-net}. | |
367 | ||
368 | We do not add @code{lib} prefixes for library packages, unless these are | |
369 | already part of the official project name. But @pxref{Python-Module} and | |
370 | @ref{Perl-Module} for special rules concerning modules for the Python and | |
371 | Perl languages. | |
372 | ||
373 | Font package names are handled differently, @pxref{Schriftarten}. | |
374 | ||
375 | ||
376 | @node Versionsnummern | |
377 | @subsection Versionsnummern | |
378 | ||
379 | @cindex package version | |
380 | We usually package only the latest version of a given free software | |
381 | project. But sometimes, for instance for incompatible library versions, two | |
382 | (or more) versions of the same package are needed. These require different | |
383 | Scheme variable names. We use the name as defined in @ref{Paketbenennung} | |
384 | for the most recent version; previous versions use the same name, suffixed | |
385 | by @code{-} and the smallest prefix of the version number that may | |
386 | distinguish the two versions. | |
387 | ||
388 | The name inside the package definition is the same for all versions of a | |
389 | package and does not contain any version number. | |
390 | ||
391 | Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie | |
392 | folgt geschrieben werden: | |
393 | ||
394 | @example | |
395 | (define-public gtk+ | |
396 | (package | |
397 | (name "gtk+") | |
398 | (version "3.9.12") | |
399 | ...)) | |
400 | (define-public gtk+-2 | |
401 | (package | |
402 | (name "gtk+") | |
403 | (version "2.24.20") | |
404 | ...)) | |
405 | @end example | |
406 | Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als | |
407 | @example | |
408 | (define-public gtk+-3.8 | |
409 | (package | |
410 | (name "gtk+") | |
411 | (version "3.8.2") | |
412 | ...)) | |
413 | @end example | |
414 | ||
415 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, | |
416 | @c for a discussion of what follows. | |
417 | @cindex version number, for VCS snapshots | |
418 | Occasionally, we package snapshots of upstream's version control system | |
419 | (VCS) instead of formal releases. This should remain exceptional, because | |
420 | it is up to upstream developers to clarify what the stable release is. Yet, | |
421 | it is sometimes necessary. So, what should we put in the @code{version} | |
422 | field? | |
423 | ||
424 | Clearly, we need to make the commit identifier of the VCS snapshot visible | |
425 | in the version string, but we also need to make sure that the version string | |
426 | is monotonically increasing so that @command{guix package --upgrade} can | |
427 | determine which version is newer. Since commit identifiers, notably with | |
428 | Git, are not monotonically increasing, we add a revision number that we | |
429 | increase each time we upgrade to a newer snapshot. The resulting version | |
430 | string looks like this: | |
431 | ||
432 | @example | |
433 | 2.0.11-3.cabba9e | |
434 | ^ ^ ^ | |
435 | | | `-- upstream commit ID | |
436 | | | | |
437 | | `--- Guix package revision | |
438 | | | |
439 | latest upstream version | |
440 | @end example | |
441 | ||
442 | It is a good idea to strip commit identifiers in the @code{version} field | |
443 | to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics | |
444 | have a role to play here) as well as problems related to OS limits such as | |
445 | the maximum shebang length (127 bytes for the Linux kernel.) It is best to | |
446 | use the full commit identifiers in @code{origin}s, though, to avoid | |
447 | ambiguities. A typical package definition may look like this: | |
448 | ||
449 | @example | |
450 | (define my-package | |
451 | (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") | |
452 | (revision "1")) ;Guix package revision | |
453 | (package | |
454 | (version (git-version "0.9" revision commit)) | |
455 | (source (origin | |
456 | (method git-fetch) | |
457 | (uri (git-reference | |
458 | (url "git://example.org/my-package.git") | |
459 | (commit commit))) | |
460 | (sha256 (base32 "1mbikn@dots{}")) | |
461 | (file-name (git-file-name name version)))) | |
462 | ;; @dots{} | |
463 | ))) | |
464 | @end example | |
465 | ||
466 | @node Zusammenfassungen und Beschreibungen | |
467 | @subsection Zusammenfassungen und Beschreibungen | |
468 | ||
469 | @cindex package description | |
470 | @cindex package synopsis | |
471 | As we have seen before, each package in GNU@tie{}Guix includes a synopsis | |
472 | and a description (@pxref{Pakete definieren}). Synopses and descriptions | |
473 | are important: They are what @command{guix package --search} searches, and a | |
474 | crucial piece of information to help users determine whether a given package | |
475 | suits their needs. Consequently, packagers should pay attention to what | |
476 | goes into them. | |
477 | ||
478 | Synopses must start with a capital letter and must not end with a period. | |
479 | They must not start with ``a'' or ``the'', which usually does not bring | |
480 | anything; for instance, prefer ``File-frobbing tool'' over ``A tool that | |
481 | frobs files''. The synopsis should say what the package is---e.g., ``Core | |
482 | GNU utilities (file, text, shell)''---or what it is used for---e.g., the | |
483 | synopsis for GNU@tie{}grep is ``Print lines matching a pattern''. | |
484 | ||
485 | Keep in mind that the synopsis must be meaningful for a very wide audience. | |
486 | For example, ``Manipulate alignments in the SAM format'' might make sense | |
487 | for a seasoned bioinformatics researcher, but might be fairly unhelpful or | |
488 | even misleading to a non-specialized audience. It is a good idea to come up | |
489 | with a synopsis that gives an idea of the application domain of the | |
490 | package. In this example, this might give something like ``Manipulate | |
491 | nucleotide sequence alignments'', which hopefully gives the user a better | |
492 | idea of whether this is what they are looking for. | |
493 | ||
494 | Descriptions should take between five and ten lines. Use full sentences, | |
495 | and avoid using acronyms without first introducing them. Please avoid | |
496 | marketing phrases such as ``world-leading'', ``industrial-strength'', and | |
497 | ``next-generation'', and avoid superlatives like ``the most | |
498 | advanced''---they are not helpful to users looking for a package and may | |
499 | even sound suspicious. Instead, try to be factual, mentioning use cases and | |
500 | features. | |
501 | ||
502 | @cindex Texinfo markup, in package descriptions | |
503 | Descriptions can include Texinfo markup, which is useful to introduce | |
504 | ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks | |
505 | (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful | |
506 | when using some characters for example @samp{@@} and curly braces which are | |
507 | the basic special characters in Texinfo (@pxref{Special Characters,,, | |
508 | texinfo, GNU Texinfo}). User interfaces such as @command{guix package | |
509 | --show} take care of rendering it appropriately. | |
510 | ||
511 | Synopses and descriptions are translated by volunteers | |
512 | @uref{http://translationproject.org/domain/guix-packages.html, at the | |
513 | Translation Project} so that as many users as possible can read them in | |
514 | their native language. User interfaces search them and display them in the | |
515 | language specified by the current locale. | |
516 | ||
517 | To allow @command{xgettext} to extract them as translatable strings, | |
518 | synopses and descriptions @emph{must be literal strings}. This means that | |
519 | you cannot use @code{string-append} or @code{format} to construct these | |
520 | strings: | |
521 | ||
522 | @lisp | |
523 | (package | |
524 | ;; @dots{} | |
525 | (synopsis "This is translatable") | |
526 | (description (string-append "This is " "*not*" " translatable."))) | |
527 | @end lisp | |
528 | ||
529 | Translation is a lot of work so, as a packager, please pay even more | |
530 | attention to your synopses and descriptions as every change may entail | |
531 | additional work for translators. In order to help them, it is possible to | |
532 | make recommendations or instructions visible to them by inserting special | |
533 | comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}): | |
534 | ||
535 | @example | |
536 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. | |
537 | (description "ARandR is designed to provide a simple visual front end | |
538 | for the X11 resize-and-rotate (RandR) extension. @dots{}") | |
539 | @end example | |
540 | ||
541 | ||
542 | @node Python-Module | |
543 | @subsection Python-Module | |
544 | ||
545 | @cindex python | |
546 | We currently package Python 2 and Python 3, under the Scheme variable names | |
547 | @code{python-2} and @code{python} as explained in @ref{Versionsnummern}. To | |
548 | avoid confusion and naming clashes with other programming languages, it | |
549 | seems desirable that the name of a package for a Python module contains the | |
550 | word @code{python}. | |
551 | ||
552 | Some modules are compatible with only one version of Python, others with | |
553 | both. If the package Foo compiles only with Python 3, we name it | |
554 | @code{python-foo}; if it compiles only with Python 2, we name it | |
555 | @code{python2-foo}. If it is compatible with both versions, we create two | |
556 | packages with the corresponding names. | |
557 | ||
558 | If a project already contains the word @code{python}, we drop this; for | |
559 | instance, the module python-dateutil is packaged under the names | |
560 | @code{python-dateutil} and @code{python2-dateutil}. If the project name | |
561 | starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as | |
562 | described above. | |
563 | ||
564 | @subsubsection Specifying Dependencies | |
565 | @cindex inputs, for Python packages | |
566 | ||
567 | Dependency information for Python packages is usually available in the | |
568 | package source tree, with varying degrees of accuracy: in the | |
569 | @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. | |
570 | ||
571 | Your mission, when writing a recipe for a Python package, is to map these | |
572 | dependencies to the appropriate type of ``input'' (@pxref{»package«-Referenz, | |
573 | inputs}). Although the @code{pypi} importer normally does a good job | |
574 | (@pxref{Aufruf von guix import}), you may want to check the following check | |
575 | list to determine which dependency goes where. | |
576 | ||
577 | @itemize | |
578 | ||
579 | @item | |
580 | We currently package Python 2 with @code{setuptools} and @code{pip} | |
581 | installed like Python 3.4 has per default. Thus you don't need to specify | |
582 | either of these as an input. @command{guix lint} will warn you if you do. | |
583 | ||
584 | @item | |
585 | Python dependencies required at run time go into @code{propagated-inputs}. | |
586 | They are typically defined with the @code{install_requires} keyword in | |
587 | @file{setup.py}, or in the @file{requirements.txt} file. | |
588 | ||
589 | @item | |
590 | Python packages required only at build time---e.g., those listed with the | |
591 | @code{setup_requires} keyword in @file{setup.py}---or only for | |
592 | testing---e.g., those in @code{tests_require}---go into | |
593 | @code{native-inputs}. The rationale is that (1) they do not need to be | |
594 | propagated because they are not needed at run time, and (2) in a | |
595 | cross-compilation context, it's the ``native'' input that we'd want. | |
596 | ||
597 | Examples are the @code{pytest}, @code{mock}, and @code{nose} test | |
598 | frameworks. Of course if any of these packages is also required at | |
599 | run-time, it needs to go to @code{propagated-inputs}. | |
600 | ||
601 | @item | |
602 | Anything that does not fall in the previous categories goes to | |
603 | @code{inputs}, for example programs or C libraries required for building | |
604 | Python packages containing C extensions. | |
605 | ||
606 | @item | |
607 | If a Python package has optional dependencies (@code{extras_require}), it is | |
608 | up to you to decide whether to add them or not, based on their | |
609 | usefulness/overhead ratio (@pxref{Einreichen von Patches, @command{guix size}}). | |
610 | ||
611 | @end itemize | |
612 | ||
613 | ||
614 | @node Perl-Module | |
615 | @subsection Perl-Module | |
616 | ||
617 | @cindex perl | |
618 | Perl programs standing for themselves are named as any other package, using | |
619 | the lowercase upstream name. For Perl packages containing a single class, | |
620 | we use the lowercase class name, replace all occurrences of @code{::} by | |
621 | dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser} | |
622 | becomes @code{perl-xml-parser}. Modules containing several classes keep | |
623 | their lowercase upstream name and are also prepended by @code{perl-}. Such | |
624 | modules tend to have the word @code{perl} somewhere in their name, which | |
625 | gets dropped in favor of the prefix. For instance, @code{libwww-perl} | |
626 | becomes @code{perl-libwww}. | |
627 | ||
628 | ||
629 | @node Java-Pakete | |
630 | @subsection Java-Pakete | |
631 | ||
632 | @cindex java | |
633 | Java programs standing for themselves are named as any other package, using | |
634 | the lowercase upstream name. | |
635 | ||
636 | To avoid confusion and naming clashes with other programming languages, it | |
637 | is desirable that the name of a package for a Java package is prefixed with | |
638 | @code{java-}. If a project already contains the word @code{java}, we drop | |
639 | this; for instance, the package @code{ngsjava} is packaged under the name | |
640 | @code{java-ngs}. | |
641 | ||
642 | For Java packages containing a single class or a small class hierarchy, we | |
643 | use the lowercase class name, replace all occurrences of @code{.} by dashes | |
644 | and prepend the prefix @code{java-}. So the class @code{apache.commons.cli} | |
645 | becomes package @code{java-apache-commons-cli}. | |
646 | ||
647 | ||
648 | @node Schriftarten | |
649 | @subsection Schriftarten | |
650 | ||
651 | @cindex Schriftarten | |
652 | For fonts that are in general not installed by a user for typesetting | |
653 | purposes, or that are distributed as part of a larger software package, we | |
654 | rely on the general packaging rules for software; for instance, this applies | |
655 | to the fonts delivered as part of the X.Org system or fonts that are part of | |
656 | TeX Live. | |
657 | ||
658 | To make it easier for a user to search for fonts, names for other packages | |
659 | containing only fonts are constructed as follows, independently of the | |
660 | upstream package name. | |
661 | ||
662 | The name of a package containing only one font family starts with | |
663 | @code{font-}; it is followed by the foundry name and a dash @code{-} if the | |
664 | foundry is known, and the font family name, in which spaces are replaced by | |
665 | dashes (and as usual, all upper case letters are transformed to lower | |
666 | case). For example, the Gentium font family by SIL is packaged under the | |
667 | name @code{font-sil-gentium}. | |
668 | ||
669 | For a package containing several font families, the name of the collection | |
670 | is used in the place of the font family name. For instance, the Liberation | |
671 | fonts consist of three families, Liberation Sans, Liberation Serif and | |
672 | Liberation Mono. These could be packaged separately under the names | |
673 | @code{font-liberation-sans} and so on; but as they are distributed together | |
674 | under a common name, we prefer to package them together as | |
675 | @code{font-liberation}. | |
676 | ||
677 | In the case where several formats of the same font family or font collection | |
678 | are packaged separately, a short form of the format, prepended by a dash, is | |
679 | added to the package name. We use @code{-ttf} for TrueType fonts, | |
680 | @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 | |
681 | fonts. | |
682 | ||
683 | ||
1e40e70b JL |
684 | @node Code-Stil |
685 | @section Code-Stil | |
686 | ||
687 | Im Allgemeinen folgt unser Code den GNU Coding Standards (@pxref{Top,,, | |
688 | standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu | |
689 | sagen haben, folgen hier einige zusätzliche Regeln. | |
690 | ||
691 | @menu | |
692 | * Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen. | |
693 | * Module:: Wo Sie Ihren Code unterbringen. | |
694 | * Datentypen und Mustervergleich:: Implementierung von Datenstrukturen. | |
695 | * Formatierung von Code:: Schreibkonventionen. | |
696 | @end menu | |
697 | ||
698 | @node Programmierparadigmen | |
699 | @subsection Programmierparadigmen | |
700 | ||
701 | Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine | |
702 | Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die | |
703 | grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur | |
704 | @code{memoize}. | |
705 | ||
706 | @node Module | |
707 | @subsection Module | |
708 | ||
709 | Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum | |
710 | @code{(guix build @dots{})} leben. Sie dürfen auf keine anderen Guix- oder | |
793dcd8c | 711 | GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges« |
1e40e70b JL |
712 | Modul ein erstellungsseitiges Modul benutzt. |
713 | ||
714 | Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum | |
715 | @code{(gnu @dots{})} und nicht in @code{(guix @dots{})} stehen. | |
716 | ||
717 | @node Datentypen und Mustervergleich | |
718 | @subsection Datentypen und Mustervergleich | |
719 | ||
720 | Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu | |
721 | benutzen, und diese dann »händisch« zu durchlaufen mit @code{car}, | |
722 | @code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen | |
723 | Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu | |
724 | lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern | |
725 | ist. | |
726 | ||
727 | Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit | |
728 | @code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er | |
729 | das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen, | |
730 | besonders mit Listen. | |
731 | ||
732 | @node Formatierung von Code | |
733 | @subsection Formatierung von Code | |
734 | ||
735 | @cindex Formatierung von Code | |
736 | @cindex Code-Stil | |
737 | Beim Schreiben von Scheme-Code halten wir uns an die üblichen | |
738 | Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das, | |
739 | dass wir uns an @url{http://mumble.net/~campbell/scheme/style.txt, | |
740 | Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses | |
741 | Dokument auch die Konventionen beschreibt, die im Code von Guile | |
742 | hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben, | |
743 | also lesen Sie es bitte. | |
744 | ||
745 | Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das | |
746 | @code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese | |
747 | sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch | |
748 | benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens | |
749 | @code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und | |
750 | hervorhebt (@pxref{Development,,, emacs-guix, The Emacs-Guix Reference | |
751 | Manual}). | |
752 | ||
753 | @cindex Einrückung, Code- | |
754 | @cindex Formatierung, Code- | |
755 | Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor | |
756 | diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können | |
757 | Sie auch Folgendes ausführen: | |
758 | ||
759 | @example | |
760 | ./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket} | |
761 | @end example | |
762 | ||
763 | @noindent | |
764 | Dadurch wird die Definition von @var{Paket} in | |
765 | @file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im | |
766 | Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen, | |
767 | lassen Sie das zweite Argument weg: | |
768 | ||
769 | @example | |
770 | ./etc/indent-code.el gnu/services/@var{Datei}.scm | |
771 | @end example | |
772 | ||
773 | @cindex Vim, zum Editieren von Scheme-Code | |
793dcd8c | 774 | Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set |
1e40e70b JL |
775 | autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während |
776 | Sie ihn schreiben. Außerdem könnte Ihnen | |
777 | @uref{https://www.vim.org/scripts/script.php?script_id=3998, | |
778 | @code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden. | |
779 | ||
780 | Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen | |
781 | Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten | |
782 | Prozeduren im Namensraum @code{(guix build @dots{})} aufgeweicht werden. | |
783 | ||
784 | Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter | |
785 | haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als | |
786 | vier Parameter entgegennehmen. | |
787 | ||
788 | ||
789 | @node Einreichen von Patches | |
790 | @section Einreichen von Patches | |
791 | ||
792 | Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git | |
793 | durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht | |
794 | unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die | |
795 | mittels @code{git format-patch} erstellt und an die Mailingliste | |
796 | @email{guix-patches@@gnu.org} geschickt werden. | |
797 | ||
798 | Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist | |
799 | unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick | |
800 | über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete | |
801 | Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine | |
802 | Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden | |
803 | kann, wobei @var{NNN} für die Folgenummer steht (@pxref{Senden einer Patch-Reihe}). | |
804 | ||
805 | Bitte schreiben Sie Commit-Logs im ChangeLog-Format (@pxref{Change Logs,,, | |
806 | standards, GNU Coding Standards}); dazu finden Sie Beispiele unter den | |
807 | bisherigen Commits. | |
808 | ||
809 | Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder | |
793dcd8c | 810 | verändert, gehen Sie bitte diese Prüfliste durch: |
1e40e70b JL |
811 | |
812 | @enumerate | |
813 | @item | |
814 | Wenn die Autoren der verpackten Software eine kryptographische Signatur für | |
815 | den Tarball der Veröffentlichung anbieten, so machen Sie sich bitte die | |
816 | Mühe, die Echtheit des Archivs zu überprüfen. Für eine abgetrennte | |
817 | GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg --verify} tun. | |
818 | ||
819 | @item | |
820 | Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für | |
821 | das Paket zu verfassen. Unter @xref{Zusammenfassungen und Beschreibungen} finden Sie | |
822 | dazu einige Richtlinien. | |
823 | ||
824 | @item | |
825 | Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder | |
826 | geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler | |
827 | (@pxref{Aufruf von guix lint}). | |
828 | ||
829 | @item | |
830 | Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, | |
831 | indem Sie @code{guix build @var{Paket}} ausführen. | |
832 | ||
61ce2e77 JL |
833 | @item |
834 | We recommend you also try building the package on other supported | |
835 | platforms. As you may not have access to actual hardware platforms, we | |
836 | recommend using the @code{qemu-binfmt-service-type} to emulate them. In | |
837 | order to enable it, add the following service to the list of services in | |
838 | your @code{operating-system} configuration: | |
839 | ||
840 | @example | |
841 | (service qemu-binfmt-service-type | |
842 | (qemu-binfmt-configuration | |
843 | (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc" "mips64el")) | |
844 | (guix-support? #t))) | |
845 | @end example | |
846 | ||
847 | Then reconfigure your system. | |
848 | ||
849 | You can then build packages for different platforms by specifying the | |
850 | @code{--system} option. For example, to build the "hello" package for the | |
851 | armhf, aarch64, powerpc, or mips64 architectures, you would run the | |
852 | following commands, respectively: | |
853 | @example | |
854 | guix build --system=armhf-linux --rounds=2 hello | |
855 | guix build --system=aarch64-linux --rounds=2 hello | |
856 | guix build --system=powerpc-linux --rounds=2 hello | |
857 | guix build --system=mips64el-linux --rounds=2 hello | |
858 | @end example | |
859 | ||
1e40e70b JL |
860 | @item |
861 | @cindex gebündelt | |
862 | Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird, | |
863 | die bereits in separaten Paketen zur Verfügung steht. | |
864 | ||
865 | Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um | |
866 | Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir | |
793dcd8c | 867 | jedoch sicherstellen, dass solche Pakete die schon in der Distribution |
1e40e70b JL |
868 | verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der |
869 | Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt | |
870 | und gespeichert) als auch der Distribution die Möglichkeit gegeben, | |
871 | ergänzende Änderungen durchzuführen, um beispielsweise | |
872 | Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort | |
793dcd8c LC |
873 | einzuspielen, die aber das gesamte System betreffen — gebündelt |
874 | mitgelieferte Kopien würden dies verhindern. | |
1e40e70b JL |
875 | |
876 | @item | |
61ce2e77 JL |
877 | Take a look at the profile reported by @command{guix size} (@pxref{Aufruf von guix size}). This will allow you to notice references to other packages |
878 | unwillingly retained. It may also help determine whether to split the | |
879 | package (@pxref{Pakete mit mehreren Ausgaben.}), and which optional | |
880 | dependencies should be used. In particular, avoid adding @code{texlive} as | |
881 | a dependency: because of its extreme size, use @code{texlive-tiny} or | |
882 | @code{texlive-union} instead. | |
1e40e70b JL |
883 | |
884 | @item | |
885 | Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls | |
886 | vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh | |
887 | --list-dependent @var{Paket}} hilft Ihnen dabei (@pxref{Aufruf von guix refresh}). | |
888 | ||
1e40e70b JL |
889 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. |
890 | @cindex Branching-Strategie | |
891 | @cindex Neuerstellungs-Zeitplan | |
892 | Je nachdem, wieviele abhängige Pakete es gibt, und entsprechend wieviele | |
893 | Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches | |
894 | statt, nach ungefähr diesen Regeln: | |
895 | ||
896 | @table @asis | |
897 | @item 300 abhängige Pakete oder weniger | |
898 | @code{master}-Branch (störfreie Änderungen). | |
899 | ||
900 | @item zwischen 300 und 1200 abhängige Pakete | |
901 | @code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle | |
902 | 3 Wochen in @code{master} gemerget. Themenbezogene Änderungen (z.B. eine | |
903 | Aktualisierung der GNOME-Plattform) können stattdessen auch auf einem | |
904 | eigenen Branch umgesetzt werden (wie @code{gnome-updates}). | |
905 | ||
906 | @item mehr als 1200 abhängige Pakete | |
907 | @code{core-updates}-Branch (kann auch größere und womöglich andere Software | |
908 | beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in | |
909 | @code{master} alle 2,5 Monate oder so gemerget. | |
910 | @end table | |
911 | ||
61ce2e77 JL |
912 | All diese Branches werden kontinuierlich |
913 | @uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} erstellt | |
914 | und in @code{master} gemerget, sobald alles erfolgreich erstellt worden | |
915 | ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, | |
916 | und zudem das Zeitfenster, während dessen noch keine vorerstellten | |
917 | Binärdateien verfügbar sind, verkürzen. | |
1e40e70b JL |
918 | |
919 | @c TODO: It would be good with badges on the website that tracks these | |
920 | @c branches. Or maybe even a status page. | |
61ce2e77 JL |
921 | Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich} |
922 | angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender | |
923 | @code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder | |
924 | IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden | |
925 | sollte. | |
1e40e70b JL |
926 | |
927 | @item | |
928 | @cindex Determinismus, von Erstellungsprozessen | |
929 | @cindex Reproduzierbare Erstellungen, Überprüfung | |
930 | Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen | |
931 | Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe | |
932 | Ergebnis wie Ihre Erstellung hat, Bit für Bit. | |
933 | ||
934 | Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male | |
935 | hintereinander auf Ihrer Maschine erstellen (@pxref{Aufruf von guix build}): | |
936 | ||
937 | @example | |
938 | guix build --rounds=2 mein-paket | |
939 | @end example | |
940 | ||
941 | Dies reicht aus, um eine ganze Klasse häufiger Ursachen von | |
942 | Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder | |
943 | zufallsgenerierte Ausgaben im Ergebnis der Erstellung. | |
944 | ||
61ce2e77 JL |
945 | Another option is to use @command{guix challenge} (@pxref{Aufruf von 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. | |
1e40e70b JL |
953 | |
954 | @item | |
955 | Beim Schreiben von Dokumentation achten Sie bitte auf eine | |
956 | geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie | |
957 | @uref{https://en.wikipedia.org/wiki/Singular_they, »they«@comma{} | |
958 | »their«@comma{} »them« im Singular}, und so weiter. | |
959 | ||
960 | @item | |
961 | Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger | |
962 | Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen | |
963 | erschwert und bremst das Durchsehen Ihres Patches. | |
964 | ||
965 | Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer | |
966 | Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version | |
967 | zusammen mit Fehlerbehebungen für das Paket. | |
968 | ||
969 | @item | |
970 | Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich | |
971 | wollen Sie dies automatisch tun lassen durch das Skript | |
972 | @command{etc/indent-code.el} (@pxref{Formatierung von Code}). | |
973 | ||
974 | @item | |
61ce2e77 JL |
975 | Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL |
976 | (@pxref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine | |
977 | automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer | |
978 | identisch von einer Generation auf die nächste, daher ist es in diesem Fall | |
979 | besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie | |
980 | @emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht | |
981 | wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr. | |
1e40e70b JL |
982 | |
983 | @end enumerate | |
984 | ||
985 | Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch | |
793dcd8c | 986 | an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den |
1e40e70b JL |
987 | Befehl @command{git send-email} benutzen (@pxref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten, |
988 | entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu | |
989 | angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie | |
990 | Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich | |
991 | nicht mehr funktionieren. | |
992 | ||
993 | Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem | |
793dcd8c | 994 | Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden. |
1e40e70b JL |
995 | |
996 | @unnumberedsubsec Senden einer Patch-Reihe | |
997 | @anchor{Senden einer Patch-Reihe} | |
998 | @cindex Patch-Reihe | |
999 | @cindex @code{git send-email} | |
1000 | @cindex @code{git-send-email} | |
1001 | ||
1002 | @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html | |
1003 | Wenn Sie eine Patch-Reihe senden (z.B. mit @code{git send-email}), schicken | |
1004 | Sie bitte als Erstes eine Nachricht an @email{guix-patches@@gnu.org} und | |
1005 | dann nachfolgende Patches an @email{@var{NNN}@@debbugs.gnu.org}, um | |
1006 | sicherzustellen, dass sie zusammen bearbeitet werden. Siehe | |
1007 | @uref{https://debbugs.gnu.org/Advanced.html, die Debbugs-Dokumentation} für | |
1008 | weitere Informationen. |