1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
---
title: Kapitel 3. Einen neuen Port erstellen
prev: books/porters-handbook/own-port
next: books/porters-handbook/slow
showBookMenu: true
weight: 3
path: "/books/porters-handbook/"
---
[[quick-porting]]
= Einen neuen Port erstellen
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 3
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/
ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]
ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
Dieser Abschnitt beschreibt, wie Sie schnell einen neuen Port erstellen können. In vielen Fällen ist dies allerdings nicht ausreichend, dann werden Sie in diesem Buch weiterlesen müssen.
Als Erstes besorgen Sie sich das Original-Tarball (komprimiertes Archiv) und legen es im `DISTDIR` ab, welches standardmäßig [.filename]#/usr/ports/distfiles# ist.
[NOTE]
====
Im Folgenden wird angenommen, dass die Software unverändert kompiliert werden konnte, dass also keinerlei Änderungen nötig waren, um den Port auf Ihrem FreeBSD-Rechner zum Laufen zu bringen. Falls Sie Änderungen vornehmen mussten, werden Sie auch den nächsten Abschnitt beachten müssen.
====
[[porting-makefile]]
== Das Makefile schreiben
Ein minimales [.filename]#Makefile# sieht in etwa so aus:
[.programlisting]
....
# New ports collection makefile for: oneko
# Date created: 5 December 1994
# Whom: asami
#
# $FreeBSD$
#
PORTNAME= oneko
PORTVERSION= 1.1b
CATEGORIES= games
MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
MAINTAINER= asami@FreeBSD.org
COMMENT= A cat chasing a mouse all over the screen
MAN1= oneko.1
MANCOMPRESSED= yes
USE_IMAKE= yes
.include <bsd.port.mk>
....
Versuchen Sie es zu verstehen. Machen Sie sich keine Gedanken um die `$FreeBSD$`-Zeile, diese wird automatisch vom CVS eingefügt, wenn der Port in den Haupt-Ports-Tree importiert wird. Ein detailliertes Beispiel finden Sie im Abschnitt <<porting-samplem,sample Makefile>>.
[[porting-desc]]
== Die Beschreibungsdateien erstellen
Es gibt zwei Beschreibungsdateien, die für jeden Port benötigt werden, ob sie tatsächlich im Paket enthalten sind oder nicht. Dies sind [.filename]#pkg-descr# und [.filename]#pkg-plist#. Der [.filename]#pkg-# Präfix unterscheidet sie von anderen Dateien.
=== [.filename]#pkg-descr#
Diese enthält eine längere Beschreibung des Ports. Einer oder mehrere Absätze, die kurz und prägnant erklären, was der Port macht, sind ausreichend.
[NOTE]
====
[.filename]#pkg-descr# enthält __keine__ Anleitung oder detaillierte Beschreibung wie der Port benutzt oder kompiliert wird! __Bitte seien Sie vorsichtig, wenn Sie aus dem [.filename]#README# oder der Manualpage kopieren__; Diese sind oft keine prägnanten Beschreibungen des Ports oder sie sind in einem ungünstigen Format (Manualpages haben z.B. bündige Zwischenräume). Wenn es für die portierte Software eine offizielle Webseite gibt, sollten Sie diese hier angeben. Fügen Sie hierzu _eine_ der Webseiten mit dem Präfix `WWW:` ein, damit automatische Werkzeuge korrekt arbeiten.
====
Das folgende Beispiel zeigt wie Ihre [.filename]#pkg-descr# aussehen sollte:
[.programlisting]
....
This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
:
(etc.)
WWW: http://www.oneko.org/
....
=== [.filename]#pkg-plist#
Diese Datei enthält eine Liste aller Dateien, die von diesem Port installiert werden. Sie wird auch die "Packliste" genannt, da das Paket durch die hier aufgeführten Dateien erstellt wird. Die Pfadangaben sind relativ zum Installationspräfix (für gewöhnlich [.filename]#/usr/local# oder [.filename]#/usr/X11R6#). Wenn Sie die `MAN__n__`-Variablen verwenden (was Sie auch machen sollten), führen Sie hier keine Manualpages auf. Wenn der Port während der Installation Verzeichnisse erstellt, stellen Sie sicher entsprechende `@dirrm`-Zeilen einzufügen, um die Verzeichnisse zu entfernen, wenn das Paket gelöscht wird.
Hier ist ein kleines Beispiel:
[.programlisting]
....
bin/oneko
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/oneko
....
Für weitere Details zur Packliste lesen Sie in der man:pkg_create[1] Manualpage nach.
[NOTE]
====
Es wird empfohlen alle Dateinamen in dieser Datei alphabetisch sortiert zu halten. Das erlaubt Ihnen die Änderungen bei einem Upgrade Ihres Ports deutlich einfacher zu Überprüfen.
====
[NOTE]
====
Eine Packlist von Hand zu erzeugen kann eine sehr mühsame Aufgabe sein. Wenn der Port eine große Anzahl Dateien installiert, kann es Zeit sparen, <<plist-autoplist,eine Packliste automatisch zu erstellen>>.
====
Es gibt nur einen Fall, in dem [.filename]#pkg-plist# weggelassen werden kann. Wenn der Port nur eine handvoll Dateien und Verzeichnisse installiert, können diese in den Variablen `PLIST_FILES` und `PLIST_DIRS` im [.filename]#Makefile# aufgelistet werden. Zum Beispiel könnten wir im obigen Beispiel ohne [.filename]#pkg-plist# für den [.filename]#oneko#-Port auskommen, indem wir die folgenden Zeilen ins [.filename]#Makefile# einfügen:
[.programlisting]
....
PLIST_FILES= bin/oneko \
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
lib/X11/oneko/mouse.xpm
PLIST_DIRS= lib/X11/oneko
....
Natürlich sollte `PLIST_DIRS` ungesetzt bleiben, wenn der Port keine eigenen Verzeichnisse installiert.
Der Preis für diese Art die Dateien eines Ports anzugeben ist, dass man keine Befehlsfolgen wie in man:pkg_create[1] nutzen kann. Deshalb ist es nur für einfache Ports geeignet und macht diese noch einfacher. Gleichzeitig bringt es den Vorteil die Anzahl der Dateien in der Ports-Sammlung zu reduzieren. Deshalb ziehen Sie bitte diese Vorgehensweise in Erwägung, bevor Sie [.filename]#pkg-plist# benutzen.
Später werden wir uns ansehen, wie [.filename]#pkg-plist# und `PLIST_FILES` benutzt werden können, um <<plist,anspruchsvollere Aufgaben>> zu erfüllen.
[[porting-checksum]]
== Die Checksummendatei erzeugen
Geben Sie einfach `make makesum` ein. Die Regeln von Make sorgen dafür, dass die Datei [.filename]#distinfo# automatisch erstellt wird.
Wenn sich die Checksumme einer heruntergeladenen Datei regelmäßig ändert und Sie sicher sind, dass Sie der Quelle trauen können (weil sie z.B. von einer Hersteller-CD oder täglich erstellter Dokumentation stammt), sollten Sie diese Dateien in der Variable `IGNOREFILES` angeben. Dann wird die Checksumme für diese Datei bei `make makesum` nicht berechnet, sondern auf `IGNORE` gesetzt.
[[porting-testing]]
== Den Port testen
Sie sollten sicherstellen, dass die Port-Regeln genau das einhalten, was Sie von ihnen erwarten, auch beim Erzeugen eines Pakets aus dem Port. Dies sind die wichtigen Punkte, die Sie überprüfen sollten.
* [.filename]#pkg-plist# enthält nichts, das nicht von Ihrem Port installiert wurde.
* [.filename]#pkg-plist# enthält alles, was von Ihrem Port installiert wurde.
* Ihr Port kann mit Hilfe von `make reinstall` mehrmals installiert werden.
* Ihr Port <<plist-cleaning,räumt>> bei der Deinstallation hinter sich auf.
[.procedure]
====
*Procedure: Empfohlene Testreihenfolge*
. `make install`
. `make package`
. `make deinstall`
. `pkg_add Paket-Name`
. `make deinstall`
. `make reinstall`
. `make package`
====
Stellen Sie bitte sicher, dass während `make package` und `make deinstall` keine Warnungen ausgegeben werden. Nach Schritt 3 überprüfen Sie bitte, ob alle neuen Verzeichnisse korrekt entfernt wurden. Und versuchen Sie die Software nach Schritt 4 zu benutzen, um sicherzustellen, dass sie korrekt funktioniert, wenn diese aus einem Paket installiert wird.
Der gründlichste Weg diese Schritte zu automatisieren ist eine Tinderbox zu installieren. Diese verwaltet `Jails`, in denen Sie alle oben genannten Schritte durchführen können, ohne den Zustand Ihres laufenden Systems zu verändern. Mehr Informationen hierzu entält [.filename]#ports/ports-mgmt/tinderbox#
[[porting-portlint]]
== Ihren Port mit `portlint` überprüfen
Bitte verwenden Sie `portlint`, um festzustellen, ob Ihr Port unseren Richtlinien entspricht. Das Programm package:ports-mgmt/portlint[] ist Teil der Ports-Sammlung. Stellen Sie vor allem sicher, dass das <<porting-samplem,Makefile>> in der richtigen Form und das <<porting-pkgname,Paket>> passend benannt ist.
[[porting-submitting]]
== Den neuen Port einreichen
Bevor Sie den neuen Port einreichen, lesen Sie bitte unbedingt den Abschnitt <<porting-dads,DOs and DON'Ts>>.
Nun, da Sie mit Ihrem Port zufrieden sind, müssen Sie ihn nur noch in den Haupt-Ports-Tree von FreeBSD einbringen, damit alle daran teilhaben können. Wir benötigen nicht Ihr [.filename]#work#-Verzeichnis oder Ihr [.filename]#pkgname.tgz#-Paket - diese können Sie nun löschen. Wenn Ihr Port beispielsweise `oneko` heißt, wechseln Sie in das Verzeichnis, in dem sich das Verzeichnis `oneko` befindet und führen den Befehl `shar find oneko > oneko.shar` aus.
Fügen Sie Ihre Datei `oneko.shar` einem Fehlerbericht an und senden Sie diesen mit Hilfe des Programms man:send-pr[1] (unter extref:{contributing}[ Bug Reports and General Commentary, CONTRIB-GENERAL] finden Sie weitere Informationen über man:send-pr[1]). Ordnen Sie den Fehlerbericht bitte in die Kategorie `Ports` mit der Klasse `Change-Request` ein (Markieren Sie den Bericht nicht als `vertraulich` (`confidential`)!). Fügen Sie bitte eine kurze Beschreibung des Programms, das Sie portiert haben, in das "Beschreibungs"-Feld des Problemberichts und die shar-Datei in das "Fix"-Feld ein (bespielsweise eine kurze Version des `COMMENT`).
[NOTE]
====
Sie können uns die Arbeit um einiges vereinfachen, wenn Sie eine gute Beschreibung in der Zusammenfassung des Problemberichtes verwenden. Wir bevorzugen etwas wie "Neuer Port: <Kategorie>/<Portname><Kurzbeschreibung des Ports>" für neue Ports. Wenn Sie sich an dieses Schema halten, ist die Chance, dass sich jemand bald Ihren Bericht ansieht, deutlich besser.
====
Noch einmal: _Bitte fügen Sie nicht das distfile der Originalquelle, das [.filename]#work#-Verzeichnis oder das Paket, das Sie mit `make package` erstellt haben, ein._ Und verwenden Sie man:shar[1] für neue Ports (und NICHT man:diff[1]).
Haben Sie bitte etwas Geduld, nachdem Sie den Port eingereicht haben. Manchmal kann es einige Monate dauern, bevor ein Port in FreeBSD eingefügt wird, obwohl es wahrscheinlich nur ein paar Tage dauert. Sie können sich die http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports[ Liste der PRs, die darauf warten, in FreeBSD committet zu werden], ansehen.
Nachdem wir einen Blick auf Ihren Port geworfen haben, werden wir, wenn nötig, bei Ihnen nachfragen und ihn in die Ports-Sammlung übernehmen. Ihr Name taucht dann auch in der Liste der extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] und in anderen Dateien auf. Ist das nicht toll?! :-)
|
