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 | 5 To automatically format a pending patch according to |
6 [Chromium style](http://www.chromium.org/developers/coding-style), from | 6 [Chromium style](https://www.chromium.org/developers/coding-style), from |
7 the command line, simply run: ``` git cl format ``` This should work on all | 7 the command line, simply run: ``` git cl format ``` This should work on all |
8 platforms _(yes, even Windows)_ without any set up or configuration: the tool | 8 platforms _(yes, even Windows)_ without any set up or configuration: the tool |
9 comes with your checkout. Like other `git-cl` commands, this operates on a diff | 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 | 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 | 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 | 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 | 13 clang-format changed. Alternatively, you can run `git cl format` with your |
14 changes uncommitted, and then commit your now-formatted code. | 14 changes uncommitted, and then commit your now-formatted code. |
15 | 15 |
16 ## Editor integrations | 16 ## Editor integrations |
17 | 17 |
18 Many developers find it useful to integrate the clang-format tool with their | 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 | 19 editor of choice. As a convenience, the scripts for this are also available in |
20 your checkout of Chrome under | 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/). | 21 [src/buildtools/clang_format/script/](https://code.google.com/p/chromium/codesea
rch#chromium/src/buildtools/clang_format/script/). |
22 | 22 |
23 If you use an editor integration, you should try to make sure that you're using | 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 | 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 | 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 | 26 other developers. The binary lives under `src/buildtools`, but it's also in your |
27 path indirectly via a `depot_tools` launcher script: | 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) | 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` | 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 | 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 | 31 checkout, the editor scripts (which anticipate clang-format on the path) should |
32 work. | 32 work. |
33 | 33 |
34 For further guidance on editor integration, see these specific pages: | 34 For further guidance on editor integration, see these specific pages: |
35 | 35 |
36 * [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-se
lection-or-area-around-cursor-using-clang-format) | 36 * [Sublime Text](https://www.chromium.org/developers/sublime-text#TOC-Format-s
election-or-area-around-cursor-using-clang-format) |
37 * [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/Cl
angFormat.html) | 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) | 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. | 39 ctrl-shift-i (elsewhere) to indent the current line or current selection. |
40 | 40 |
41 ## Are robots taking over my freedom to choose where newlines go? | 41 ## Are robots taking over my freedom to choose where newlines go? |
42 | 42 |
43 No. For the project as a whole, using clang-format is just one optional way to | 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 | 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. | 45 formattings would also satisfy the style guide, and all are okay. |
46 | 46 |
47 Having said that, many clang-format converts have found that relying on a tool | 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 | 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 | 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 | 50 concerns whose resolution can't be automated, or to do something else that |
51 matters. | 51 matters. |
52 | 52 |
53 In directories where most contributors have already adopted clang-format, and | 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 | 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 | 55 intend to experiment with standardizing on clang-format. When these local |
56 standards apply, it will be enforced by a PRESUBMIT.py check. | 56 standards apply, it will be enforced by a PRESUBMIT.py check. |
57 | 57 |
58 ## Reporting problems | 58 ## Reporting problems |
59 | 59 |
60 If clang-format is broken, or produces badly formatted code, please file a | 60 If clang-format is broken, or produces badly formatted code, please file a |
61 [bug]. Assign it to thakis@chromium.org or nick@chromium.org who will route it | 61 [bug]. Assign it to thakis@chromium.org or nick@chromium.org who will route it |
62 upstream. | 62 upstream. |
63 | 63 |
64 [bug]: | 64 [bug]: |
65 https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produced%
20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20Chro
mium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%2
0honed%20stylistic%20dander%0A-%20No%20sane%20human%20would%20ever%20choose%0A%0
AHere%27s%20the%20code%20before%20formatting:%0A%0A%0AHere%27s%20the%20code%20af
ter%20formatting:%0A%0A%0AHere%27s%20how%20it%20ought%20to%20look:%0A%0A%0ACode%
20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20p
roblem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,O
S-? | 65 https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produced%
20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20Chro
mium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%2
0honed%20stylistic%20dander%0A-%20No%20sane%20human%20would%20ever%20choose%0A%0
AHere%27s%20the%20code%20before%20formatting:%0A%0A%0AHere%27s%20the%20code%20af
ter%20formatting:%0A%0A%0AHere%27s%20how%20it%20ought%20to%20look:%0A%0A%0ACode%
20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20p
roblem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,O
S-? |
OLD | NEW |