Import nubots formatter and format code base

.clang-format

@@ -0,0 +1,127 @@
+---
+# C++ files
+Language: Cpp
+BasedOnStyle: Google
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveMacros: true
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: false
+AllowAllConstructorInitializersOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortLambdasOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterCaseLabel: false
+  AfterClass: false
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: true
+  BeforeElse: true
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeBraces: Custom
+BreakInheritanceList: BeforeComma
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeComma
+BreakStringLiterals: true
+ColumnLimit: 120
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+FixNamespaceComments: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  # System includes
+  - Regex: "^<.*>"
+    Priority: 1
+  # Extensions
+  - Regex: '^"extension/.*"'
+    Priority: 100
+  # Messages
+  - Regex: '^"message/.*"'
+    Priority: 101
+    # Utilities
+  - Regex: '^"utility/.*"'
+    Priority: 102
+  # Other headers
+  - Regex: '^".*"'
+    Priority: 2
+IndentCaseLabels: true
+IndentPPDirectives: BeforeHash
+IndentWrappedFunctionNames: true
+IndentWidth: 4
+KeepEmptyLinesAtTheStartOfBlocks: true
+MaxEmptyLinesToKeep: 2
+NamespaceIndentation: All
+PointerAlignment: Left
+ReflowComments: true
+SortIncludes: true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: true
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Cpp11
+TabWidth: 4
+UseTab: Never
+
+---
+# Protocol buffers
+Language: Proto
+BasedOnStyle: Google
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: true
+AlignEscapedNewlinesLeft: false
+AlignOperands: true
+AlignTrailingComments: true
+AllowShortBlocksOnASingleLine: false
+ColumnLimit: 120
+IndentWidth: 4
+KeepEmptyLinesAtTheStartOfBlocks: true
+MaxEmptyLinesToKeep: 2
+ReflowComments: true
+SortIncludes: true
+SpaceBeforeAssignmentOperators: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+TabWidth: 4
+UseTab: Never

.cmake-format.py

