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
8 für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der
9 Erstellung von Paketen (@pxref{Paketrichtlinien}).
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.
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.
27 * Erstellung aus dem Git:: Das Neueste und Beste.
28 * Guix vor der Installation ausführen:: Hacker-Tricks.
29 * Perfekt eingerichtet:: Die richtigen Werkzeuge.
30 * Paketrichtlinien:: Die Distribution wachsen lassen.
31 * Code-Stil:: Wie Mitwirkende hygienisch arbeiten.
32 * Einreichen von Patches:: Teilen Sie Ihre Arbeit.
35 @node Erstellung aus dem Git
36 @section Erstellung aus dem Git
38 Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die
39 neueste Version aus dem Git-Softwarebestand verwenden:
42 git clone https://git.savannah.gnu.org/git/guix.git
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}).
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)}.
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
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}
72 guix environment guix --ad-hoc help2man git strace
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:
80 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
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
93 export ACLOCAL_PATH=/usr/share/aclocal
96 In @xref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie
97 weitere Informationen.
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}).
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
107 Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}.
110 @node Guix vor der Installation ausführen
111 @section Guix vor der Installation ausführen
113 Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im
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.
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
131 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
132 $ ./pre-inst-env guix build hello
136 Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt:
139 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
146 @cindex Lese-Auswerten-Schreiben-Schleife
147 @dots{} und auf einer REPL (@pxref{Using Guile Interactively,,, guile, Guile
151 $ ./pre-inst-env guile
152 scheme@@(guile-user)> ,use(guix)
153 scheme@@(guile-user)> ,use(gnu)
154 scheme@@(guile-user)> (define snakes
156 (lambda (package lst)
157 (if (string-prefix? "python"
158 (package-name package))
162 scheme@@(guile-user)> (length snakes)
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}.
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.
177 @node Perfekt eingerichtet
178 @section Perfekt eingerichtet
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:
187 guix package -i emacs guile emacs-geiser
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.
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"))
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.
212 @cindex Code-Schnipsel
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.
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"))
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.
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.
245 @node Paketrichtlinien
246 @section Paketrichtlinien
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
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
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}.
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}):
276 ./pre-inst-env guix build gnew --keep-failed
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.
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:
289 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
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
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.
308 * Software-Freiheit:: Was in die Distribution aufgenommen werden
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
314 * Python-Module:: Ein Touch britischer Comedy.
315 * Perl-Module:: Kleine Perlen.
316 * Java-Pakete:: Kaffeepause.
317 * Schriftarten:: Schriften verschriftlicht.
320 @node Software-Freiheit
321 @subsection Software-Freiheit
323 @c ===========================================================================
325 @c This file was generated with po4a. Translate the source file.
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
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.
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.
353 @subsection Paketbenennung
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}.
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
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
373 Font package names are handled differently, @pxref{Schriftarten}.
376 @node Versionsnummern
377 @subsection Versionsnummern
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.
388 The name inside the package definition is the same for all versions of a
389 package and does not contain any version number.
391 Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie
392 folgt geschrieben werden:
400 (define-public gtk+-2
406 Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als
408 (define-public gtk+-3.8
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}
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:
435 | | `-- upstream commit ID
437 | `--- Guix package revision
439 latest upstream version
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:
451 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
452 (revision "1")) ;Guix package revision
454 (version (git-version "0.9" revision commit))
458 (url "git://example.org/my-package.git")
460 (sha256 (base32 "1mbikn@dots{}"))
461 (file-name (git-file-name name version))))
466 @node Zusammenfassungen und Beschreibungen
467 @subsection Zusammenfassungen und Beschreibungen
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
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''.
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.
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
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.
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.
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
525 (synopsis "This is translatable")
526 (description (string-append "This is " "*not*" " translatable.")))
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}):
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{}")
543 @subsection Python-Module
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
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.
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
564 @subsubsection Specifying Dependencies
565 @cindex inputs, for Python packages
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}.
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.
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.
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.
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.
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}.
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.
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}}).
615 @subsection Perl-Module
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}.
630 @subsection Java-Pakete
633 Java programs standing for themselves are named as any other package, using
634 the lowercase upstream name.
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
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}.
649 @subsection 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
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.
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}.
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}.
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
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.
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.
698 @node Programmierparadigmen
699 @subsection Programmierparadigmen
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
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
711 GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges«
712 Modul ein erstellungsseitiges Modul benutzt.
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.
717 @node Datentypen und Mustervergleich
718 @subsection Datentypen und Mustervergleich
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
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.
732 @node Formatierung von Code
733 @subsection Formatierung von Code
735 @cindex Formatierung von Code
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.
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
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:
760 ./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket}
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:
770 ./etc/indent-code.el gnu/services/@var{Datei}.scm
773 @cindex Vim, zum Editieren von Scheme-Code
774 Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set
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.
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.
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.
789 @node Einreichen von Patches
790 @section Einreichen von Patches
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.
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}).
805 Bitte schreiben Sie Commit-Logs im ChangeLog-Format (@pxref{Change Logs,,,
806 standards, GNU Coding Standards}); dazu finden Sie Beispiele unter den
809 Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder
810 verändert, gehen Sie bitte diese Prüfliste durch:
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.
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.
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}).
830 Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann,
831 indem Sie @code{guix build @var{Paket}} ausführen.
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:
841 (service qemu-binfmt-service-type
842 (qemu-binfmt-configuration
843 (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc" "mips64el"))
847 Then reconfigure your system.
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:
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
862 Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird,
863 die bereits in separaten Paketen zur Verfügung steht.
865 Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um
866 Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir
867 jedoch sicherstellen, dass solche Pakete die schon in der Distribution
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
873 einzuspielen, die aber das gesamte System betreffen — gebündelt
874 mitgelieferte Kopien würden dies verhindern.
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.
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}).
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:
897 @item 300 abhängige Pakete oder weniger
898 @code{master}-Branch (störfreie Änderungen).
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}).
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.
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.
919 @c TODO: It would be good with badges on the website that tracks these
920 @c branches. Or maybe even a status page.
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
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.
934 Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male
935 hintereinander auf Ihrer Maschine erstellen (@pxref{Aufruf von guix build}):
938 guix build --rounds=2 mein-paket
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.
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}
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.
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.
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.
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}).
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.
985 Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch
986 an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den
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.
993 Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem
994 Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden.
996 @unnumberedsubsec Senden einer Patch-Reihe
997 @anchor{Senden einer Patch-Reihe}
999 @cindex @code{git send-email}
1000 @cindex @code{git-send-email}
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.