Wie erstelle ich im Kernel Abschnitt 9 Manpages, die Funktionen, Datenstrukturen und Header dokumentieren?

Die Kernel - Quellen enthalten , Funktionen und Datenstrukturen , die dokumentiert sind, beispielsweise in panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

Anstatt jedes Mal die Quellen durchzugehen, wäre es nützlich, diese APIs als Manpages anzuzeigen und dieses vorhandene Dokumentationsframework zu nutzen.

Wie installiert / erstellt man die Kernel Section 9 Manpages ( /usr/share/man/man9), die die oben genannten Funktionen und Datenstrukturen dokumentieren?

Der Inhalt wird direkt (siehe auch dies ) aus den Quell- C-Dateien ¹ analysiert :

Um eine eingebettete, C-freundliche, leicht zu wartende, aber konsistente und extrahierbare Dokumentation der Funktionen und Datenstrukturen im Linux-Kernel bereitzustellen, hat der Linux-Kernel einen konsistenten Stil zur Dokumentation von Funktionen und deren Parametern sowie deren Strukturen und Strukturen übernommen Mitglieder.

Das Format für diese Dokumentation wird als Kernel-Doc-Format bezeichnet. Es ist in dieser Datei Documentation / kernel-doc-nano-HOWTO.txt dokumentiert.

Dieser Stil bettet die Dokumentation mit ein paar einfachen Konventionen in die Quelldateien ein. Das Skript / Kernel-Doc-Perl-Skript, einige SGML-Vorlagen in Documentation / DocBook und andere Tools verstehen diese Konventionen und werden verwendet, um diese eingebettete Dokumentation in verschiedene Dokumente zu extrahieren. [...]

Das Eröffnungskommentar "/ **" ist für Kernel-Doc-Kommentare reserviert. Nur so markierte Kommentare werden von den Kernel-Doc-Skripten berücksichtigt, und alle so markierten Kommentare müssen im Kernel-Doc-Format vorliegen.

Dies bedeutet, dass nur solche formatierten Kommentare auf diese Weise extrahiert werden können und dass Sie das vom Prozess verwendete Perl- Skript nutzen können:kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

und deshalb, dass Sie nicht auf das Mandocs- Ziel beschränkt sind :

Nach der Installation wird die Dokumentation mit "psdocs erstellen", "pdfdocs erstellen", "htmldocs erstellen" oder "mandocs erstellen" im angeforderten Format gerendert.

Es gibt auch treiberspezifische Textdateien im Kernel-Repository / in der Quelle. Allgemeiner gesagt , ihr Linux - man-pages Projekt ( man1 durch man8 ist) verfügbar zum Download bereit . In einem letzten Hinweis verwaltet kernel.org auch einige Ausgabedokumentationen .

^{1. Der Kernel ist nicht der einzige Fall, in dem eine solche Technik zum Generieren von Manpages verwendet wird. GNU Coreutils ist ein solcher anderer Fall; Die meisten seiner Manpages werden mithilfe der Ausgabe des Inhalts generiert , dessen command --helpInhalt in der Verwendungsfunktion der Utility-Quelldatei ( 1 2 ) enthalten ist.}

Angenommen, Sie verwenden Ubuntu.

apt-get install linux-manual-3.2

oder ähnlich (wählen Sie die richtige Version). Es gibt auch ein anderes Dokumentationspaket

apt-get install linux-doc

aber das ist html.

Laden Sie den Kernel-Quellcode herunter und führen Sie ihn im Quellverzeichnis aus

make mandocs

Nachdem die Manndokumente erstellt wurden, führen Sie sie aus

make installmandocs

Dadurch werden die Handbuchseiten in installiert /usr/local/man/man9/. Jetzt können Sie Manpages durch Eingabe anzeigen man <api-name>oder beim Bearbeiten vimeinfach Küber den API-Namen drücken .