firefox-main/docs/code-quality/coding-style/format_cpp_code_with_clang-format.md

Source code

Revision control

Copy as Markdown

Other Tools

# Formatting C++ Code With clang-format
Mozilla uses the Google coding style for whitespace, which is enforced
specific version of the binary will be installed when
`./mach bootstrap` is run. We build our own binaries and update them
as needed.
Options are explicitly defined [in clang-format
If the options are changed in clang upstream, this might cause some
changes in the Firefox tree. For this reason, it is best to use the
mozilla-provided binaries.
## Manual formatting
We provide mach subcommands for running [clang-format] from the
command-line. These wrappers handle ensuring the correct version of
[clang-format] is installed and run.
If [clang-format] isn't installed, the binaries will be automatically
downloaded from taskcluster and installed into ~/.mozbuild. We build our
own [clang-format] binaries.
### Formatting local changes
```
$ ./mach lint -l clang-format
```
When run without path arguments, it will lint the files you have
modified.
To automatically fix formatting issues:
```
$ ./mach format -l clang-format
```
Or equivalently:
```
$ ./mach lint -l clang-format --fix
```
### Formatting specific paths
```
$ ./mach format <path> # Format <path> in-place, picks the right formatter
```
The command accepts paths to reformat specific directories or files,
automatically selecting the appropriate formatter.
### Configuring the clang-format commit hook
To run clang-format at commit phase, run `mach bootstrap` or just add
the following line in the `hgrc` file:
```ini
[extensions]
clang-format = ~/.mozbuild/version-control-tools/hgext/clang-format
```
We use a hg extension as they are more flexible than hooks.
With git, the configuration is the following:
```
# From the root git directory:
$ ln -s $(pwd)/tools/lint/hooks_clang_format.py .git/hooks/pre-commit
```
You'll likely need to install the `python-hglib` package for your OS,
or else you may get errors like `abort: No module named hglib.client!`
when you try to commit.
## Editor integration
It is possible to configure many editors to support running
`clang-format` automatically on save, or when run from within the
editor.
### Editor plugins
- Eclipse
- Install the
plugin
- In Preferences -> C/C++ -> CppStyle, set the clang-format path to
\~/.mozbuild/clang-tools/clang-tidy/bin/clang-format
- (Optional) check "Run clang-format on file save"
(Or install
[clang-format](http://melpa.org/#/clang-format) from MELPA)
- [google-c-style](http://melpa.org/#/google-c-style) from MELPA
- [alternative
- [Visual
- [llvm.org plugin](http://llvm.org/builds/)
- [Integrated support in Visual Studio
- [Visual Studio
- [Script for patch
### Configuration
These tools generally run clang-format themselves, and won't use
`./mach lint`. The binary installed by our tooling will be
located at `~/.mozbuild/clang-tools/clang-tidy/bin/clang-format`.
You typically shouldn't need to specify any other special configuration
in your editor besides the clang-format binary. Most of the
configuration that clang-format relies on for formatting is stored
inside our source tree. More specifically, using the .clang-format file
located in the root of the repository. Please note that this doesn't
include the list of ignored files and directories (provided by
.clang-format-ignore which is a feature provided by the mach command
wrapper).
Coding style configuration is done within clang-format itself. When we
change the configuration (incorrect configuration, new feature in clang,
etc), we use {searchfox}`local overrides <mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0:.clang-format>`.
### Ignored files & directories
We maintain a {searchfox}`list of ignored directories and files <mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0:.clang-format-ignore>`,
which is used by `./mach lint -l clang-format`. This is generally only used
for code broken by clang-format, and third-party code.
### Ignored code hunks
Sections of code may have formatting disabled using comments. If a
section must not be formatted, the following comments will disable the
reformat:
```
// clang-format off
my code which should not be reformatted
// clang-format on
```
You can find an {searchfox}`example of code not formatted <mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0:xpcom/io/nsEscape.cpp#22>`.
## Ignore lists
To make sure that the blame/annotate features of Mercurial or git aren't
affected. Two files are maintained to keep track of the reformatting
commits.
### With Mercurial
The list is stored in
Commit messages should also contain the string
`# ignore-this-changeset`
The syntax in this file is generated using the following syntax:
```
$ hg log --template '{node} - {author|person} - {desc|strip|firstline}\n'
```
### With git
The list is stored in
and contains git revisions for both gecko-dev and the git cinnabar
repository.