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