Commit | Line | Data |
---|---|---|
1e40e70b JL |
1 | @node Mitwirken |
2 | @chapter Mitwirken | |
3 | ||
4 | Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um | |
5 | es wachsen zu lassen! Bitte kontaktieren Sie uns auf | |
6 | @email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir | |
7 | freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich | |
793dcd8c | 8 | für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der |
c04052e4 | 9 | Erstellung von Paketen (siehe @ref{Paketrichtlinien}). |
1e40e70b JL |
10 | |
11 | @cindex Verhaltensregeln, für Mitwirkende | |
12 | @cindex Verhaltenskodex für Mitwirkende | |
13 | Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung | |
14 | bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten | |
15 | kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für | |
16 | Mitwirkende«, der von @url{http://contributor-covenant.org/} übernommen | |
17 | wurde. Eine übersetzte Fassung finden Sie auf | |
18 | @url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct} | |
19 | sowie eine mitgelieferte, englische Fassung in der Datei | |
20 | @file{CODE-OF-CONDUCT} im Quellbaum. | |
21 | ||
22 | Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der | |
23 | Online-Kommunikation ihre echten Namen preisgeben. Sie können einen | |
24 | beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden. | |
25 | ||
26 | @menu | |
27 | * Erstellung aus dem Git:: Das Neueste und Beste. | |
28 | * Guix vor der Installation ausführen:: Hacker-Tricks. | |
29 | * Perfekt eingerichtet:: Die richtigen Werkzeuge. | |
61ce2e77 | 30 | * Paketrichtlinien:: Die Distribution wachsen lassen. |
1e40e70b JL |
31 | * Code-Stil:: Wie Mitwirkende hygienisch arbeiten. |
32 | * Einreichen von Patches:: Teilen Sie Ihre Arbeit. | |
33 | @end menu | |
34 | ||
35 | @node Erstellung aus dem Git | |
36 | @section Erstellung aus dem Git | |
37 | ||
38 | Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die | |
39 | neueste Version aus dem Git-Softwarebestand verwenden: | |
40 | ||
41 | @example | |
42 | git clone https://git.savannah.gnu.org/git/guix.git | |
43 | @end example | |
44 | ||
45 | Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den | |
c04052e4 LC |
46 | Installationsanweisungen genannten Paketen weitere nötig (siehe |
47 | @ref{Voraussetzungen}). | |
1e40e70b JL |
48 | |
49 | @itemize | |
50 | @item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; | |
51 | @item @url{http://gnu.org/software/automake/, GNU Automake}; | |
52 | @item @url{http://gnu.org/software/gettext/, GNU Gettext}; | |
53 | @item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; | |
54 | @item @url{http://www.graphviz.org/, Graphviz}; | |
55 | @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}. | |
56 | @end itemize | |
57 | ||
58 | Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist | |
59 | natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in | |
60 | der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um | |
61 | an Guix zu arbeiten: | |
62 | ||
63 | @example | |
64 | guix environment guix | |
65 | @end example | |
66 | ||
c04052e4 | 67 | In @ref{Aufruf von guix environment} finden Sie weitere Informationen zu |
1e40e70b JL |
68 | diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc} |
69 | hinzugefügt werden: | |
70 | ||
71 | @example | |
72 | guix environment guix --ad-hoc help2man git strace | |
73 | @end example | |
74 | ||
75 | Führen Sie @command{./bootstrap} aus, um die Infrastruktur des | |
c04052e4 | 76 | Erstellungssystems mit Autoconf und Automake zu erzeugen. Möglicherweise |
1e40e70b JL |
77 | erhalten Sie eine Fehlermeldung wie diese: |
78 | ||
79 | @example | |
80 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES | |
81 | @end example | |
82 | ||
83 | @noindent | |
84 | Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden | |
85 | konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass | |
86 | @file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile | |
87 | bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake | |
88 | in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht | |
89 | nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden | |
90 | Befehl aufrufen: | |
91 | ||
92 | @example | |
93 | export ACLOCAL_PATH=/usr/share/aclocal | |
94 | @end example | |
95 | ||
c04052e4 | 96 | In @ref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie |
1e40e70b JL |
97 | weitere Informationen. |
98 | ||
99 | Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf, | |
100 | @code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei | |
101 | @var{Verzeichnis} der von Ihrer aktuellen Installation verwendete | |
c04052e4 | 102 | @code{localstatedir}-Wert ist (weitere Informationen siehe @ref{Der Store}). |
1e40e70b JL |
103 | |
104 | Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen | |
c04052e4 LC |
105 | (siehe @ref{Den Testkatalog laufen lassen}). Falls etwas fehlschlägt, werfen Sie |
106 | einen Blick auf die Installationsanweisungen (siehe @ref{Installation}) oder | |
107 | senden Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}. | |
1e40e70b JL |
108 | |
109 | ||
110 | @node Guix vor der Installation ausführen | |
111 | @section Guix vor der Installation ausführen | |
112 | ||
793dcd8c | 113 | Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im |
1e40e70b JL |
114 | lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie |
115 | tatsächlich zu installieren. So können Sie zwischen Ihrem | |
116 | Endnutzer-»Straßenanzug« und Ihrem »Faschingskostüm« unterscheiden. | |
117 | ||
61ce2e77 JL |
118 | Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt |
119 | werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie | |
120 | sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix | |
c04052e4 | 121 | verfügbar sind (siehe @ref{Erstellung aus dem Git}) und darin einfach vor jeden |
61ce2e77 JL |
122 | Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env} |
123 | befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo | |
124 | es durch @command{./configure} erzeugt wird), zum Beispiel so@footnote{Die | |
125 | Befehlszeilenoption @option{-E} von @command{sudo} stellt sicher, dass | |
126 | @code{GUILE_LOAD_PATH} richtig gesetzt wird, damit @command{guix-daemon} und | |
127 | die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden | |
128 | können.}: | |
1e40e70b JL |
129 | |
130 | @example | |
131 | $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild | |
132 | $ ./pre-inst-env guix build hello | |
133 | @end example | |
134 | ||
135 | @noindent | |
136 | Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt: | |
137 | ||
138 | @example | |
139 | $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' | |
140 | ||
141 | ;;; ("x86_64-linux") | |
142 | @end example | |
143 | ||
144 | @noindent | |
145 | @cindex REPL | |
146 | @cindex Lese-Auswerten-Schreiben-Schleife | |
c04052e4 LC |
147 | @dots{} und auf einer REPL (siehe @ref{Using Guile Interactively,,, guile, |
148 | Guile Reference Manual}): | |
1e40e70b JL |
149 | |
150 | @example | |
151 | $ ./pre-inst-env guile | |
152 | scheme@@(guile-user)> ,use(guix) | |
153 | scheme@@(guile-user)> ,use(gnu) | |
154 | scheme@@(guile-user)> (define snakes | |
155 | (fold-packages | |
156 | (lambda (package lst) | |
157 | (if (string-prefix? "python" | |
158 | (package-name package)) | |
159 | (cons package lst) | |
160 | lst)) | |
161 | '())) | |
162 | scheme@@(guile-user)> (length snakes) | |
163 | $1 = 361 | |
164 | @end example | |
165 | ||
166 | Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die | |
167 | nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und | |
168 | @env{GUILE_LOAD_PATH}. | |
169 | ||
61ce2e77 JL |
170 | Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum |
171 | @emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische | |
c04052e4 | 172 | Verknüpfung @file{~/.config/guix/current} (siehe @ref{Aufruf von guix pull}). Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen |
61ce2e77 | 173 | @command{git pull} benutzen. |
1e40e70b JL |
174 | |
175 | ||
176 | @node Perfekt eingerichtet | |
177 | @section Perfekt eingerichtet | |
178 | ||
c04052e4 LC |
179 | Um perfekt für das Hacken an Guix eingerichtet zu sein, brauchen Sie an sich |
180 | dasselbe wie um perfekt für das Hacken mit Guile (siehe @ref{Using Guile in | |
181 | Emacs,,, guile, Guile Reference Manual}). Zunächst brauchen Sie mehr als ein | |
182 | Textverarbeitungsprogramm, Sie brauchen | |
183 | @url{http://www.gnu.org/software/emacs, Emacs} zusammen mit den vom | |
184 | wunderbaren @url{http://nongnu.org/geiser/, Geiser} verliehenen Kräften. Um | |
185 | diese zu installieren, können Sie Folgendes ausführen: | |
61ce2e77 JL |
186 | |
187 | @example | |
188 | guix package -i emacs guile emacs-geiser | |
189 | @end example | |
1e40e70b JL |
190 | |
191 | Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs | |
192 | heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu | |
193 | Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie | |
194 | kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition | |
c04052e4 LC |
195 | zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr (siehe |
196 | @ref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen | |
1e40e70b JL |
197 | Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die |
198 | Quelldateien in Ihrem Checkout gefunden werden. | |
199 | ||
200 | @lisp | |
201 | ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} | |
202 | (with-eval-after-load 'geiser-guile | |
203 | (add-to-list 'geiser-guile-load-path "~/src/guix")) | |
204 | @end lisp | |
205 | ||
206 | Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten | |
207 | Scheme-Modus. Aber Sie dürfen auch | |
208 | @url{http://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es | |
209 | bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so | |
210 | zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken | |
211 | oder den nachfolgenden S-Ausdruck verwerfen, etc. | |
212 | ||
213 | @cindex Code-Schnipsel | |
214 | @cindex Vorlagen | |
215 | @cindex Tipparbeit sparen | |
216 | Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und | |
217 | Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können | |
218 | mit @url{http://joaotavora.github.io/yasnippet/, YASnippet} zusammen benutzt | |
219 | werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln | |
220 | umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer | |
221 | @var{yas-snippet-dirs}-Variablen in Emacs hinzufügen. | |
222 | ||
223 | @lisp | |
224 | ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} | |
225 | (with-eval-after-load 'yasnippet | |
226 | (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) | |
227 | @end lisp | |
228 | ||
61ce2e77 JL |
229 | Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit} |
230 | voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine | |
231 | Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB} | |
232 | eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines | |
233 | Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um | |
234 | eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie | |
235 | @code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der | |
236 | Homepage-URI eines Pakets auf HTTPS einzufügen. | |
1e40e70b JL |
237 | |
238 | Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie | |
239 | @code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch | |
240 | die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter | |
241 | umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere | |
242 | Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst | |
243 | wieder weiter umgeschrieben werden kann. | |
244 | ||
245 | ||
61ce2e77 JL |
246 | @node Paketrichtlinien |
247 | @section Paketrichtlinien | |
248 | ||
c04052e4 LC |
249 | @cindex Pakete definieren |
250 | Die GNU-Distribution ist noch sehr jung und einige Ihrer Lieblingspakete | |
251 | könnten noch fehlen. Dieser Abschnitt beschreibt, wie Sie dabei helfen | |
252 | können, die Distribution wachsen zu lassen. | |
253 | ||
254 | Pakete mit freier Software werden normalerweise in Form von @dfn{Tarballs | |
255 | mit dem Quellcode} angeboten — typischerweise in | |
256 | @file{tar.gz}-Archivdateien, in denen alle Quelldateien enthalten sind. Ein | |
257 | Paket zur Distribution hinzuzufügen, bedeutet also zweierlei Dinge: Zum | |
258 | einen fügt man ein @dfn{Rezept} ein, das beschreibt, wie das Paket erstellt | |
259 | werden kann, einschließlich einer Liste von anderen Paketen, die für diese | |
260 | Erstellung gebraucht werden, zum anderen fügt man @dfn{Paketmetadaten} zum | |
261 | Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen. | |
262 | ||
263 | In Guix sind all diese Informationen ein Teil der | |
264 | @dfn{Paketdefinitionen}. In Paketdefinitionen hat man eine abstrahierte, | |
265 | hochsprachliche Sicht auf das Paket. Sie werden in der Syntax der | |
266 | Scheme-Programmiersprache verfasst; tatsächlich definieren wir für jedes | |
267 | Paket eine Variable und binden diese an dessen Definition, um die Variable | |
268 | anschließend aus einem Modul heraus zu exportieren (siehe @ref{Paketmodule}). Allerdings ist @emph{kein} tiefgehendes Wissen über Scheme | |
269 | erforderlich, um Pakete zu erstellen. Mehr Informationen über | |
270 | Paketdefinitionen finden Sie im Abschnitt @ref{Pakete definieren}. | |
271 | ||
272 | Eine fertige Paketdefinition kann, nachdem sie in eine Datei im | |
273 | Quell-Verzeichnisbaum von Guix eingesetzt wurde, mit Hilfe des Befehls | |
274 | @command{guix build} getestet werden (siehe @ref{Aufruf von guix build}). Wenn | |
275 | das Paket zum Beispiel den Namen @code{gnew} trägt, können Sie folgenden | |
276 | Befehl aus dem Erstellungs-Verzeichnisbaum von Guix heraus ausführen (siehe | |
277 | @ref{Guix vor der Installation ausführen}): | |
61ce2e77 JL |
278 | |
279 | @example | |
280 | ./pre-inst-env guix build gnew --keep-failed | |
281 | @end example | |
282 | ||
c04052e4 LC |
283 | Wenn Sie @code{--keep-failed} benutzen, ist es leichter, fehlgeschlagene |
284 | Erstellungen zu untersuchen, weil dann der Verzeichnisbaum der | |
285 | fehlgeschlagenen Erstellung zugänglich bleibt. Eine andere nützliche | |
286 | Befehlszeilenoption bei der Fehlersuche ist @code{--log-file}, womit das | |
287 | Erstellungsprotokoll eingesehen werden kann. | |
61ce2e77 | 288 | |
c04052e4 LC |
289 | Wenn der @command{guix}-Befehl das Paket nicht erkennt, kann es daran |
290 | liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine | |
291 | @code{define-public}-Klausel fehlt, die die Paketvariable exportiert. Um das | |
292 | herauszufinden, können Sie das Modul aus Guile heraus laden, um mehr | |
293 | Informationen über den tatsächlichen Fehler zu bekommen: | |
61ce2e77 JL |
294 | |
295 | @example | |
296 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' | |
297 | @end example | |
298 | ||
c04052e4 LC |
299 | Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte |
300 | einen Patch (siehe @ref{Einreichen von Patches}). Wenn Sie dabei Hilfe brauchen | |
301 | sollten, helfen wir gerne. Ab dem Zeitpunkt, zu dem der Patch als Commit ins | |
302 | Guix-Repository eingepflegt wurde, wird das neue Paket automatisch durch | |
303 | @url{http://hydra.gnu.org/jobset/gnu/master, unser System zur | |
304 | Kontinuierlichen Integration} auf allen unterstützten Plattformen erstellt. | |
61ce2e77 | 305 | |
c04052e4 LC |
306 | @cindex Substituierer |
307 | Benutzern steht die neue Paketdefinition zur Verfügung, nachdem sie das | |
308 | 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 | |
309 | Paket zu erstellen, werden bei der Installation automatisch Binärdateien von | |
310 | dort heruntergeladen (siehe @ref{Substitute}). Menschliches Eingreifen muss | |
311 | nur stattfinden, um den Patch zu überprüfen und anzuwenden. | |
61ce2e77 JL |
312 | |
313 | ||
314 | @menu | |
315 | * Software-Freiheit:: Was in die Distribution aufgenommen werden | |
316 | darf. | |
317 | * Paketbenennung:: Was macht einen Namen aus? | |
318 | * Versionsnummern:: Wenn der Name noch nicht genug ist. | |
319 | * Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige | |
320 | Paket zu finden. | |
321 | * Python-Module:: Ein Touch britischer Comedy. | |
322 | * Perl-Module:: Kleine Perlen. | |
323 | * Java-Pakete:: Kaffeepause. | |
324 | * Schriftarten:: Schriften verschriftlicht. | |
325 | @end menu | |
326 | ||
327 | @node Software-Freiheit | |
328 | @subsection Software-Freiheit | |
329 | ||
330 | @c =========================================================================== | |
331 | @c | |
332 | @c This file was generated with po4a. Translate the source file. | |
333 | @c | |
334 | @c =========================================================================== | |
335 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. | |
c04052e4 LC |
336 | @cindex freie Software |
337 | Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der | |
338 | Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist @dfn{freie Software}, was | |
339 | bedeutet, dass Benutzer die | |
340 | @url{http://www.gnu.org/philosophy/free-sw.de.html,vier wesentlichen | |
341 | Freiheiten} haben: das Programm auszuführen, es zu untersuchen, das Programm | |
342 | in Form seines Quellcodes anzupassen und exakte Kopien ebenso wie | |
343 | modifizierte Versionen davon an andere weiterzugeben. Die Pakete, die Sie in | |
344 | der GNU-Distribution finden, stellen ausschließlich solche Software zur | |
345 | Verfügung, die Ihnen diese vier Freiheiten gewährt. | |
346 | ||
347 | Außerdem befolgt die GNU-Distribution die | |
348 | @url{http://www.gnu.org/distros/free-system-distribution-guidelines.de.html,Richtlinien | |
349 | für freie Systemverteilungen}. Unter anderem werden unfreie Firmware sowie | |
350 | Empfehlungen von unfreier Software abgelehnt und Möglichkeiten zum Umgang | |
351 | mit Markenzeichen und Patenten werden diskutiert. | |
352 | ||
353 | Ansonsten freier Paketquellcode von manchen Anbietern enthält einen kleinen | |
354 | und optionalen Teil, der diese Richtlinien verletzt. Zum Beispiel kann | |
355 | dieser Teil selbst unfreier Code sein. Wenn das vorkommt, wird der sie | |
356 | verletzende Teil mit angemessenen Patches oder Code-Schnipseln innerhalb der | |
357 | @code{origin}-Form des Pakets entfernt (siehe @ref{Pakete definieren}). Dadurch liefert Ihnen @code{guix build --source} nur den | |
358 | »befreiten« Quellcode und nicht den unmodifizierten Quellcode des Anbieters. | |
61ce2e77 JL |
359 | |
360 | ||
361 | @node Paketbenennung | |
362 | @subsection Paketbenennung | |
363 | ||
c04052e4 LC |
364 | @cindex Paketname |
365 | Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es | |
366 | den Namen der @emph{Scheme-Variablen}, der direkt nach @code{define-public} | |
367 | im Code steht. Mit diesem Namen kann das Paket im Scheme-Code nutzbar | |
368 | gemacht und zum Beispiel als Eingabe eines anderen Pakets benannt | |
369 | werden. Zum anderen gibt es die Zeichenkette im @code{name}-Feld einer | |
370 | Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie | |
371 | @command{guix package} und @command{guix build} benutzt. | |
61ce2e77 | 372 | |
c04052e4 LC |
373 | Meistens sind die beiden identisch und ergeben sich aus einer Umwandlung des |
374 | vom Anbieter verwendeten Projektnamens in Kleinbuchstaben, bei der | |
375 | Unterstriche durch Bindestriche ersetzt werden. Zum Beispiel wird GNUnet | |
376 | unter dem Paketnamen @code{gnunet} angeboten und SDL_net als @code{sdl-net}. | |
61ce2e77 | 377 | |
c04052e4 LC |
378 | An Bibliothekspakete hängen wir vorne kein @code{lib} als Präfix an, solange |
379 | es nicht Teil des offiziellen Projektnamens ist. Beachten Sie aber die | |
380 | Abschnitte @ref{Python-Module} und @ref{Perl-Module}, in denen | |
381 | Sonderregeln für Module der Programmiersprachen Python und Perl beschrieben | |
382 | sind. | |
61ce2e77 | 383 | |
c04052e4 | 384 | Auch Pakete mit Schriftarten werden anders behandelt, siehe @ref{Schriftarten}. |
61ce2e77 JL |
385 | |
386 | ||
387 | @node Versionsnummern | |
388 | @subsection Versionsnummern | |
389 | ||
c04052e4 LC |
390 | @cindex Paketversion |
391 | Normalerweise stellen wir nur für die neueste Version eines | |
392 | Freie-Software-Projekts ein Paket bereit. Manchmal gibt es allerdings Fälle | |
393 | wie zum Beispiel untereinander inkompatible Bibliotheksversionen, so dass | |
394 | zwei (oder mehr) Versionen desselben Pakets angeboten werden müssen. In | |
395 | diesem Fall müssen wir verschiedene Scheme-Variablennamen benutzen. Wir | |
396 | benutzen dann für die neueste Version den Namen, wie er im Abschnitt | |
397 | @ref{Paketbenennung} festgelegt wird, und geben vorherigen Versionen | |
398 | denselben Namen mit einem zusätzlichen Suffix aus @code{-} gefolgt vom | |
399 | kürzesten Präfix der Versionsnummer, mit dem noch immer zwei Versionen | |
400 | unterschieden werden können. | |
401 | ||
402 | Der Name innerhalb der Paketdefinition ist hingegen derselbe für alle | |
403 | Versionen eines Pakets und enthält keine Versionsnummer. | |
61ce2e77 JL |
404 | |
405 | Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie | |
406 | folgt geschrieben werden: | |
407 | ||
408 | @example | |
409 | (define-public gtk+ | |
410 | (package | |
411 | (name "gtk+") | |
412 | (version "3.9.12") | |
413 | ...)) | |
414 | (define-public gtk+-2 | |
415 | (package | |
416 | (name "gtk+") | |
417 | (version "2.24.20") | |
418 | ...)) | |
419 | @end example | |
420 | Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als | |
421 | @example | |
422 | (define-public gtk+-3.8 | |
423 | (package | |
424 | (name "gtk+") | |
425 | (version "3.8.2") | |
426 | ...)) | |
427 | @end example | |
428 | ||
429 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, | |
430 | @c for a discussion of what follows. | |
c04052e4 LC |
431 | @cindex Versionsnummer, bei Snapshots aus Versionskontrolle |
432 | Gelegentlich fügen wir auch Pakete für Snapshots aus dem | |
433 | Versionskontrollsystem des Anbieters statt formaler Veröffentlichungen zur | |
434 | Distribution hinzu. Das sollte die Ausnahme bleiben, weil die Entwickler | |
435 | selbst klarstellen sollten, welche Version als die stabile Veröffentlichung | |
436 | gelten sollte, ab und zu ist es jedoch notwendig. Was also sollten wir dann | |
437 | im @code{version}-Feld eintragen? | |
438 | ||
439 | Offensichtlich muss der Bezeichner des Commits, den wir als Snapshot aus dem | |
440 | Versionskontrollsystem nehmen, in der Versionszeichenkette zu erkennen sein, | |
441 | aber wir müssen auch sicherstellen, dass die Version monoton steigend ist, | |
442 | damit @command{guix package --upgrade} feststellen kann, welche Version die | |
443 | neuere ist. Weil Commit-Bezeichner, insbesondere bei Git, nicht monoton | |
444 | steigen, müssen wir eine Revisionsnummer hinzufügen, die wir jedes Mal | |
445 | erhöhen, wenn wir das Paket auf einen neueren Snapshot aktualisieren. Die | |
446 | sich ergebende Versionszeichenkette sieht dann so aus: | |
61ce2e77 JL |
447 | |
448 | @example | |
449 | 2.0.11-3.cabba9e | |
450 | ^ ^ ^ | |
c04052e4 | 451 | | | `-- Commit-ID beim Anbieter |
61ce2e77 | 452 | | | |
c04052e4 | 453 | | `--- Revisionsnummer des Guix-Pakets |
61ce2e77 | 454 | | |
c04052e4 | 455 | die neueste Version, die der Anbieter veröffentlicht hat |
61ce2e77 JL |
456 | @end example |
457 | ||
c04052e4 LC |
458 | Es ist eine gute Idee, die Commit-Bezeichner im @code{version}-Feld auf, |
459 | sagen wir, 7 Ziffern zu beschränken. Das sieht besser aus (angenommen, das | |
460 | sollte hier eine Rolle spielen) und vermeidet Probleme, die mit der | |
461 | maximalen Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Am | |
462 | besten benutzt man jedoch den vollständigen Commit-Bezeichner in | |
463 | @code{origin}s, um Mehrdeutigkeiten zu vermeiden. Eine typische | |
464 | Paketdefinition könnte so aussehen: | |
61ce2e77 JL |
465 | |
466 | @example | |
c04052e4 | 467 | (define mein-paket |
61ce2e77 | 468 | (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") |
c04052e4 | 469 | (revision "1")) ;Guix-Paketrevision |
61ce2e77 JL |
470 | (package |
471 | (version (git-version "0.9" revision commit)) | |
472 | (source (origin | |
473 | (method git-fetch) | |
474 | (uri (git-reference | |
c04052e4 | 475 | (url "git://example.org/mein-paket.git") |
61ce2e77 JL |
476 | (commit commit))) |
477 | (sha256 (base32 "1mbikn@dots{}")) | |
478 | (file-name (git-file-name name version)))) | |
479 | ;; @dots{} | |
480 | ))) | |
481 | @end example | |
482 | ||
483 | @node Zusammenfassungen und Beschreibungen | |
484 | @subsection Zusammenfassungen und Beschreibungen | |
485 | ||
c04052e4 LC |
486 | @cindex Paketbeschreibung |
487 | @cindex Paketzusammenfassung | |
488 | Wie wir bereits gesehen haben, enthält jedes Paket in GNU@tie{}Guix eine (im | |
489 | Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine | |
490 | Beschreibung (englisch: Description; siehe @ref{Pakete definieren}). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden | |
491 | mit @command{guix package --search} durchsucht und stellen eine | |
492 | entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob | |
493 | das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler Acht | |
494 | geben, was sie dort eintragen. | |
495 | ||
496 | Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht | |
497 | mit einem Punkt enden. Sie dürfen nicht mit den Artikeln »a« oder »the« | |
498 | beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum | |
499 | Beispiel sollte »File-frobbing tool« gegenüber »A tool that frobs files« | |
500 | vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim | |
501 | Paket handelt — z.B.@: »Core GNU utilities (file, text, shell)« —, oder | |
502 | aussagen, wofür es benutzt wird — z.B.@: ist die Zusammenfassung für | |
503 | GNU@tie{}grep »Print lines matching a pattern«. | |
504 | ||
505 | Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen | |
506 | Sinn ergeben muss. Zum Beispiel würde »Manipulate alignments in the SAM | |
507 | format« vielleicht von einem erfahrenen Forscher in der Bioinformatik | |
508 | verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig | |
509 | hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es | |
510 | ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine | |
511 | Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier | |
512 | würden sich die Nutzer mit »Manipulate nucleotide sequence alignments« | |
513 | hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach | |
514 | sie suchen. | |
515 | ||
516 | Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie | |
517 | vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor | |
518 | eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie »world-leading« | |
519 | (»weltweit führend«), »industrial-strength« (»industrietauglich«) und | |
520 | »next-generation« (»der nächsten Generation«) ebenso wie Superlative wie | |
521 | »the most advanced« (»das fortgeschrittenste«) — davon haben Nutzer nichts, | |
522 | wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen | |
523 | Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und | |
524 | Funktionalitäten zu erwähnen. | |
525 | ||
526 | @cindex Texinfo-Auszeichnungen, in Paketbeschreibungen | |
527 | Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das | |
528 | bedeutet, Text kann Verzierungen wie @code{@@code} oder @code{@@dfn}, | |
529 | Auflistungen oder Hyperlinks enthalten (siehe @ref{Overview,,, texinfo, GNU | |
530 | Texinfo}). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte | |
531 | Zeichen wie @samp{@@} und geschweifte Klammern schreiben, weil es sich dabei | |
532 | um die grundlegenden Sonderzeichen in Texinfo handelt (siehe @ref{Special | |
533 | Characters,,, texinfo, GNU Texinfo}). Benutzungsschnittstellen wie | |
534 | @command{guix package --show} kümmern sich darum, solche Auszeichnungen | |
535 | angemessen darzustellen. | |
536 | ||
537 | Zusammenfassungen und Beschreibungen werden von Freiwilligen | |
538 | @uref{http://translationproject.org/domain/guix-packages.html, beim | |
539 | Translation Project} übersetzt, damit so viele Nutzer wie möglich sie in | |
540 | ihrer Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie | |
541 | in der von der aktuell eingestellten Locale festgelegten Sprache durchsucht | |
542 | und angezeigt werden. | |
543 | ||
544 | Damit @command{xgettext} sie als übersetzbare Zeichenketten extrahieren | |
545 | kann, @emph{müssen} Zusammenfassungen und Beschreibungen einfache | |
546 | Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten | |
547 | nicht mit Prozeduren wie @code{string-append} oder @code{format} | |
548 | konstruieren können: | |
61ce2e77 JL |
549 | |
550 | @lisp | |
551 | (package | |
552 | ;; @dots{} | |
553 | (synopsis "This is translatable") | |
554 | (description (string-append "This is " "*not*" " translatable."))) | |
555 | @end lisp | |
556 | ||
c04052e4 LC |
557 | Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso |
558 | mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren, | |
559 | weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den | |
560 | Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese | |
561 | sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel | |
562 | einfügen (siehe @ref{xgettext Invocation,,, gettext, GNU Gettext}): | |
61ce2e77 JL |
563 | |
564 | @example | |
565 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. | |
566 | (description "ARandR is designed to provide a simple visual front end | |
567 | for the X11 resize-and-rotate (RandR) extension. @dots{}") | |
568 | @end example | |
569 | ||
570 | ||
571 | @node Python-Module | |
572 | @subsection Python-Module | |
573 | ||
574 | @cindex python | |
c04052e4 LC |
575 | Zur Zeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils |
576 | über die Scheme-Variablen mit den Namen @code{python-2} und @code{python} | |
577 | zur Verfügung, entsprechend der Erklärungen im Abschnitt @ref{Versionsnummern}. Um Verwirrungen und Namenskollisionen mit anderen | |
578 | Programmiersprachen zu vermeiden, erscheint es als wünschenswert, dass der | |
579 | Name eines Pakets für ein Python-Modul auch das Wort @code{python} enthält. | |
580 | ||
581 | Manche Module sind nur mit einer Version von Python kompatibel, andere mit | |
582 | beiden. Wenn das Paket Foo nur mit Python 3 kompiliert werden kann, geben | |
583 | wir ihm den Namen @code{python-foo}, wenn es nur mit Python 2 kompilierbar | |
584 | ist, wählen wir den Namen @code{python2-foo}. Ist es mit beiden Versionen | |
585 | kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen. | |
586 | ||
587 | Wenn ein Projekt bereits das Wort @code{python} im Namen hat, lassen wir es | |
588 | weg; zum Beispiel ist das Modul python-dateutil unter den Namen | |
589 | @code{python-dateutil} und @code{python2-dateutil} verfügbar. Wenn der | |
590 | Projektname mit @code{py} beginnt (z.B.@: @code{pytz}), behalten wir ihn bei | |
591 | und stellen das oben beschriebene Präfix voran. | |
592 | ||
593 | @subsubsection Abhängigkeiten angeben | |
594 | @cindex Eingaben, für Python-Pakete | |
595 | ||
596 | Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und | |
597 | mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des | |
598 | Paketquellcodes: in der Datei @file{setup.py}, in @file{requirements.txt} | |
599 | oder in @file{tox.ini}. | |
600 | ||
601 | Wenn Sie ein Rezept für ein Python-Paket schreiben, lautet Ihr Auftrag, | |
602 | diese Abhängigkeiten auf angemessene Arten von »Eingaben« abzubilden (siehe | |
603 | @ref{»package«-Referenz, inputs}). Obwohl der @code{pypi}-Importer hier | |
604 | normalerweise eine gute Arbeit leistet (siehe @ref{Aufruf von guix import}), | |
605 | könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo | |
606 | welche Abhängigkeit eingeordnet werden sollte. | |
61ce2e77 JL |
607 | |
608 | @itemize | |
609 | ||
610 | @item | |
c04052e4 LC |
611 | Derzeit ist unser Python-2-Paket so geschrieben, dass es @code{setuptools} |
612 | und @code{pip} installiert, wie es auch in den Vorgaben zu Python 3.4 | |
613 | gemacht wird. Sie müssen also keines der beiden als Eingabe angeben. Wenn | |
614 | Sie es doch tun, wird @command{guix lint} Sie darauf mit einer Warnung | |
615 | aufmerksam machen. | |
61ce2e77 JL |
616 | |
617 | @item | |
c04052e4 LC |
618 | Python-Abhängigkeiten, die zur Laufzeit gebraucht werden, stehen im |
619 | @code{propagated-inputs}-Feld. Solche werden typischerweise mit dem | |
620 | Schlüsselwort @code{install_requires} in @file{setup.py} oder in der Datei | |
621 | @file{requirements.txt} definiert. | |
61ce2e77 JL |
622 | |
623 | @item | |
c04052e4 LC |
624 | Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B.@: jene, |
625 | die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py} | |
626 | aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in | |
627 | @code{tests_require} —, stehen in @code{native-inputs}. Die Begründung ist, | |
628 | dass (1) sie nicht propagiert werden müssen, weil sie zur Laufzeit nicht | |
629 | gebraucht werden, und (2) wir beim Cross-Kompilieren die »native« Eingabe | |
630 | des Wirtssystems wollen. | |
631 | ||
632 | Beispiele sind die Testrahmen @code{pytest}, @code{mock} und | |
633 | @code{nose}. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit | |
634 | benötigt wird, muss es doch in @code{propagated-inputs} stehen. | |
61ce2e77 JL |
635 | |
636 | @item | |
c04052e4 LC |
637 | Alles, was nicht in die bisher genannten Kategorien fällt, steht in |
638 | @code{inputs}, zum Beispiel Programme oder C-Bibliotheken, die zur | |
639 | Erstellung von Python-Paketen mit enthaltenen C-Erweiterungen gebraucht | |
640 | werden. | |
61ce2e77 JL |
641 | |
642 | @item | |
c04052e4 LC |
643 | Wenn ein Python-Paket optionale Abhängigkeiten hat (@code{extras_require}), |
644 | ist es Ihnen überlassen, sie hinzuzufügen oder nicht hinzuzufügen, je | |
645 | nachdem wie es um deren Verhältnis von Nützlichkeit zu anderen Nachteilen | |
646 | steht (siehe @ref{Einreichen von Patches, @command{guix size}}). | |
61ce2e77 JL |
647 | |
648 | @end itemize | |
649 | ||
650 | ||
651 | @node Perl-Module | |
652 | @subsection Perl-Module | |
653 | ||
654 | @cindex perl | |
c04052e4 LC |
655 | Eigenständige Perl-Programme bekommen einen Namen wie jedes andere Paket, |
656 | unter Nutzung des Namens beim Anbieter in Kleinbuchstaben. Für Perl-Pakete, | |
657 | die eine einzelne Klasse enthalten, ersetzen wir alle Vorkommen von | |
658 | @code{::} durch Striche und hängen davor das Präfix @code{perl-} an. Die | |
659 | Klasse @code{XML::Parser} wird also zu @code{perl-xml-parser}. Module, die | |
660 | mehrere Klassen beinhalten, behalten ihren Namen beim Anbieter, in | |
661 | Kleinbuchstaben gesetzt, und auch an sie wird vorne das Präfix @code{perl-} | |
662 | angehängt. Es gibt die Tendenz, solche Module mit dem Wort @code{perl} | |
663 | irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes | |
664 | weggelassen. Zum Beispiel wird aus @code{libwww-perl} bei uns | |
665 | @code{perl-libwww}. | |
61ce2e77 JL |
666 | |
667 | ||
668 | @node Java-Pakete | |
669 | @subsection Java-Pakete | |
670 | ||
671 | @cindex java | |
c04052e4 LC |
672 | Eigenständige Java-Programme werden wie jedes andere Paket benannt, d.h.@: |
673 | mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter. | |
674 | ||
675 | Um Verwirrungen und Namenskollisionen mit anderen Programmiersprachen zu | |
676 | vermeiden, ist es wünschenswert, dass dem Namem eines Pakets zu einem | |
677 | Java-Paket das Präfix @code{java-} vorangestellt wird. Wenn ein Projekt | |
678 | bereits das Wort @code{java} im Namen trägt, lassen wir es weg; zum Beispiel | |
679 | befindet sich das Java-Paket @code{ngsjava} in einem Paket namens | |
61ce2e77 JL |
680 | @code{java-ngs}. |
681 | ||
c04052e4 LC |
682 | Bei Java-Paketen, die eine einzelne Klasse oder eine kleine |
683 | Klassenhierarchie enthalten, benutzen wir den Klassennamen in | |
684 | Kleinbuchstaben und ersetzen dabei alle Vorkommen von @code{.} durch Striche | |
685 | und setzen das Präfix @code{java-} davor. Die Klasse | |
686 | @code{apache.commons.cli} wird also zum Paket | |
687 | @code{java-apache-commons-cli}. | |
61ce2e77 JL |
688 | |
689 | ||
690 | @node Schriftarten | |
691 | @subsection Schriftarten | |
692 | ||
693 | @cindex Schriftarten | |
c04052e4 LC |
694 | Wenn Schriftarten in der Regel nicht von Nutzern zur Textbearbeitung |
695 | installiert werden oder als Teil eines größeren Software-Pakets mitgeliefert | |
696 | werden, gelten dafür die allgemeinen Paketrichtlinien für Software. Zum | |
697 | Beispiel trifft das auf als Teil des X.Org-Systems ausgelieferte | |
698 | Schriftarten zu, oder auf Schriftarten, die ein Teil von TeX Live sind. | |
699 | ||
700 | Damit es Nutzer leichter haben, nach Schriftarten zu suchen, konstruieren | |
701 | wir die Namen von anderen Paketen, die nur Schriftarten enthalten, nach dem | |
702 | folgenden Schema, egal was der Paketname beim Anbieter ist. | |
703 | ||
704 | Der Name eines Pakets, das nur eine Schriftfamilie enthält, beginnt mit | |
705 | @code{font-}. Darauf folgt der Name des Schriftenherstellers und ein Strich | |
706 | @code{-}, sofern bekannt ist, wer der Schriftenhersteller ist, und dann der | |
707 | Name der Schriftfamilie, in dem Leerzeichen durch Striche ersetzt werden | |
708 | (und wie immer mit Großbuchstaben statt Kleinbuchstaben). Zum Beispiel | |
709 | befindet sich die von SIL hergestellte Gentium-Schriftfamilie im Paket mit | |
710 | dem Namen @code{font-sil-gentium}. | |
711 | ||
712 | Wenn ein Paket mehrere Schriftfamilien enthält, wird der Name der Sammlung | |
713 | anstelle des Schriftfamiliennamens benutzt. Zum Beispiel umfassen die | |
714 | Liberation-Schriftarten drei Familien: Liberation Sans, Liberation Serif und | |
715 | Liberation Mono. Man könnte sie getrennt voneinander mit den Namen | |
716 | @code{font-liberation-sans} und so weiter in Pakete einteilen, da sie aber | |
717 | unter einem gemeinsamen Namen angeboten werden, packen wir sie lieber | |
718 | zusammen in ein Paket mit dem Namen @code{font-liberation}. | |
719 | ||
720 | Für den Fall, dass mehrere Formate derselben Schriftfamilie oder | |
721 | Schriftartensammlung in separate Pakete kommen, wird ein Kurzname für das | |
722 | Format mit einem Strich vorne zum Paketnamen hinzugefügt. Wir benutzen | |
723 | @code{-ttf} für TrueType-Schriftarten, @code{-otf} für OpenType-Schriftarten | |
724 | und @code{-type1} für PostScript-Typ-1-Schriftarten. | |
61ce2e77 JL |
725 | |
726 | ||
1e40e70b JL |
727 | @node Code-Stil |
728 | @section Code-Stil | |
729 | ||
c04052e4 | 730 | Im Allgemeinen folgt unser Code den GNU Coding Standards (siehe @ref{Top,,, |
1e40e70b JL |
731 | standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu |
732 | sagen haben, folgen hier einige zusätzliche Regeln. | |
733 | ||
734 | @menu | |
735 | * Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen. | |
736 | * Module:: Wo Sie Ihren Code unterbringen. | |
737 | * Datentypen und Mustervergleich:: Implementierung von Datenstrukturen. | |
738 | * Formatierung von Code:: Schreibkonventionen. | |
739 | @end menu | |
740 | ||
741 | @node Programmierparadigmen | |
742 | @subsection Programmierparadigmen | |
743 | ||
744 | Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine | |
745 | Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die | |
746 | grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur | |
747 | @code{memoize}. | |
748 | ||
749 | @node Module | |
750 | @subsection Module | |
751 | ||
752 | Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum | |
753 | @code{(guix build @dots{})} leben. Sie dürfen auf keine anderen Guix- oder | |
793dcd8c | 754 | GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges« |
1e40e70b JL |
755 | Modul ein erstellungsseitiges Modul benutzt. |
756 | ||
757 | Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum | |
758 | @code{(gnu @dots{})} und nicht in @code{(guix @dots{})} stehen. | |
759 | ||
760 | @node Datentypen und Mustervergleich | |
761 | @subsection Datentypen und Mustervergleich | |
762 | ||
763 | Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu | |
764 | benutzen, und diese dann »händisch« zu durchlaufen mit @code{car}, | |
765 | @code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen | |
766 | Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu | |
767 | lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern | |
768 | ist. | |
769 | ||
770 | Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit | |
771 | @code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er | |
772 | das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen, | |
773 | besonders mit Listen. | |
774 | ||
775 | @node Formatierung von Code | |
776 | @subsection Formatierung von Code | |
777 | ||
778 | @cindex Formatierung von Code | |
779 | @cindex Code-Stil | |
780 | Beim Schreiben von Scheme-Code halten wir uns an die üblichen | |
781 | Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das, | |
782 | dass wir uns an @url{http://mumble.net/~campbell/scheme/style.txt, | |
783 | Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses | |
784 | Dokument auch die Konventionen beschreibt, die im Code von Guile | |
785 | hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben, | |
786 | also lesen Sie es bitte. | |
787 | ||
788 | Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das | |
789 | @code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese | |
790 | sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch | |
791 | benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens | |
792 | @code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und | |
c04052e4 | 793 | hervorhebt (siehe @ref{Entwicklung,,, emacs-guix, The Emacs-Guix Reference |
1e40e70b JL |
794 | Manual}). |
795 | ||
796 | @cindex Einrückung, Code- | |
797 | @cindex Formatierung, Code- | |
798 | Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor | |
799 | diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können | |
800 | Sie auch Folgendes ausführen: | |
801 | ||
802 | @example | |
803 | ./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket} | |
804 | @end example | |
805 | ||
806 | @noindent | |
807 | Dadurch wird die Definition von @var{Paket} in | |
808 | @file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im | |
809 | Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen, | |
810 | lassen Sie das zweite Argument weg: | |
811 | ||
812 | @example | |
813 | ./etc/indent-code.el gnu/services/@var{Datei}.scm | |
814 | @end example | |
815 | ||
816 | @cindex Vim, zum Editieren von Scheme-Code | |
793dcd8c | 817 | Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set |
1e40e70b JL |
818 | autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während |
819 | Sie ihn schreiben. Außerdem könnte Ihnen | |
820 | @uref{https://www.vim.org/scripts/script.php?script_id=3998, | |
821 | @code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden. | |
822 | ||
823 | Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen | |
824 | Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten | |
825 | Prozeduren im Namensraum @code{(guix build @dots{})} aufgeweicht werden. | |
826 | ||
827 | Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter | |
828 | haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als | |
829 | vier Parameter entgegennehmen. | |
830 | ||
831 | ||
832 | @node Einreichen von Patches | |
833 | @section Einreichen von Patches | |
834 | ||
835 | Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git | |
836 | durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht | |
837 | unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die | |
838 | mittels @code{git format-patch} erstellt und an die Mailingliste | |
839 | @email{guix-patches@@gnu.org} geschickt werden. | |
840 | ||
841 | Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist | |
842 | unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick | |
843 | über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete | |
844 | Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine | |
845 | Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden | |
c04052e4 | 846 | kann, wobei @var{NNN} für die Folgenummer steht (siehe @ref{Senden einer Patch-Reihe}). |
1e40e70b | 847 | |
c04052e4 LC |
848 | Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe @ref{Change |
849 | Logs,,, standards, GNU Coding Standards}); dazu finden Sie Beispiele unter | |
850 | den bisherigen Commits. | |
1e40e70b JL |
851 | |
852 | Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder | |
793dcd8c | 853 | verändert, gehen Sie bitte diese Prüfliste durch: |
1e40e70b JL |
854 | |
855 | @enumerate | |
856 | @item | |
c04052e4 LC |
857 | Wenn die Autoren der verpackten Software eine kryptografische Signatur |
858 | bzw. Beglaubigung für den Tarball der Veröffentlichung anbieten, so machen | |
859 | Sie sich bitte die Mühe, die Echtheit des Archivs zu überprüfen. Für eine | |
860 | abgetrennte GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg | |
861 | --verify} tun. | |
1e40e70b JL |
862 | |
863 | @item | |
864 | Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für | |
c04052e4 | 865 | das Paket zu verfassen. Unter @ref{Zusammenfassungen und Beschreibungen} finden Sie |
1e40e70b JL |
866 | dazu einige Richtlinien. |
867 | ||
868 | @item | |
869 | Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder | |
c04052e4 LC |
870 | geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe |
871 | @ref{Aufruf von guix lint}). | |
1e40e70b JL |
872 | |
873 | @item | |
874 | Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, | |
875 | indem Sie @code{guix build @var{Paket}} ausführen. | |
876 | ||
61ce2e77 | 877 | @item |
c04052e4 LC |
878 | Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten |
879 | Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware | |
880 | für diese Plattformen haben, empfehlen wir, den | |
881 | @code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu | |
882 | aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste | |
883 | (»services«) in Ihrer @code{operating-system}-Konfiguration ein: | |
61ce2e77 JL |
884 | |
885 | @example | |
886 | (service qemu-binfmt-service-type | |
887 | (qemu-binfmt-configuration | |
c04052e4 | 888 | (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) |
61ce2e77 JL |
889 | (guix-support? #t))) |
890 | @end example | |
891 | ||
c04052e4 | 892 | Rekonfigurieren Sie anschließend Ihr System. |
61ce2e77 | 893 | |
c04052e4 LC |
894 | Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die |
895 | Befehlszeilenoption @code{--system} angeben. Um zum Beispiel das Paket | |
896 | »hello« für die Architekturen armhf, aarch64 oder mips64 erstellen zu | |
897 | lassen, würden Sie jeweils die folgenden Befehle angeben: | |
61ce2e77 JL |
898 | @example |
899 | guix build --system=armhf-linux --rounds=2 hello | |
900 | guix build --system=aarch64-linux --rounds=2 hello | |
61ce2e77 JL |
901 | guix build --system=mips64el-linux --rounds=2 hello |
902 | @end example | |
903 | ||
1e40e70b JL |
904 | @item |
905 | @cindex gebündelt | |
906 | Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird, | |
907 | die bereits in separaten Paketen zur Verfügung steht. | |
908 | ||
909 | Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um | |
910 | Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir | |
793dcd8c | 911 | jedoch sicherstellen, dass solche Pakete die schon in der Distribution |
1e40e70b JL |
912 | verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der |
913 | Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt | |
914 | und gespeichert) als auch der Distribution die Möglichkeit gegeben, | |
915 | ergänzende Änderungen durchzuführen, um beispielsweise | |
916 | Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort | |
793dcd8c LC |
917 | einzuspielen, die aber das gesamte System betreffen — gebündelt |
918 | mitgelieferte Kopien würden dies verhindern. | |
1e40e70b JL |
919 | |
920 | @item | |
c04052e4 LC |
921 | Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe |
922 | @ref{Aufruf von guix size}). Dadurch können Sie Referenzen auf andere Pakete | |
923 | finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu | |
924 | entscheiden, ob das Paket aufgespalten werden sollte (siehe @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet | |
925 | werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere | |
926 | vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie | |
927 | stattdessen @code{texlive-tiny} oder @code{texlive-union}. | |
1e40e70b JL |
928 | |
929 | @item | |
930 | Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls | |
931 | vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh | |
c04052e4 | 932 | --list-dependent @var{Paket}} hilft Ihnen dabei (siehe @ref{Aufruf von guix refresh}). |
1e40e70b | 933 | |
1e40e70b JL |
934 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. |
935 | @cindex Branching-Strategie | |
936 | @cindex Neuerstellungs-Zeitplan | |
937 | Je nachdem, wieviele abhängige Pakete es gibt, und entsprechend wieviele | |
938 | Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches | |
939 | statt, nach ungefähr diesen Regeln: | |
940 | ||
941 | @table @asis | |
942 | @item 300 abhängige Pakete oder weniger | |
943 | @code{master}-Branch (störfreie Änderungen). | |
944 | ||
945 | @item zwischen 300 und 1200 abhängige Pakete | |
946 | @code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle | |
c04052e4 LC |
947 | 3 Wochen mit @code{master} zusammengeführt. Themenbezogene Änderungen |
948 | (z.B.@: eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf | |
949 | einem eigenen Branch umgesetzt werden (wie @code{gnome-updates}). | |
1e40e70b JL |
950 | |
951 | @item mehr als 1200 abhängige Pakete | |
952 | @code{core-updates}-Branch (kann auch größere und womöglich andere Software | |
953 | beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in | |
954 | @code{master} alle 2,5 Monate oder so gemerget. | |
955 | @end table | |
956 | ||
61ce2e77 JL |
957 | All diese Branches werden kontinuierlich |
958 | @uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} erstellt | |
959 | und in @code{master} gemerget, sobald alles erfolgreich erstellt worden | |
960 | ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, | |
961 | und zudem das Zeitfenster, während dessen noch keine vorerstellten | |
962 | Binärdateien verfügbar sind, verkürzen. | |
1e40e70b JL |
963 | |
964 | @c TODO: It would be good with badges on the website that tracks these | |
965 | @c branches. Or maybe even a status page. | |
61ce2e77 JL |
966 | Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich} |
967 | angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender | |
968 | @code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder | |
969 | IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden | |
970 | sollte. | |
1e40e70b JL |
971 | |
972 | @item | |
973 | @cindex Determinismus, von Erstellungsprozessen | |
974 | @cindex Reproduzierbare Erstellungen, Überprüfung | |
975 | Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen | |
976 | Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe | |
977 | Ergebnis wie Ihre Erstellung hat, Bit für Bit. | |
978 | ||
979 | Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male | |
c04052e4 | 980 | hintereinander auf Ihrer Maschine erstellen (siehe @ref{Aufruf von guix build}): |
1e40e70b JL |
981 | |
982 | @example | |
983 | guix build --rounds=2 mein-paket | |
984 | @end example | |
985 | ||
986 | Dies reicht aus, um eine ganze Klasse häufiger Ursachen von | |
987 | Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder | |
988 | zufallsgenerierte Ausgaben im Ergebnis der Erstellung. | |
989 | ||
c04052e4 LC |
990 | 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 |
991 | commitet und von @code{@value{SUBSTITUTE-SERVER}} erstellt wurde, um zu | |
992 | sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser: | |
993 | Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen | |
994 | Sie @command{guix publish} aus. Da sich die entfernte Erstellungsmaschine | |
995 | wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme | |
996 | durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum | |
997 | Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem | |
998 | Betriebssystem-Kernel — zum Beispiel, indem @code{uname} oder | |
999 | @file{/proc}-Dateien verwendet werden. | |
1e40e70b JL |
1000 | |
1001 | @item | |
1002 | Beim Schreiben von Dokumentation achten Sie bitte auf eine | |
1003 | geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie | |
1004 | @uref{https://en.wikipedia.org/wiki/Singular_they, »they«@comma{} | |
c04052e4 | 1005 | »their«@comma{} »them« im Singular} und so weiter. |
1e40e70b JL |
1006 | |
1007 | @item | |
1008 | Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger | |
1009 | Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen | |
1010 | erschwert und bremst das Durchsehen Ihres Patches. | |
1011 | ||
1012 | Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer | |
1013 | Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version | |
1014 | zusammen mit Fehlerbehebungen für das Paket. | |
1015 | ||
1016 | @item | |
1017 | Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich | |
1018 | wollen Sie dies automatisch tun lassen durch das Skript | |
c04052e4 | 1019 | @command{etc/indent-code.el} (siehe @ref{Formatierung von Code}). |
1e40e70b JL |
1020 | |
1021 | @item | |
c04052e4 LC |
1022 | Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe |
1023 | @ref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine | |
61ce2e77 JL |
1024 | automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer |
1025 | identisch von einer Generation auf die nächste, daher ist es in diesem Fall | |
1026 | besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie | |
1027 | @emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht | |
1028 | wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr. | |
1e40e70b JL |
1029 | |
1030 | @end enumerate | |
1031 | ||
1032 | Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch | |
793dcd8c | 1033 | an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den |
c04052e4 | 1034 | Befehl @command{git send-email} benutzen (siehe @ref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten, |
1e40e70b JL |
1035 | entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu |
1036 | angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie | |
1037 | Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich | |
1038 | nicht mehr funktionieren. | |
1039 | ||
1040 | Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem | |
793dcd8c | 1041 | Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden. |
1e40e70b JL |
1042 | |
1043 | @unnumberedsubsec Senden einer Patch-Reihe | |
1044 | @anchor{Senden einer Patch-Reihe} | |
1045 | @cindex Patch-Reihe | |
1046 | @cindex @code{git send-email} | |
1047 | @cindex @code{git-send-email} | |
1048 | ||
1049 | @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html | |
c04052e4 LC |
1050 | Wenn Sie eine Patch-Reihe senden (z.B.@: mit @code{git send-email}), |
1051 | schicken Sie bitte als Erstes eine Nachricht an | |
1052 | @email{guix-patches@@gnu.org} und dann nachfolgende Patches an | |
1053 | @email{@var{NNN}@@debbugs.gnu.org}, um sicherzustellen, dass sie zusammen | |
1054 | bearbeitet werden. Siehe @uref{https://debbugs.gnu.org/Advanced.html, die | |
1055 | Debbugs-Dokumentation} für weitere Informationen. |