198 lines · plain
1.. include:: ../disclaimer-ita.rst2 3:Original: :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`4:Translator: Federico Vaga <federico.vaga@vaga.pv.it>5 6.. _it_clangformat:7 8clang-format9============10``clang-format`` è uno strumento per formattare codice C/C++/... secondo11un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto12e non copre tutti i singoli casi, ma è abbastanza buono per essere utile.13 14``clang-format`` può essere usato per diversi fini:15 16 - Per riformattare rapidamente un blocco di codice secondo lo stile del17 kernel. Particolarmente utile quando si sposta del codice e lo si18 allinea/ordina. Vedere it_clangformatreformat_.19 20 - Identificare errori di stile, refusi e possibili miglioramenti nei21 file che mantieni, le modifiche che revisioni, le differenze,22 eccetera. Vedere it_clangformatreview_.23 24 - Ti aiuta a seguire lo stile del codice, particolarmente utile per i25 nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi26 progetti con stili di codifica differenti.27 28Il suo file di configurazione è ``.clang-format`` e si trova nella cartella29principale dei sorgenti del kernel. Le regole scritte in quel file tentano30di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire31il più possibile32:ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.33Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare34le regole di base per un particolare sottosistema o cartella. Per farlo,35potete sovrascriverle scrivendole in un altro file ``.clang-format`` in36una sottocartella.37 38Questo strumento è già stato incluso da molto tempo nelle distribuzioni39Linux più popolari. Cercate ``clang-format`` nel vostro repositorio.40Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang41oppure generarlo dai codici sorgenti:42 43 https://releases.llvm.org/download.html44 45Troverete più informazioni ai seguenti indirizzi:46 47 https://clang.llvm.org/docs/ClangFormat.html48 49 https://clang.llvm.org/docs/ClangFormatStyleOptions.html50 51 52.. _it_clangformatreview:53 54Revisionare lo stile di codifica per file e modifiche55-----------------------------------------------------56 57Eseguendo questo programma, potrete revisionare un intero sottosistema,58cartella o singoli file alla ricerca di errori di stile, refusi o59miglioramenti.60 61Per farlo, potete eseguire qualcosa del genere::62 63 # Make sure your working directory is clean!64 clang-format -i kernel/*.[ch]65 66E poi date un'occhiata a *git diff*.67 68Osservare le righe di questo diff è utile a migliorare/aggiustare69le opzioni di stile nel file di configurazione; così come per verificare70le nuove funzionalità/versioni di ``clang-format``.71 72``clang-format`` è in grado di leggere diversi diff unificati, quindi73potrete revisionare facilmente delle modifiche e *git diff*.74La documentazione si trova al seguente indirizzo:75 76 https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting77 78Per evitare che ``clang-format`` formatti alcune parti di un file, potete79scrivere nel codice::80 81 int formatted_code;82 // clang-format off83 void unformatted_code ;84 // clang-format on85 void formatted_code_again;86 87Nonostante si attraente l'idea di utilizzarlo per mantenere un file88sempre in sintonia con ``clang-format``, specialmente per file nuovi o89se siete un manutentore, ricordatevi che altre persone potrebbero usare90una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto.91Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del92kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente93utilizzato.94 95 96.. _it_clangformatreformat:97 98Riformattare blocchi di codice99------------------------------100 101Utilizzando dei plugin per il vostro editor, potete riformattare una102blocco (selezione) di codice con una singola combinazione di tasti.103Questo è particolarmente utile: quando si riorganizza il codice, per codice104complesso, macro multi-riga (e allineare le loro "barre"), eccetera.105 106Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove107questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione,108può essere davvero molto utile.109 110Questo programma si integra con molti dei più popolari editor. Alcuni di111essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente.112Al seguente indirizzo troverete le istruzioni:113 114 https://clang.llvm.org/docs/ClangFormat.html115 116Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor117e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso.118 119Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format``120che potete personalizzare con le vostre opzioni.121Consultare it_clangformatextra_.122 123 124.. _it_clangformatmissing:125 126Cose non supportate127-------------------128 129``clang-format`` non ha il supporto per alcune cose che sono comuni nel130codice del kernel. Sono facili da ricordare; quindi, se lo usate131regolarmente, imparerete rapidamente a evitare/ignorare certi problemi.132 133In particolare, quelli più comuni che noterete sono:134 135 - Allineamento di ``#define`` su una singola riga, per esempio::136 137 #define TRACING_MAP_BITS_DEFAULT 11138 #define TRACING_MAP_BITS_MAX 17139 #define TRACING_MAP_BITS_MIN 7140 141 contro::142 143 #define TRACING_MAP_BITS_DEFAULT 11144 #define TRACING_MAP_BITS_MAX 17145 #define TRACING_MAP_BITS_MIN 7146 147 - Allineamento dei valori iniziali, per esempio::148 149 static const struct file_operations uprobe_events_ops = {150 .owner = THIS_MODULE,151 .open = probes_open,152 .read = seq_read,153 .llseek = seq_lseek,154 .release = seq_release,155 .write = probes_write,156 };157 158 contro::159 160 static const struct file_operations uprobe_events_ops = {161 .owner = THIS_MODULE,162 .open = probes_open,163 .read = seq_read,164 .llseek = seq_lseek,165 .release = seq_release,166 .write = probes_write,167 };168 169 170.. _it_clangformatextra:171 172Funzionalità e opzioni aggiuntive173---------------------------------174 175Al fine di minimizzare le differenze fra il codice attuale e l'output176del programma, alcune opzioni di stile e funzionalità non sono abilitate177nella configurazione base. In altre parole, lo scopo è di rendere le178differenze le più piccole possibili, permettendo la semplificazione179della revisione di file, differenze e modifiche.180 181In altri casi (per esempio un particolare sottosistema/cartella/file), lo182stile del kernel potrebbe essere diverso e abilitare alcune di queste183opzioni potrebbe dare risultati migliori.184 185Per esempio:186 187 - Allineare assegnamenti (``AlignConsecutiveAssignments``).188 189 - Allineare dichiarazioni (``AlignConsecutiveDeclarations``).190 191 - Riorganizzare il testo nei commenti (``ReflowComments``).192 193 - Ordinare gli ``#include`` (``SortIncludes``).194 195Piuttosto che per interi file, solitamente sono utili per la riformattazione196di singoli blocchi. In alternativa, potete creare un altro file197``.clang-format`` da utilizzare con il vostro editor/IDE.198