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. If you are comfortable with Docker, you can use the [docker image
0026 used by the
0027 CI](https://github.com/acts-project/machines/blob/master/format14/Dockerfile).
0028 You can use the script located in `CI/check_format_local` similar to the
0029 description above. Other options to obtain a compatible `clang-format` version
0030 are to use your package manager (e.g. Ubuntu distributions usually offer a set of
0031 versions to install), or to use statically linked binaries from
0032 [here](https://github.com/muttleyxd/clang-tools-static-binaries)[^1] and use them with:
0033
0034 ```console
0035 CLANG_FORMAT_BINARY=<path/to/clang-format> CI/check_format $SOURCE_DIR
0036 ```
0037
0038 You can also download the required changes by clicking on *Summary* on the top left-hand
0039 portion of the CI job and scrolling down to the bottom of the page (see *Changed*).
0040 However, it is suggested to run the `CI/check_format` locally before committing, to not
0041 clog the shared resources with repeated checks.
0042
0043 ## Python formatting
0044
0045 Formatting of the Python source code uses the library
0046 [`black`](https://github.com/psf/black). To run it, you can locally install the
0047 `black` package. You can use `pip` to install it:
0048
0049 ```console
0050 $ pip install black
0051 $ black <source>
0052 ```
0053
0054 :::{tip}
0055 It is **strongly recommended** to use a [virtual
0056 environment](https://realpython.com/python-virtual-environments-a-primer/) for
0057 this purpose! For example, run
0058
0059 ```console
0060 $ python -m venv venv
0061 $ source venv/bin/activate
0062 ```
0063
0064 and then install and use black. You can also use a tool like
0065 [`pipx`](https://github.com/pypa/pipx) to simplify this.
0066 :::
0067
0068 [^1]: This repository is external to the ACTS project, so proceed with caution!
