1.. _docs-pw-style: 2 3============ 4Style guides 5============ 6.. tip:: 7 8 Pigweed runs ``pw format`` as part of ``pw presubmit`` to perform some code 9 formatting checks. To speed up the review process, consider adding ``pw 10 presubmit`` as a git push hook using the following command: 11 ``pw presubmit --install`` 12 13.. grid:: 2 14 15 .. grid-item-card:: :octicon:`diff-added` C++ style 16 :link: docs-pw-style-cpp 17 :link-type: ref 18 :class-item: sales-pitch-cta-primary 19 20 Our C++ style guide: an extension of the Google C++ style with further 21 restrictions and guidance for embedded 22 23 24 .. grid-item-card:: :octicon:`pencil` Commit messages 25 :link: docs-pw-style-commit-message 26 :link-type: ref 27 :class-item: sales-pitch-cta-secondary 28 29 How to format commit messages for Pigweed 30 31.. grid:: 2 32 33 .. grid-item-card:: :octicon:`code-square` Protobuf 34 :link: docs-pw-style-protobuf 35 :link-type: ref 36 :class-item: sales-pitch-cta-secondary 37 38 How to structure reference documentation for C++ code 39 40 .. grid-item-card:: :octicon:`terminal` CLI style 41 :link: docs-pw-style-cli 42 :link-type: ref 43 :class-item: sales-pitch-cta-secondary 44 45 How to style your CLI program so that it behaves 46 consistently with other Pigweed CLI programs 47 48-------------------------- 49Documentation style guides 50-------------------------- 51See the :ref:`documentation contributors homepage <docs-contrib-docs>`. 52 53.. todo-check: disable 54 55.. _docs-pw-todo-style: 56 57---------- 58TODO style 59---------- 60Pigweed expects TODO annotations to adhere to the following style: 61 62.. todo-check: disable 63 64.. code-block:: py 65 66 # TODO: https://pwbug.dev/123456789 - Some explanation of the problem at 67 # hand, which may span multiple lines if necessary. 68 69.. todo-check: enable 70 71.. admonition:: Note 72 73 Please include the ``https://`` to make it easier for code editors to 74 identify the bugs as URLs. 75 76In Markdown docs like 77`Rustdoc <https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html>`_ 78the following format is preferred: 79 80.. todo-check: disable 81 82.. code-block:: rs 83 84 //! TODO: <pwbug.dev/123456789> - Explanation. 85 86.. todo-check: enable 87 88.. admonition:: Note 89 90 For Rustdoc, omit ``https://``. The additional Markdown syntax makes the 91 link explicit, and including ``https://`` makes the preamble disruptively 92 lengthy. 93 94Some older forms are still allowed but discouraged. We allow the following 95formats, ordered by preference with the preferred patterns at the top: 96 97.. todo-check: disable 98 99.. code-block:: py 100 101 # TODO: https://pwbug.dev/1234 - Explanation. 102 # TODO: b/1234 - Explanation. 103 # TODO: username@ - Explanation. 104 # TODO: [email protected] - Explanation. 105 # TODO(b/1234): Explanation. 106 # TODO(username): Explanation. 107 108.. todo-check: enable 109 110.. todo-check: enable 111 112----------------- 113Copyright headers 114----------------- 115Every Pigweed file containing source code must include copyright and license 116information. This includes any JS/CSS files that you might be serving out to 117browsers. 118 119Apache header source code files that support ``//`` comments: 120 121.. code-block:: none 122 123 // Copyright 2023 The Pigweed Authors 124 // 125 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 126 // use this file except in compliance with the License. You may obtain a copy of 127 // the License at 128 // 129 // https://www.apache.org/licenses/LICENSE-2.0 130 // 131 // Unless required by applicable law or agreed to in writing, software 132 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 133 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 134 // License for the specific language governing permissions and limitations under 135 // the License. 136 137Apache header for source code files that support ``#`` comments: 138 139.. code-block:: none 140 141 # Copyright 2023 The Pigweed Authors 142 # 143 # Licensed under the Apache License, Version 2.0 (the "License"); you may not 144 # use this file except in compliance with the License. You may obtain a copy of 145 # the License at 146 # 147 # https://www.apache.org/licenses/LICENSE-2.0 148 # 149 # Unless required by applicable law or agreed to in writing, software 150 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 151 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 152 # License for the specific language governing permissions and limitations under 153 # the License. 154 155 156.. _python-style: 157 158------------ 159Python style 160------------ 161Pigweed uses the standard Python style: PEP8, which is available on the web at 162https://www.python.org/dev/peps/pep-0008/. All Pigweed Python code should pass 163``pw format``, which invokes ``black`` with a couple options. 164 165Python versions 166=============== 167Pigweed officially supports :ref:`a few Python versions 168<docs-concepts-python-version>`. Upstream Pigweed code must support those Python 169versions. The only exception is :ref:`module-pw_env_setup`, which must also 170support Python 2 and 3.6. 171 172--------------- 173Build files: GN 174--------------- 175Each Pigweed source module requires a GN build file named BUILD.gn. This 176encapsulates the build targets and specifies their sources and dependencies. 177GN build files use a format similar to `Bazel's BUILD files 178<https://docs.bazel.build/versions/main/build-ref.html>`_ 179(see the `Bazel style guide 180<https://docs.bazel.build/versions/main/skylark/build-style.html>`_). 181 182C/C++ build targets include a list of fields. The primary fields are: 183 184* ``<public>`` -- public header files 185* ``<sources>`` -- source files and private header files 186* ``<public_configs>`` -- public build configuration 187* ``<configs>`` -- private build configuration 188* ``<public_deps>`` -- public dependencies 189* ``<deps>`` -- private dependencies 190 191Assets within each field must be listed in alphabetical order. 192 193.. code-block:: cpp 194 195 # Here is a brief example of a GN build file. 196 197 import("$dir_pw_unit_test/test.gni") 198 199 config("public_include_path") { 200 include_dirs = [ "public" ] 201 visibility = [":*"] 202 } 203 204 pw_source_set("pw_sample_module") { 205 public = [ "public/pw_sample_module/sample_module.h" ] 206 sources = [ 207 "public/pw_sample_module/internal/secret_header.h", 208 "sample_module.cc", 209 "used_by_sample_module.cc", 210 ] 211 public_configs = [ ":public_include_path" ] 212 public_deps = [ dir_pw_status ] 213 deps = [ dir_pw_varint ] 214 } 215 216 pw_test_group("tests") { 217 tests = [ ":sample_module_test" ] 218 } 219 220 pw_test("sample_module_test") { 221 sources = [ "sample_module_test.cc" ] 222 deps = [ ":sample_module" ] 223 } 224 225 pw_doc_group("docs") { 226 sources = [ "docs.rst" ] 227 } 228 229------------------ 230Build files: Bazel 231------------------ 232Build files for the Bazel build system must be named ``BUILD.bazel``. Bazel can 233interpret files named just ``BUILD``, but Pigweed uses ``BUILD.bazel`` to avoid 234ambiguity with other build systems or tooling. 235 236Pigweed's Bazel files follow the `Bazel style guide 237<https://docs.bazel.build/versions/main/skylark/build-style.html>`_. 238 239------------------ 240Build files: Soong 241------------------ 242Build files (blueprints) for the Soong build system must be named 243``Android.bp``. The way Pigweed modules and backends are used is documented in 244:ref:`module-pw_build_android`. 245 246.. _owners-style: 247 248-------------------- 249Code Owners (OWNERS) 250-------------------- 251If you use Gerrit for source code hosting and have the 252`code-owners <https://android-review.googlesource.com/plugins/code-owners/Documentation/backend-find-owners.html>`__ 253plug-in enabled Pigweed can help you enforce consistent styling on those files 254and also detects some errors. 255 256The styling follows these rules. 257 258#. Content is grouped by type of line (Access grant, include, etc). 259#. Each grouping is sorted alphabetically. 260#. Groups are placed the following order with a blank line separating each 261 grouping. 262 263 * "set noparent" line 264 * "include" lines 265 * "file:" lines 266 * user grants (some examples: "*", "[email protected]") 267 * "per-file:" lines 268 269This plugin will, by default, act upon any file named "OWNERS". 270 271.. toctree:: 272 :hidden: 273 274 C++ <style/cpp> 275 Commit message <style/commit_message> 276 CLI <style/cli> 277 Protobuf <style/protobuf> 278 reStructuredText <style/rest> 279 Doxygen <style/doxygen> 280 Writing <style/writing> 281