Skip to content

Commit

Permalink
Markdown style fixes for:
Browse files Browse the repository at this point in the history 
code_coverage.md
cocoa_tips_and_tricks.md
closure_compilation.md
clang_format.md
clang_tool_refactoring.md
clang.md

R=nodir
BUG=524256

Review URL: https://codereview.chromium.org/1306233003

Cr-Commit-Position: refs/heads/master@{#345652}
  • Loading branch information
@andybons
andybons authored and Commit bot committed Aug 26, 2015
1 parent 00d111c commit 6eaa0c0
Show file tree
Hide file tree
Showing 6 changed files with 322 additions and 155 deletions.
106 changes: 67 additions & 39 deletions docs/clang.md
View file
Original file line number Diff line number Diff line change
@@ -1,99 +1,127 @@
[Clang](http://clang.llvm.org/) is a compiler with many desirable features (outlined on their website).
# Clang

Chrome can be built with Clang. It is now the default compiler on Mac and Linux for building Chrome, and it is currently useful for its warning and error messages on Android and Windows.
[Clang](http://clang.llvm.org/) is a compiler with many desirable features
(outlined on their website).

See [the open bugs](http://code.google.com/p/chromium/issues/list?q=label:clang).
Chrome can be built with Clang. It is now the default compiler on Mac and Linux
for building Chrome, and it is currently useful for its warning and error
messages on Android and Windows.

See
[the open bugs](http://code.google.com/p/chromium/issues/list?q=label:clang).

[TOC]

## Build instructions

Get clang (happens automatically during `gclient runhooks` on Mac and Linux):
```
tools/clang/scripts/update.sh
```

(Only needs to be run once per checkout, and clang will be automatically updated by `gclient runhooks`.)
tools/clang/scripts/update.sh

(Only needs to be run once per checkout, and clang will be automatically updated
by `gclient runhooks`.)

### Reverting to gcc on linux

We don't have bots that test this, but building with gcc4.8+ should still work on Linux. If your system gcc is new enough, use this to build with gcc if you don't want to build with clang:
We don't have bots that test this, but building with gcc4.8+ should still work
on Linux. If your system gcc is new enough, use this to build with gcc if you
don't want to build with clang:

```
GYP_DEFINES=clang=0 build/gyp_chromium
```
GYP_DEFINES=clang=0 build/gyp_chromium

### Ninja

Regenerate the build files (`clang=1` is on by default on Mac and Linux):

If you use gyp:
```
GYP_DEFINES=clang=1 build/gyp_chromium
```
If you use gyp: `GYP_DEFINES=clang=1 build/gyp_chromium`

If you use gn, run `gn args` and add `is_clang = true` to your args.gn file.

Build:
```
ninja -C out/Debug chrome
```
Build: `ninja -C out/Debug chrome`

## Mailing List

http://groups.google.com/a/chromium.org/group/clang/topics

## Using plugins

The [chromium style plugin](http://dev.chromium.org/developers/coding-style/chromium-style-checker-errors) is used by default when clang is used.
The
[chromium style plugin](http://dev.chromium.org/developers/coding-style/chromium-style-checker-errors)
is used by default when clang is used.

If you're working on the plugin, you can build it locally like so:

1. Run `./tools/clang/scripts/update.sh --force-local-build --without-android` to build the plugin.
1. Build with clang like described above.
1. Run `./tools/clang/scripts/update.sh --force-local-build --without-android`
to build the plugin.
1. Build with clang like described above.

To run [other plugins](WritingClangPlugins.md), add these to your `GYP_DEFINES`:
TODO: writing_clang_plugins does not exist.
To run [other plugins](writing_clang_plugins.md), add these to your
`GYP_DEFINES`:

* `clang_load`: Absolute path to a dynamic library containing your plugin
* `clang_add_plugin`: tells clang to run a specific PluginASTAction
* `clang_load`: Absolute path to a dynamic library containing your plugin
* `clang_add_plugin`: tells clang to run a specific PluginASTAction

So for example, you could use the plugin in this directory with:

* `GYP_DEFINES='clang=1 clang_load=/path/to/libFindBadConstructs.so clang_add_plugin=find-bad-constructs' gclient runhooks`
* `GYP_DEFINES='clang=1 clang_load=/path/to/libFindBadConstructs.so
clang_add_plugin=find-bad-constructs' gclient runhooks`

## Using the clang static analyzer

See ClangStaticAnalyzer.
See [clang_static_analyser.md](clang_static_analyser.md).

## Windows

**Experimental!**

clang can be used as compiler on Windows. Clang uses Visual Studio's linker and SDK, so you still need to have Visual Studio installed.
clang can be used as compiler on Windows. Clang uses Visual Studio's linker and
SDK, so you still need to have Visual Studio installed.

Things should compile, and all tests should pass. You can check these bots for how things are currently looking: http://build.chromium.org/p/chromium.fyi/console?category=win%20clang
Things should compile, and all tests should pass. You can check these bots for
how things are currently looking:
http://build.chromium.org/p/chromium.fyi/console?category=win%20clang

```
``` shell
python tools\clang\scripts\update.py
set GYP_DEFINES=clang=1
python build\gyp_chromium

# or, if you use gn, run `gn args` and add `is_clang = true` to your args.gn
ninja -C out\Debug chrome
```

Current brokenness:

* Goma doesn't work.
* Debug info is very limited.
* To get colored diagnostics, you need to be running [ansicon](https://github.com/adoxa/ansicon/releases).
* Goma doesn't work.
* Debug info is very limited.
* To get colored diagnostics, you need to be running
[ansicon](https://github.com/adoxa/ansicon/releases).

## Using a custom clang binary

If you want to try building Chromium with your own clang binary that you've already built, set `make_clang_dir` to the directory containing `bin/clang` (i.e. the directory you ran cmake in, or your `Release+Asserts` folder if you use the configure/make build). You also need to disable chromium's clang plugin by setting `clang_use_chrome_plugins=0`, as it likely won't load in your custom clang binary.
If you want to try building Chromium with your own clang binary that you've
already built, set `make_clang_dir` to the directory containing `bin/clang`
(i.e. the directory you ran cmake in, or your `Release+Asserts` folder if you
use the configure/make build). You also need to disable chromium's clang plugin
by setting `clang_use_chrome_plugins=0`, as it likely won't load in your custom
clang binary.

Here's an example that also disables debug info and enables the component build (both not strictly necessary, but they will speed up your build):
Here's an example that also disables debug info and enables the component build
(both not strictly necessary, but they will speed up your build):

```shell
GYP_DEFINES="clang=1 fastbuild=1 component=shared_library \
clang_use_chrome_plugins=0 make_clang_dir=$HOME/src/llvm-build" \
build/gyp_chromium
```
GYP_DEFINES="clang=1 fastbuild=1 component=shared_library clang_use_chrome_plugins=0 make_clang_dir=$HOME/src/llvm-build" build/gyp_chromium
```

You can then run `head out/Release/build.ninja` and check that the first to lines set `cc` and `cxx` to your clang binary. If things look good, run `ninja -C out/Release` to build.
You can then run `head out/Release/build.ninja` and check that the first to
lines set `cc` and `cxx` to your clang binary. If things look good, run `ninja
-C out/Release` to build.

If your clang revision is very different from the one currently used in chromium

If your clang revision is very different from the one currently used in chromium – check tools/clang/scripts/update.sh to find chromium's clang revision – you might have to tweak warning flags. Or you could set `werror=` in the line above to disable warnings as errors (but this only works on Linux).
* Check `tools/clang/scripts/update.sh` to find chromium's clang revision
* You might have to tweak warning flags. Or you could set `werror=` in the
line above to disable warnings as errors (but this only works on Linux).
71 changes: 52 additions & 19 deletions docs/clang_format.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,65 @@
## Using clang-format on Chromium C++ Code
# Using clang-format on Chromium C++ Code

### Easiest usage, from the command line
## Easiest usage, from the command line

To automatically format a pending patch according to <a href='http://www.chromium.org/developers/coding-style'>Chromium style</a>, from the command line, simply run:
```
git cl format
```
This should work on all platforms _(yes, even Windows)_ without any set up or configuration: the tool comes with your checkout. Like other `git-cl` commands, this operates on a diff relative to the upstream branch. Only the lines that you've 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 show you what clang-format changed. Alternatively, you can run `git cl format` with your changes uncommitted, and then commit your now-formatted code.
To automatically format a pending patch according to
[Chromium style](http://www.chromium.org/developers/coding-style), from
the command line, simply run: ``` git cl format ``` This should work on all
platforms _(yes, even Windows)_ without any set up or configuration: the tool
comes with your checkout. Like other `git-cl` commands, this operates on a diff
relative to the upstream branch. Only the lines that you've 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 show you what
clang-format changed. Alternatively, you can run `git cl format` with your
changes uncommitted, and then commit your now-formatted code.

### Editor integrations
## Editor integrations

Many developers find it useful to integrate the clang-format tool with their editor 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>.
Many developers find it useful to integrate the clang-format tool with their
editor of choice. As a convenience, the scripts for this are also available in
your checkout of Chrome under
[src/buildtools/clang_format/script/](https://code.google.com/p/chromium/codesearch#chromium/src/buildtools/clang_format/script/).

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 automatically 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.com/p/chromium/codesearch#chromium/tools/depot_tools/clang-format'><code>clang-format</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.
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
automatically 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:
[clang-format](https://code.google.com/p/chromium/codesearch#chromium/tools/depot_tools/clang-format)
([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 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.

For further guidance on editor integration, see these specific pages:
* <a href='http://www.chromium.org/developers/sublime-text#TOC-Format-selection-or-area-around-cursor-using-clang-format'>Sublime Text</a>
* <a href='http://clang.llvm.org/docs/ClangFormat.html '>llvm's guidelines for vim, emacs, and bbedit</a>
* For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac) ctrl-shift-i (elsewhere) to indent the current line or current selection.

### Are robots taking over my freedom to choose where newlines go?
* [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-selection-or-area-around-cursor-using-clang-format)
* [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/ClangFormat.html)
* For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac)
ctrl-shift-i (elsewhere) to indent the current line or current selection.

No. For the project as a whole, using clang-format is just one optional way to format your code. While it will produce style-guide conformant code, other formattings would also satisfy the style guide, and all are okay.
## Are robots taking over my freedom to choose where newlines go?

Having said that, many clang-format converts have found that relying on a tool saves both them and their reviewers time. The saved time can then be used to discover functional defects in their patch, to address style/readability concerns whose resolution can't be automated, or to do something else that matters.
No. For the project as a whole, using clang-format is just one optional way to
format your code. While it will produce style-guide conformant code, other
formattings would also satisfy the style guide, and all are okay.

In directories where most contributors have already adopted clang-format, and code is already consistent with what clang-format would produce, some teams intend to experiment with standardizing on clang-format. When these local standards apply, it will be enforced by a PRESUBMIT.py check.
Having said that, many clang-format converts have found that relying on a tool
saves both them and their reviewers time. The saved time can then be used to
discover functional defects in their patch, to address style/readability
concerns whose resolution can't be automated, or to do something else that
matters.

### Reporting problems
In directories where most contributors have already adopted clang-format, and
code is already consistent with what clang-format would produce, some teams
intend to experiment with standardizing on clang-format. When these local
standards apply, it will be enforced by a PRESUBMIT.py check.

If clang-format is broken, or produces badly formatted code, please file a <a href='https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produced%20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20Chromium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%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%0ACode%20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20problem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,OS-?'>Chromium bug using this link</a>. Assign it to thakis@chromium.org or nick@chromium.org who will route it upstream.
## Reporting problems

If clang-format is broken, or produces badly formatted code, please file a
[bug]. Assign it to thakis@chromium.org or nick@chromium.org who will route it
upstream.

[bug]:
https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produced%20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20Chromium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%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%0ACode%20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20problem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,OS-?
Loading

0 comments on commit 6eaa0c0

Please sign in to comment.