1 .. include:: ../disclaimer-ita.rst
2
3 :Original: Documentation/doc-guide/index.rst
4
5 =========================================
6 Includere gli i file di intestazione uAPI
7 =========================================
8
9 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
10 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
11 fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
12 dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
13 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
14 di mantenere allineate la documentazione della uAPI (API spazio utente)
15 con le modifiche del kernel.
16 Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
17 Esso dev'essere invocato attraverso un Makefile, mentre si genera la
18 documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
19 consultate ``Documentation/userspace-api/media/Makefile``.
20
21 .. _it_parse_headers:
22
23 parse_headers.pl
24 ^^^^^^^^^^^^^^^^
25
26 NOME
27 ****
28
29
30 parse_headers.pl - analizza i file C al fine di identificare funzioni,
31 strutture, enumerati e definizioni, e creare riferimenti per Sphinx
32
33 SINTASSI
34 ********
35
36
37 \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
38
39 Dove <options> può essere: --debug, --usage o --help.
40
41
42 OPZIONI
43 *******
44
45
46
47 \ **--debug**\
48
49 Lo script viene messo in modalità verbosa, utile per il debugging.
50
51
52 \ **--usage**\
53
54 Mostra un messaggio d'aiuto breve e termina.
55
56
57 \ **--help**\
58
59 Mostra un messaggio d'aiuto dettagliato e termina.
60
61
62 DESCRIZIONE
63 ***********
64
65 Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
66 reStructuredText incluso mediante il blocco ..parsed-literal
67 con riferimenti alla documentazione che descrive l'API. Opzionalmente,
68 il programma accetta anche un altro file (EXCEPTIONS_FILE) che
69 descrive quali elementi debbano essere ignorati o il cui riferimento
70 deve puntare ad elemento diverso dal predefinito.
71
72 Il file generato sarà disponibile in (OUT_FILE).
73
74 Il programma è capace di identificare *define*, funzioni, strutture,
75 tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
76 per ognuno di loro. Inoltre, esso è capace di distinguere le #define
77 utilizzate per specificare i comandi ioctl di Linux.
78
79 Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
80 \ **ignore**\ o \ **replace**\ .
81
82 La sintassi per ignore è:
83
84 ignore \ **tipo**\ \ **nome**\
85
86 La dichiarazione \ **ignore**\ significa che non verrà generato alcun
87 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ .
88
89
90 La sintassi per replace è:
91
92 replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\
93
94 La dichiarazione \ **replace**\ significa che verrà generato un
95 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
96 di utilizzare il valore predefinito, verrà utilizzato il valore
97 \ **nuovo_valore**\ .
98
99 Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti:
100
101
102 \ **ioctl**\
103
104 La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
105 come la seguente:
106
107 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
108
109
110
111 \ **define**\
112
113 La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
114 trovata in C_FILE.
115
116
117
118 \ **typedef**\
119
120 La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
121 in C_FILE.
122
123
124
125 \ **struct**\
126
127 La dichiarazione ignore o replace verrà applicata ai nomi di strutture
128 in C_FILE.
129
130
131
132 \ **enum**\
133
134 La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
135 in C_FILE.
136
137
138
139 \ **symbol**\
140
141 La dichiarazione ignore o replace verrà applicata ai nomi di valori di
142 enumerati in C_FILE.
143
144 Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà
145 automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e
146 \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e
147 \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
148 nella dichiarazione stessa.
149
150
151 ESEMPI
152 ******
153
154
155 ignore define _VIDEODEV2_H
156
157
158 Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
159
160 ignore symbol PRIVATE
161
162
163 In un enumerato come il seguente:
164
165 enum foo { BAR1, BAR2, PRIVATE };
166
167 Non genererà alcun riferimento per \ **PRIVATE**\ .
168
169 replace symbol BAR1 :c:type:\`foo\`
170 replace symbol BAR2 :c:type:\`foo\`
171
172
173 In un enumerato come il seguente:
174
175 enum foo { BAR1, BAR2, PRIVATE };
176
177 Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
178
179
180 BUGS
181 ****
182
183 Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
184
185
186 COPYRIGHT
187 *********
188
189
190 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
191
192 Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
193
194 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
195 Non c'è alcuna garanzia, nei limiti permessi dalla legge.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.