@@ -0,0 +1,246 @@
+#
+# MIT License
+#
+# Copyright (c) 2019 NUbots
+#
+# This file is part of the NUSim codebase.
+# See https://github.com/NUbots/NUSim for further info.
+#
+# Imported from NUbots (https://github.com/NUbots/NUbots) so that CMake files format
+# identically in both repos; only the custom-command entries below differ.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+# ----------------------------------
+# Options affecting listfile parsing
+# ----------------------------------
+with section("parse"):
+
+    # Specify structure for custom cmake functions
+    additional_commands = {}
+
+    # Specify variable tags.
+    vartags = []
+
+    # Specify property tags.
+    proptags = []
+
+# -----------------------------
+# Options affecting formatting.
+# -----------------------------
+with section("format"):
+
+    # How wide to allow formatted cmake files
+    line_width = 120
+
+    # How many spaces to tab for indent
+    tab_size = 2
+
+    # If an argument group contains more than this many sub-groups (parg or kwarg
+    # groups) then force it to a vertical layout.
+    max_subgroups_hwrap = 2
+
+    # If a positional argument group contains more than this many arguments, then
+    # force it to a vertical layout.
+    max_pargs_hwrap = 6
+
+    # If a cmdline positional group consumes more than this many lines without
+    # nesting, then invalidate the layout (and nest)
+    max_rows_cmdline = 2
+
+    # If true, separate flow control names from their parentheses with a space
+    separate_ctrl_name_with_space = False
+
+    # If true, separate function names from parentheses with a space
+    separate_fn_name_with_space = False
+
+    # If a statement is wrapped to more than one line, than dangle the closing
+    # parenthesis on its own line.
+    dangle_parens = True
+
+    # If the trailing parenthesis must be 'dangled' on its on line, then align it
+    # to this reference: `prefix`: the start of the statement,  `prefix-indent`:
+    # the start of the statement, plus one indentation  level, `child`: align to
+    # the column of the arguments
+    dangle_align = "prefix"
+
+    # If the statement spelling length (including space and parenthesis) is
+    # smaller than this amount, then force reject nested layouts.
+    min_prefix_chars = 4
+
+    # If the statement spelling length (including space and parenthesis) is larger
+    # than the tab width by more than this amount, then force reject un-nested
+    # layouts.
+    max_prefix_chars = 10
+
+    # If a candidate layout is wrapped horizontally but it exceeds this many
+    # lines, then reject the layout.
+    max_lines_hwrap = 2
+
+    # What style line endings to use in the output.
+    line_ending = "unix"
+
+    # Format command names consistently as 'lower' or 'upper' case
+    command_case = "canonical"
+
+    # Format keywords consistently as 'lower' or 'upper' case
+    keyword_case = "upper"
+
+    # A list of command names which should always be wrapped
+    always_wrap = ["K1SIM_ROLE", "k1sim_role"]
+
+    # If true, the argument lists which are known to be sortable will be sorted
+    # lexicographicall
+    enable_sort = True
+
+    # If true, the parsers may infer whether or not an argument list is sortable
+    # (without annotation).
+    autosort = True
+
+    # By default, if cmake-format cannot successfully fit everything into the
+    # desired linewidth it will apply the last, most agressive attempt that it
+    # made. If this flag is True, however, cmake-format will print error, exit
+    # with non-zero status code, and write-out nothing
+    require_valid_layout = False
+
+    # A dictionary mapping layout nodes to a list of wrap decisions. See the
+    # documentation for more information.
+    layout_passes = {}
+
+# ------------------------------------------------
+# Options affecting comment reflow and formatting.
+# ------------------------------------------------
+with section("markup"):
+
+    # What character to use for bulleted lists
+    bullet_char = "*"
+
+    # What character to use as punctuation after numerals in an enumerated list
+    enum_char = "."
+
+    # If comment markup is enabled, don't reflow the first comment block in each
+    # listfile. Use this to preserve formatting of your copyright/license
+    # statements.
+    first_comment_is_literal = False
+
+    # If comment markup is enabled, don't reflow any comment block which matches
+    # this (regex) pattern. Default is `None` (disabled).
+    literal_comment_pattern = None
+
+    # Regular expression to match preformat fences in comments default=
+    # ``r'^\s*([`~]{3}[`~]*)(.*)$'``
+    fence_pattern = "^\\s*([`~]{3}[`~]*)(.*)$"
+
+    # Regular expression to match rulers in comments default=
+    # ``r'^\s*[^\w\s]{3}.*[^\w\s]{3}$'``
+    ruler_pattern = "^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$"
+
+    # If a comment line matches starts with this pattern then it is explicitly a
+    # trailing comment for the preceeding argument. Default is '#<'
+    explicit_trailing_pattern = "#<"
+
+    # If a comment line starts with at least this many consecutive hash
+    # characters, then don't lstrip() them off. This allows for lazy hash rulers
+    # where the first hash char is not separated by space
+    hashruler_min_length = 10
+
+    # If true, then insert a space between the first hash char and remaining hash
+    # chars in a hash ruler, and normalize its length to fill the column
+    canonicalize_hashrulers = True
+
+    # enable comment markup parsing and reflow
+    enable_markup = True
+
+# ----------------------------
+# Options affecting the linter
+# ----------------------------
+with section("lint"):
+
+    # a list of lint codes to disable
+    disabled_codes = []
+
+    # regular expression pattern describing valid function names
+    function_pattern = "[0-9a-z_]+"
+
+    # regular expression pattern describing valid macro names
+    macro_pattern = "[0-9A-Z_]+"
+
+    # regular expression pattern describing valid names for variables with global
+    # scope
+    global_var_pattern = "[0-9A-Z][0-9A-Z_]+"
+
+    # regular expression pattern describing valid names for variables with global
+    # scope (but internal semantic)
+    internal_var_pattern = "_[0-9A-Z][0-9A-Z_]+"
+
+    # regular expression pattern describing valid names for variables with local
+    # scope
+    local_var_pattern = "[0-9a-z_]+"
+
+    # regular expression pattern describing valid names for privatedirectory
+    # variables
+    private_var_pattern = "_[0-9a-z_]+"
+
+    # regular expression pattern describing valid names for publicdirectory
+    # variables
+    public_var_pattern = "[0-9A-Z][0-9A-Z_]+"
+
+    # regular expression pattern describing valid names for keywords used in
+    # functions or macros
+    keyword_pattern = "[0-9A-Z_]+"
+
+    # In the heuristic for C0201, how many conditionals to match within a loop in
+    # before considering the loop a parser.
+    max_conditionals_custom_parser = 2
+
+    # Require at least this many newlines between statements
+    min_statement_spacing = 1
+
+    # Require no more than this many newlines between statements
+    max_statement_spacing = 1
+    max_returns = 6
+    max_branches = 12
+    max_arguments = 5
+    max_localvars = 15
+    max_statements = 50
+
+# -------------------------------
+# Options affecting file encoding
+# -------------------------------
+with section("encode"):
+
+    # If true, emit the unicode byte-order mark (BOM) at the start of the file
+    emit_byteorder_mark = False
+
+    # Specify the encoding of the input file. Defaults to utf-8
+    input_encoding = "utf-8"
+
+    # Specify the encoding of the output file. Defaults to utf-8. Note that cmake
+    # only claims to support utf-8 so be careful when using anything else
+    output_encoding = "utf-8"
+
+# -------------------------------------
+# Miscellaneous configurations options.
+# -------------------------------------
+with section("misc"):
+
+    # A dictionary containing any per-command configuration overrides. Currently
+    # only `command_case` is supported.
+    per_command = {}

docs/K1_MUJOCO_SETUP.md

@@ -179,6 +179,22 @@ The C++ deploy MuJoCo version is pinned in `cmake/MuJoCoTarget.cmake`, `docker/D
 `tools/install_deps.sh`. Keep the training side (the mujoco_playground fork, §7) on the same MuJoCo
 version to avoid a sim2sim gap; bumping one means bumping **all** and rebuilding the image (`./b image`).
 
+### Formatting
+
+`./b format` runs the same formatters, at the same pinned versions and against the same configs, as
+NUbots: clang-format 14.0.6 (`.clang-format`), cmake-format (`.cmake-format.py`), isort and black. A
+given file therefore formats identically in either repo.
+
+```bash
+./b format              # files that differ from origin/main
+./b format --all        # every tracked file
+./b format --check      # print a diff instead of writing; exits 1 if anything differs
+./b format '*.cpp'      # limit to a glob
+```
+
+It runs on the host out of the uv environment (`uv sync` happens automatically), not in the docker
+image. `mujoco/idl_gen/` is excluded: it is fastddsgen output, regenerated by the build.
+
 ### Extra `./b` commands
 
 - **`./b image`** — (re)build the docker toolchain image. `./b build` only builds it when it's *missing*, so