Lines Matching +full:code +full:- +full:format +full:- +full:check
1 .. _module-pw_presubmit:
6 .. pigweed-module::
10 checking and fixing code format. It also includes the presubmit check script for
19 The ``pw_presubmit`` module also includes ``pw format``, a tool that provides a
20 unified interface for automatically formatting code in a variety of languages.
21 With ``pw format``, you can format Bazel, C, C++, Python, GN, and Go code
22 according to configurations defined by your project. ``pw format`` leverages
23 existing tools like ``clang-format``, and it’s simple to add support for new
28 :alt: ``pw format`` demo
34 .. todo-check: disable
36 * Check code format of several languages including C, C++, and Python
47 * Forbid non-inclusive language
48 * Check format of TODO lines
52 .. todo-check: enable
54 -------------
56 -------------
59 -------------------------------------------
60 Creating a presubmit check for your project
61 -------------------------------------------
62 Creating a presubmit check for a project using ``pw_presubmit`` is simple, but
63 requires some customization. Projects must define their own presubmit check
67 :ref:`pw_cli <module-pw_cli>` plugin, so that it can be run as ``pw
70 Setting up the command-line interface
72 The ``pw_presubmit.cli`` module sets up the command-line interface for a
77 ----------------------------------------------
88 -------------------------------
94 --------------------------
95 The ``pw_presubmit`` command line interface includes an ``--output-directory``
99 or running ``pw presubmit --clean``.
101 .. _module-pw_presubmit-presubmit-checks:
105 A presubmit check is defined as a function or other callable. The function must
114 .. code-block:: python
125 subprocess.run(['make', 'release'], check=True)
127 Presubmit checks functions are grouped into "programs" -- a named series of
130 :ref:`example script <example-script>` uses ``pw_presubmit.Programs`` to define
135 skipped. This can be overridden with the ``--base`` and ``--full`` arguments to
136 ``pw presubmit``. In automated testing ``--full`` is recommended, except for
137 lint/format checks where ``--base HEAD~1`` is recommended.
161 --------
168 * ``_func``: Substep code
176 -------------------------
180 Code Formatting
186 all use language-specific formatters like clang-format or black.
190 * `CSS <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/178810>`_
191 * `JSON <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/171991>`_
192 * `reStructuredText <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/168541>`_
193 * `TypeScript <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/164825>`_
195 These will suggest fixes using ``pw format --fix``.
197 Options for code formatting can be specified in the ``pigweed.json`` file
198 (see also :ref:`SEED-0101 <seed-0101>`). These apply to both ``pw presubmit``
199 steps that check code formatting and ``pw format`` commands that either check
200 or fix code formatting.
212 .. code-block:: json
217 "format": {
231 Blocks of code can be required to be kept in sorted order using comments like
234 .. code-block:: python
236 # keep-sorted: start
240 # keep-sorted: end
243 presubmit program. Adding ``ignore-case`` to the start line will use
244 case-insensitive sorting.
247 are preserved, even with ``ignore-case``. To allow duplicates, add
248 ``allow-dupes`` to the start line.
250 Prefixes can be ignored by adding ``ignore-prefix=`` followed by a
251 comma-separated list of prefixes. The list below will be kept in this order.
254 .. code-block:: python
256 # keep-sorted: start ignore-prefix=',"
260 # keep-sorted: end
264 ``sticky-comments=no``.
266 .. todo-check: disable
268 .. code-block:: python
270 # keep-sorted: start
271 # TODO: b/1234 - Fix this.
273 # TODO: b/5678 - Also fix this.
275 # keep-sorted: end
277 .. todo-check: enable
279 By default, the prefix of the keep-sorted line is assumed to be the comment
281 ``sticky-comments=%,#`` to the start line.
284 Thus, the following block is already sorted. keep-sorted blocks can not be
285 nested, so there's no ability to add a keep-sorted block for the sub-items.
287 .. code-block::
289 # keep-sorted: start
294 # keep-sorted: end
296 The presubmit check will suggest fixes using ``pw keep-sorted --fix``.
302 Various rules can be applied to .gitmodules files. This check can be included
309 must be on a Google-managed Gerrit server.
311 Google-managed Gerrit URLs for submodules most be in this list. Entries
312 should be like ``pigweed`` for ``pigweed-review.googlesource.com``.
328 There's a ``pragma_once`` check that confirms the first non-comment line of
334 There's an ``ifndef_guard`` check that confirms the first two non-comment lines
340 This check is not used in Pigweed itself but is available to projects using
343 .. todo-check: disable
347 There's a check that confirms ``TODO`` lines match a given format. Upstream
348 Pigweed expects these to look like ``TODO: https://pwbug.dev/### -
352 :ref:`docs-pw-todo-style`.
354 .. todo-check: enable
359 and ``gn_python_check``. They assume there's a top-level ``python`` GN target.
365 .. inclusive-language: disable
367 The inclusive language check looks for words that are typical of non-inclusive
368 code, like using "master" and "slave" in place of "primary" and "secondary" or
369 "sanity check" in place of "consistency check".
371 .. inclusive-language: enable
374 "inclusive-language: ignore" on the line in question or the line above it, or
375 for entire blocks by using "inclusive-language: disable" before the block and
376 "inclusive-language: enable" after the block.
379 .. is repeated here: inclusive-language: enable.
383 There's a check that requires folders matching specific patterns contain
389 source files and is discussed in `Code Formatting`.
393 The JSON check requires all ``*.json`` files to be valid JSON files. It can be
400 ``source_in_build.gn(filter)`` and similar functions to a presubmit check. The
401 CMake check additionally requires a callable that invokes CMake with appropriate
405 ------------
409 .. _example-script:
413 --------
415 <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`_ using
431 A simple example presubmit check script follows. This can be copied-and-pasted
432 to serve as a starting point for a project's presubmit check script.
434 See ``pigweed_presubmit.py`` for a more complex presubmit check script example.
436 .. code-block:: python
438 """Example presubmit check script."""
482 build.gn_check(ctx) # Run after building to check generated files.
498 # Use the upstream pragma_once check, but apply a different set of path
506 # Presubmit check programs
520 # Include the upstream inclusive language check.
522 # Include just the lint-related Python checks.
545 def run(install: bool, remote_ref: str | None, **presubmit_args) -> int:
546 """Process the --install argument then invoke pw_presubmit."""
548 # Install the presubmit Git pre-push hook, if requested.
553 "pre-push",
556 "-m",
558 "--base",
560 "--remote-ref",
576 def main() -> int:
581 # Define an option for installing a Git pre-push hook for this script.
583 "--install",
585 help="Install the presubmit as a Git pre-push hook and exit.",
589 # is run as a pre-push hook. The destination variable in the parsed args
593 "--remote-ref",
596 help="Remote ref of the push command, for use by the pre-push hook.",
606 ---------------------
607 Code formatting tools
608 ---------------------
610 external code format tools. The file ``format_code.py`` can be invoked directly
611 from the command line or from ``pw`` as ``pw format``.
615 A simple example of adding support for a custom format. This code wraps the
616 built in formatter to add a new format. It could also be used to replace
619 .. code-block:: python
634 check=your_check.check,
639 def _run(exclude, **kwargs) -> int:
640 """Check and fix formatting for source files in the repo."""
654 .. pw_presubmit-nav-end
660 format