1055 lines
48 KiB
Text
1055 lines
48 KiB
Text
@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 (siehe @ref{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 (siehe
|
||
@ref{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 @ref{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 erzeugen. 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 @ref{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 siehe @ref{Der Store}).
|
||
|
||
Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen
|
||
(siehe @ref{Den Testkatalog laufen lassen}). Falls etwas fehlschlägt, werfen Sie
|
||
einen Blick auf die Installationsanweisungen (siehe @ref{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 (siehe @ref{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 (siehe @ref{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} (siehe @ref{Aufruf von guix pull}). Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen
|
||
@command{git pull} benutzen.
|
||
|
||
|
||
@node Perfekt eingerichtet
|
||
@section Perfekt eingerichtet
|
||
|
||
Um perfekt für das Hacken an Guix eingerichtet zu sein, brauchen Sie an sich
|
||
dasselbe wie um perfekt für das Hacken mit Guile (siehe @ref{Using Guile in
|
||
Emacs,,, guile, Guile Reference Manual}). Zunächst brauchen Sie mehr als ein
|
||
Textverarbeitungsprogramm, Sie brauchen
|
||
@url{http://www.gnu.org/software/emacs, Emacs} zusammen mit den vom
|
||
wunderbaren @url{http://nongnu.org/geiser/, Geiser} verliehenen Kräften. Um
|
||
diese zu installieren, können Sie Folgendes ausführen:
|
||
|
||
@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 (siehe
|
||
@ref{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 Pakete definieren
|
||
Die GNU-Distribution ist noch sehr jung und einige Ihrer Lieblingspakete
|
||
könnten noch fehlen. Dieser Abschnitt beschreibt, wie Sie dabei helfen
|
||
können, die Distribution wachsen zu lassen.
|
||
|
||
Pakete mit freier Software werden normalerweise in Form von @dfn{Tarballs
|
||
mit dem Quellcode} angeboten — typischerweise in
|
||
@file{tar.gz}-Archivdateien, in denen alle Quelldateien enthalten sind. Ein
|
||
Paket zur Distribution hinzuzufügen, bedeutet also zweierlei Dinge: Zum
|
||
einen fügt man ein @dfn{Rezept} ein, das beschreibt, wie das Paket erstellt
|
||
werden kann, einschließlich einer Liste von anderen Paketen, die für diese
|
||
Erstellung gebraucht werden, zum anderen fügt man @dfn{Paketmetadaten} zum
|
||
Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen.
|
||
|
||
In Guix sind all diese Informationen ein Teil der
|
||
@dfn{Paketdefinitionen}. In Paketdefinitionen hat man eine abstrahierte,
|
||
hochsprachliche Sicht auf das Paket. Sie werden in der Syntax der
|
||
Scheme-Programmiersprache verfasst; tatsächlich definieren wir für jedes
|
||
Paket eine Variable und binden diese an dessen Definition, um die Variable
|
||
anschließend aus einem Modul heraus zu exportieren (siehe @ref{Paketmodule}). Allerdings ist @emph{kein} tiefgehendes Wissen über Scheme
|
||
erforderlich, um Pakete zu erstellen. Mehr Informationen über
|
||
Paketdefinitionen finden Sie im Abschnitt @ref{Pakete definieren}.
|
||
|
||
Eine fertige Paketdefinition kann, nachdem sie in eine Datei im
|
||
Quell-Verzeichnisbaum von Guix eingesetzt wurde, mit Hilfe des Befehls
|
||
@command{guix build} getestet werden (siehe @ref{Aufruf von guix build}). Wenn
|
||
das Paket zum Beispiel den Namen @code{gnew} trägt, können Sie folgenden
|
||
Befehl aus dem Erstellungs-Verzeichnisbaum von Guix heraus ausführen (siehe
|
||
@ref{Guix vor der Installation ausführen}):
|
||
|
||
@example
|
||
./pre-inst-env guix build gnew --keep-failed
|
||
@end example
|
||
|
||
Wenn Sie @code{--keep-failed} benutzen, ist es leichter, fehlgeschlagene
|
||
Erstellungen zu untersuchen, weil dann der Verzeichnisbaum der
|
||
fehlgeschlagenen Erstellung zugänglich bleibt. Eine andere nützliche
|
||
Befehlszeilenoption bei der Fehlersuche ist @code{--log-file}, womit das
|
||
Erstellungsprotokoll eingesehen werden kann.
|
||
|
||
Wenn der @command{guix}-Befehl das Paket nicht erkennt, kann es daran
|
||
liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine
|
||
@code{define-public}-Klausel fehlt, die die Paketvariable exportiert. Um das
|
||
herauszufinden, können Sie das Modul aus Guile heraus laden, um mehr
|
||
Informationen über den tatsächlichen Fehler zu bekommen:
|
||
|
||
@example
|
||
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
|
||
@end example
|
||
|
||
Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte
|
||
einen Patch (siehe @ref{Einreichen von Patches}). Wenn Sie dabei Hilfe brauchen
|
||
sollten, helfen wir gerne. Ab dem Zeitpunkt, zu dem der Patch als Commit ins
|
||
Guix-Repository eingepflegt wurde, wird das neue Paket automatisch durch
|
||
@url{http://hydra.gnu.org/jobset/gnu/master, unser System zur
|
||
Kontinuierlichen Integration} auf allen unterstützten Plattformen erstellt.
|
||
|
||
@cindex Substituierer
|
||
Benutzern steht die neue Paketdefinition zur Verfügung, nachdem sie das
|
||
nächste Mal @command{guix pull} ausgeführt haben (siehe @ref{Aufruf von guix pull}). Wenn @code{@value{SUBSTITUTE-SERVER}} selbst damit fertig ist, das
|
||
Paket zu erstellen, werden bei der Installation automatisch Binärdateien von
|
||
dort heruntergeladen (siehe @ref{Substitute}). Menschliches Eingreifen muss
|
||
nur stattfinden, um den Patch zu überprüfen und anzuwenden.
|
||
|
||
|
||
@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 freie Software
|
||
Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der
|
||
Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist @dfn{freie Software}, was
|
||
bedeutet, dass Benutzer die
|
||
@url{http://www.gnu.org/philosophy/free-sw.de.html,vier wesentlichen
|
||
Freiheiten} haben: das Programm auszuführen, es zu untersuchen, das Programm
|
||
in Form seines Quellcodes anzupassen und exakte Kopien ebenso wie
|
||
modifizierte Versionen davon an andere weiterzugeben. Die Pakete, die Sie in
|
||
der GNU-Distribution finden, stellen ausschließlich solche Software zur
|
||
Verfügung, die Ihnen diese vier Freiheiten gewährt.
|
||
|
||
Außerdem befolgt die GNU-Distribution die
|
||
@url{http://www.gnu.org/distros/free-system-distribution-guidelines.de.html,Richtlinien
|
||
für freie Systemverteilungen}. Unter anderem werden unfreie Firmware sowie
|
||
Empfehlungen von unfreier Software abgelehnt und Möglichkeiten zum Umgang
|
||
mit Markenzeichen und Patenten werden diskutiert.
|
||
|
||
Ansonsten freier Paketquellcode von manchen Anbietern enthält einen kleinen
|
||
und optionalen Teil, der diese Richtlinien verletzt. Zum Beispiel kann
|
||
dieser Teil selbst unfreier Code sein. Wenn das vorkommt, wird der sie
|
||
verletzende Teil mit angemessenen Patches oder Code-Schnipseln innerhalb der
|
||
@code{origin}-Form des Pakets entfernt (siehe @ref{Pakete definieren}). Dadurch liefert Ihnen @code{guix build --source} nur den
|
||
»befreiten« Quellcode und nicht den unmodifizierten Quellcode des Anbieters.
|
||
|
||
|
||
@node Paketbenennung
|
||
@subsection Paketbenennung
|
||
|
||
@cindex Paketname
|
||
Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es
|
||
den Namen der @emph{Scheme-Variablen}, der direkt nach @code{define-public}
|
||
im Code steht. Mit diesem Namen kann das Paket im Scheme-Code nutzbar
|
||
gemacht und zum Beispiel als Eingabe eines anderen Pakets benannt
|
||
werden. Zum anderen gibt es die Zeichenkette im @code{name}-Feld einer
|
||
Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie
|
||
@command{guix package} und @command{guix build} benutzt.
|
||
|
||
Meistens sind die beiden identisch und ergeben sich aus einer Umwandlung des
|
||
vom Anbieter verwendeten Projektnamens in Kleinbuchstaben, bei der
|
||
Unterstriche durch Bindestriche ersetzt werden. Zum Beispiel wird GNUnet
|
||
unter dem Paketnamen @code{gnunet} angeboten und SDL_net als @code{sdl-net}.
|
||
|
||
An Bibliothekspakete hängen wir vorne kein @code{lib} als Präfix an, solange
|
||
es nicht Teil des offiziellen Projektnamens ist. Beachten Sie aber die
|
||
Abschnitte @ref{Python-Module} und @ref{Perl-Module}, in denen
|
||
Sonderregeln für Module der Programmiersprachen Python und Perl beschrieben
|
||
sind.
|
||
|
||
Auch Pakete mit Schriftarten werden anders behandelt, siehe @ref{Schriftarten}.
|
||
|
||
|
||
@node Versionsnummern
|
||
@subsection Versionsnummern
|
||
|
||
@cindex Paketversion
|
||
Normalerweise stellen wir nur für die neueste Version eines
|
||
Freie-Software-Projekts ein Paket bereit. Manchmal gibt es allerdings Fälle
|
||
wie zum Beispiel untereinander inkompatible Bibliotheksversionen, so dass
|
||
zwei (oder mehr) Versionen desselben Pakets angeboten werden müssen. In
|
||
diesem Fall müssen wir verschiedene Scheme-Variablennamen benutzen. Wir
|
||
benutzen dann für die neueste Version den Namen, wie er im Abschnitt
|
||
@ref{Paketbenennung} festgelegt wird, und geben vorherigen Versionen
|
||
denselben Namen mit einem zusätzlichen Suffix aus @code{-} gefolgt vom
|
||
kürzesten Präfix der Versionsnummer, mit dem noch immer zwei Versionen
|
||
unterschieden werden können.
|
||
|
||
Der Name innerhalb der Paketdefinition ist hingegen derselbe für alle
|
||
Versionen eines Pakets und enthält keine Versionsnummer.
|
||
|
||
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 Versionsnummer, bei Snapshots aus Versionskontrolle
|
||
Gelegentlich fügen wir auch Pakete für Snapshots aus dem
|
||
Versionskontrollsystem des Anbieters statt formaler Veröffentlichungen zur
|
||
Distribution hinzu. Das sollte die Ausnahme bleiben, weil die Entwickler
|
||
selbst klarstellen sollten, welche Version als die stabile Veröffentlichung
|
||
gelten sollte, ab und zu ist es jedoch notwendig. Was also sollten wir dann
|
||
im @code{version}-Feld eintragen?
|
||
|
||
Offensichtlich muss der Bezeichner des Commits, den wir als Snapshot aus dem
|
||
Versionskontrollsystem nehmen, in der Versionszeichenkette zu erkennen sein,
|
||
aber wir müssen auch sicherstellen, dass die Version monoton steigend ist,
|
||
damit @command{guix package --upgrade} feststellen kann, welche Version die
|
||
neuere ist. Weil Commit-Bezeichner, insbesondere bei Git, nicht monoton
|
||
steigen, müssen wir eine Revisionsnummer hinzufügen, die wir jedes Mal
|
||
erhöhen, wenn wir das Paket auf einen neueren Snapshot aktualisieren. Die
|
||
sich ergebende Versionszeichenkette sieht dann so aus:
|
||
|
||
@example
|
||
2.0.11-3.cabba9e
|
||
^ ^ ^
|
||
| | `-- Commit-ID beim Anbieter
|
||
| |
|
||
| `--- Revisionsnummer des Guix-Pakets
|
||
|
|
||
die neueste Version, die der Anbieter veröffentlicht hat
|
||
@end example
|
||
|
||
Es ist eine gute Idee, die Commit-Bezeichner im @code{version}-Feld auf,
|
||
sagen wir, 7 Ziffern zu beschränken. Das sieht besser aus (angenommen, das
|
||
sollte hier eine Rolle spielen) und vermeidet Probleme, die mit der
|
||
maximalen Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Am
|
||
besten benutzt man jedoch den vollständigen Commit-Bezeichner in
|
||
@code{origin}s, um Mehrdeutigkeiten zu vermeiden. Eine typische
|
||
Paketdefinition könnte so aussehen:
|
||
|
||
@example
|
||
(define mein-paket
|
||
(let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
|
||
(revision "1")) ;Guix-Paketrevision
|
||
(package
|
||
(version (git-version "0.9" revision commit))
|
||
(source (origin
|
||
(method git-fetch)
|
||
(uri (git-reference
|
||
(url "git://example.org/mein-paket.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 Paketbeschreibung
|
||
@cindex Paketzusammenfassung
|
||
Wie wir bereits gesehen haben, enthält jedes Paket in GNU@tie{}Guix eine (im
|
||
Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine
|
||
Beschreibung (englisch: Description; siehe @ref{Pakete definieren}). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden
|
||
mit @command{guix package --search} durchsucht und stellen eine
|
||
entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob
|
||
das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler Acht
|
||
geben, was sie dort eintragen.
|
||
|
||
Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht
|
||
mit einem Punkt enden. Sie dürfen nicht mit den Artikeln »a« oder »the«
|
||
beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum
|
||
Beispiel sollte »File-frobbing tool« gegenüber »A tool that frobs files«
|
||
vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim
|
||
Paket handelt — z.B.@: »Core GNU utilities (file, text, shell)« —, oder
|
||
aussagen, wofür es benutzt wird — z.B.@: ist die Zusammenfassung für
|
||
GNU@tie{}grep »Print lines matching a pattern«.
|
||
|
||
Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen
|
||
Sinn ergeben muss. Zum Beispiel würde »Manipulate alignments in the SAM
|
||
format« vielleicht von einem erfahrenen Forscher in der Bioinformatik
|
||
verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig
|
||
hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es
|
||
ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine
|
||
Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier
|
||
würden sich die Nutzer mit »Manipulate nucleotide sequence alignments«
|
||
hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach
|
||
sie suchen.
|
||
|
||
Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie
|
||
vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor
|
||
eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie »world-leading«
|
||
(»weltweit führend«), »industrial-strength« (»industrietauglich«) und
|
||
»next-generation« (»der nächsten Generation«) ebenso wie Superlative wie
|
||
»the most advanced« (»das fortgeschrittenste«) — davon haben Nutzer nichts,
|
||
wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen
|
||
Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und
|
||
Funktionalitäten zu erwähnen.
|
||
|
||
@cindex Texinfo-Auszeichnungen, in Paketbeschreibungen
|
||
Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das
|
||
bedeutet, Text kann Verzierungen wie @code{@@code} oder @code{@@dfn},
|
||
Auflistungen oder Hyperlinks enthalten (siehe @ref{Overview,,, texinfo, GNU
|
||
Texinfo}). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte
|
||
Zeichen wie @samp{@@} und geschweifte Klammern schreiben, weil es sich dabei
|
||
um die grundlegenden Sonderzeichen in Texinfo handelt (siehe @ref{Special
|
||
Characters,,, texinfo, GNU Texinfo}). Benutzungsschnittstellen wie
|
||
@command{guix package --show} kümmern sich darum, solche Auszeichnungen
|
||
angemessen darzustellen.
|
||
|
||
Zusammenfassungen und Beschreibungen werden von Freiwilligen
|
||
@uref{http://translationproject.org/domain/guix-packages.html, beim
|
||
Translation Project} übersetzt, damit so viele Nutzer wie möglich sie in
|
||
ihrer Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie
|
||
in der von der aktuell eingestellten Locale festgelegten Sprache durchsucht
|
||
und angezeigt werden.
|
||
|
||
Damit @command{xgettext} sie als übersetzbare Zeichenketten extrahieren
|
||
kann, @emph{müssen} Zusammenfassungen und Beschreibungen einfache
|
||
Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten
|
||
nicht mit Prozeduren wie @code{string-append} oder @code{format}
|
||
konstruieren können:
|
||
|
||
@lisp
|
||
(package
|
||
;; @dots{}
|
||
(synopsis "This is translatable")
|
||
(description (string-append "This is " "*not*" " translatable.")))
|
||
@end lisp
|
||
|
||
Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso
|
||
mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren,
|
||
weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den
|
||
Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese
|
||
sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel
|
||
einfügen (siehe @ref{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
|
||
Zur Zeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils
|
||
über die Scheme-Variablen mit den Namen @code{python-2} und @code{python}
|
||
zur Verfügung, entsprechend der Erklärungen im Abschnitt @ref{Versionsnummern}. Um Verwirrungen und Namenskollisionen mit anderen
|
||
Programmiersprachen zu vermeiden, erscheint es als wünschenswert, dass der
|
||
Name eines Pakets für ein Python-Modul auch das Wort @code{python} enthält.
|
||
|
||
Manche Module sind nur mit einer Version von Python kompatibel, andere mit
|
||
beiden. Wenn das Paket Foo nur mit Python 3 kompiliert werden kann, geben
|
||
wir ihm den Namen @code{python-foo}, wenn es nur mit Python 2 kompilierbar
|
||
ist, wählen wir den Namen @code{python2-foo}. Ist es mit beiden Versionen
|
||
kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen.
|
||
|
||
Wenn ein Projekt bereits das Wort @code{python} im Namen hat, lassen wir es
|
||
weg; zum Beispiel ist das Modul python-dateutil unter den Namen
|
||
@code{python-dateutil} und @code{python2-dateutil} verfügbar. Wenn der
|
||
Projektname mit @code{py} beginnt (z.B.@: @code{pytz}), behalten wir ihn bei
|
||
und stellen das oben beschriebene Präfix voran.
|
||
|
||
@subsubsection Abhängigkeiten angeben
|
||
@cindex Eingaben, für Python-Pakete
|
||
|
||
Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und
|
||
mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des
|
||
Paketquellcodes: in der Datei @file{setup.py}, in @file{requirements.txt}
|
||
oder in @file{tox.ini}.
|
||
|
||
Wenn Sie ein Rezept für ein Python-Paket schreiben, lautet Ihr Auftrag,
|
||
diese Abhängigkeiten auf angemessene Arten von »Eingaben« abzubilden (siehe
|
||
@ref{»package«-Referenz, inputs}). Obwohl der @code{pypi}-Importer hier
|
||
normalerweise eine gute Arbeit leistet (siehe @ref{Aufruf von guix import}),
|
||
könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo
|
||
welche Abhängigkeit eingeordnet werden sollte.
|
||
|
||
@itemize
|
||
|
||
@item
|
||
Derzeit ist unser Python-2-Paket so geschrieben, dass es @code{setuptools}
|
||
und @code{pip} installiert, wie es auch in den Vorgaben zu Python 3.4
|
||
gemacht wird. Sie müssen also keines der beiden als Eingabe angeben. Wenn
|
||
Sie es doch tun, wird @command{guix lint} Sie darauf mit einer Warnung
|
||
aufmerksam machen.
|
||
|
||
@item
|
||
Python-Abhängigkeiten, die zur Laufzeit gebraucht werden, stehen im
|
||
@code{propagated-inputs}-Feld. Solche werden typischerweise mit dem
|
||
Schlüsselwort @code{install_requires} in @file{setup.py} oder in der Datei
|
||
@file{requirements.txt} definiert.
|
||
|
||
@item
|
||
Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B.@: jene,
|
||
die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py}
|
||
aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in
|
||
@code{tests_require} —, stehen in @code{native-inputs}. Die Begründung ist,
|
||
dass (1) sie nicht propagiert werden müssen, weil sie zur Laufzeit nicht
|
||
gebraucht werden, und (2) wir beim Cross-Kompilieren die »native« Eingabe
|
||
des Wirtssystems wollen.
|
||
|
||
Beispiele sind die Testrahmen @code{pytest}, @code{mock} und
|
||
@code{nose}. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit
|
||
benötigt wird, muss es doch in @code{propagated-inputs} stehen.
|
||
|
||
@item
|
||
Alles, was nicht in die bisher genannten Kategorien fällt, steht in
|
||
@code{inputs}, zum Beispiel Programme oder C-Bibliotheken, die zur
|
||
Erstellung von Python-Paketen mit enthaltenen C-Erweiterungen gebraucht
|
||
werden.
|
||
|
||
@item
|
||
Wenn ein Python-Paket optionale Abhängigkeiten hat (@code{extras_require}),
|
||
ist es Ihnen überlassen, sie hinzuzufügen oder nicht hinzuzufügen, je
|
||
nachdem wie es um deren Verhältnis von Nützlichkeit zu anderen Nachteilen
|
||
steht (siehe @ref{Einreichen von Patches, @command{guix size}}).
|
||
|
||
@end itemize
|
||
|
||
|
||
@node Perl-Module
|
||
@subsection Perl-Module
|
||
|
||
@cindex perl
|
||
Eigenständige Perl-Programme bekommen einen Namen wie jedes andere Paket,
|
||
unter Nutzung des Namens beim Anbieter in Kleinbuchstaben. Für Perl-Pakete,
|
||
die eine einzelne Klasse enthalten, ersetzen wir alle Vorkommen von
|
||
@code{::} durch Striche und hängen davor das Präfix @code{perl-} an. Die
|
||
Klasse @code{XML::Parser} wird also zu @code{perl-xml-parser}. Module, die
|
||
mehrere Klassen beinhalten, behalten ihren Namen beim Anbieter, in
|
||
Kleinbuchstaben gesetzt, und auch an sie wird vorne das Präfix @code{perl-}
|
||
angehängt. Es gibt die Tendenz, solche Module mit dem Wort @code{perl}
|
||
irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes
|
||
weggelassen. Zum Beispiel wird aus @code{libwww-perl} bei uns
|
||
@code{perl-libwww}.
|
||
|
||
|
||
@node Java-Pakete
|
||
@subsection Java-Pakete
|
||
|
||
@cindex java
|
||
Eigenständige Java-Programme werden wie jedes andere Paket benannt, d.h.@:
|
||
mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter.
|
||
|
||
Um Verwirrungen und Namenskollisionen mit anderen Programmiersprachen zu
|
||
vermeiden, ist es wünschenswert, dass dem Namem eines Pakets zu einem
|
||
Java-Paket das Präfix @code{java-} vorangestellt wird. Wenn ein Projekt
|
||
bereits das Wort @code{java} im Namen trägt, lassen wir es weg; zum Beispiel
|
||
befindet sich das Java-Paket @code{ngsjava} in einem Paket namens
|
||
@code{java-ngs}.
|
||
|
||
Bei Java-Paketen, die eine einzelne Klasse oder eine kleine
|
||
Klassenhierarchie enthalten, benutzen wir den Klassennamen in
|
||
Kleinbuchstaben und ersetzen dabei alle Vorkommen von @code{.} durch Striche
|
||
und setzen das Präfix @code{java-} davor. Die Klasse
|
||
@code{apache.commons.cli} wird also zum Paket
|
||
@code{java-apache-commons-cli}.
|
||
|
||
|
||
@node Schriftarten
|
||
@subsection Schriftarten
|
||
|
||
@cindex Schriftarten
|
||
Wenn Schriftarten in der Regel nicht von Nutzern zur Textbearbeitung
|
||
installiert werden oder als Teil eines größeren Software-Pakets mitgeliefert
|
||
werden, gelten dafür die allgemeinen Paketrichtlinien für Software. Zum
|
||
Beispiel trifft das auf als Teil des X.Org-Systems ausgelieferte
|
||
Schriftarten zu, oder auf Schriftarten, die ein Teil von TeX Live sind.
|
||
|
||
Damit es Nutzer leichter haben, nach Schriftarten zu suchen, konstruieren
|
||
wir die Namen von anderen Paketen, die nur Schriftarten enthalten, nach dem
|
||
folgenden Schema, egal was der Paketname beim Anbieter ist.
|
||
|
||
Der Name eines Pakets, das nur eine Schriftfamilie enthält, beginnt mit
|
||
@code{font-}. Darauf folgt der Name des Schriftenherstellers und ein Strich
|
||
@code{-}, sofern bekannt ist, wer der Schriftenhersteller ist, und dann der
|
||
Name der Schriftfamilie, in dem Leerzeichen durch Striche ersetzt werden
|
||
(und wie immer mit Großbuchstaben statt Kleinbuchstaben). Zum Beispiel
|
||
befindet sich die von SIL hergestellte Gentium-Schriftfamilie im Paket mit
|
||
dem Namen @code{font-sil-gentium}.
|
||
|
||
Wenn ein Paket mehrere Schriftfamilien enthält, wird der Name der Sammlung
|
||
anstelle des Schriftfamiliennamens benutzt. Zum Beispiel umfassen die
|
||
Liberation-Schriftarten drei Familien: Liberation Sans, Liberation Serif und
|
||
Liberation Mono. Man könnte sie getrennt voneinander mit den Namen
|
||
@code{font-liberation-sans} und so weiter in Pakete einteilen, da sie aber
|
||
unter einem gemeinsamen Namen angeboten werden, packen wir sie lieber
|
||
zusammen in ein Paket mit dem Namen @code{font-liberation}.
|
||
|
||
Für den Fall, dass mehrere Formate derselben Schriftfamilie oder
|
||
Schriftartensammlung in separate Pakete kommen, wird ein Kurzname für das
|
||
Format mit einem Strich vorne zum Paketnamen hinzugefügt. Wir benutzen
|
||
@code{-ttf} für TrueType-Schriftarten, @code{-otf} für OpenType-Schriftarten
|
||
und @code{-type1} für PostScript-Typ-1-Schriftarten.
|
||
|
||
|
||
@node Code-Stil
|
||
@section Code-Stil
|
||
|
||
Im Allgemeinen folgt unser Code den GNU Coding Standards (siehe @ref{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 (siehe @ref{Entwicklung,,, 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 (siehe @ref{Senden einer Patch-Reihe}).
|
||
|
||
Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe @ref{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 kryptografische Signatur
|
||
bzw. Beglaubigung 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 @ref{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 (siehe
|
||
@ref{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
|
||
Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten
|
||
Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware
|
||
für diese Plattformen haben, empfehlen wir, den
|
||
@code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu
|
||
aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste
|
||
(»services«) in Ihrer @code{operating-system}-Konfiguration ein:
|
||
|
||
@example
|
||
(service qemu-binfmt-service-type
|
||
(qemu-binfmt-configuration
|
||
(platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
|
||
(guix-support? #t)))
|
||
@end example
|
||
|
||
Rekonfigurieren Sie anschließend Ihr System.
|
||
|
||
Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die
|
||
Befehlszeilenoption @code{--system} angeben. Um zum Beispiel das Paket
|
||
»hello« für die Architekturen armhf, aarch64 oder mips64 erstellen zu
|
||
lassen, würden Sie jeweils die folgenden Befehle angeben:
|
||
@example
|
||
guix build --system=armhf-linux --rounds=2 hello
|
||
guix build --system=aarch64-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
|
||
Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe
|
||
@ref{Aufruf von guix size}). Dadurch können Sie Referenzen auf andere Pakete
|
||
finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu
|
||
entscheiden, ob das Paket aufgespalten werden sollte (siehe @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet
|
||
werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere
|
||
vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie
|
||
stattdessen @code{texlive-tiny} oder @code{texlive-union}.
|
||
|
||
@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 (siehe @ref{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 mit @code{master} zusammengeführt. 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 (siehe @ref{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.
|
||
|
||
Eine weitere Möglichkeit ist, @command{guix challenge} (siehe @ref{Aufruf von guix challenge}) zu benutzen. Sie können es ausführen, sobald ein Paket
|
||
commitet und von @code{@value{SUBSTITUTE-SERVER}} erstellt wurde, um zu
|
||
sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser:
|
||
Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen
|
||
Sie @command{guix publish} aus. Da sich die entfernte Erstellungsmaschine
|
||
wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme
|
||
durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum
|
||
Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem
|
||
Betriebssystem-Kernel — zum Beispiel, indem @code{uname} oder
|
||
@file{/proc}-Dateien verwendet werden.
|
||
|
||
@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} (siehe @ref{Formatierung von Code}).
|
||
|
||
@item
|
||
Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe
|
||
@ref{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 (siehe @ref{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.
|