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