format_cpp_code_with_clang-format.rst (8402B)
1 ===================================== 2 Formatting C++ Code With clang-format 3 ===================================== 4 5 Mozilla uses the Google coding style for whitespace, which is enforced 6 using `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__. A 7 specific version of the binary will be installed when 8 ``./mach clang-format`` or ``./mach bootstrap`` are run. We build our 9 own binaries and update them as needed. 10 11 Options are explicitly defined `in clang-format 12 itself <https://github.com/llvm-mirror/clang/blob/e8a55f98df6bda77ee2eaa7f7247bd655f79ae0e/lib/Format/Format.cpp#L856>`__. 13 If the options are changed in clang upstream, this might cause some 14 changes in the Firefox tree. For this reason, it is best to use the 15 mozilla-provided binaries. 16 17 Manual formatting 18 ----------------- 19 20 We provide a mach subcommand for running clang-format from the 21 command-line. This wrapper handles ensuring the correct version of 22 clang-format is installed and run. 23 24 If clang-format isn’t installed, the binaries will be automatically 25 downloaded from taskcluster and installed into ~/.mozbuild. We build our 26 own clang-format binaries. 27 28 29 Formatting local changes 30 ~~~~~~~~~~~~~~~~~~~~~~~~ 31 32 :: 33 34 $ ./mach clang-format 35 36 When run without arguments, it will run on a local diff. This could miss 37 some reformatting (for example, when blocks are touched). 38 (`searchfox <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/python/mozbuild/mozbuild/code-analysis/mach_commands.py#1620>`__) 39 40 41 Formatting specific paths 42 ~~~~~~~~~~~~~~~~~~~~~~~~~ 43 44 :: 45 46 $ ./mach clang-format -p <path> # Format <path> in-place 47 $ ./mach clang-format -p <path> -s # Show changes 48 49 The command also accepts a ``-p`` argument to reformat a specific 50 directory or file, and a ``-s`` flag to show the changes instead of 51 applying them to the working directory 52 (`searchfox <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/python/mozbuild/mozbuild/code-analysis/mach_commands.py#1633>`__) 53 54 55 Formatting specific commits / revisions 56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 58 :: 59 60 $ ./mach clang-format -c HEAD # Format a single git commit 61 $ ./mach clang-format -c HEAD~~..HEAD # Format a range of git commits 62 63 The command accepts a ``-c`` argument that takes a revision number or 64 commit range, and will format the lines modified by those commits. 65 (`searchfox <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/python/mozbuild/mozbuild/code-analysis/mach_commands.py#1635>`__) 66 67 68 Scripting Clang-Format 69 ~~~~~~~~~~~~~~~~~~~~~~ 70 71 Clang format expects that the path being passed to it is the path 72 on-disk. If this is not the case, for example when formatting a 73 temporary file, the "real" path must be specified. This can be done with 74 the ``--assume-filename <path>`` argument. 75 76 77 Configuring the clang-format commit hook 78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 80 To run clang-format at commit phase, run ``mach bootstrap`` or just add 81 the following line in the ``hgrc`` file: 82 83 .. code:: ini 84 85 [extensions] 86 clang-format = ~/.mozbuild/version-control-tools/hgext/clang-format 87 88 We use a hg extension as they are more flexible than hooks. 89 90 With git, the configuration is the following: 91 92 :: 93 94 # From the root git directory: 95 $ ln -s $(pwd)/tools/lint/hooks_clang_format.py .git/hooks/pre-commit 96 97 You'll likely need to install the ``python-hglib`` package for your OS, 98 or else you may get errors like ``abort: No module named hglib.client!`` 99 when you try to commit. 100 101 102 Editor integration 103 ------------------ 104 105 It is possible to configure many editors to support running 106 ``clang-format`` automatically on save, or when run from within the 107 editor. 108 109 110 Editor plugins 111 ~~~~~~~~~~~~~~ 112 113 - `Atom <https://atom.io/packages/clang-format>`__ 114 - `BBEdit <http://clang.llvm.org/docs/ClangFormat.html#bbedit-integration>`__ 115 116 - `clang-format-bbedit.applescript <https://raw.githubusercontent.com/llvm-mirror/clang/master/tools/clang-format/clang-format-bbedit.applescript>`__ 117 118 - Eclipse 119 120 - Install the 121 `CppStyle <https://marketplace.eclipse.org/content/cppstyle>`__ 122 plugin 123 - In Preferences -> C/C++ -> CppStyle, set the clang-format path to 124 ~/.mozbuild/clang-tools/clang-tidy/bin/clang-format 125 - (Optional) check "Run clang-format on file save" 126 127 - `Emacs <http://clang.llvm.org/docs/ClangFormat.html#emacs-integration>`__ 128 129 - `clang-format.el <https://raw.githubusercontent.com/llvm-mirror/clang/master/tools/clang-format/clang-format.el>`__ 130 (Or install 131 `clang-format <http://melpa.org/#/clang-format>`__ from MELPA) 132 - `google-c-style <http://melpa.org/#/google-c-style>`__ from MELPA 133 134 - `Sublime Text <https://packagecontrol.io/packages/Clang%20Format>`__ 135 136 - `alternative 137 tool <https://github.com/rosshemsley/SublimeClangFormat>`__ 138 139 - `Vim <http://clang.llvm.org/docs/ClangFormat.html#vim-integration>`__ 140 141 - `clang-format.py <https://raw.githubusercontent.com/llvm-mirror/clang/master/tools/clang-format/clang-format.py>`__ 142 - `vim-clang-format <https://github.com/rhysd/vim-clang-format>`__ 143 144 - `Visual 145 Studio <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat>`__ 146 147 - `llvm.org plugin <http://llvm.org/builds/>`__ 148 - `Integrated support in Visual Studio 149 2017 <https://blogs.msdn.microsoft.com/vcblog/2018/03/13/clangformat-support-in-visual-studio-2017-15-7-preview-1/>`__ 150 151 - `Visual Studio 152 Code <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`__ 153 - `XCode <https://github.com/travisjeffery/ClangFormat-Xcode>`__ 154 - `Script for patch 155 reformatting <http://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting>`__ 156 157 - `clang-format-diff.py <https://raw.githubusercontent.com/llvm-mirror/clang/master/tools/clang-format/clang-format-diff.py>`__ 158 159 160 Configuration 161 ~~~~~~~~~~~~~ 162 163 These tools generally run clang-format themselves, and won't use 164 ``./mach clang-format``. The binary installed by our tooling will be 165 located at ``~/.mozbuild/clang-tools/clang-tidy/bin/clang-format``. 166 167 You typically shouldn't need to specify any other special configuration 168 in your editor besides the clang-format binary. Most of the 169 configuration that clang-format relies on for formatting is stored 170 inside our source tree. More specifically, using the .clang-format file 171 located in the root of the repository. Please note that this doesn't 172 include the list of ignored files and directories (provided by 173 .clang-format-ignore which is a feature provided by the mach command 174 wrapper). 175 176 Coding style configuration is done within clang-format itself. When we 177 change the configuration (incorrect configuration, new feature in clang, 178 etc), we use `local 179 overrides <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/.clang-format>`__. 180 181 182 Ignored files & directories 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 185 We maintain a `list of ignored directories and 186 files <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/.clang-format-ignore>`__, 187 which is used by ``./mach clang-format``. This is generally only used 188 for code broken by clang-format, and third-party code. 189 190 191 Ignored code hunks 192 ~~~~~~~~~~~~~~~~~~ 193 194 Sections of code may have formatting disabled using comments. If a 195 section must not be formatted, the following comments will disable the 196 reformat: 197 198 :: 199 200 // clang-format off 201 my code which should not be reformatted 202 // clang-format on 203 204 You can find an `example of code not 205 formatted <https://searchfox.org/mozilla-central/rev/501eb4718d73870892d28f31a99b46f4783efaa0/xpcom/io/nsEscape.cpp#22>`__. 206 207 208 Ignore lists 209 ------------ 210 211 To make sure that the blame/annotate features of Mercurial or git aren't 212 affected. Two files are maintained to keep track of the reformatting 213 commits. 214 215 216 With Mercurial 217 ~~~~~~~~~~~~~~ 218 219 | The list is stored in 220 `https://searchfox.org/mozilla-central/source/.hg-annotate-ignore-revs </en-US/docs/>`__ 221 | Commit messages should also contain the string ``# ignore-this-changeset`` 222 223 The syntax in this file is generated using the following syntax: 224 225 :: 226 227 $ hg log --template '{node} - {author|person} - {desc|strip|firstline}\n' 228 229 With git 230 ~~~~~~~~ 231 232 The list is stored in 233 `https://searchfox.org/mozilla-central/source/.git-blame-ignore-revs </en-US/docs/>`__ 234 and contains git revisions for both gecko-dev and the git cinnabar 235 repository.