0001 .. include:: ../disclaimer-ita.rst
0002
0003 .. note:: Per leggere la documentazione originale in inglese:
0004 :ref:`Documentation/doc-guide/index.rst <doc_guide>`
0005
0006 =========================================
0007 Includere gli i file di intestazione uAPI
0008 =========================================
0009
0010 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
0011 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
0012 fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
0013 dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
0014 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
0015 di mantenere allineate la documentazione della uAPI (API spazio utente)
0016 con le modifiche del kernel.
0017 Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
0018 Esso dev'essere invocato attraverso un Makefile, mentre si genera la
0019 documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
0020 consultate ``Documentation/userspace-api/media/Makefile``.
0021
0022 .. _it_parse_headers:
0023
0024 parse_headers.pl
0025 ^^^^^^^^^^^^^^^^
0026
0027 NOME
0028 ****
0029
0030
0031 parse_headers.pl - analizza i file C al fine di identificare funzioni,
0032 strutture, enumerati e definizioni, e creare riferimenti per Sphinx
0033
0034 SINTASSI
0035 ********
0036
0037
0038 \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
0039
0040 Dove <options> può essere: --debug, --usage o --help.
0041
0042
0043 OPZIONI
0044 *******
0045
0046
0047
0048 \ **--debug**\
0049
0050 Lo script viene messo in modalità verbosa, utile per il debugging.
0051
0052
0053 \ **--usage**\
0054
0055 Mostra un messaggio d'aiuto breve e termina.
0056
0057
0058 \ **--help**\
0059
0060 Mostra un messaggio d'aiuto dettagliato e termina.
0061
0062
0063 DESCRIZIONE
0064 ***********
0065
0066 Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
0067 ReStructuredText incluso mediante il blocco ..parsed-literal
0068 con riferimenti alla documentazione che descrive l'API. Opzionalmente,
0069 il programma accetta anche un altro file (EXCEPTIONS_FILE) che
0070 descrive quali elementi debbano essere ignorati o il cui riferimento
0071 deve puntare ad elemento diverso dal predefinito.
0072
0073 Il file generato sarà disponibile in (OUT_FILE).
0074
0075 Il programma è capace di identificare *define*, funzioni, strutture,
0076 tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
0077 per ognuno di loro. Inoltre, esso è capace di distinguere le #define
0078 utilizzate per specificare i comandi ioctl di Linux.
0079
0080 Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
0081 \ **ignore**\ o \ **replace**\ .
0082
0083 La sintassi per ignore è:
0084
0085 ignore \ **tipo**\ \ **nome**\
0086
0087 La dichiarazione \ **ignore**\ significa che non verrà generato alcun
0088 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ .
0089
0090
0091 La sintassi per replace è:
0092
0093 replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\
0094
0095 La dichiarazione \ **replace**\ significa che verrà generato un
0096 riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
0097 di utilizzare il valore predefinito, verrà utilizzato il valore
0098 \ **nuovo_valore**\ .
0099
0100 Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti:
0101
0102
0103 \ **ioctl**\
0104
0105 La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
0106 come la seguente:
0107
0108 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
0109
0110
0111
0112 \ **define**\
0113
0114 La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
0115 trovata in C_FILE.
0116
0117
0118
0119 \ **typedef**\
0120
0121 La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
0122 in C_FILE.
0123
0124
0125
0126 \ **struct**\
0127
0128 La dichiarazione ignore o replace verrà applicata ai nomi di strutture
0129 in C_FILE.
0130
0131
0132
0133 \ **enum**\
0134
0135 La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
0136 in C_FILE.
0137
0138
0139
0140 \ **symbol**\
0141
0142 La dichiarazione ignore o replace verrà applicata ai nomi di valori di
0143 enumerati in C_FILE.
0144
0145 Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà
0146 automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e
0147 \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e
0148 \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
0149 nella dichiarazione stessa.
0150
0151
0152 ESEMPI
0153 ******
0154
0155
0156 ignore define _VIDEODEV2_H
0157
0158
0159 Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
0160
0161 ignore symbol PRIVATE
0162
0163
0164 In un enumerato come il seguente:
0165
0166 enum foo { BAR1, BAR2, PRIVATE };
0167
0168 Non genererà alcun riferimento per \ **PRIVATE**\ .
0169
0170 replace symbol BAR1 :c:type:\`foo\`
0171 replace symbol BAR2 :c:type:\`foo\`
0172
0173
0174 In un enumerato come il seguente:
0175
0176 enum foo { BAR1, BAR2, PRIVATE };
0177
0178 Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
0179
0180
0181 BUGS
0182 ****
0183
0184 Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
0185
0186
0187 COPYRIGHT
0188 *********
0189
0190
0191 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
0192
0193 Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
0194
0195 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
0196 Non c'è alcuna garanzia, nei limiti permessi dalla legge.
