Come creare le manpage della sezione 9 del kernel che documentano funzioni, strutture di dati e intestazioni?

I sorgenti del kernel contengono funzioni e strutture di dati documentate, ad esempio 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, ...)

Invece di consultare le fonti ogni volta, sarebbe utile visualizzare quelle API come pagine man e sfruttare questo framework di documentazione esistente.

Come si installa / crea la manpage della sezione 9 del kernel ( /usr/share/man/man9) che documenta le funzioni e le strutture dati sopra menzionate?

kernel man documentation

— kakeh
fonte

Vuoi condividere la distribuzione che stai utilizzando?

— tink

Perché sei così sicuro che ci sono sempre pagine man (specialmente aggiornate) per ogni versione?

— mdpc,

@mdpc perché un kernel ben mantenuto non avrà pagine man, penso che la mia domanda sia valida

— kakeh

"Devi installare xmlto" sembra il punto di partenza, no?

— Braiam,

@Bralam ha aggiornato la sorpresa :(

— kakeh,

Risposte:

Il contenuto viene analizzato direttamente (vedi anche questo ) dai file .c di origine ¹ :

Al fine di fornire una documentazione incorporata, di facile comprensione, facile da mantenere, ma coerente ed estraibile delle funzioni e delle strutture di dati nel kernel Linux, il kernel Linux ha adottato uno stile coerente per documentare le funzioni, i loro parametri, le strutture e i loro membri.

Il formato per questa documentazione è chiamato il formato kernel-doc. È documentato in questo file Documentation / kernel-doc-nano-HOWTO.txt.

Questo stile incorpora la documentazione nei file di origine, usando alcune semplici convenzioni. Gli script / script perl kernel-doc, alcuni modelli SGML in Documentation / DocBook e altri strumenti comprendono queste convenzioni e vengono utilizzati per estrarre questa documentazione incorporata in vari documenti. [...]

Il segno di commento di apertura "/ **" è riservato ai commenti kernel-doc. Solo i commenti così contrassegnati verranno considerati dagli script kernel-doc e tutti i commenti così contrassegnati devono essere in formato kernel-doc.

Ciò significa che solo questi commenti formattati possono essere estratti in questo modo e che è possibile sfruttare lo script Perl utilizzato dal processo:kernel-doc make

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

e quindi che non sei limitato al target mandocs :

Dopo l'installazione, "make psdocs", "make pdfdocs", "make htmldocs" o "make mandocs" visualizzeranno la documentazione nel formato richiesto.

Ci sono anche file di testo specifici del driver nel repository / sorgente del kernel. Più in generale, il loro progetto di pagine man di Linux (da man1 a man8 ) è disponibile per il download. In un'ultima nota kernel.org mantiene anche alcuni documenti di output .

^{1. Il kernel non è l'unico caso in cui tale tecnica viene utilizzata per generare manpage. Il coreutils GNU è un altro caso del genere; la maggior parte delle sue manpage sono generate usando l'output del command --helpcontenuto che è nella funzione di utilizzo il file sorgente dell'utilità ( 1 2 ).}

— Comunità
fonte

make mandocs mi lanciaMakefile:19: /Documentation/DocBook/media/Makefile: No such file or directory

— kakeh,

sì, ce l'ho, ma Documentation/non è presente nel /suo presente in/lib/modules/3.2.0-57-generic-pae/build/

— kakeh

@Shyam Questi sono i file per i moduli ecc., Come il collegamento ai file di testo nel mio A. Puoi forse provare ./scripts/kernel-doc -man ./**/*.c >mydocdalla directory superiore dei sorgenti e vedere se non riesci a mettere tutto direttamente in un file analizzando direttamente i sorgenti .

Supponendo che tu stia usando Ubuntu,

apt-get install linux-manual-3.2

o simile (scegli la versione corretta). C'è anche un altro pacchetto di documentazione

apt-get install linux-doc

ma questo è html.

— Faheem Mitha
fonte

questo non mostra la documentazione del kernel api

— kakeh,

Esempio @Shyam?

— Faheem Mitha,

Su Arch (Bang) ho: linux- manpages 3.14-1 che contiene la sezione 9 manpage! Grazie! Un esempio è kcalloc.9.gz . Ce ne sono circa 4000 ...

@Faheem Mitha treid di visualizzazione man alloc_register_regionma ha detto che nessun inserimento manuale è diverso da quello delle pagine man ??

— Kakeh,

@FaheemMitha non credo che le API di basso livello del kernel siano disponibili con Linux-Doc!

— Kakeh,

Scarica il codice sorgente del kernel ed esegui nella directory sorgente

make mandocs

Dopo che i documenti man sono stati fatti, eseguire

make installmandocs

Ciò installerà le pagine di manuale in /usr/local/man/man9/. Ora puoi visualizzare le pagine man digitando man <api-name>, o se stai modificando vimbasta premere Ksul nome dell'API.

— manav mn
fonte

Ma il makefile in /usr/src/linux-headers-5.0.0-38/Makefilenon ha regola mandocsnéinstallmandocs

— Pastore