196 lines · plain
1.. include:: ../disclaimer-ita.rst2 3:Original: Documentation/doc-guide/index.rst4 5=========================================6Includere gli i file di intestazione uAPI7=========================================8 9Qualche volta è utile includere dei file di intestazione e degli esempi di codice C10al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti11fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API12dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi13d'avviso se un simbolo non viene trovato nella documentazione. Questo permette14di mantenere allineate la documentazione della uAPI (API spazio utente)15con le modifiche del kernel.16Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.17Esso dev'essere invocato attraverso un Makefile, mentre si genera la18documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel19consultate ``Documentation/userspace-api/media/Makefile``.20 21.. _it_parse_headers:22 23parse_headers.pl24^^^^^^^^^^^^^^^^25 26NOME27****28 29 30parse_headers.pl - analizza i file C al fine di identificare funzioni,31strutture, enumerati e definizioni, e creare riferimenti per Sphinx32 33SINTASSI34********35 36 37\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]38 39Dove <options> può essere: --debug, --usage o --help.40 41 42OPZIONI43*******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 62DESCRIZIONE63***********64 65Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo66reStructuredText incluso mediante il blocco ..parsed-literal67con riferimenti alla documentazione che descrive l'API. Opzionalmente,68il programma accetta anche un altro file (EXCEPTIONS_FILE) che69descrive quali elementi debbano essere ignorati o il cui riferimento70deve puntare ad elemento diverso dal predefinito.71 72Il file generato sarà disponibile in (OUT_FILE).73 74Il programma è capace di identificare *define*, funzioni, strutture,75tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti76per ognuno di loro. Inoltre, esso è capace di distinguere le #define77utilizzate per specificare i comandi ioctl di Linux.78 79Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:80\ **ignore**\ o \ **replace**\ .81 82La sintassi per ignore è:83 84ignore \ **tipo**\ \ **nome**\85 86La dichiarazione \ **ignore**\ significa che non verrà generato alcun87riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ .88 89 90La sintassi per replace è:91 92replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\93 94La dichiarazione \ **replace**\ significa che verrà generato un95riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece96di utilizzare il valore predefinito, verrà utilizzato il valore97\ **nuovo_valore**\ .98 99Per 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 ioctl105 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 #define114 trovata in C_FILE.115 116 117 118\ **typedef**\119 120 La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef121 in C_FILE.122 123 124 125\ **struct**\126 127 La dichiarazione ignore o replace verrà applicata ai nomi di strutture128 in C_FILE.129 130 131 132\ **enum**\133 134 La dichiarazione ignore o replace verrà applicata ai nomi di enumerati135 in C_FILE.136 137 138 139\ **symbol**\140 141 La dichiarazione ignore o replace verrà applicata ai nomi di valori di142 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**\ e146 \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e147 \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente148 nella dichiarazione stessa.149 150 151ESEMPI152******153 154 155ignore define _VIDEODEV2_H156 157 158Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.159 160ignore symbol PRIVATE161 162 163In un enumerato come il seguente:164 165enum foo { BAR1, BAR2, PRIVATE };166 167Non genererà alcun riferimento per \ **PRIVATE**\ .168 169replace symbol BAR1 :c:type:\`foo\`170replace symbol BAR2 :c:type:\`foo\`171 172 173In un enumerato come il seguente:174 175enum foo { BAR1, BAR2, PRIVATE };176 177Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.178 179 180BUGS181****182 183Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>184 185 186COPYRIGHT187*********188 189 190Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.191 192Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.193 194Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.195Non c'è alcuna garanzia, nei limiti permessi dalla legge.196