.. _coding_style:


Coding Style Guidelines
#######################

.. toctree::
   :maxdepth: 1

   naming.rst
   code.rst
   cmake.rst
   devicetree.rst
   kconfig.rst
   python.rst


Style Tools
***********

Checkpatch
==========

The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
coding style conformity.

.. note::
   checkpatch does not currently run on Windows.

Checkpatch is available in the scripts directory. To invoke it when committing
code, make the file *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit
it to contain:

.. code-block:: bash

    #!/bin/sh
    set -e exec
    exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -

Instead of running checkpatch at each commit, you may prefer to run it only
before pushing on zephyr repo. To do this, make the file
*$ZEPHYR_BASE/.git/hooks/pre-push* executable and edit it to contain:

.. code-block:: bash

    #!/bin/sh
    remote="$1"
    url="$2"

    z40=0000000000000000000000000000000000000000

    echo "Run push hook"

    while read local_ref local_sha remote_ref remote_sha
    do
        args="$remote $url $local_ref $local_sha $remote_ref $remote_sha"
        exec ${ZEPHYR_BASE}/scripts/series-push-hook.sh $args
    done

    exit 0

If you want to override checkpatch verdict and push you branch despite reported
issues, you can add option --no-verify to the git push command.

A different way for running ``checkpatch`` is by using :ref:`check_compliance_py`
script, which does additional style and compliance related checks.

clang-format
============

The `clang-format tool <https://clang.llvm.org/docs/ClangFormat.html>`_ can
be helpful to quickly reformat large amounts of new source code to our
`Coding Style Guidelines`_ standards together with the ``.clang-format`` configuration file
provided in the repository. ``clang-format`` is well integrated into most
editors, but you can also run it manually like this:

.. code-block:: bash

   clang-format -i my_source_file.c

``clang-format`` is part of LLVM, which can be downloaded from the project
`releases page <https://github.com/llvm/llvm-project/releases>`_. Note that if
you are a Linux user, ``clang-format`` will likely be available as a package in
your distribution repositories.

When there are differences between the `Coding Style Guidelines`_ guidelines and the
formatting generated by code formatting tools, the `Coding Style Guidelines`_ guidelines
take precedence. If there is ambiguity between formatting tools and the
guidelines, maintainers may decide which style should be adopted.

dts-linter
============

The `dts-linter <https://www.npmjs.com/package/dts-linter>`_ can be helpful
to quickly reformat large amounts of devicetree files to our `Coding Style Guidelines`_
standards. You can also run it manually like this:

For individual files

.. code-block:: bash

   npx --prefix ./scripts/ci dts-linter --format --file board.dts --file board_pinctrl.dtsi --patchFile diff.patch
   git apply diff.patch

You can omit ``--file`` and this will format all files under the directory where the command
has been called. Alternatively ``--cwd`` can also be passed set the base dir where the tool
should look for files. This option is also used to make the paths relative in the patch file.

You can also fix in place with

.. code-block:: bash

   npx --prefix ./scripts/ci dts-linter --formatFixAll


Editor Integration
~~~~~~~~~~~~~~~~~~

* For VS Code: Install the extension from the `VS Code Marketplace <https://marketplace.visualstudio.com/items?itemName=KyleMicallefBonnici.dts-lsp>`_ or `Open VSIX <https://open-vsx.org/extension/KyleMicallefBonnici/dts-lsp>`_
* For other editors with LSP Client support: Use the devicetree-language-server `devicetree-language-server <https://www.npmjs.com/package/devicetree-language-server>`_

Make sure you follow `Devicetree Style Guidelines <https://docs.zephyrproject.org/latest/contribute/style/devicetree.html>`_
requirements to configure the editor correctly.