clang-format로 커널 코드 포매팅하기

용도, 설정과 설치

이 문서는 이탈리아어 공통 면책 고지 `../disclaimer-ita.rst`를 포함하고 공식 원문 `Documentation/dev-tools/clang-format.rst`를 참조합니다. 번역자는 Federico Vaga이며 페이지 anchor는 `it_clangformat`입니다.

`clang-format`은 규칙과 heuristic에 따라 C, C++ 등의 코드를 포매팅하는 도구입니다. 모든 특수 사례를 완벽히 처리하지는 않지만 커널 개발에 실용적으로 사용할 만큼 충분한 결과를 제공합니다.

첫째 용도는 이동하거나 재배치한 코드 블록을 커널 스타일에 빠르게 맞추는 것입니다. 특히 복잡한 코드, 정렬, 순서 조정의 초벌 작업에 유용하며 `it_clangformatreformat` 절에서 자세히 다룹니다.

둘째 용도는 유지하는 파일, 검토 중인 변경, diff에서 스타일 오류와 오타, 개선 가능성을 찾는 것입니다. 이 검토 흐름은 `it_clangformatreview` 절에서 설명합니다.

셋째로 서로 다른 코딩 스타일을 가진 여러 프로젝트를 오가는 개발자나 커널 신규 기여자가 Linux 스타일을 따르도록 돕습니다. 결과는 출발점이며 최종 판단은 개발자 검토가 맡습니다.

기본 설정 파일 `.clang-format`은 커널 소스 루트에 있으며 Linux 커널 코딩 스타일을 최대한 근사합니다. 관련 기준은 `Documentation/translations/it_IT/process/coding-style.rst`의 `it_codingstyle` 참조입니다.

커널 전체가 완전히 같은 세부 스타일을 사용하지는 않습니다. 특정 하위 시스템이나 디렉터리에서 다른 규칙이 필요하면 하위 디렉터리에 별도 `.clang-format`을 두어 상위 설정을 덮어쓸 수 있습니다.

대부분의 Linux 배포판은 `clang-format` 패키지를 제공합니다. 패키지 저장소에서 설치하거나 LLVM/Clang 사전 빌드 바이너리를 내려받거나 소스에서 빌드할 수 있습니다. 릴리스, 사용법, 스타일 옵션 URL은 원문에 제공됩니다.

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
:Translator: Federico Vaga <[email protected]>

.. _it_clangformat:

clang-format
============
``clang-format`` è uno strumento per formattare codice C/C++/... secondo
un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto
e non copre tutti i singoli casi, ma è abbastanza buono per essere utile.

``clang-format`` può essere usato per diversi fini:

  - Per riformattare rapidamente un blocco di codice secondo lo stile del
    kernel. Particolarmente utile quando si sposta del codice e lo si
    allinea/ordina. Vedere it_clangformatreformat_.

  - Identificare errori di stile, refusi e possibili miglioramenti nei
    file che mantieni, le modifiche che revisioni, le differenze,
    eccetera. Vedere it_clangformatreview_.

  - Ti aiuta a seguire lo stile del codice, particolarmente utile per i
    nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi
    progetti con stili di codifica differenti.

Il suo file di configurazione è ``.clang-format`` e si trova nella cartella
principale dei sorgenti del kernel. Le regole scritte in quel file tentano
di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire
il più possibile
:ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare
le regole di base per un particolare sottosistema o cartella. Per farlo,
potete sovrascriverle scrivendole in un altro file ``.clang-format`` in
una sottocartella.

Questo strumento è già stato incluso da molto tempo nelle distribuzioni
Linux più popolari. Cercate ``clang-format`` nel vostro repositorio.
Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang
oppure generarlo dai codici sorgenti:

    https://releases.llvm.org/download.html

Troverete più informazioni ai seguenti indirizzi:

    https://clang.llvm.org/docs/ClangFormat.html

    https://clang.llvm.org/docs/ClangFormatStyleOptions.html

파일과 변경의 스타일 검토

`it_clangformatreview` 절은 전체 하위 시스템, 디렉터리 또는 개별 파일에서 스타일 오류, 오타와 개선점을 찾는 방법을 설명합니다.

먼저 작업 디렉터리가 깨끗한지 확인한 뒤 `clang-format -i kernel/*.[ch]`처럼 대상 C와 header 파일을 제자리 포매팅합니다. 그런 다음 반드시 `git diff`로 실제 변경을 검토합니다.

