From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 09A9142805; Wed, 22 Mar 2023 18:07:13 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E3B1542C76; Wed, 22 Mar 2023 18:07:03 +0100 (CET) Received: from mail-pl1-f171.google.com (mail-pl1-f171.google.com [209.85.214.171]) by mails.dpdk.org (Postfix) with ESMTP id 909394282D for ; Wed, 22 Mar 2023 18:07:01 +0100 (CET) Received: by mail-pl1-f171.google.com with SMTP id kq3so7483221plb.13 for ; Wed, 22 Mar 2023 10:07:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20210112.gappssmtp.com; s=20210112; t=1679504820; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=0yXKBH6I1stiduY1hTpu4Uw35o6Qk/lmXA+06SpTH6o=; b=pgTUMbmVOs4yJRmLX5snflq+oA2GvdTB2B2iENr8kEbJehdQyOMPiJUWo3g+LYgA/V Wsx3xUD3ow/bewN2TdTiXcEXroJ8C8D/Z3hy9RVyFD8tRJkzClf1B8yUWoDyqHzwUnQB g67MLPwfljjhffGucZZ0w7etQlWSrHSvuroBdeZbsVqHSEJhfTxWoQE15vFRS69zpppx xq0YeitU505TUG5ZfFYZUCTSanABB4RU6yFtt29W2SEDADSWYF1rlFOGzTfjy6DWVeeE FlE3+R9rfu1c/SaDcba6yJYNr2FRHKpuY/uzjvpd7pnLxosHBJoeLP21IhY1ErrMBkP6 +7aQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1679504820; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=0yXKBH6I1stiduY1hTpu4Uw35o6Qk/lmXA+06SpTH6o=; b=E6KIIPAdu2DcvQfOAJpI1L/En7rZBAsnMkOZ5JDqAfzCNiCS8DfTUXuE34MRLnfCyk 8DwMwanf45zUMfgL6UARP1dwtK2ToBbcI8rSlcuhdLPrYY8IC2soaQ432CP2v2PKrKj5 YpLYXMt+xdEfDfj9O0QjaLc6MwFZpjM8Fhew4pX33SY49hXTFwOURxBmgky+IP0azj1O xMs7bcSbq8l6m2RGgcCYLDV+nDorvVcWPOtimt549ak6k7J/7WURQPbEr2UV/Wuj4LOP KdgQknhVohIkmNT4vL5SeH2WJd2xxD9lihzaQnDNv3AGQqtXweqacd1hWm4MPmWUberR mkZQ== X-Gm-Message-State: AO0yUKX4K4zoFkOahkF+lic/fA2ksKR1wtzlcEzSe1olPkWOat2HwnTK ZRR0E7DA0GPra2LsXumFA0YgZoZcFHQWhdoxqxs7WA== X-Google-Smtp-Source: AK7set8FlOfls6LGN/YbUR0IG27AqCnFh6+W4KzLEyKFW1W/r87KOJAEQbzkDDtFmT4E2njdG4CacA== X-Received: by 2002:a05:6a20:b29f:b0:cc:a8d7:ad7e with SMTP id ei31-20020a056a20b29f00b000cca8d7ad7emr198017pzb.60.1679504820408; Wed, 22 Mar 2023 10:07:00 -0700 (PDT) Received: from hermes.local (204-195-120-218.wavecable.com. [204.195.120.218]) by smtp.gmail.com with ESMTPSA id c18-20020a62e812000000b006227c3d5e29sm10698765pfi.16.2023.03.22.10.06.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Mar 2023 10:06:59 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger Subject: [RFC 2/2] doc: add clang-format documentation Date: Wed, 22 Mar 2023 10:06:55 -0700 Message-Id: <20230322170655.45166-3-stephen@networkplumber.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230322170655.45166-1-stephen@networkplumber.org> References: <20230322170655.45166-1-stephen@networkplumber.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Modify existing Linux kernel documentation of clang-format to match usage in DPDK. Still waiting for right to reuse acknowledgment for original Linux kernel author of this documentation. If not ok, then can just write a new version. Probably need some wording about applicability to base driver code. Signed-off-by: Stephen Hemminger --- doc/guides/contributing/clang-format.rst | 184 +++++++++++++++++++++++ doc/guides/contributing/index.rst | 1 + 2 files changed, 185 insertions(+) create mode 100644 doc/guides/contributing/clang-format.rst diff --git a/doc/guides/contributing/clang-format.rst b/doc/guides/contributing/clang-format.rst new file mode 100644 index 000000000000..4b3dda0d520c --- /dev/null +++ b/doc/guides/contributing/clang-format.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2023 The DPDK contributors + Original from Linux kernel docs + +.. _clangformat: + +clang-format +============ + +``clang-format`` is a tool to format C/C++/... code according to +a set of rules and heuristics. Like most tools, it is not perfect +nor covers every single case, but it is good enough to be helpful. + +``clang-format`` can be used for several purposes: + + - Quickly reformat a block of code to the DPDK style. Specially useful + when moving code around and aligning/sorting. See clangformatreformat_. + + - Spot style mistakes, typos and possible improvements in files + you maintain, patches you review, diffs, etc. See clangformatreview_. + + - Help you follow the coding style rules, specially useful for those + new to DPDK development or working at the same time in several + projects with different coding styles. + +Its configuration file is ``.clang-format`` in the root of the DPDK tree. +The rules contained there try to approximate the most common DPDK +coding style. They also try to follow :ref:`coding_style` +as much as possible. A driver may have a slightly different style, +it is possible that you may want to tweak the defaults for a particular +folder. To do so, you can override the defaults by writing +another ``.clang-format`` file in a subfolder. + +The tool itself has already been included in the repositories of popular +Linux distributions for a long time. Search for ``clang-format`` in +your repositories. Otherwise, you can either download pre-built +LLVM/clang binaries or build the source code from: + + https://releases.llvm.org/download.html + +See more information about the tool at: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _clangformatreview: + +Review files and patches for coding style +----------------------------------------- + +By running the tool in its inline mode, you can review full subsystems, +folders or individual files for code style mistakes, typos or improvements. + +To do so, you can run something like:: + + # Make sure your working directory is clean! + clang-format -i driver/*.[ch] + +And then take a look at the git diff. + +Counting the lines of such a diff is also useful for improving/tweaking +the style options in the configuration file; as well as testing new +``clang-format`` features/versions. + +``clang-format`` also supports reading unified diffs, so you can review +patches and git diffs easily. See the documentation at: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +To avoid ``clang-format`` formatting some portion of a file, you can do:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +While it might be tempting to use this to keep a file always in sync with +``clang-format``, specially if you are writing new files or if you are +a maintainer, please note that people might be running different +``clang-format`` versions or not have it available at all. Therefore, +you should probably refrain yourself from using this for all sources. + +.. _clangformatreformat: + +Reformatting blocks of code +--------------------------- + +By using an integration with your text editor, you can reformat arbitrary +blocks (selections) of code with a single keystroke. This is specially +useful when moving code around, for complex code that is deeply intended, +for multi-line macros (and aligning their backslashes), etc. + +Remember that you can always tweak the changes afterwards in those cases +where the tool did not do an optimal job. But as a first approximation, +it can be very useful. + +There are integrations for many popular text editors. For some of them, +like vim, emacs, BBEdit and Visual Studio you can find support built-in. +For instructions, read the appropriate section at: + + https://clang.llvm.org/docs/ClangFormat.html + +For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other +editors and IDEs you should be able to find ready-to-use plugins. + +For this use case, consider using a secondary ``.clang-format`` +so that you can tweak a few options. See clangformatextra_. + + +.. _clangformatmissing: + +Missing support +--------------- + +``clang-format`` is missing support for some things that are common +in DPDK code. They are easy to remember, so if you use the tool +regularly, you will quickly learn to avoid/ignore those. + +In particular, some very common ones you will notice are: + + - Aligned blocks of one-line ``#defines``, e.g.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + vs.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + - Aligned designated initializers, e.g.:: + + static const struct eth_dev_ops ops = { + .dev_close = eth_dev_close, + .dev_start = eth_dev_start, + .dev_stop = eth_dev_stop, + .dev_configure = eth_dev_configure, + .dev_infos_get = eth_dev_info, + }; + + vs.:: + + static const struct eth_dev_ops ops = { + .dev_close = eth_dev_close, + .dev_start = eth_dev_start, + .dev_stop = eth_dev_stop, + .dev_configure = eth_dev_configure, + .dev_infos_get = eth_dev_info, + }; + + +.. _clangformatextra: + +Extra features/options +---------------------- + +Some features/style options are not enabled by default in the configuration +file in order to minimize the differences between the output and the current +code. In other words, to make the difference as small as possible, +which makes reviewing full-file style, as well diffs and patches as easy +as possible. + +In other cases (e.g. particular subsystems/folders/files), the DPDK style +might be different and enabling some of these options may approximate +better the style there. + +For instance: + + - Aligning assignments (``AlignConsecutiveAssignments``). + + - Aligning declarations (``AlignConsecutiveDeclarations``). + + - Reflowing text in comments (``ReflowComments``). + + - Sorting ``#includes`` (``SortIncludes``). + +They are typically useful for block re-formatting, rather than full-file. +You might want to create another ``.clang-format`` file and use that one +from your editor/IDE instead. diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst index 7a9e6b368e1c..68e70f2350a4 100644 --- a/doc/guides/contributing/index.rst +++ b/doc/guides/contributing/index.rst @@ -9,6 +9,7 @@ Contributor's Guidelines :numbered: coding_style + clang-format design abi_policy abi_versioning -- 2.39.2