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