OLD | NEW |
---|---|
1 ## Using clang-format on Chromium C++ Code | 1 # Using clang-format on Chromium C++ Code |
2 | 2 |
3 ### Easiest usage, from the command line | 3 ## Easiest usage, from the command line |
4 | 4 |
5 To automatically format a pending patch according to <a href='http://www.chromiu m.org/developers/coding-style'>Chromium style</a>, from the command line, simply run: | 5 To automatically format a pending patch according to |
6 ``` | 6 [Chromium style](http://www.chromium.org/developers/coding-style), from |
7 git cl format | 7 the command line, simply run: ``` git cl format ``` This should work on all |
8 ``` | 8 platforms _(yes, even Windows)_ without any set up or configuration: the tool |
9 This should work on all platforms _(yes, even Windows)_ without any set up or co nfiguration: the tool comes with your checkout. Like other `git-cl` commands, th is operates on a diff relative to the upstream branch. Only the lines that you'v e already touched in your patch will be reformatted. You can commit your changes to your git branch and then run `git cl format`, after which `git diff` will sh ow you what clang-format changed. Alternatively, you can run `git cl format` wit h your changes uncommitted, and then commit your now-formatted code. | 9 comes with your checkout. Like other `git-cl` commands, this operates on a diff |
10 relative to the upstream branch. Only the lines that you've already touched in | |
11 your patch will be reformatted. You can commit your changes to your git branch | |
12 and then run `git cl format`, after which `git diff` will show you what | |
13 clang-format changed. Alternatively, you can run `git cl format` with your | |
14 changes uncommitted, and then commit your now-formatted code. | |
10 | 15 |
11 ### Editor integrations | 16 ## Editor integrations |
12 | 17 |
13 Many developers find it useful to integrate the clang-format tool with their edi tor of choice. As a convenience, the scripts for this are also available in your checkout of Chrome under <a href='https://code.google.com/p/chromium/codesearch #chromium/src/buildtools/clang_format/script/'><code>src/buildtools/clang_format /script/</code></a>. | 18 Many developers find it useful to integrate the clang-format tool with their |
19 editor of choice. As a convenience, the scripts for this are also available in | |
20 your checkout of Chrome under | |
21 [src/buildtools/clang_format/script/](https://code.google.com/p/chromium/codesea rch#chromium/src/buildtools/clang_format/script/). | |
14 | 22 |
15 If you use an editor integration, you should try to make sure that you're using the version of clang-format that comes with your checkout. That way, you'll auto matically get updates and be running a tool that formats consistently with other developers. The binary lives under `src/buildtools`, but it's also in your path indirectly via a `depot_tools` launcher script: <a href='https://code.google.co m/p/chromium/codesearch#chromium/tools/depot_tools/clang-format'><code>clang-for mat</code></a> (<a href='https://code.google.com/p/chromium/codesearch#chromium/ tools/depot_tools/clang-format.bat'><code>clang-format.bat</code></a> on Windows ). Assuming that `depot_tools` is in your editor's `PATH` and the editor command runs from a working directory inside the Chromium checkout, the editor scripts (which anticipate clang-format on the path) should work. | 23 If you use an editor integration, you should try to make sure that you're using |
24 the version of clang-format that comes with your checkout. That way, you'll | |
25 automatically get updates and be running a tool that formats consistently with | |
26 other developers. The binary lives under `src/buildtools`, but it's also in your | |
27 path indirectly via a `depot_tools` launcher script: | |
28 [clang-format](https://code.google.com/p/chromium/codesearch#chromium/tools/depo t_tools/clang-format) | |
29 ([clang-format.bat](https://code.google.com/p/chromium/codesearch#chromium/tools /depot_tools/clang-format.bat) on Windows). Assuming that `depot_tools` is in yo ur editor's `PATH` | |
30 and the editor command runs from a working directory inside the Chromium | |
31 checkout, the editor scripts (which anticipate clang-format on the path) should | |
32 work. | |
16 | 33 |
17 For further guidance on editor integration, see these specific pages: | 34 For further guidance on editor integration, see these specific pages: |
18 * <a href='http://www.chromium.org/developers/sublime-text#TOC-Format-selectio n-or-area-around-cursor-using-clang-format'>Sublime Text</a> | |
19 * <a href='http://clang.llvm.org/docs/ClangFormat.html '>llvm's guidelines for vim, emacs, and bbedit</a> | |
20 * For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac) c trl-shift-i (elsewhere) to indent the current line or current selection. | |
21 | 35 |
22 ### Are robots taking over my freedom to choose where newlines go? | 36 * [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-se lection-or-area-around-cursor-using-clang-format) |
37 * [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/Cl angFormat.html) | |
38 * For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac) | |
39 ctrl-shift-i (elsewhere) to indent the current line or current selection. | |
23 | 40 |
24 No. For the project as a whole, using clang-format is just one optional way to f ormat your code. While it will produce style-guide conformant code, other format tings would also satisfy the style guide, and all are okay. | 41 ## Are robots taking over my freedom to choose where newlines go? |
25 | 42 |
26 Having said that, many clang-format converts have found that relying on a tool s aves both them and their reviewers time. The saved time can then be used to disc over functional defects in their patch, to address style/readability concerns wh ose resolution can't be automated, or to do something else that matters. | 43 No. For the project as a whole, using clang-format is just one optional way to |
44 format your code. While it will produce style-guide conformant code, other | |
45 formattings would also satisfy the style guide, and all are okay. | |
27 | 46 |
28 In directories where most contributors have already adopted clang-format, and co de is already consistent with what clang-format would produce, some teams intend to experiment with standardizing on clang-format. When these local standards ap ply, it will be enforced by a PRESUBMIT.py check. | 47 Having said that, many clang-format converts have found that relying on a tool |
48 saves both them and their reviewers time. The saved time can then be used to | |
49 discover functional defects in their patch, to address style/readability | |
50 concerns whose resolution can't be automated, or to do something else that | |
51 matters. | |
29 | 52 |
30 ### Reporting problems | 53 In directories where most contributors have already adopted clang-format, and |
54 code is already consistent with what clang-format would produce, some teams | |
55 intend to experiment with standardizing on clang-format. When these local | |
56 standards apply, it will be enforced by a PRESUBMIT.py check. | |
31 | 57 |
32 If clang-format is broken, or produces badly formatted code, please file a <a hr ef='https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produ ced%20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20 Chromium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20fine ly%20honed%20stylistic%20dander%0A-%20No%20sane%20human%20would%20ever%20choose% 0A%0AHere%27s%20the%20code%20before%20formatting:%0A%0A%0AHere%27s%20the%20code% 20after%20formatting:%0A%0A%0AHere%27s%20how%20it%20ought%20to%20look:%0A%0A%0AC ode%20review%20link%20for%20full%20files/context:&summary=clang-format%20quality %20problem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Too ls,OS-?'>Chromium bug using this link</a>. Assign it to thakis@chromium.org or n ick@chromium.org who will route it upstream. | 58 ## Reporting problems |
59 | |
60 If clang-format is broken, or produces badly formatted code, please file a | |
61 [Chromium bug using this link](https://code.google.com/p/chromium/issues/entry?c omment=clang-format%20produced%20code%20that%20(choose%20all%20that%20apply):%20 %0A-%20Doesn%27t%20match%20Chromium%20style%0A-%20Doesn%27t%20match%20blink%20st yle%0A-%20Riles%20my%20finely%20honed%20stylistic%20dander%0A-%20No%20sane%20hum an%20would%20ever%20choose%0A%0AHere%27s%20the%20code%20before%20formatting:%0A% 0A%0AHere%27s%20the%20code%20after%20formatting:%0A%0A%0AHere%27s%20how%20it%20o ught%20to%20look:%0A%0A%0ACode%20review%20link%20for%20full%20files/context:&sum mary=clang-format%20quality%20problem&cc=thakis@chromium.org,%20nick@chromium.or g&labels=Type-Bug,Build-Tools,OS-?). | |
nodir
2015/08/26 16:26:17
nit: for long bug links, I usually move the to the
Bons
2015/08/26 19:43:14
Done.
| |
62 Assign it to thakis@chromium.org or nick@chromium.org who will route it | |
63 upstream. | |
OLD | NEW |