diff options
Diffstat (limited to 'doc/contributing.de.texi')
| -rw-r--r-- | doc/contributing.de.texi | 1008 |
1 files changed, 0 insertions, 1008 deletions
diff --git a/doc/contributing.de.texi b/doc/contributing.de.texi deleted file mode 100644 index 259523aa6f..0000000000 --- a/doc/contributing.de.texi +++ /dev/null @@ -1,1008 +0,0 @@ -@node Mitwirken -@chapter Mitwirken - -Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um -es wachsen zu lassen! Bitte kontaktieren Sie uns auf -@email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir -freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich -für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der -Erstellung von Paketen (@pxref{Paketrichtlinien}). - -@cindex Verhaltensregeln, für Mitwirkende -@cindex Verhaltenskodex für Mitwirkende -Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung -bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten -kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für -Mitwirkende«, der von @url{http://contributor-covenant.org/} übernommen -wurde. Eine übersetzte Fassung finden Sie auf -@url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct} -sowie eine mitgelieferte, englische Fassung in der Datei -@file{CODE-OF-CONDUCT} im Quellbaum. - -Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der -Online-Kommunikation ihre echten Namen preisgeben. Sie können einen -beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden. - -@menu -* Erstellung aus dem Git:: Das Neueste und Beste. -* Guix vor der Installation ausführen:: Hacker-Tricks. -* Perfekt eingerichtet:: Die richtigen Werkzeuge. -* Paketrichtlinien:: Die Distribution wachsen lassen. -* Code-Stil:: Wie Mitwirkende hygienisch arbeiten. -* Einreichen von Patches:: Teilen Sie Ihre Arbeit. -@end menu - -@node Erstellung aus dem Git -@section Erstellung aus dem Git - -Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die -neueste Version aus dem Git-Softwarebestand verwenden: - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den -Installationsanweisungen genannten Paketen weitere nötig -(@pxref{Voraussetzungen}). - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}. -@end itemize - -Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist -natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in -der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um -an Guix zu arbeiten: - -@example -guix environment guix -@end example - -In @xref{Aufruf von guix environment} finden Sie weitere Informationen zu -diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc} -hinzugefügt werden: - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -Führen Sie @command{./bootstrap} aus, um die Infrastruktur des -Erstellungssystems mit Autoconf und Automake zu erstellen. Möglicherweise -erhalten Sie eine Fehlermeldung wie diese: - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden -konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass -@file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile -bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake -in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht -nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden -Befehl aufrufen: - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -In @xref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie -weitere Informationen. - -Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf, -@code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei -@var{Verzeichnis} der von Ihrer aktuellen Installation verwendete -@code{localstatedir}-Wert ist (weitere Informationen auf @pxref{Der Store}). - -Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen -(@pxref{Die Testsuite laufen lassen}). Falls etwas fehlschlägt, werfen Sie einen -Blick auf die Installationsanweisungen (@pxref{Installation}) oder senden -Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}. - - -@node Guix vor der Installation ausführen -@section Guix vor der Installation ausführen - -Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im -lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie -tatsächlich zu installieren. So können Sie zwischen Ihrem -Endnutzer-»Straßenanzug« und Ihrem »Faschingskostüm« unterscheiden. - -Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt -werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie -sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix -verfügbar sind (@pxref{Erstellung aus dem Git}) und darin einfach vor jeden -Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env} -befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo -es durch @command{./configure} erzeugt wird), zum Beispiel so@footnote{Die -Befehlszeilenoption @option{-E} von @command{sudo} stellt sicher, dass -@code{GUILE_LOAD_PATH} richtig gesetzt wird, damit @command{guix-daemon} und -die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden -können.}: - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt: - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex Lese-Auswerten-Schreiben-Schleife -@dots{} und auf einer REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}): - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define snakes - (fold-packages - (lambda (package lst) - (if (string-prefix? "python" - (package-name package)) - (cons package lst) - lst)) - '())) -scheme@@(guile-user)> (length snakes) -$1 = 361 -@end example - -Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die -nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und -@env{GUILE_LOAD_PATH}. - -Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum -@emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische -Verknüpfung @file{~/.config/guix/current} (@pxref{Aufruf von guix pull}). Um -Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen -@command{git pull} benutzen. - - -@node Perfekt eingerichtet -@section Perfekt eingerichtet - -The Perfect Setup to hack on Guix is basically the perfect setup used for -Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference -Manual}). First, you need more than an editor, you need -@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful -@url{http://nongnu.org/geiser/, Geiser}. To set that up, run: - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs -heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu -Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie -kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition -zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr -(@pxref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen -Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die -Quelldateien in Ihrem Checkout gefunden werden. - -@lisp -;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten -Scheme-Modus. Aber Sie dürfen auch -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es -bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so -zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken -oder den nachfolgenden S-Ausdruck verwerfen, etc. - -@cindex Code-Schnipsel -@cindex Vorlagen -@cindex Tipparbeit sparen -Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und -Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können -mit @url{http://joaotavora.github.io/yasnippet/, YASnippet} zusammen benutzt -werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln -umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer -@var{yas-snippet-dirs}-Variablen in Emacs hinzufügen. - -@lisp -;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit} -voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine -Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB} -eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines -Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um -eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie -@code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der -Homepage-URI eines Pakets auf HTTPS einzufügen. - -Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie -@code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch -die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter -umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere -Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst -wieder weiter umgeschrieben werden kann. - - -@node Paketrichtlinien -@section Paketrichtlinien - -@cindex packages, creating -The GNU distribution is nascent and may well lack some of your favorite -packages. This section describes how you can help make the distribution -grow. - -Free software packages are usually distributed in the form of @dfn{source -code tarballs}---typically @file{tar.gz} files that contain all the source -files. Adding a package to the distribution means essentially two things: -adding a @dfn{recipe} that describes how to build the package, including a -list of other packages required to build it, and adding @dfn{package -metadata} along with that recipe, such as a description and licensing -information. - -In Guix all this information is embodied in @dfn{package definitions}. -Package definitions provide a high-level view of the package. They are -written using the syntax of the Scheme programming language; in fact, for -each package we define a variable bound to the package definition, and -export that variable from a module (@pxref{Paketmodule}). However, -in-depth Scheme knowledge is @emph{not} a prerequisite for creating -packages. For more information on package definitions, @pxref{Pakete definieren}. - -Once a package definition is in place, stored in a file in the Guix source -tree, it can be tested using the @command{guix build} command -(@pxref{Aufruf von guix build}). For example, assuming the new package is -called @code{gnew}, you may run this command from the Guix build tree -(@pxref{Guix vor der Installation ausführen}): - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Using @code{--keep-failed} makes it easier to debug build failures since it -provides access to the failed build tree. Another useful command-line -option when debugging is @code{--log-file}, to access the build log. - -If the package is unknown to the @command{guix} command, it may be that the -source file contains a syntax error, or lacks a @code{define-public} clause -to export the package variable. To figure it out, you may load the module -from Guile to get more information about the actual error: - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Once your package builds correctly, please send us a patch -(@pxref{Einreichen von Patches}). Well, if you need help, we will be happy to -help you too. Once the patch is committed in the Guix repository, the new -package automatically gets built on the supported platforms by -@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration -system}. - -@cindex substituter -Users can obtain the new package definition simply by running @command{guix -pull} (@pxref{Aufruf von guix pull}). When @code{@value{SUBSTITUTE-SERVER}} -is done building the package, installing the package automatically downloads -binaries from there (@pxref{Substitute}). The only place where human -intervention is needed is to review and apply the patch. - - -@menu -* Software-Freiheit:: Was in die Distribution aufgenommen werden - darf. -* Paketbenennung:: Was macht einen Namen aus? -* Versionsnummern:: Wenn der Name noch nicht genug ist. -* Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige - Paket zu finden. -* Python-Module:: Ein Touch britischer Comedy. -* Perl-Module:: Kleine Perlen. -* Java-Pakete:: Kaffeepause. -* Schriftarten:: Schriften verschriftlicht. -@end menu - -@node Software-Freiheit -@subsection Software-Freiheit - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex free software -The GNU operating system has been developed so that users can have freedom -in their computing. GNU is @dfn{free software}, meaning that users have the -@url{http://www.gnu.org/philosophy/free-sw.html,four essential freedoms}: to -run the program, to study and change the program in source code form, to -redistribute exact copies, and to distribute modified versions. Packages -found in the GNU distribution provide only software that conveys these four -freedoms. - -In addition, the GNU distribution follow the -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free -software distribution guidelines}. Among other things, these guidelines -reject non-free firmware, recommendations of non-free software, and discuss -ways to deal with trademarks and patents. - -Some otherwise free upstream package sources contain a small and optional -subset that violates the above guidelines, for instance because this subset -is itself non-free code. When that happens, the offending items are removed -with appropriate patches or code snippets in the @code{origin} form of the -package (@pxref{Pakete definieren}). This way, @code{guix build --source} -returns the ``freed'' source rather than the unmodified upstream source. - - -@node Paketbenennung -@subsection Paketbenennung - -@cindex package name -A package has actually two names associated with it: First, there is the -name of the @emph{Scheme variable}, the one following @code{define-public}. -By this name, the package can be made known in the Scheme code, for instance -as input to another package. Second, there is the string in the @code{name} -field of a package definition. This name is used by package management -commands such as @command{guix package} and @command{guix build}. - -Both are usually the same and correspond to the lowercase conversion of the -project name chosen upstream, with underscores replaced with hyphens. For -instance, GNUnet is available as @code{gnunet}, and SDL_net as -@code{sdl-net}. - -We do not add @code{lib} prefixes for library packages, unless these are -already part of the official project name. But @pxref{Python-Module} and -@ref{Perl-Module} for special rules concerning modules for the Python and -Perl languages. - -Font package names are handled differently, @pxref{Schriftarten}. - - -@node Versionsnummern -@subsection Versionsnummern - -@cindex package version -We usually package only the latest version of a given free software -project. But sometimes, for instance for incompatible library versions, two -(or more) versions of the same package are needed. These require different -Scheme variable names. We use the name as defined in @ref{Paketbenennung} -for the most recent version; previous versions use the same name, suffixed -by @code{-} and the smallest prefix of the version number that may -distinguish the two versions. - -The name inside the package definition is the same for all versions of a -package and does not contain any version number. - -Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie -folgt geschrieben werden: - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, -@c for a discussion of what follows. -@cindex version number, for VCS snapshots -Occasionally, we package snapshots of upstream's version control system -(VCS) instead of formal releases. This should remain exceptional, because -it is up to upstream developers to clarify what the stable release is. Yet, -it is sometimes necessary. So, what should we put in the @code{version} -field? - -Clearly, we need to make the commit identifier of the VCS snapshot visible -in the version string, but we also need to make sure that the version string -is monotonically increasing so that @command{guix package --upgrade} can -determine which version is newer. Since commit identifiers, notably with -Git, are not monotonically increasing, we add a revision number that we -increase each time we upgrade to a newer snapshot. The resulting version -string looks like this: - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- upstream commit ID - | | - | `--- Guix package revision - | -latest upstream version -@end example - -It is a good idea to strip commit identifiers in the @code{version} field -to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics -have a role to play here) as well as problems related to OS limits such as -the maximum shebang length (127 bytes for the Linux kernel.) It is best to -use the full commit identifiers in @code{origin}s, though, to avoid -ambiguities. A typical package definition may look like this: - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Guix package revision - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/my-package.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Zusammenfassungen und Beschreibungen -@subsection Zusammenfassungen und Beschreibungen - -@cindex package description -@cindex package synopsis -As we have seen before, each package in GNU@tie{}Guix includes a synopsis -and a description (@pxref{Pakete definieren}). Synopses and descriptions -are important: They are what @command{guix package --search} searches, and a -crucial piece of information to help users determine whether a given package -suits their needs. Consequently, packagers should pay attention to what -goes into them. - -Synopses must start with a capital letter and must not end with a period. -They must not start with ``a'' or ``the'', which usually does not bring -anything; for instance, prefer ``File-frobbing tool'' over ``A tool that -frobs files''. The synopsis should say what the package is---e.g., ``Core -GNU utilities (file, text, shell)''---or what it is used for---e.g., the -synopsis for GNU@tie{}grep is ``Print lines matching a pattern''. - -Keep in mind that the synopsis must be meaningful for a very wide audience. -For example, ``Manipulate alignments in the SAM format'' might make sense -for a seasoned bioinformatics researcher, but might be fairly unhelpful or -even misleading to a non-specialized audience. It is a good idea to come up -with a synopsis that gives an idea of the application domain of the -package. In this example, this might give something like ``Manipulate -nucleotide sequence alignments'', which hopefully gives the user a better -idea of whether this is what they are looking for. - -Descriptions should take between five and ten lines. Use full sentences, -and avoid using acronyms without first introducing them. Please avoid -marketing phrases such as ``world-leading'', ``industrial-strength'', and -``next-generation'', and avoid superlatives like ``the most -advanced''---they are not helpful to users looking for a package and may -even sound suspicious. Instead, try to be factual, mentioning use cases and -features. - -@cindex Texinfo markup, in package descriptions -Descriptions can include Texinfo markup, which is useful to introduce -ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks -(@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful -when using some characters for example @samp{@@} and curly braces which are -the basic special characters in Texinfo (@pxref{Special Characters,,, -texinfo, GNU Texinfo}). User interfaces such as @command{guix package ---show} take care of rendering it appropriately. - -Synopses and descriptions are translated by volunteers -@uref{http://translationproject.org/domain/guix-packages.html, at the -Translation Project} so that as many users as possible can read them in -their native language. User interfaces search them and display them in the -language specified by the current locale. - -To allow @command{xgettext} to extract them as translatable strings, -synopses and descriptions @emph{must be literal strings}. This means that -you cannot use @code{string-append} or @code{format} to construct these -strings: - -@lisp -(package - ;; @dots{} - (synopsis "This is translatable") - (description (string-append "This is " "*not*" " translatable."))) -@end lisp - -Translation is a lot of work so, as a packager, please pay even more -attention to your synopses and descriptions as every change may entail -additional work for translators. In order to help them, it is possible to -make recommendations or instructions visible to them by inserting special -comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}): - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Python-Module -@subsection Python-Module - -@cindex python -We currently package Python 2 and Python 3, under the Scheme variable names -@code{python-2} and @code{python} as explained in @ref{Versionsnummern}. To -avoid confusion and naming clashes with other programming languages, it -seems desirable that the name of a package for a Python module contains the -word @code{python}. - -Some modules are compatible with only one version of Python, others with -both. If the package Foo compiles only with Python 3, we name it -@code{python-foo}; if it compiles only with Python 2, we name it -@code{python2-foo}. If it is compatible with both versions, we create two -packages with the corresponding names. - -If a project already contains the word @code{python}, we drop this; for -instance, the module python-dateutil is packaged under the names -@code{python-dateutil} and @code{python2-dateutil}. If the project name -starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as -described above. - -@subsubsection Specifying Dependencies -@cindex inputs, for Python packages - -Dependency information for Python packages is usually available in the -package source tree, with varying degrees of accuracy: in the -@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. - -Your mission, when writing a recipe for a Python package, is to map these -dependencies to the appropriate type of ``input'' (@pxref{»package«-Referenz, -inputs}). Although the @code{pypi} importer normally does a good job -(@pxref{Aufruf von guix import}), you may want to check the following check -list to determine which dependency goes where. - -@itemize - -@item -We currently package Python 2 with @code{setuptools} and @code{pip} -installed like Python 3.4 has per default. Thus you don't need to specify -either of these as an input. @command{guix lint} will warn you if you do. - -@item -Python dependencies required at run time go into @code{propagated-inputs}. -They are typically defined with the @code{install_requires} keyword in -@file{setup.py}, or in the @file{requirements.txt} file. - -@item -Python packages required only at build time---e.g., those listed with the -@code{setup_requires} keyword in @file{setup.py}---or only for -testing---e.g., those in @code{tests_require}---go into -@code{native-inputs}. The rationale is that (1) they do not need to be -propagated because they are not needed at run time, and (2) in a -cross-compilation context, it's the ``native'' input that we'd want. - -Examples are the @code{pytest}, @code{mock}, and @code{nose} test -frameworks. Of course if any of these packages is also required at -run-time, it needs to go to @code{propagated-inputs}. - -@item -Anything that does not fall in the previous categories goes to -@code{inputs}, for example programs or C libraries required for building -Python packages containing C extensions. - -@item -If a Python package has optional dependencies (@code{extras_require}), it is -up to you to decide whether to add them or not, based on their -usefulness/overhead ratio (@pxref{Einreichen von Patches, @command{guix size}}). - -@end itemize - - -@node Perl-Module -@subsection Perl-Module - -@cindex perl -Perl programs standing for themselves are named as any other package, using -the lowercase upstream name. For Perl packages containing a single class, -we use the lowercase class name, replace all occurrences of @code{::} by -dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser} -becomes @code{perl-xml-parser}. Modules containing several classes keep -their lowercase upstream name and are also prepended by @code{perl-}. Such -modules tend to have the word @code{perl} somewhere in their name, which -gets dropped in favor of the prefix. For instance, @code{libwww-perl} -becomes @code{perl-libwww}. - - -@node Java-Pakete -@subsection Java-Pakete - -@cindex java -Java programs standing for themselves are named as any other package, using -the lowercase upstream name. - -To avoid confusion and naming clashes with other programming languages, it -is desirable that the name of a package for a Java package is prefixed with -@code{java-}. If a project already contains the word @code{java}, we drop -this; for instance, the package @code{ngsjava} is packaged under the name -@code{java-ngs}. - -For Java packages containing a single class or a small class hierarchy, we -use the lowercase class name, replace all occurrences of @code{.} by dashes -and prepend the prefix @code{java-}. So the class @code{apache.commons.cli} -becomes package @code{java-apache-commons-cli}. - - -@node Schriftarten -@subsection Schriftarten - -@cindex Schriftarten -For fonts that are in general not installed by a user for typesetting -purposes, or that are distributed as part of a larger software package, we -rely on the general packaging rules for software; for instance, this applies -to the fonts delivered as part of the X.Org system or fonts that are part of -TeX Live. - -To make it easier for a user to search for fonts, names for other packages -containing only fonts are constructed as follows, independently of the -upstream package name. - -The name of a package containing only one font family starts with -@code{font-}; it is followed by the foundry name and a dash @code{-} if the -foundry is known, and the font family name, in which spaces are replaced by -dashes (and as usual, all upper case letters are transformed to lower -case). For example, the Gentium font family by SIL is packaged under the -name @code{font-sil-gentium}. - -For a package containing several font families, the name of the collection -is used in the place of the font family name. For instance, the Liberation -fonts consist of three families, Liberation Sans, Liberation Serif and -Liberation Mono. These could be packaged separately under the names -@code{font-liberation-sans} and so on; but as they are distributed together -under a common name, we prefer to package them together as -@code{font-liberation}. - -In the case where several formats of the same font family or font collection -are packaged separately, a short form of the format, prepended by a dash, is -added to the package name. We use @code{-ttf} for TrueType fonts, -@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 -fonts. - - -@node Code-Stil -@section Code-Stil - -Im Allgemeinen folgt unser Code den GNU Coding Standards (@pxref{Top,,, -standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu -sagen haben, folgen hier einige zusätzliche Regeln. - -@menu -* Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen. -* Module:: Wo Sie Ihren Code unterbringen. -* Datentypen und Mustervergleich:: Implementierung von Datenstrukturen. -* Formatierung von Code:: Schreibkonventionen. -@end menu - -@node Programmierparadigmen -@subsection Programmierparadigmen - -Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine -Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die -grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur -@code{memoize}. - -@node Module -@subsection Module - -Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum -@code{(guix build @dots{})} leben. Sie dürfen auf keine anderen Guix- oder -GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges« -Modul ein erstellungsseitiges Modul benutzt. - -Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum -@code{(gnu @dots{})} und nicht in @code{(guix @dots{})} stehen. - -@node Datentypen und Mustervergleich -@subsection Datentypen und Mustervergleich - -Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu -benutzen, und diese dann »händisch« zu durchlaufen mit @code{car}, -@code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen -Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu -lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern -ist. - -Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit -@code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er -das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen, -besonders mit Listen. - -@node Formatierung von Code -@subsection Formatierung von Code - -@cindex Formatierung von Code -@cindex Code-Stil -Beim Schreiben von Scheme-Code halten wir uns an die üblichen -Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das, -dass wir uns an @url{http://mumble.net/~campbell/scheme/style.txt, -Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses -Dokument auch die Konventionen beschreibt, die im Code von Guile -hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben, -also lesen Sie es bitte. - -Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das -@code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese -sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch -benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens -@code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und -hervorhebt (@pxref{Development,,, emacs-guix, The Emacs-Guix Reference -Manual}). - -@cindex Einrückung, Code- -@cindex Formatierung, Code- -Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor -diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können -Sie auch Folgendes ausführen: - -@example -./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket} -@end example - -@noindent -Dadurch wird die Definition von @var{Paket} in -@file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im -Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen, -lassen Sie das zweite Argument weg: - -@example -./etc/indent-code.el gnu/services/@var{Datei}.scm -@end example - -@cindex Vim, zum Editieren von Scheme-Code -Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set -autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während -Sie ihn schreiben. Außerdem könnte Ihnen -@uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden. - -Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen -Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten -Prozeduren im Namensraum @code{(guix build @dots{})} aufgeweicht werden. - -Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter -haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als -vier Parameter entgegennehmen. - - -@node Einreichen von Patches -@section Einreichen von Patches - -Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git -durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht -unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die -mittels @code{git format-patch} erstellt und an die Mailingliste -@email{guix-patches@@gnu.org} geschickt werden. - -Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist -unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick -über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete -Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine -Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden -kann, wobei @var{NNN} für die Folgenummer steht (@pxref{Senden einer Patch-Reihe}). - -Bitte schreiben Sie Commit-Logs im ChangeLog-Format (@pxref{Change Logs,,, -standards, GNU Coding Standards}); dazu finden Sie Beispiele unter den -bisherigen Commits. - -Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder -verändert, gehen Sie bitte diese Prüfliste durch: - -@enumerate -@item -Wenn die Autoren der verpackten Software eine kryptographische Signatur für -den Tarball der Veröffentlichung anbieten, so machen Sie sich bitte die -Mühe, die Echtheit des Archivs zu überprüfen. Für eine abgetrennte -GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg --verify} tun. - -@item -Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für -das Paket zu verfassen. Unter @xref{Zusammenfassungen und Beschreibungen} finden Sie -dazu einige Richtlinien. - -@item -Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder -geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler -(@pxref{Aufruf von guix lint}). - -@item -Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, -indem Sie @code{guix build @var{Paket}} ausführen. - -@item -We recommend you also try building the package on other supported -platforms. As you may not have access to actual hardware platforms, we -recommend using the @code{qemu-binfmt-service-type} to emulate them. In -order to enable it, add the following service to the list of services in -your @code{operating-system} configuration: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc" "mips64el")) - (guix-support? #t))) -@end example - -Then reconfigure your system. - -You can then build packages for different platforms by specifying the -@code{--system} option. For example, to build the "hello" package for the -armhf, aarch64, powerpc, or mips64 architectures, you would run the -following commands, respectively: -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=powerpc-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex gebündelt -Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird, -die bereits in separaten Paketen zur Verfügung steht. - -Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um -Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir -jedoch sicherstellen, dass solche Pakete die schon in der Distribution -verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der -Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt -und gespeichert) als auch der Distribution die Möglichkeit gegeben, -ergänzende Änderungen durchzuführen, um beispielsweise -Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort -einzuspielen, die aber das gesamte System betreffen — gebündelt -mitgelieferte Kopien würden dies verhindern. - -@item -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 -unwillingly retained. It may also help determine whether to split the -package (@pxref{Pakete mit mehreren Ausgaben.}), and which optional -dependencies should be used. In particular, avoid adding @code{texlive} as -a dependency: because of its extreme size, use @code{texlive-tiny} or -@code{texlive-union} instead. - -@item -Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls -vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh ---list-dependent @var{Paket}} hilft Ihnen dabei (@pxref{Aufruf von guix refresh}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. -@cindex Branching-Strategie -@cindex Neuerstellungs-Zeitplan -Je nachdem, wieviele abhängige Pakete es gibt, und entsprechend wieviele -Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches -statt, nach ungefähr diesen Regeln: - -@table @asis -@item 300 abhängige Pakete oder weniger -@code{master}-Branch (störfreie Änderungen). - -@item zwischen 300 und 1200 abhängige Pakete -@code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle -3 Wochen in @code{master} gemerget. Themenbezogene Änderungen (z.B. eine -Aktualisierung der GNOME-Plattform) können stattdessen auch auf einem -eigenen Branch umgesetzt werden (wie @code{gnome-updates}). - -@item mehr als 1200 abhängige Pakete -@code{core-updates}-Branch (kann auch größere und womöglich andere Software -beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in -@code{master} alle 2,5 Monate oder so gemerget. -@end table - -All diese Branches werden kontinuierlich -@uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} erstellt -und in @code{master} gemerget, sobald alles erfolgreich erstellt worden -ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, -und zudem das Zeitfenster, während dessen noch keine vorerstellten -Binärdateien verfügbar sind, verkürzen. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich} -angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender -@code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder -IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden -sollte. - -@item -@cindex Determinismus, von Erstellungsprozessen -@cindex Reproduzierbare Erstellungen, Überprüfung -Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen -Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe -Ergebnis wie Ihre Erstellung hat, Bit für Bit. - -Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male -hintereinander auf Ihrer Maschine erstellen (@pxref{Aufruf von guix build}): - -@example -guix build --rounds=2 mein-paket -@end example - -Dies reicht aus, um eine ganze Klasse häufiger Ursachen von -Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder -zufallsgenerierte Ausgaben im Ergebnis der Erstellung. - -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 -by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same -result as you did. Better yet: Find another machine that can build it and -run @command{guix publish}. Since the remote build machine is likely -different from yours, this can catch non-determinism issues related to the -hardware---e.g., use of different instruction set extensions---or to the -operating system kernel---e.g., reliance on @code{uname} or @file{/proc} -files. - -@item -Beim Schreiben von Dokumentation achten Sie bitte auf eine -geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie -@uref{https://en.wikipedia.org/wiki/Singular_they, »they«@comma{} -»their«@comma{} »them« im Singular}, und so weiter. - -@item -Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger -Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen -erschwert und bremst das Durchsehen Ihres Patches. - -Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer -Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version -zusammen mit Fehlerbehebungen für das Paket. - -@item -Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich -wollen Sie dies automatisch tun lassen durch das Skript -@command{etc/indent-code.el} (@pxref{Formatierung von Code}). - -@item -Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL -(@pxref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine -automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer -identisch von einer Generation auf die nächste, daher ist es in diesem Fall -besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie -@emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht -wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr. - -@end enumerate - -Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch -an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den -Befehl @command{git send-email} benutzen (@pxref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten, -entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu -angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie -Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich -nicht mehr funktionieren. - -Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem -Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden. - -@unnumberedsubsec Senden einer Patch-Reihe -@anchor{Senden einer Patch-Reihe} -@cindex Patch-Reihe -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -Wenn Sie eine Patch-Reihe senden (z.B. mit @code{git send-email}), schicken -Sie bitte als Erstes eine Nachricht an @email{guix-patches@@gnu.org} und -dann nachfolgende Patches an @email{@var{NNN}@@debbugs.gnu.org}, um -sicherzustellen, dass sie zusammen bearbeitet werden. Siehe -@uref{https://debbugs.gnu.org/Advanced.html, die Debbugs-Dokumentation} für -weitere Informationen. |