Warning, /acts/docs/contribution/run_formatting.md is written in an unsupported language. File is not indexed.
0001 (howto_format)=
0002
0003 # Source code formatting
0004
0005 ## C++ formatting: `clang-format`
0006
0007 Code formatting is handled by
0008 [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html). A configuration
0009 file is available in the repository root at `.clang-format` and should be used
0010 to automatically format the code. Many editors / IDEs support `clang-format`
0011 and also format-on-save actions.
0012
0013 The ACTS CI system will automatically check code formatting using the provided
0014 `clang-format` configuration and will notify incompatible formatting.
0015
0016 To simplify this, a script located in `CI/check_format` can be used like:
0017
0018 ```console
0019 $ CI/check_format $SOURCE_DIR
0020 ```
0021
0022 In some cases, different `clang-format` versions will result in slightly
0023 different outputs. In many cases, this is accepted by the CI. However, it is
0024 recommended to use the same major version of `clang-format` to perform local
0025 formatting. Options to obtain a compatible `clang-format` version
0026 are to use your package manager (e.g. Ubuntu distributions usually offer a set of
0027 versions to install), or to use statically linked binaries from
0028 [here](https://github.com/muttleyxd/clang-tools-static-binaries)[^1] and use them with:
0029
0030 ```console
0031 CLANG_FORMAT_BINARY=<path/to/clang-format> CI/check_format $SOURCE_DIR
0032 ```
0033
0034 You can also download the required changes by clicking on *Summary* on the top left-hand
0035 portion of the CI job and scrolling down to the bottom of the page (see *Changed*).
0036 However, it is suggested to run the `CI/check_format` locally before committing, to not
0037 clog the shared resources with repeated checks.
0038
0039 ## Python formatting
0040
0041 Formatting of the Python source code uses the library
0042 [`black`](https://github.com/psf/black). To run it, you can locally install the
0043 `black` package. You can use `pip` to install it:
0044
0045 ```console
0046 $ pip install black
0047 $ black <source>
0048 ```
0049
0050 :::{tip}
0051 It is **strongly recommended** to use a [virtual
0052 environment](https://realpython.com/python-virtual-environments-a-primer/) for
0053 this purpose! For example, run
0054
0055 ```console
0056 $ python -m venv venv
0057 $ source venv/bin/activate
0058 ```
0059
0060 and then install and use black. You can also use a tool like
0061 [`pipx`](https://github.com/pypa/pipx) to simplify this.
0062 :::
0063
0064 [^1]: This repository is external to the ACTS project, so proceed with caution!