Per farlo, potete eseguire qualcosa del genere::

    # Make sure your working directory is clean!
    clang-format -i kernel/*.[ch]

E poi date un'occhiata a *git diff*.

diff를 살펴보면 `.clang-format` 스타일 옵션을 개선할 근거를 얻고, 새 `clang-format` 기능이나 버전이 기존 커널 코드에 어떤 결과를 내는지도 시험할 수 있습니다.

`clang-format`은 여러 unified diff를 읽을 수 있으므로 패치와 `git diff`에 포함된 변경 줄만 쉽게 검토할 수 있습니다. 원문은 patch reformatting script 문서 URL을 연결합니다.

특정 영역을 자동 포매팅에서 제외하려면 `// clang-format off`와 `// clang-format on` marker 사이에 코드를 둘 수 있습니다.

Per evitare che ``clang-format`` formatti alcune parti di un file, potete
scrivere nel codice::

    int formatted_code;
    // clang-format off
        void    unformatted_code  ;
    // clang-format on
    void formatted_code_again;

하지만 커널 코드에 이 marker를 상시 넣는 것은 자제해야 합니다. 개발자마다 다른 `clang-format` 버전을 쓰거나 도구를 전혀 사용하지 않을 수 있어, 소스가 특정 포매터 버전에 의존하게 되기 때문입니다.

따라서 marker는 매력적인 수단이지만 `clang-format`이 커널 개발에서 널리 정착하기 전까지는 일반적인 유지 방식으로 권장되지 않습니다.

.. _it_clangformatreview:

Revisionare lo stile di codifica per file e modifiche
-----------------------------------------------------

Eseguendo questo programma, potrete revisionare un intero sottosistema,
cartella o singoli file alla ricerca di errori di stile, refusi o
miglioramenti.

Per farlo, potete eseguire qualcosa del genere::

    # Make sure your working directory is clean!
    clang-format -i kernel/*.[ch]

E poi date un'occhiata a *git diff*.

Osservare le righe di questo diff è utile a migliorare/aggiustare
le opzioni di stile nel file di configurazione; così come per verificare
le nuove funzionalità/versioni di ``clang-format``.

``clang-format`` è in grado di leggere diversi diff unificati, quindi
potrete revisionare facilmente delle modifiche e *git diff*.
La documentazione si trova al seguente indirizzo:

    https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting

Per evitare che ``clang-format`` formatti alcune parti di un file, potete
scrivere nel codice::

    int formatted_code;
    // clang-format off
        void    unformatted_code  ;
    // clang-format on
    void formatted_code_again;

Nonostante si attraente l'idea di utilizzarlo per mantenere un file
sempre in sintonia con ``clang-format``, specialmente per file nuovi o
se siete un manutentore, ricordatevi che altre persone potrebbero usare
una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto.
Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del
kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente
utilizzato.

편집기에서 코드 블록 재포매팅

편집기 plugin을 사용하면 선택한 코드 블록을 단축키 한 번으로 재포매팅할 수 있습니다. 코드 재구성, 복잡한 구문, 여러 줄 macro의 역슬래시 정렬 등에 특히 유용합니다.

도구가 좋지 않은 결과를 낸 부분은 언제든 수동으로 고칠 수 있습니다. `clang-format` 출력은 완성본이 아니라 유용한 첫 근사치로 취급해야 합니다.

Vim, Emacs, BBEdit, Visual Studio 같은 편집기는 직접 통합을 지원합니다. Atom, Eclipse, Sublime Text, Visual Studio Code, XCode와 다른 editor·IDE도 사용할 수 있는 plugin을 찾을 수 있습니다.

블록 재포매팅 용도에는 추가 옵션으로 맞춘 두 번째 `.clang-format` 파일을 고려할 수 있습니다. 세부 옵션은 `it_clangformatextra` 절에서 다룹니다.

.. _it_clangformatreformat:

Riformattare blocchi di codice
------------------------------

Utilizzando dei plugin per il vostro editor, potete riformattare una
blocco (selezione) di codice con una singola combinazione di tasti.
Questo è particolarmente utile: quando si riorganizza il codice, per codice
complesso, macro multi-riga (e allineare le loro "barre"), eccetera.

Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove
questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione,
può essere davvero molto utile.

Questo programma si integra con molti dei più popolari editor. Alcuni di
essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente.
Al seguente indirizzo troverete le istruzioni:

    https://clang.llvm.org/docs/ClangFormat.html

Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor
e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso.

Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format``
che potete personalizzare con le vostre opzioni.
Consultare it_clangformatextra_.

지원되지 않는 커널 정렬 관례

`clang-format`은 커널 코드에서 흔한 몇 가지 관례를 지원하지 않습니다. 자주 사용하면 어떤 결과를 피하거나 무시해야 하는지 쉽게 익힐 수 있습니다.

첫 사례는 여러 단일 행 `#define`의 값 열을 맞추는 정렬입니다. 커널 원문은 macro 이름 뒤 공백으로 숫자 열을 맞추지만 포매터는 공백을 하나로 줄일 수 있습니다.

In particolare, quelli più comuni che noterete sono:

  - Allineamento di ``#define`` su una singola riga, per esempio::

        #define TRACING_MAP_BITS_DEFAULT       11
        #define TRACING_MAP_BITS_MAX           17
        #define TRACING_MAP_BITS_MIN           7

    contro::

        #define TRACING_MAP_BITS_DEFAULT 11
        #define TRACING_MAP_BITS_MAX 17
        #define TRACING_MAP_BITS_MIN 7

두 번째 사례는 구조체 지정 초기화자의 등호를 세로로 맞추는 방식입니다. `file_operations` 예제에서 커널 스타일은 `.owner`, `.open`, `.read` 등의 `=` 위치를 정렬하지만 포매터는 각 이름 바로 뒤에 공백 하나와 등호를 둡니다.

  - Allineamento dei valori iniziali, per esempio::

        static const struct file_operations uprobe_events_ops = {
                .owner          = THIS_MODULE,
                .open           = probes_open,
                .read           = seq_read,
                .llseek         = seq_lseek,
                .release        = seq_release,
                .write          = probes_write,
        };

    contro::

        static const struct file_operations uprobe_events_ops = {
                .owner = THIS_MODULE,
                .open = probes_open,
                .read = seq_read,
                .llseek = seq_lseek,
                .release = seq_release,
                .write = probes_write,
        };

두 출력 모두 C 의미는 같지만 기존 파일의 시각적 관례와 diff 크기에 영향을 줍니다. 자동 결과를 그대로 적용하지 말고 주변 코드 스타일을 기준으로 필요한 정렬을 복원해야 합니다.

.. _it_clangformatmissing:

Cose non supportate
-------------------

``clang-format`` non ha il supporto per alcune cose che sono comuni nel
codice del kernel. Sono facili da ricordare; quindi, se lo usate
regolarmente, imparerete rapidamente a evitare/ignorare certi problemi.

In particolare, quelli più comuni che noterete sono:

  - Allineamento di ``#define`` su una singola riga, per esempio::

        #define TRACING_MAP_BITS_DEFAULT       11
        #define TRACING_MAP_BITS_MAX           17
        #define TRACING_MAP_BITS_MIN           7

    contro::

        #define TRACING_MAP_BITS_DEFAULT 11
        #define TRACING_MAP_BITS_MAX 17
        #define TRACING_MAP_BITS_MIN 7

  - Allineamento dei valori iniziali, per esempio::

        static const struct file_operations uprobe_events_ops = {
                .owner          = THIS_MODULE,
                .open           = probes_open,
                .read           = seq_read,
                .llseek         = seq_lseek,
                .release        = seq_release,
                .write          = probes_write,
        };

    contro::

        static const struct file_operations uprobe_events_ops = {
                .owner = THIS_MODULE,
                .open = probes_open,
                .read = seq_read,
                .llseek = seq_lseek,
                .release = seq_release,
                .write = probes_write,
        };

추가 기능과 스타일 옵션

기본 설정은 현재 커널 코드와 포매터 출력의 차이를 최소화하기 위해 일부 스타일 옵션과 기능을 비활성화합니다. 작은 diff는 파일과 패치 검토를 단순하게 합니다.

특정 하위 시스템, 디렉터리 또는 파일의 기존 스타일이 다르면 일부 옵션을 켜는 편이 더 나은 결과를 낼 수 있습니다.

예시 옵션은 연속 대입 정렬 `AlignConsecutiveAssignments`, 연속 선언 정렬 `AlignConsecutiveDeclarations`, 주석 문장 재배치 `ReflowComments`, `#include` 정렬 `SortIncludes`입니다.

이 옵션들은 파일 전체를 일괄 변경하기보다 개별 블록을 재포매팅할 때 유용한 경우가 많습니다. 또는 편집기·IDE 전용의 별도 `.clang-format` 설정을 만들 수 있습니다.

.. _it_clangformatextra:

Funzionalità e opzioni aggiuntive
---------------------------------

Al fine di minimizzare le differenze fra il codice attuale e l'output
del programma, alcune opzioni di stile e funzionalità non sono abilitate
nella configurazione base. In altre parole, lo scopo è di rendere le
differenze le più piccole possibili, permettendo la semplificazione
della revisione di file, differenze e modifiche.

In altri casi (per esempio un particolare sottosistema/cartella/file), lo
stile del kernel potrebbe essere diverso e abilitare alcune di queste
opzioni potrebbe dare risultati migliori.

Per esempio:

  - Allineare assegnamenti (``AlignConsecutiveAssignments``).

  - Allineare dichiarazioni (``AlignConsecutiveDeclarations``).

  - Riorganizzare il testo nei commenti (``ReflowComments``).

  - Ordinare gli ``#include`` (``SortIncludes``).

Piuttosto che per interi file, solitamente sono utili per la riformattazione
di singoli blocchi. In alternativa, potete creare un altro file
``.clang-format`` da utilizzare con il vostro editor/IDE.