1 .. include:: ../disclaimer-ita.rst
3 .. note:: Per leggere la documentazione originale in inglese:
4 :ref:`Documentation/doc-guide/index.rst <doc_guide>`
6 =========================================
7 Includere gli i file di intestazione uAPI
8 =========================================
10 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
11 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
12 fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
13 dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
14 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
15 di mantenere allineate la documentazione della uAPI (API spazio utente)
16 con le modifiche del kernel.
17 Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
18 Esso dev'essere invocato attraverso un Makefile, mentre si genera la
19 documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
20 consultate ``Documentation/userspace-api/media/Makefile``.
31 parse_headers.pl - analizza i file C al fine di identificare funzioni,
32 strutture, enumerati e definizioni, e creare riferimenti per Sphinx
38 \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
40 Dove <options> può essere: --debug, --usage o --help.
50 Lo script viene messo in modalità verbosa, utile per il debugging.
55 Mostra un messaggio d'aiuto breve e termina.
60 Mostra un messaggio d'aiuto dettagliato e termina.
66 Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
67 ReStructuredText incluso mediante il blocco ..parsed-literal
68 con riferimenti alla documentazione che descrive l'API. Opzionalmente,
69 il programma accetta anche un altro file (EXCEPTIONS_FILE) che
70 descrive quali elementi debbano essere ignorati o il cui riferimento
71 deve puntare ad elemento diverso dal predefinito.
73 Il file generato sarà disponibile in (OUT_FILE).
75 Il programma è capace di identificare *define*, funzioni, strutture,
76 tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
77 per ognuno di loro. Inoltre, esso è capace di distinguere le #define
78 utilizzate per specificare i comandi ioctl di Linux.
80 Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
81 \ **ignore**\ o \ **replace**\ .
83 La sintassi per ignore è:
85 ignore \ **tipo**\ \ **nome**\
87 La dichiarazione \ **ignore**\ significa che non verrà generato alcun
88 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ .
91 La sintassi per replace è:
93 replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\
95 La dichiarazione \ **replace**\ significa che verrà generato un
96 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
97 di utilizzare il valore predefinito, verrà utilizzato il valore
100 Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti:
105 La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
108 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
114 La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
121 La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
128 La dichiarazione ignore o replace verrà applicata ai nomi di strutture
135 La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
142 La dichiarazione ignore o replace verrà applicata ai nomi di valori di
145 Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà
146 automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e
147 \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e
148 \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
149 nella dichiarazione stessa.
156 ignore define _VIDEODEV2_H
159 Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
161 ignore symbol PRIVATE
164 In un enumerato come il seguente:
166 enum foo { BAR1, BAR2, PRIVATE };
168 Non genererà alcun riferimento per \ **PRIVATE**\ .
170 replace symbol BAR1 :c:type:\`foo\`
171 replace symbol BAR2 :c:type:\`foo\`
174 In un enumerato come il seguente:
176 enum foo { BAR1, BAR2, PRIVATE };
178 Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
184 Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
191 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
193 Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
195 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
196 Non c'è alcuna garanzia, nei limiti permessi dalla legge.