| .. include:: ../disclaimer-ita.rst |
| |
| :Original: Documentation/doc-guide/index.rst |
| |
| ========================================= |
| Includere gli i file di intestazione uAPI |
| ========================================= |
| |
| Qualche volta è utile includere dei file di intestazione e degli esempi di codice C |
| al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti |
| fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API |
| dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi |
| d'avviso se un simbolo non viene trovato nella documentazione. Questo permette |
| di mantenere allineate la documentazione della uAPI (API spazio utente) |
| con le modifiche del kernel. |
| Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti. |
| Esso dev'essere invocato attraverso un Makefile, mentre si genera la |
| documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel |
| consultate ``Documentation/userspace-api/media/Makefile``. |
| |
| .. _it_parse_headers: |
| |
| parse_headers.pl |
| ^^^^^^^^^^^^^^^^ |
| |
| NOME |
| **** |
| |
| |
| parse_headers.pl - analizza i file C al fine di identificare funzioni, |
| strutture, enumerati e definizioni, e creare riferimenti per Sphinx |
| |
| SINTASSI |
| ******** |
| |
| |
| \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] |
| |
| Dove <options> può essere: --debug, --usage o --help. |
| |
| |
| OPZIONI |
| ******* |
| |
| |
| |
| \ **--debug**\ |
| |
| Lo script viene messo in modalità verbosa, utile per il debugging. |
| |
| |
| \ **--usage**\ |
| |
| Mostra un messaggio d'aiuto breve e termina. |
| |
| |
| \ **--help**\ |
| |
| Mostra un messaggio d'aiuto dettagliato e termina. |
| |
| |
| DESCRIZIONE |
| *********** |
| |
| Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo |
| ReStructuredText incluso mediante il blocco ..parsed-literal |
| con riferimenti alla documentazione che descrive l'API. Opzionalmente, |
| il programma accetta anche un altro file (EXCEPTIONS_FILE) che |
| descrive quali elementi debbano essere ignorati o il cui riferimento |
| deve puntare ad elemento diverso dal predefinito. |
| |
| Il file generato sarà disponibile in (OUT_FILE). |
| |
| Il programma è capace di identificare *define*, funzioni, strutture, |
| tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti |
| per ognuno di loro. Inoltre, esso è capace di distinguere le #define |
| utilizzate per specificare i comandi ioctl di Linux. |
| |
| Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni: |
| \ **ignore**\ o \ **replace**\ . |
| |
| La sintassi per ignore è: |
| |
| ignore \ **tipo**\ \ **nome**\ |
| |
| La dichiarazione \ **ignore**\ significa che non verrà generato alcun |
| riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ . |
| |
| |
| La sintassi per replace è: |
| |
| replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\ |
| |
| La dichiarazione \ **replace**\ significa che verrà generato un |
| riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece |
| di utilizzare il valore predefinito, verrà utilizzato il valore |
| \ **nuovo_valore**\ . |
| |
| Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti: |
| |
| |
| \ **ioctl**\ |
| |
| La dichiarazione ignore o replace verrà applicata su definizioni di ioctl |
| come la seguente: |
| |
| #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) |
| |
| |
| |
| \ **define**\ |
| |
| La dichiarazione ignore o replace verrà applicata su una qualsiasi #define |
| trovata in C_FILE. |
| |
| |
| |
| \ **typedef**\ |
| |
| La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef |
| in C_FILE. |
| |
| |
| |
| \ **struct**\ |
| |
| La dichiarazione ignore o replace verrà applicata ai nomi di strutture |
| in C_FILE. |
| |
| |
| |
| \ **enum**\ |
| |
| La dichiarazione ignore o replace verrà applicata ai nomi di enumerati |
| in C_FILE. |
| |
| |
| |
| \ **symbol**\ |
| |
| La dichiarazione ignore o replace verrà applicata ai nomi di valori di |
| enumerati in C_FILE. |
| |
| Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà |
| automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e |
| \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e |
| \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente |
| nella dichiarazione stessa. |
| |
| |
| ESEMPI |
| ****** |
| |
| |
| ignore define _VIDEODEV2_H |
| |
| |
| Ignora una definizione #define _VIDEODEV2_H nel file C_FILE. |
| |
| ignore symbol PRIVATE |
| |
| |
| In un enumerato come il seguente: |
| |
| enum foo { BAR1, BAR2, PRIVATE }; |
| |
| Non genererà alcun riferimento per \ **PRIVATE**\ . |
| |
| replace symbol BAR1 :c:type:\`foo\` |
| replace symbol BAR2 :c:type:\`foo\` |
| |
| |
| In un enumerato come il seguente: |
| |
| enum foo { BAR1, BAR2, PRIVATE }; |
| |
| Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C. |
| |
| |
| BUGS |
| **** |
| |
| Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com> |
| |
| |
| COPYRIGHT |
| ********* |
| |
| |
| Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. |
| |
| Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. |
| |
| Questo è software libero: siete liberi di cambiarlo e ridistribuirlo. |
| Non c'è alcuna garanzia, nei limiti permessi dalla legge. |
