Inhaltsverzeichnis
debian/rules
debian/control
debian/changelog
debconf
.orig.tar.{gz,bz2,xz}
-Dateien
Debian's quality is largely due to the Debian Policy, which defines explicit baseline requirements that all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very talented people have created great tools, tools which help you, the Debian maintainer, create and maintain excellent packages.
Dieses Kapitel stellt einige optimale Vorgehensweisen für Debian-Entwickler vor. Das alles sind lediglich Empfehlungen und keine Anforderungen oder feste Regeln. Es sind nur subjektive Hinweise, Ratschläge und Fingerzeige, die von Debian-Entwicklern gesammelt wurden. Suchen Sie sich einfach das heraus, was Ihnen am meisten zusagt.
The following recommendations apply to the debian/rules
file. Since debian/rules
controls the build process
and selects the files that go into the package (directly or indirectly),
it's usually the file maintainers spend the most time on.
Der Grund für die Benutzung von Helferskripten in
debian/rules
ist, dass sie den Betreuern eine
gemeinsame allgemeine Logik inmitten vieler Pakete ermöglichen. Nehmen Sie
zum Beispiel die Frage, wie Menü-Einträge installiert werden: Sie müssen die
Datei in /usr/share/menu
(oder
/usr/lib/menu
für ausführbare binäre Menü-Dateien, wenn
nötig) ablegen und den Betreuerskripten Befehle hinzufügen, um Menü-Einträge
zu registrieren bzw. ihre Registrierung zu entfernen. Dies ist eine sehr
häufige Tätigkeit für Pakete. Warum sollte daher jeder Betreuer all dies für
sich selbst neu schreiben und dabei möglicherweise Fehler verursachen?
Außerdem, gesetzt den Fall, das Menü-Verzeichnis würde sich ändern, müsste
dann jedes Paket geändert werden.
Helferskripte kümmern sich um diese Probleme. Angenommen, Sie erfüllen alle Gepflogenheiten, die das Helferskript erwartet, dann kümmert sich das Helferskript um alle Einzelheiten. Änderungen an den Richtlinien können im Helferskript erledigt werden. Dann müssen Pakete nur mit der neuen Version des Helferskripts erstellt und sonst nicht geändert werden.
Anhang A, Überblick über die Werkzeuge der Debian-Betreuer enthält ein paar verschiedene Helferskripte. Das
gängigste und beste Helfersystem (nach Meinung von Debian) ist debhelper
. Frühere Helfersysteme wie debmake
waren monolithisch. Man konnte nicht
einen Teil des Helferskripts herausgreifen und verwenden, den man nützlich
fand, sondern musste den Helfer für alles benutzen. debhelper
besteht jedoch aus mehreren getrennten
kleinen dh_*-Programmen. dh_installman
installiert und komprimiert zum Beispiel Handbuchseiten,
dh_installmenu installiert Menü-Dateien und so
weiter. Daher bietet es eine ausreichende Flexibilität, die kleinen
Helferskripte dort zu benutzen, wo sie nützlich sind, in Verbindung mit
handgemachten Befehlen in debian/rules
.
Sie können mit debhelper
beginnen,
indem Sie debhelper(1) lesen und sich die Beispiele
ansehen, die dem Paket beigefügt sind. dh_make aus dem
Paket dh-make
(siehe Abschnitt A.3.2, „dh-make
“) kann benutzt werden, um ein einfaches Quellpaket in ein
mit debhelper
bearbeitetes Paket
umzuwandeln. Gleichwohl sollte diese Kurzform Sie jedoch nicht davon
überzeugen, dass Sie sich nicht plagen müssen, um die einzelnen
dh_*-Helfer zu verstehen. Falls Sie einen Helfer benutzen
möchten, müssen Sie sich die Zeit nehmen zu lernen, wie dieser Helfer
benutzt wird, um zu verstehen, was er erwartet und wie er sich verhält.
Große, komplexe Pakete könnten mehrere Fehler haben, die Sie bewältigen
müssen. Falls Sie mehrere Fehler direkt im Quellcode beheben und nicht
sorgfältig vorgehen, kann es schwierig werden, die verschiedenen Patches,
die Sie bereitgestellt haben, zu unterscheiden. Es kann ziemlich chaotisch
werden, wenn Sie das Paket auf eine neue Originalversion aktualisieren
müssen, die einige (aber nicht alle) Korrekturen enthält. Sie können nicht
die komplette Zusammenstellung der Diffs nehmen (z.B. aus
.diff.gz
) und austüfteln, welcher Patch es als Einheit
zurücksetzt, da Fehler im Original behoben wurden.
Fortunately, with the source format “3.0 (quilt)” it is now possible to keep
patches separate without having to modify debian/rules
to set up a patch system. Patches are stored in
debian/patches/
and when the source package is unpacked
patches listed in debian/patches/series
are
automatically applied. As the name implies, patches can be managed with
quilt.
Wenn Sie den älteren Quellcode »1.0« verwenden, ist es auch möglich, Patches
zu trennen, aber es muss ein zugehöriges Patch-System verwandt werden: Die
Patch-Dateien werden innerhalb der Debian-Patch-Datei
(.diff.gz
) mitgeliefert, normalerweise im Verzeichnis
debian/
. Der einzige Unterschied ist, dass sie nicht
unmittelbar von dpkg-source angewandt werden, sondern von
der build
-Regel der Datei
debian/rules
durch eine Abhängigkeit in der
patch
-Regel. Im Gegenzug werden sie von der Regel
clean
durch eine Abhängigkeit zur Regel
unpatch
umgekehrt.
quilt is the recommended tool for this. It does all of
the above, and also allows one to manage patch series. See the quilt
package for more information.
Es gibt noch andere Werkzeuge, um Patches zu verwalten, wie
dpatch und das in cdbs
eingebaute Patch-System.
Ein einzelnes Quellpaket wird oft mehrere Binärpakete erstellen, entweder um
mehrere Geschmacksrichtungen der gleichen Software bereitzustellen (wie beim
vim
-Quellpaket) oder um mehrere
kleine Pakete anstelle eines einzelnen großen zu erzeugen (z.B. damit der
Benutzer nur die benötigte Untermenge installieren kann und dadurch
Plattenplatz spart).
Der zweite Fall kann einfach in debian/rules
verwaltet
werden. Sie müssen nur die entsprechenden Dateien aus dem Build-Verzeichnis
in die entsprechenden temporären Baumstrukturen des Pakets verschieben. Dies
können Sie mit install oder dh_install
aus debhelper
erledigen. Sorgen Sie
dafür, dass Sie die unterschiedlichen Umsetzungen der verschiedenen Pakete
prüfen, um sicherzustellen, dass Sie die wechselseitigen Abhängigkeiten in
debian/control
richtig gesetzt haben.
The first case is a bit more difficult since it involves multiple recompiles
of the same software but with different configuration options. The
vim
source package is an example of
how to manage this using a hand-crafted debian/rules
file.
Die folgenden Vorgehensweisen sind maßgeblich für die Datei
debian/control
. Sie ergänzen die Richtlinien für
Paketbeschreibungen.
Die Beschreibung des Pakets, wie es durch das entsprechende Feld in der
Datei control
definiert wird, enthält sowohl die
Paketübersicht als auch die ausführliche Beschreibung des Pakets. Abschnitt 6.2.1, „Allgemeine Leitlinien für Paketbeschreibungen“ beschreibt übliche Richtlinien für beide Teile
der Paketbeschreibung. Diesen folgend stellt Abschnitt 6.2.2, „Die Paketübersicht oder Kurzbeschreibung“ Richtlinien speziell für die Übersicht bereit
und Abschnitt 6.2.3, „Die ausführliche Beschreibung“ enthält spezielle Richtlinien für die
Beschreibung.
Die Paketbeschreibung sollte für den erwarteten Durchschnittsanwender geschrieben werden, der Durchschnittsperson, die das Paket benutzt und davon profitiert. Entwicklungspakete sind beispielsweise für Entwickler und können in einer technischen Sprache verfasst werden. Anwendungen für allgemeinere Zwecke, wie Editoren, sollten für Anwender mit weniger technischem Verständnis geschrieben werden.
Die Durchsicht der Paketbeschreibungen mündet in der Schlussfolgerung, dass die meisten Paketbeschreibungen technischer Natur sind, also nicht so geschrieben, dass sie für Anwender ohne technischen Hintergrund einen Sinn ergeben. Sofern Ihr Paket nicht wirklich für technikkundige Anwender gedacht ist, ist dies ein Problem.
Wie können sie für nicht technikkundige Anwender schreiben? Vermeiden Sie Fachsprache. Vermeiden Sie, sich auf Anwendungen und Rahmenwerke zu beziehen, mit denen der Anwender möglicherweise nicht vertraut ist – GNOME oder KDE sind in Ordnung, da Anwender wahrscheinlich mit diesen Begriffen vertraut sind, aber GTK+ vermutlich nicht. Versuchen Sie nicht irgendein Wissen vorauszusetzen, geben Sie eine Einführung.
Seien Sie objektiv. Paketbeschreibungen sind nicht der richtige Ort, um Ihr Paket zu verfechten, egal wie sehr Sie es mögen. Denken Sie daran, dass der Leser nicht die gleichen Dinge wichtig nimmt, wie Sie.
Bezüge zu Namen anderer Softwarepakete, Protokollnamen, Standards oder Spezifikationen sollten, falls sie existiert, in ihrer vorschriftsmäßigen Form verwandt werden. Benutzen Sie zum Beispiel X Window System, X11 oder X, nicht X Windows, X-Windows, or X Window. Benutzen Sie GTK+, nicht GTK oder gtk. Benutzen Sie GNOME, nicht Gnome. Benutzen Sie PostScript, nicht Postscript oder postscript.
Falls Sie Probleme beim Verfassen Ihrer Beschreibung haben, könnten Sie sie
an <debian-l10n-english@lists.debian.org>
senden und um Rückmeldung ersuchen.
Die Richtlinie legt fest, dass die Übersichtszeile (die Kurzbeschreibung) kurz sein muss, den Paketnamen nicht wiederholen darf, aber trotzdem informativ sein muss.
Die Übersichtsfunktionen sind ein Ausdruck, der das Paket beschreibt, kein kompletter Satz, daher ist Zeichensetzung unangebracht: Es wird weder eine besondere Großschreibung noch ein abschließender Punkt benötigt. Außerdem sollten jegliche bestimmten und unbestimmten Artikel am Anfang weggelassen werden – »a«, »an« oder »the«. Deshalb zum Beispiel:
Package: libeg0 Description: exemplification support library
Technisch gesehen ist dies eine Nominalphrase im Gegensatz zu einer
Verbalphrase. Eine gute Entscheidungsregel ist, dass es möglich sein sollte,
den Paket-Namen
und die
Übersicht
in diesem Schema zu ersetzen:
Das Paket Name
stellt {ein,eine,den,einige}
Übersicht
zur Verfügung.
Zusammenstellungen verwandter Pakete können ein alternatives Schema benutzen, das die Übersicht in zwei Teile unterteilt, als erstes eine Beschreibung der ganzen Suite und als zweites eine Zusammenfassung der Rolle, die das Paket darin spielt:
Package: eg-tools Description: simple exemplification system (utilities) Package: eg-doc Description: simple exemplification system - documentation
Diese Übersicht folgt einem geänderten Schema. Wo ein Paket
»Name
« die Übersicht
»Suite
(Rolle
)« oder
»Suite
- Rolle
« hat,
sollten die Elemente so ausgedrückt werden, dass sie in dieses Schema
passen:
Das Paket Name
stellt {ein,eine,die}
Rolle
für die Suite
zur Verfügung.
Die ausführliche Beschreibung ist die wichtigste für den Benutzer verfügbare Information über ein Paket, bevor er es installiert. Sie sollte alle nötigen Informationen bereitstellen, damit der Anwender entscheiden kann, ob er das Paket installieren möchte. Es ist anzunehmen, dass der Benutzer bereits die Paketübersicht gelesen hat.
Die ausführliche Beschreibung sollte aus vollständigen Sätzen bestehen.
Der erste Absatz der ausführlichen Beschreibung sollte die folgenden Fragen beantworten: Was tut das Paket? Bei welchen Aufgaben hilft es dem Anwender? Es ist wichtig, dies auf eine nicht technische Weise zu beschreiben, sogar dann, wenn die Zielgruppe des Pakets notwendigerweise einen technischen Hintergrund hat.
The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?
Seien Sie vorsichtig, um Rechtschreib- und Grammatikfehler zu
vermeiden. Sorgen Sie für eine Rechtschreibprüfung. Sowohl
ispell als auch aspell haben spezielle
Modi zur Prüfung von debian/control
-Dateien:
ispell -d american -g debian/control
aspell -d en -D -c debian/control
Anwender erwarten normalerweise, dass diese Fragen in der Paketbeschreibung beantwortet werden:
Was tut das Paket? Falls es eine Erweiterung eines anderen Pakets ist, dann sollte eines Kurzbeschreibung des Pakets, das es erweitert, hier eingefügt werden.
Warum sollte ich dieses Paket wollen? Dies bezieht sich auf das vorhergehende, aber nicht das gleiche (dies ist ein Mail-Client. Er ist toll, schnell, hat Schnittstellen zu PGP, LDAP und IMAP, hat die Funktionen X, Y und Z).
Falls dieses Paket nicht direkt installiert werden sollte, sondern von einem anderen Paket mitinstalliert wird, sollte dies erwähnt werden.
Falls das Paket experimental
ist oder es andere Gründe
gibt, weshalb es nicht benutzt werden sollte und wenn es andere Pakete gibt,
die stattdessen benutzt werden sollen, sollte dies auch hier stehen.
How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?
Es wird empfohlen, dass Sie die URL der Homepage des Pakets in das Feld
Homepage
im Abschnitt Source
von
debian/control
hinzufügen. Diese Information in die
Paketbeschreibung selbst einzutragen, wird als missbilligt angesehen.
Es gibt zusätzliche Felder für den Ort des Versionsverwaltungssystems in
debian/control
.
Der Wert dieses Feldes sollte eine http://
-URL sein, die
auf eine via Web zu durchsuchende Kopie des Versionsverwaltungssystem-Depots
verweist, das benutzt wird, um das angegebene Paket zu verwalten, falls
verfügbar.
Die Information ist dazu gedacht, dem Endanwender zu nutzen, der gewillt
ist, die letzte am Paket geleistete Arbeit zu durchstöbern (z.B. wenn nach
einem Patch gesucht wird, der einen Fehler behebt, der in der
Fehlerdatenbank als pending
gekennzeichnet ist).
Value of this field should be a string identifying unequivocally the
location of the Version Control System repository used to maintain the given
package, if available. *
identifies the Version Control
System; currently the following systems are supported by the package
tracking system: arch
, bzr
(Bazaar),
cvs
, darcs
, git
,
hg
(Mercurial), mtn
(Monotone),
svn
(Subversion). It is allowed to specify different VCS
fields for the same package: they will all be shown in the PTS web
interface.
Die Information ist für Benutzer bestimmt, die im gegebenen Versionsverwaltungssystem sachkundig sind und bereit, die aktuelle Version des Pakets aus den VCS-Quellen zu erstellen. Andere Nutzungen dieser Information könnten das automatische Erstellen der letzen VCS-Version des Pakets umfassen. Dazu sollte der vom Feld angegebene Ort versionsunabhängig sein und auf den Hauptzweig (main branch) zeigen (bei Versionsverwaltungssystemen, die dieses Konzept unterstützen). Außerdem sollte der Endanwender auf den Ort, auf den verwiesen wird, zugreifen können. Die Erfüllung dieser Anforderungen könnte einen anonymen Zugriff voraussetzen, statt auf eine Version mit SSH-Zugriff zu verweisen.
Im folgenden Beispiel sehen Sie ein Beispiel von einem Feld eines
Subversion-Depots des Pakets vim
. Beachten Sie, wie die URL im
svn://
-Schema aufgebaut ist (im Gegensatz zu
svn+ssh://
) und wie sie auf den Zweig
trunk/
zeigt. Außerdem wird ebenfalls die Benutzung der
Felder Vcs-Browser
und Homepage
, wie
oben beschrieben, gezeigt.
Source: vim Section: editors Priority: optional <snip> Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim Homepage: http://www.vim.org
Die folgenden Vorgehensweisen ergänzen die Richtlinien für Änderungsprotokolldateien.
Der Änderungsprotokolleintrag einer Paketüberarbeitung (Changelog) dokumentiert Änderungen in nur dieser Überarbeitung. Der Schwerpunkt liegt auf der Beschreibung bedeutender und für den Anwender sichtbarer Änderungen, die seit der letzten Version vorgenommen wurden.
Der Fokus liegt darauf, was geändert wurde – wer, wie und wann ist normalerweise nicht so wichtig. Erinnern Sie gleichwohl höflich an die Leute, die merklich Hilfe beim Erstellen des Pakets geleistet haben (die z.B. Patches gesandt haben).
Es ist nicht nötig, belanglose und offensichtliche Änderungen näher
auszuführen. Sie können außerdem mehrere Änderungen in einem Eintrag
zusammenfassen. Fassen Sie sich andererseits nicht zu kurz, falls Sie eine
größere Änderung vorgenommen haben. Stellen Sie insbesondere klar, falls es
Änderungen gibt, die das Verhalten des Programms ändern. Benutzen Sie für
weitere Erklärungen die Datei README.Debian
.
Benutzen Sie geläufiges Englisch, so dass die Mehrheit der Leser es begreifen kann. Vermeiden Sie Abkürzungen, technische Begriffe und Fachsprache, wenn Sie Änderungen erklären, die Fehlerberichte schließen, insbesondere bei Fehlern, die von Anwendern eingereicht wurden, die Ihnen als technisch unerfahren aufgefallen sind. Seien Sie höflich, fluchen Sie nicht.
Manchmal ist es wünschenswert, den Änderungsprotokolleinträgen die Namen der Dateien voranzustellen, die geändert wurden. Es ist jedoch nicht nötig, explizit jede einzelne geänderte Datei aufzuführen, insbesondere dann nicht, wenn die Änderung klein oder wiederholend war. Sie können Platzhalter verwenden.
Treffen Sie keine Annahmen, wenn Sie sich auf Fehler beziehen. Sagen Sie, welches Problem vorlag, wie es behoben wurde und hängen Sie die Zeichenkette »closes: #nnnnn« an. Weitere Informationen erhalten Sie unter Abschnitt 5.8.4, „Wann Fehler durch neue Uploads geschlossen werden“.
The release team have indicated that they expect most uploads to
unstable
to use urgency=medium. That is, you should choose
urgency=medium unless there is some
particular reason for the upload to migrate to testing
more quickly or slowly (see Abschnitt 5.13.2, „Aktualisierungen von Unstable“). For
example, you might select urgency=low if
the changes since the last upload are large and might be disruptive in
unanticipated ways.
Die Änderungsprotokolleinträge sollten keine allgemeinen Paketierungsthemen dokumentieren (Hey, falls Sie die Foo.conf suchen, die ist in /etc/blah/.), da von Administratoren und Anwendern angenommen wird, dass sie zumindest entfernt damit vertraut sind, wie solche Dinge im Allgemeinen auf Debian-Systemen eingerichtet sind. Erwähnen Sie jedoch, wenn Sie den Ort einer Konfigurationsdatei ändern.
Die einzigen Fehler, die mit einem Änderungsprotokolleintrag geschlossen werden, sollten Fehler sein, die tatsächlich in der gleichen Überarbeitung des Pakets behoben werden. Das Schließen von Fehlern ohne Bezug dazu, ist eine falsche Vorgehensweise. Siehe Abschnitt 5.8.4, „Wann Fehler durch neue Uploads geschlossen werden“.
Die Änderungsprotokolleinträge sollten nicht für zufällige Diskussionen mit Leuten, die Fehler melden (Ich kann keine Schutzverletzungen sehen, wenn ich Foo mit der Option Bar starte. Senden Sie weitere Informationen.), allgemeine Äußerungen über das Leben, das Universum und alles mögliche (Entschuldigung, dass der Upload so lange brauchte, aber ich hatte die Grippe.) oder Hilfeersuchen (Die Fehlerliste für dieses Paket ist riesig, bitte packen Sie mit an) benutzt werden. Solche Dinge werden normalerweise nicht von Ihrer Zielgruppe bemerkt, könnten aber viele Leute stören, die Informationen über tatsächliche Änderungen am Paket lesen möchten. Weitere Informationen über die Benutzung der Fehlerdatenbank finden Sie unter Abschnitt 5.8.2, „Auf Fehler antworten“.
Es ist ein alter Brauch, im ersten regulären Upload des Paketbetreuers das Beheben von Fehlern durch Non-Maintainer-Uploads zu bestätigen. Da Debian nun über eine Versionsverwaltung verfügt, reicht es aus, die NMU-Änderungsprotokolleinträge zu erhalten und diese Tatsache nur in Ihrem eigenen Änderungsprotokolleintrag zu erwähnen.
Die folgenden Beispiele demonstrieren einige häufige Fehler oder Beispiele für schlechten Stil in Änderungsprotokolleinträgen.
* Fixed all outstanding bugs.
Dies teilt den Lesern offensichtlich nichts Nützliches mit.
* Applied patch from Jane Random.
Was war das für ein Patch?
* Late night install target overhaul.
Welche Korrektur wurde ausgeführt? Soll die Erwähnung der späten Nacht daran erinnern, dass man dem Code nicht trauen sollte?
* Korrigiert vsync FU w/ historischen CRTs.
Zu viele Abkürzungen und es ist nicht klar, wovon der äh ... Mist (Hoppla, ein Schimpfwort) tatsächlich handelt oder wie er korrigiert wurde.
* This is not a bug, closes: #nnnnnn.
Erst einmal ist es absolut unnötig, das Paket hochzuladen, um diese Information zu übermitteln. Benutzen Sie stattdessen die Fehlerdatenbank. Zweitens fehlt die Erklärung, warum dieser Bericht kein Fehler ist.
* Has been fixed for ages, but I forgot to close; closes: #54321.
If for some reason you didn't mention the bug number in a previous changelog entry, there's no problem, just close the bug normally in the BTS. There's no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don't have to track bugs that they fixed ages ago in your changelog).
* Closes: #12345, #12346, #15432
Wo ist die Beschreibung? Falls Ihnen keine aussagekräftige Nachricht einfällt, beginnen Sie damit, die Titel der verschiedenen Fehler einzufügen.
Wichtige Nachrichten über Änderungen in einem Paket können auch in die
NEWS.Debian
-Dateien geschrieben werden. Die Nachrichten
werden durch Werkzeuge wie apt-listchanges
vor dem ganzen Rest des
Änderungsprotokolls angezeigt. Dies ist das bevorzugte Mittel, dem Anwender
bedeutende Änderungen in einem Paket mitzuteilen. Es ist besser, als
debconf
-Notizen zu benutzen, da es
weniger stört und der Anwender nach der Installation zurückgehen und in der
NEWS.Debian
-Datei nachschlagen kann. Es ist auch
besser, als die Hauptänderungen in README.Debian
aufzuführen, da der Anwender solche Notizen leicht übersehen kann.
Das Dateiformat entspricht dem des Änderungsprotokolls, die Sternchen werden
allerdings weggelassen und jedes Nachrichtenelement wird, wenn nötig, mit
einem vollständigen Satz beschrieben, statt der kurz gefassten
Zusammenfassungen, die in ein Änderungsprotokoll einfließen. Sie sind gut
beraten, Ihre Datei durch dpkg-parsechangelog
laufen zu
lassen, um die Formatierung zu prüfen, da sie nicht automatisch während des
Builds getestet wird, so wie dies beim Änderungsprotokoll geschieht. Hier
nun ein Beispiel einer echten NEWS.Debian
-Datei:
cron (3.0pl1-74) unstable; urgency=low The checksecurity script is no longer included with the cron package: it now has its own package, checksecurity. If you liked the functionality provided with that script, please install the new package. -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
Die Datei NEWS.Debian
wird als
/usr/share/doc/
installiert. Sie ist komprimiert und hat immer diesen Namen, auch in nativen
Debian-Paketen. Falls Sie Paket
/NEWS.Debian.gzdebhelper
benutzen, wird
dh_installchangelogs
die
debian/NEWS
-Dateien für Sie installieren.
Anders als Änderungsprotokolldateien müssen Sie die
debian/NEWS
-Dateien nicht bei jeder Veröffentlichung
aktualisieren. Aktualisieren Sie sie nur, wenn Sie etwas besonders
berichtenswertes haben, worüber der Anwender Bescheid wissen sollte. Falls
Sie überhaupt keine Nachrichten haben, ist es nicht nötig, Ihrem Paket eine
debian/NEWS
-Datei mitzugeben. Keine Nachricht ist eine
gute Nachricht!
Maintainer scripts include the files debian/postinst
,
debian/preinst
, debian/prerm
and
debian/postrm
. These scripts take care of any package
installation or deinstallation setup that isn't handled merely by the
creation or removal of files and directories. The following instructions
supplement the Debian Policy.
Betreuerskripte müssen idempotent sein. Das bedeutet, dass Sie sicherstellen müssen, dass nichts Schlimmes passiert, wenn das Skript zweimal aufgerufen wird, während es normalerweise nur einmal aufgerufen würde.
Standardein- und -ausgabe könnten zu Protokollierungszwecken umgeleitet werden (z.B. in Pipes), verlassen Sie sich daher nicht darauf, dass sie ein Terminal sind.
Jegliche Bedienerführung oder interaktive Konfiguration sollte so gering wie
möglich gehalten werden. Wenn es nötig ist, sollten Sie das Paket
debconf
für die Schnittstelle
benutzen. Denken Sie daran, dass diese Bedienerführung nur in der
configure
-Stufe des postinst
-Skripts
stattfinden kann.
Halten Sie die Betreuerskripte so einfach wie möglich. Es wird empfohlen,
nur reine POSIX-Shell-Skripte zu benutzen. Falls Sie irgendwelche
Bash-Funktionen benötigen, vergessen Sie nicht, dass das Betreuerskript eine
Shebang-Zeile haben muss. POSIX-Shell oder Bash werden für Perl bevorzugt,
da sie debhelper
ermöglichen, den
Skripten einfach Teile hinzuzufügen.
Falls Sie Ihre Betreuerskripte ändern, stellen Sie sicher, dass Sie das Entfernen des Pakets, die mehrmalige Installation und das vollständige Entfernen testen. Vergewissern Sie sich, dass nach dem vollständigen Entfernen des Pakets alles komplett gelöscht ist, sprich es muss jede Datei entfernt sein, die direkt oder indirekt in irgendeinem Betreuerskript erstellt wurde.
Falls Sie prüfen möchten, ob ein Befehl existiert, sollten Sie etwas benutzen wie:
if which install-docs > /dev/null; then ...
Sie können diese Funktion benutzen, um $PATH
nach einem
Befehlsnamen zu durchsuchen, der als Argument übergegeben wird. Sie gibt
»true« (null) zurück, falls der Befehl gefunden wurde und »false«, falls
nicht. Dies ist wirklich die am ehesten portierbare Möglichkeit, da
command -v
, type und
which nicht POSIX-konform sind.
Obwohl which eine akzeptable Alternative ist, da es aus
dem benötigten Paket debianutils
stammt, liegt es nicht auf der Wurzelpartition. Was bedeutet, es liegt eher
in /usr/bin
als in /bin
, so dass
es nicht in Skripten benutzt werden kann, die vor dem Einhängen von
/usr
ausgeführt werden. Dieses Problem werden
allerdings die meisten Skripte nicht haben.
Debconf
is a configuration
management system that can be used by all the various packaging scripts
(postinst
mainly) to request feedback from the user
concerning how to configure the package. Direct user interactions must now
be avoided in favor of debconf
interaction. This will enable non-interactive installations in the future.
Debconf ist ein großartiges Werkzeug, aber es wird oft mangelhaft benutzt. Viele alltägliche Fehler sind auf der Handbuchseite debconf-devel(7) aufgeführt. Sie sollten sie lesen, falls Sie sich entscheiden, Debconf zu benutzen. Außerdem werden hier ein paar optimale Vorgehensweisen vorgestellt.
Diese Leitlinien enthalten einige Schreibstil- und Typografie-Empfehlungen, allgemeine Betrachtungen über die Benutzung von Debconf sowie spezifischere Empfehlungen für einige Teile der Distribution (das Installationssystem besispielsweise).
Seit Debconf in Debian erschien, wurde es öfter missbraucht und viel von der Kritik, die bei der Debian-Distribution einging, rührte vom Debconf-Missbrauch her und bemängelte die Notwendigkeit, ein großes Fragenbündel beantworten zu müssen, bevor eine Kleinigkeit installiert war.
Keep usage notes to what they belong: the NEWS.Debian
,
or README.Debian
file. Only use notes for important
notes that may directly affect the package usability. Remember that notes
will always block the install until confirmed or bother the user by email.
Carefully choose the questions' priorities in maintainer scripts. See debconf-devel(7) for details about priorities. Most questions should use medium and low priorities.
Die meisten Debian-Paketbetreuer haben nicht Englisch als Muttersprache. Daher ist es für sie nicht einfach, korrekt formulierte Vorlagen zu verfassen.
Bitte benutzen (und missbrauchen) Sie die Mailingliste
<debian-l10n-english@lists.debian.org>
. Lassen Sie Ihre Vorlagen dort korrekturlesen.
Schlecht geschriebene Vorlagen werfen ein armseliges Bild auf Ihr Paket, Ihre Arbeit ... oder sogar auf Debian selbst.
Vermeiden Sie soweit möglich technische Fachsprache. Auch wenn sich einige Begriffe für Sie vertraut anhören, könnten sie für andere unverständlich sein. Falls sie sich nicht vermeiden lassen, versuchen Sie sie zu erklären (benutzen Sie die erweiterte Beschreibung). Versuchen Sie dabei, zwischen Aussagekraft und Einfachheit abzuwägen.
Debconf templates may be translated. Debconf, along with its sister package po-debconf, offers a simple framework for getting templates translated by translation teams or even individuals.
Bitte benutzen Sie Gettext-basierte Vorlagen. Installieren Sie po-debconf
auf Ihrem Entwicklungssystem und
lesen Sie dessen Dokumentation (man po-debconf ist ein
guter Anfang).
Avoid changing templates too often. Changing template text induces more
work for translators, which will get their translation fuzzied. A fuzzy
translation is a string for which the original changed since it was
translated, therefore requiring some update by a translator to be usable.
When changes are small enough, the original translation is kept in PO files
but marked as fuzzy
.
Falls Sie planen, Änderungen an Ihren Originalvorlagen vorzunehmen, benutzen
Sie bitte das Benachrichtigungssystem namens
podebconf-report-po, das vom Paket po-debconf
bereitgestellt wird, um die
Übersetzer zu kontaktieren. Die meisten aktiven Übersetzer sind sehr
zugänglich, und deren Arbeit zusammen mit Ihren geänderten Vorlagen
einzubeziehen, wird Sie vor zusätzlichen Uploads bewahren. Falls Sie
Gettext-basierte Vorlagen verwenden, werden die Namen und E-Mail-Adressen
der Übersetzer in den Kopfzeilen der PO-Dateien erwähnt und von
podebconf-report-po benutzt.
Ein empfohlene Art, das Hilfswerkzeug zu benutzen ist:
cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"
This command will first synchronize the PO and POT files in
debian/po
with the template files listed in
debian/po/POTFILES.in
. Then, it will send a call for
new translations, in the <debian-i18n@lists.debian.org>
mailing list. Finally, it will
also send a call for translation updates to the language team (mentioned in
the Language-Team
field of each PO file) as well as the
last translator (mentioned in Last-translator
).
Es wird immer gewürdigt, wenn Sie den Übersetzern einen Abgabetermin nennen, so dass diese ihre Arbeit organisieren können. Bitte denken Sie daran, dass einige Übersetzer-Teams einen formalisierten Übersetzungs-/Korrekturprozess haben und eine Zeitspanne, die kürzer als zehn Tage ist, als unangemessen angesehen wird. Eine kürzere Frist übt zuviel Druck auf die Übersetzer-Teams aus und sollte nur für sehr kleine Änderungen gewählt werden.
Im Zweifelsfall können Sie auch das Übersetzer-Team für eine bestimmte
Sprache (debian-l10n-xxxxx@lists.debian.org) oder die Mailingliste
<debian-i18n@lists.debian.org>
kontaktieren.
Wenn der Text einer Debconf-Vorlage korrigiert wurde und Sie sicher sind, dass die Änderung keine Übersetzungen beeinflusst, seien Sie so nett zu den Übersetzern, die fuzzy-Markierungen aus deren Übersetzungen zu entfernen.
Falls Sie dies nicht tun, wird die ganze Vorlage nicht übersetzt sein, bis Ihnen ein Übersetzer eine Aktualisierung zusendet.
Um die fuzzy-Markierungen aus Übersetzungen zu
entfernen, können Sie msguntypot benutzen (Teil des
Pakets po4a
).
Erzeugen Sie die POT- und PO-Dateien neu.
debconf-updatepo
Erstellen Sie eine Kopie der POT-Datei.
cp templates.pot templates.pot.orig
Erstellen Sie eine Kopie aller PO-Dateien.
mkdir po_fridge; cp *.po po_fridge
Ändern Sie die Debconf-Vorlagedateien, um den Tippfehler zu korrigieren.
Erzeugen Sie die POT- und PO-Dateien (wieder) neu.
debconf-updatepo
An dieser Stelle markiert die Korrektur des Tippfehlers alle Übersetzungen mit »fuzzy« und diese unglückliche Änderung ist die einzige zwischen den PO-Dateien Ihres Hauptverzeichnisses und denen aus fridge. Hier nun eine Erklärung, wie das gelöst wird.
Verwerfen Sie die mit »fuzzy« markierte Übersetzung und stellen Sie die aus fridge wieder her.
cp po_fridge/*.po .
Führen Sie manuell die PO-Dateien mit der neuen POT-Datei zusammen, unter Berücksichtigung/Vermeidung des nutzlosen »fuzzy«.
msguntypot -o templates.pot.orig -n templates.pot *.po
Räumen Sie auf.
rm -rf templates.pot.orig po_fridge
Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes... have no meaning for users of graphical interfaces that use checkboxes for boolean questions.
Zeichenkettenvorlagen sollten außerdem vermeiden, Vorgabewerte in ihrer Beschreibung zu erwähnen. Erstens sind diese zusätzlich zu den Werten, die der Anwender sieht, vorhanden. Außerdem könnten sich diese Werte von der Auswahl des Paketbetreuers unterscheiden (zum Beispiel, wenn die Debconf-Datenbank voreingestellt ist).
Versuchen Sie, allgemein ausgedrückt, Bezug auf Benutzeraktionen zu vermeiden. Geben Sie nur Tatsachen wieder.
You should avoid the use of first person (I will do this... or We recommend...). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if ... instead of This can be enabled if....
As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like "maintainer") whose gender is unknown. Instead, you should use the plural form (singular they).
Dieser Teil stellt einige Informationen bereit, die überwiegend von der Handbuchseite debconf-devel(7) übernommen wurden.
resultiert in einem Eingabefeld freier Form, in das der Benutzer jegliche Zeichenkette eingeben kann.
gibt dem Benutzer eine Eingabeaufforderung für ein Passwort aus. Benutzen Sie dies mit Vorsicht. Vergegenwärtigen Sie sich, dass das Passwort, das der Benutzer eingibt, in die Debconf-Datenbank geschrieben wird. Sie sollten diesen Wert möglicherweise aus der Datenbank löschen, sobald dies möglich ist.
Eine Auswahl aus mehreren Werten. Die Auswahlmöglichkeiten müssen in einem
»Choices« benannten Feld angegeben werden. Trennen Sie die möglichen Werte
mit Komma und Leerzeichen, wie hier: Choices: yes, no,
maybe
.
Falls Auswahlmöglichkeiten übersetzbare Zeichenketten sind, kann das Feld
durch Benutzung von __Choices
als übersetzbar
gekennzeichnet werden. Der doppelte Unterstrich wird jede Auswahl in eine
separate Zeichenkette heraustrennen.
Das System po-debconf bietet außerdem interessante Möglichkeiten, um nur einige Auswahlmöglichkeiten als übersetzbar zu kennzeichnen. Ein Beispiel:
Template: foo/bar Type: Select #flag:translate:3 __Choices: PAL, SECAM, Other _Description: TV standard: Please choose the TV standard used in your country.
In diesem Beispiel ist nur die Zeichenkette »Other« übersetzbar, während das andere Abkürzungen sind, die nicht übersetzt werden sollten. Obiges ermöglicht, dass nur »Other« in die POT- und PO-Dateien eingefügt wird.
Das Schaltersystem der Debconf-Vorlagen bietet viele solcher Möglichkeiten. Die Handbuchseite po-debconf(7) führt all diese Möglichkeiten auf.
Wie der Datentyp »select«, außer dass der Benutzer eine beliebige Anzahl von Elementen aus der Auswahlliste auswählen kann (oder gar keins).
Statt per se als Frage stellt dieser Datentyp einen Hinweis dar, der dem Benutzer angezeigt werden kann. Er sollte nur für wichtige Anmerkungen benutzt werden, die der Benutzer wirklich sehen sollte, weil Debconf großen Aufwand betreibt, um sicherzustellen, dass der Benutzer sie wahrnimmt; die Installation wird gestoppt, bis der Benutzer eine Taste drückt, in manchen Fällen bekommt er sogar eine Benachrichtigung per E-Mail.
This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).
Es wird empfohlen, diesen Typ für jegliche Nachricht zu verwenden, die die Aufmerksamkeit des Anwenders für irgendeine Art von Korrektur auf sich ziehen muss.
Vorlagenbeschreibungen haben zwei Teile: kurz und erweitert. Die Kurzbeschreibung steht in der Zeile »Description:« der Vorlage.
Die Kurzbeschreibung sollte knapp gehalten werden (ungefähr 50 Zeichen), so dass sie in den meisten Debconf-Schnittstellen untergebracht werden kann. Es hilft obendrein Übersetzern, wenn sie kurz gehalten wird, da Übersetzungen normalerweise dazu neigen, länger als das Original zu sein.
The short description should be able to stand on its own. Some interfaces do not show the long description by default, or only if the user explicitly asks for it or even do not show it at all. Avoid things like: "What do you want to do?"
Die Kurzbeschreibung muss nicht notwendigerweise aus einem vollständigen Satz bestehen. Dies ist Teil der Forderung nach kurzen, brauchbaren Empfehlungen.
Die erweiterte Beschreibung sollte die Kurzbeschreibung nicht Wort für Wort wiederholen. Falls Ihnen keine ausführliche Beschreibung einfällt, denken Sie zuerst etwas darüber nach. Schreiben Sie an debian-devel. Bitten Sie um Hilfe. Nehmen Sie Schreibunterricht! Diese erweiterte Beschreibung ist wichtig. Falls Sie nach allem noch immer nicht damit zurecht kommen, lassen Sie sie leer.
Die erweiterte Beschreibung sollte in ganzen Sätzen verfasst sein. Absätze sollten kurz gehalten werden, um die Leserlichkeit zu verbessern. Vermischen Sie nicht zwei Ideen in einem Absatz, sondern benutzen Sie lieber einen anderen Absatz.
Seien Sie nicht zu gesprächig. Benutzer tendieren dazu, zu ausführliche Bildschirminhalte zu ignorieren. 20 Zeilen sind erfahrungsgemäß die Grenze, die Sie nicht überschreiten sollten, da dies bedeutet, dass Anwender klassische Dialogfenster nicht scrollen müssen und viele Leute tun das einfach nicht.
Die erweiterte Beschreibung sollte keine Frage enthalten.
Um etwas über besondere Regeln zu erfahren, die vom Vorlagentyp (string, boolean etc.) abhängen, lesen Sie das Folgende.
This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.
keine besondere Angabe, außer: Benutzen Sie den geeigneten Typ bezogen auf den vorhergehenden Abschnitt.
Es folgen spezifische Anweisungen für ordnungsgemäßes Verfassen der Beschreibung (kurz und erweitert), abhängig vom Vorlagentyp.
Die Kurzbeschreibung ist eine Abfrage und kein Titel. Vermeiden Sie den Fragestil (IP-Adresse?) und geben Sie offenen Abfragen (IP-Adresse:) den Vorzug. Es wird empfohlen, Doppelpunkte zu benutzen.
Die erweiterte Beschreibung ist eine Ergänzung der Kurzbeschreibung. Im erweiterten Teil erklären Sie, was gefragt ist, anstatt die gleiche Frage in längerer Formulierung wieder zu stellen. Benutzen Sie ganze Sätze. Von knappem Schreibstil wird strikt abgeraten.
The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).
Nochmals: Bitte vermeiden Sie, sich auf Schnittstellen-spezifische Dinge zu beziehen. Ein häufiger Fehler bei solchen Vorlagen ist, auf Ja-Typ-Konstruktionen zu antworten.
The short description is a prompt and not a title. Do not use useless "Please choose..." constructions. Users are clever enough to figure out they have to choose something... :)
Die erweiterte Beschreibung wird die Kurzbeschreibung vervollständigen. Sie könnte sich auf die verfügbaren Auswahlmöglichkeiten beziehen. Sie könnte zudem erwähnen, dass der Anwender unter mehr als einer verfügbaren Auswahlmöglichkeit wählen kann, falls es sich um eine »multiselect«-Vorlage handelt.
Die Kurzbeschreibung sollte als Titel betrachtet werden.
Die erweiterte Beschreibung ist das, was als detaillierte Erklärung der Notiz angezeigt wird. Sätze, kein knapper Schreibstil.
Do not abuse debconf. Notes are the most
common way to abuse debconf. As written in the debconf-devel manual page:
it's best to use them only for warning about very serious problems. The
NEWS.Debian
or README.Debian
files
are the appropriate location for a lot of notes. If, by reading this, you
consider converting your Note type templates to entries in
NEWS.Debian
or README.Debian
,
please consider keeping existing translations for the future.
Falls sich »Choices« zu oft ändert, sollten Sie in Betracht ziehen, zum __Choices-Trick zu greifen. Dies wird jede einzelne Auswahl in eine einzelne Zeichenkette aufteilen, was Übersetzern beträchtlich bei ihrer Arbeit helfen wird.
If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick.
This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.
Ein Beispiel aus den Vorlagen des Pakets Geneweb:
Template: geneweb/lang Type: select __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) # This is the default choice. Translators may put their own language here # instead of the default. # WARNING : you MUST use the ENGLISH NAME of your language # For instance, the French translator will need to put French (fr) here. _Default: English[ translators, please see comment in PO files] _Description: Geneweb default language:
Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.
Die Kommentare werden benötigt, da der _Default-Trick etwas verwirrend ist: Die Übersetzer können ihre eigene Auswahl nehmen.
Do NOT use an empty default field. If you don't want to use default values, do not use Default at all.
If you use po-debconf (and you should; see Abschnitt 6.5.2.2, „Seien sie nett zu Übersetzern“), consider making this field translatable, if you think it may be translated.
Falls der Vorgabewert von Sprache oder Land abhängen könnte (zum Beispiel, weil es sich bei der Auswahl um eine Sprachauswahl handelt), ziehen Sie in Betracht, den Typ _Default zu benutzen, der in po-debconf(7) dokumentiert ist.
This section contains global information for developers to make translators' lives easier. More information for translators and developers interested in internationalization are available in the Internationalisation and localisation in Debian documentation.
Wie Portierer haben auch Übersetzer eine schwierige Aufgabe. Sie arbeiten an vielen Paketen und müssen mit vielen verschiedenen Paketbetreuern zusammenarbeiten, deren Muttersprache meist nicht Englisch ist. Sie sollten ihnen daher besondere Geduld entgegenbringen.
The goal of debconf
was to make
package configuration easier for maintainers and for users. Originally,
translation of debconf templates was handled with
debconf-mergetemplate. However, that technique is now
deprecated; the best way to accomplish debconf
internationalization is by using the
po-debconf
package. This method is
easier both for maintainer and translators; transition scripts are provided.
Wenn po-debconf
benutzt wird, werden
die Übersetzungen in .po
-Dateien gespeichert (mit
gettext-Übersetzungstechniken herausgezogen). Spezielle
Vorlagendateien enthalten die Originalnachrichten und markieren, welche
Felder übersetzbar sind. Wenn Sie den Wert eines übersetzbaren Feldes durch
Aufruf von debconf-updatepo ändern, wird die Übersetzung
für Übersetzer als aufmerksamkeitsbedürfend gekennzeichnet. Dann, zur
Build-Zeit, wird das Programm dh_installdebconf wie von
Zauberhand dafür sorgen, dass alle Vorlagen zusammen mit den aktuellen
Übersetzungen in die Binärpakete einfließen. Weitere Einzelheiten können Sie
der Handbuchseite po-debconf(7) entnehmen.
Internationalisierte Dokumentation für Anwender ist wichtig, bereitet aber viel Mühe. Es gibt keine Möglichkeit, all diese Arbeit zu vermeiden, aber Sie können den Übersetzern einige Dinge erleichtern.
Falls Sie Dokumentationen in irgendwelchem Umfang betreuen, ist es für
Übersetzer einfacher, wenn Sie Zugriff auf das Versionsverwaltungssystem
haben. Dadurch können Übersetzer die Unterschiede zwischen zwei Versionen
der Dokumentation anschauen, so dass sie beispielsweise sehen können, was
neu übersetzt werden muss. Es wird empfohlen, dass die übersetzte
Dokumentation eine Notiz darüber bereithält, auf welcher Revision des
Quellcodes die Übersetzung basiert. Ein interessantes System wird von doc-check aus dem debian-installer
-Paket bereitgestellt, das eine
Übersicht über den Übersetzungsstatus für eine angegebene Sprache
anzeigt. Dazu werden strukturierte Kommentare für die aktuelle Revision der
zu übersetzenden Datei und für eine übersetzte Datei die Revision des
Originals auf der die Übersetzung basiert, angezeigt. Möglicherweise möchten
Sie dies anpassen und in Ihrem VCS-Bereich bereitstellen.
If you maintain XML or SGML documentation, we suggest that you isolate any language-independent information and define those as entities in a separate file that is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files.
Some tools (e.g. po4a
, poxml
, or the translate-toolkit
) are specialized in extracting
the translatable material from different formats. They produce PO files, a
format quite common to translators, which permits seeing what needs to be
re-translated when the translated document is updated.
Die Dateien config.sub
und
config.guess
von autoconf aktuell zu
halten ist für Portierer kritisch, insbesondere auf eher unbeständigen
Architekturen. Einige sehr gute Paketierungsvorgehensweisen für jegliche
Pakete, die autoconf und/oder automake
benutzen, wurden in /usr/share/doc/autotools-dev/README.Debian.gz
aus dem Paket autotools-dev
zusammengefasst. Es wird
eindringlich geraten, diese Datei und die folgenden Empfehlungen zu lesen.
Bibliotheken unterscheiden sich immer von Paketen aus unterschiedlichen Gründen. Die Richtlinien verhängen mehrere Beschränkungen, um ihre Verwaltung zu erleichtern und sicherzustellen, dass Upgrades so einfach wie möglich sind, wenn eine neue Originalversion herauskommt. Eine kaputte Bibliothek kann dazu führen, dass Dutzende davon abhängige Pakete beschädigt werden.
Gute Vorgehensweisen für das Paketieren von Bibliotheken wurden in der Anleitung zum Paketieren von Bibliotheken zusammengefasst.
Achten Sie darauf, dass Sie den Richtlinien für Dokumentation folgen.
Falls Ihr Paket Dokumentation enthält, die aus XML oder SGML erstellt wurde, wird empfohlen, nicht die XML- oder SGML-Quellen im (in den) Binärpaket(en) mitzuliefern. Falls Anwender den Quellcode der Dokumentation möchten, sollten sie das Quellpaket herunterladen.
Die Richtlinie gibt an, dass die Dokumentation im HTML-Format weitergegeben werden sollte. Außerdem wird empfohlen, die Dokumentation im PDF-Format und als Klartext mitzuliefern, falls geeignet und falls die Ausgabe in einer vernünftigen Qualität möglich ist. Es ist allgemein jedoch nicht angemessen, Klartextversionen von Dokumentationen mitzuliefern, deren Quellformat HTML ist.
Bedeutende mitgelieferte Handbücher sollten sich selbst bei der Installation
mit doc-base
registrieren. Weitere
Einzelheiten erhalten Sie in der Dokumentation des Pakets doc-base
.
Die Debian-Richtlinien (Abschnitt 12.1) schreiben vor, dass Handbuchseiten jedem Programm, jedem Hilfswerkzeug und jeder Funktion beiliegen sollten und für andere Objekte, wie Konfigurationsdateien, wird dies nahegelegt. Falls die von Ihnen paketierte Arbeit nicht über eine solche Handbuchseite verfügt, dann überlegen Sie sich, eine zu schreiben, die Ihrem Paket beigefügt und an die Originalautoren gesandt wird.
The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using xsltproc, pod2man and rst2man respectively. To a lesser extent, the help2man program can also be used to write a stub.
Mehrere besondere Typen von Paketen haben spezielle Unter-Richtlinien und zugehörige Paketierungsregeln und -Vorgehensweisen:
Perl related packages have a Perl
policy; some examples of packages following that policy are
libdbd-pg-perl
(binary perl module)
or libmldbm-perl
(arch independent
perl module).
Python related packages have their Python policy; see /usr/share/doc/python/python-policy.txt.gz
in the python
package.
Emacs zugehörige Pakete haben die Emacs-Richtlinie.
Java zugehörige Pakete haben ihre Java-Richtlinie.
OCaml related packages have their own policy, found in /usr/share/doc/ocaml/ocaml_packaging_policy.gz
from the ocaml
package. A good
example is the camlzip
source
package.
Pakete, die XML- oder SGML-DTDs bereitstellen, sollten konform zu den
Empfehlungen im Paket sgml-base-doc
sein.
Lisp-Pakete sollten sich selbst mit common-lisp-controller
registrieren. Siehe dazu
/usr/share/doc/common-lisp-controller/README.packaging
.
Es ist nicht unüblich, eine größere Menge architekturunabhängiger Daten mit einem Programm zu paketieren, zum Beispiel Audiodateien, eine Symbolsammlung, Hintergrundmuster oder grafische Dateien. Falls die Größe dieser Daten vernachlässigbar im Vergleich zum Rest des Pakets ist, ist es wahrscheinlich am besten, alles in einem einzelnen Paket zu halten.
However, if the size of the data is considerable, consider splitting it out
into a separate, architecture-independent package
(_all.deb
). By doing this, you avoid needless
duplication of the same data into ten or more .debs, one per each
architecture. While this adds some extra overhead into the
Packages
files, it saves a lot of disk space on Debian
mirrors. Separating out architecture-independent data also reduces
processing time of lintian (see Abschnitt A.2, „Lint-Werkzeuge für Pakete“) when run over the entire Debian archive.
Falls Sie eine bestimmte Locale während des Builds benötigen, können Sie mittels dieses Tricks eine temporäre Datei erstellen:
Falls Sie LOCPATH
auf die Entsprechung von
/usr/lib/locale
und LC_ALL
auf den
Namen der Locale setzen, die sie generieren, sollten Sie erreichen, was Sie
möchten, ohne dass Sie Root sind. Etwas wie:
LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 mkdir -p $LOCALE_PATH localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET # Die Locale verwenden LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
Deborphan ist ein Programm, das Anwendern hilft, Pakete aufzuspüren, die sicher vom System entfernt werden können, d.h. diejenigen, von denen keine Pakete abhängen. Die Standardoperation ist, nur innerhalb der Abschnitte »libs« und »oldlibs« zu suchen, um Jagd auf unbenutzte Bibliotheken zu machen. Wenn aber das richtige Argument übergeben wird, versucht es auch, andere nutzlose Pakete zu erwischen.
Mit --guess-dummy
versucht deborphan
zum Beispiel, alle Übergangspakete zu suchen, die für ein Upgrade benötigt
wurden, die nun aber sicher entfernt werden können. Dazu sucht es nach den
Zeichenketten »dummy« oder »transitional« in dessen Kurzbeschreibung.
Wenn Sie also solch ein Paket erstellen, achten Sie bitte darauf, diesen Text in Ihrer Kurzbeschreibung zu verwenden. Um nach Beispielen zu suchen, führen Sie einfach apt-cache search .|grep dummy oder apt-cache search .|grep transitional aus.
Außerdem wird empfohlen, den Abschnitt in oldlibs
und die
Priorität in extra
zu ändern, um die Arbeit von
deborphan zu erleichtern.
Es gibt zwei Arten von Original-Quell-Tarballs: unberührten Quellcode und neu paketierten Quellcode der Originalautoren.
Das charakteristische Merkmal eines unberührten Tarballs ist, dass die
.orig.tar.{gz,bz2,xz}
-Datei Byte für Byte identisch mit
einem offiziell weitergegebenen Tarball des Originalautors ist.[5] Dies ermöglicht die Benutzung von Prüfsummen, um
auf einfache Weise alle Änderungen zwischen Debians Version und der der
Originalautoren zu prüfen, die in der Diff-Datei in Debian enthalten
sind. Falls außerdem der Originalquellcode riesig ist, können
Originalautoren und andere, die bereits den Original-Tarball haben,
Download-Zeit sparen, falls sie Ihre Paketierung im Detail inspizieren
möchten.
There are no universally accepted guidelines that upstream authors follow regarding the directory structure inside their tarball, but dpkg-source is nevertheless able to deal with most upstream tarballs as pristine source. Its strategy is equivalent to the following:
Es entpackt den Tarball in eine leeres temporäres Verzeichnis mittels
zcat path/to/Paketname
_Originalversion
.orig.tar.gz | tar xf -
Falls das temporäre Verzeichnis danach nur ein Verzeichnis und keine anderen
Dateien enthält, benennt dpkg-source dieses Verzeichnis
in
um. Der Name des Verzeichnisses auf der obersten Ebene im Tarball ist ohne
Bedeutung und geht verloren.
Paketname
_Originalversion
(.orig)
Andernfalls muss der Tarball der Originalautoren ohne ein sonst übliches
Verzeichnis der obersten Ebene gepackt worden sein (Schande über den
Originalautor!). In diesem Fall benennt dpkg-source das
temporäre Verzeichnis selbst in
um.
Paketname
_Originalversion
(.orig)
Sie sollten Pakete, wenn möglich, mit einem unberührten Quell-Tarball hochladen, aber es gibt viele Gründe, warum das manchmal nicht möglich ist. Dies ist der Fall, wenn die Originalautoren den Quellcode gar nicht als Gzip-gepackte Tar-Datei weitergeben oder falls der Tarball der Originalautoren nicht-DFSG-freies Material enthält, das Sie vor den Hochladen entfernen müssen.
In diesen Fällen muss der Entwickler selbst eine geeignete
.orig.tar.{gz,bz2,xz}
-Datei bauen. Solch einen Tarball
nennen wir neu paketierten Originalquellcode. Beachten Sie, dass sich neu
paketierter Originalquellcode von einem nativen Debian-Paket
unterscheidet. Eine neu paketierte Quelle kommt mit Debian-spezifischen
Änderungen in einem separaten .diff.gz
oder
.debian.tar.{gz,bz2,xz}
daher und hat eine
Versionsnummer, die sich aus der Originalversion
und der Debian-version
zusammensetzt.
Es könnte Gründe geben, aus denen es wünschenswert wäre, den Quellcode neu
zu paketieren, obwohl die Originalautoren ein
.tar.{gz,bz2,xz}
verteilen, dass im Prinzip in seiner
unberührten Form benutzt werden könnte. Der naheliegendste Grund ist, wenn
signifikante Platzersparnis durch Neukomprimierung des
Tar-Archivs oder Entfernen von wirklich nutzlosem Müll aus dem
Qriginalarchiv erzielt werden kann. Handeln Sie hier nach eigenem Ermessen,
aber seien Sie darauf vorbereitet, Ihre Entscheidung zu verteidigen, falls
Sie einen Quellcode neu paketieren, der unberührt sein könnte.
Eine neu paketierte .orig.tar.{gz,bz2,xz}
sollte im resultierenden Quellpaket
dokumentiert sein. Detaillierte Informationen, wie der neu paketierte
Quellcode gewonnen wurde und wie dies reproduziert werden kann, sollten in
debian/copyright
bereitgestellt werden. Es ist außerdem
eine gute Idee, ein get-orig-source
-Target in Ihrer
debian/rules
-Datei bereitzustellen, die den Prozess
wiederholt, wie im Policy-Handbuch beschrieben unter Main building script:
debian/rules
.
sollte keine Datei enthalten, die nicht von dem/den Originalautor(en) stammt oder deren Inhalt von Ihnen geändert wurde.[6]
sollte außer, wenn es aus rechtlichen
Gründen unmöglich ist, die ganze Erstellungs- und Portierungsinfrastruktur
aufbewahren, die vom Originalautor bereitgestellt wurde. Es ist zum Beispiel
kein ausreichender Grund für das Weglassen einer Datei, wenn sie nur für die
Erstellung unter MS-DOS benutzt wird. Gleichermaßen sollte ein
Makefile
, das vom Originalautor bereitgestellt wurde,
nicht einmal dann weggelassen werden, wenn das erste, was Ihre
debian/rules
tut, das Überschreiben durch Ausführen
eines Konfigurationsskripts ist.
(Begründung: Es ist üblich für Debian-Anwender, die Software für nicht-Debian-Plattformen erstellen möchten, den Quellcode von einem Debian-Spiegel abzurufen, anstatt den Speicherort der ordnungsgemäßen Originaldistribution zu suchen).
sollte als Namen des Verzeichnisses auf
der obersten Ebene des Tarballs
benutzen. Dies ermöglicht die Unterscheidung von unberührten und neu
paketierten Tarballs.
Paketname
-Originalversion
.orig
sollte mit Gzip oder Bzip mit der maximalen Komprimierung gepackt werden.
Sometimes it is necessary to change binary files contained in the original
tarball, or to add binary files that are not in it. This is fully supported
when using source packages in “3.0 (quilt)” format; see the
dpkg-source(1)
manual page for details. When using the older format “1.0”, binary files
can't be stored in the .diff.gz
so you must store a
uuencoded (or similar) version of the file(s) and decode
it at build time in debian/rules
(and move it in its
official location).
Ein Debug-Paket ist ein Paket, dessen Name mit -dbg endet. Es enthält zusätzliche Informationen, die gdb benutzen kann. Da Debian-Programme standardmäßig unverhüllt sind, sind Debugging-Informationen, einschließlich Namen und Zeilennummern andernfalls nicht verfügbar, wenn gdb auf Debian-Programmen ausgeführt wird. Debug-Pakete ermöglichen Anwendern, die diese zusätzlichen Debugging-Informationen benötigen, sie zu installieren, ohne das normale System mit diesen Informationen aufzublähen.
It is up to a package's maintainer whether to create a debug package or not. Maintainers are encouraged to create debug packages for library packages, since this can aid in debugging many programs linked to a library. In general, debug packages do not need to be added for all programs; doing so would bloat the archive. But if a maintainer finds that users often need a debugging version of a program, it can be worthwhile to make a debug package for it. Programs that are core infrastructure, such as Apache and the X server are also good candidates for debug packages.
Einige Debug-Pakete könnten ein ganz spezielles Debugging-Build einer
Bibliothek oder eines anderen Programms haben, aber die meisten können
Speicher und Build-Zeit sparen, indem sie stattdessen separate
Debugging-Symbole enthalten, die gdb spontan finden und
laden kann, wenn in einem Programm oder einer Bibliothek nach Fehlern
gesucht wird. Die Konvention in Debian besagt, dass diese Symbole in
/usr/lib/debug/
aufbewahrt werden, wobei Pfad
Pfad
der Pfad zum
ausführbaren Programm oder der Bibliothek ist. Debugging-Symbole für
/usr/bin/foo
wandern beispielsweise nach
/usr/lib/debug/usr/bin/foo
und Debugging-Symbole für
/usr/lib/libfoo.so.1
nach
/usr/lib/debug/usr/lib/libfoo.so.1
.
Die Debugging-Symbole können mit objcopy --only-keep-debug aus einer Objektdatei extrahiert werden. Dann kann die Objektdatei enthüllt und objcopy --add-gnu-debuglink benutzt werden, um den Pfad zur Debugging-Symboldatei anzugeben. objcopy(1) erklärt im Detail, wie dies funktioniert.
Der Befehl dh_strip in debhelper
unterstützt das Erstellen von
Debug-Paketen und kann sich um die Benutzung von objcopy
kümmern, um die Debugging-Symbole für Sie herauszusuchen. Falls Ihr Paket
debhelper
benutzt, müssen Sie nur
dh_strip --dbg-package=libfoo-dbg aufrufen und einen
Eintrag in debian/control
für das Debug-Paket
hinzufügen.
Beachten Sie, dass Debug-Pakete von dem Paket abhängen sollten, für das sie Debugging-Symbole bereitstellen und diese Abhängigkeit sollte mit einer Version versehen werden. Zum Beispiel:
Depends: libfoo (= ${binary:Version})
Ein Meta-Paket ist meist ein leeres Paket, das es vereinfacht, eine
Zusammenstellung von Paketen zu installieren, die sich im Lauf der Zeit
weiterentwickeln können. Dies wird erreicht, indem das Metapaket von allen
Paketen der Zusammenstellung abhängt. Dank der Fähigkeiten von APT kann der
Betreuer des Meta-Pakets die Abhängigkeiten anpassen und das System des
Anwenders wird automatisch die zusätzlichen Pakete erhalten. Die
weggelassenen Pakete, die automatisch installiert wurden, werden außerdem
als Kandidaten für das Entfernen gekennzeichnet (und werden sogar durch
aptitude automatisch entfernt). gnome
und linux-image-amd64
sind zwei Beispiele für
Meta-Pakete (gebaut durch die Quellpakete meta-gnome2
und linux-latest
).
The long description of the meta-package must clearly document its purpose so that the user knows what they will lose if they remove the package. Being explicit about the consequences is recommended. This is particularly important for meta-packages that are installed during initial installation and that have not been explicitly installed by the user. Those tend to be important to ensure smooth system upgrades and the user should be discouraged from uninstalling them to avoid potential breakages.
[5] We cannot prevent upstream authors from changing the tarball they distribute
without also incrementing the version number, so there can be no guarantee
that a pristine tarball is identical to what upstream
currently distributing at any point in time. All that
can be expected is that it is identical to something that upstream once
did distribute. If a difference arises later (say, if
upstream notices that they weren't using maximal compression in their
original distribution and then re-gzip it), that's just
too bad. Since there is no good way to upload a new
.orig.tar.{gz,bz2,xz}
for the same version, there is
not even any point in treating this situation as a bug.
[6] As a special exception, if the omission of non-free files would lead to the
source failing to build without assistance from the Debian diff, it might be
appropriate to instead edit the files, omitting only the non-free parts of
them, and/or explain the situation in a README.source
file in the root of the source tree. But in that case please also urge the
upstream author to make the non-free components easier to separate from the
rest of the source.