docs/clang.md

   1 # Clang
   2
   3 [Clang](http://clang.llvm.org/) is a compiler with many desirable features
   4 (outlined on their website).
   5
   6 Chrome can be built with Clang. It is now the default compiler on Mac and Linux
   7 for building Chrome, and it is currently useful for its warning and error
   8 messages on Android and Windows.
   9
  10 See
  11 [the open bugs](http://code.google.com/p/chromium/issues/list?q=label:clang).
  12
  13 [TOC]
  14
  15 ## Build instructions
  16
  17 Get clang (happens automatically during `gclient runhooks` on Mac and Linux):
  18
  19     tools/clang/scripts/update.sh
  20
  21 (Only needs to be run once per checkout, and clang will be automatically updated
  22 by `gclient runhooks`.)
  23
  24 ### Reverting to gcc on linux
  25
  26 We don't have bots that test this, but building with gcc4.8+ should still work
  27 on Linux. If your system gcc is new enough, use this to build with gcc if you
  28 don't want to build with clang:
  29
  30     GYP_DEFINES=clang=0 build/gyp_chromium
  31
  32 ### Ninja
  33
  34 Regenerate the build files (`clang=1` is on by default on Mac and Linux):
  35
  36 If you use gyp: `GYP_DEFINES=clang=1 build/gyp_chromium`
  37
  38 If you use gn, run `gn args` and add `is_clang = true` to your args.gn file.
  39
  40 Build: `ninja -C out/Debug chrome`
  41
  42 ## Mailing List
  43
  44 http://groups.google.com/a/chromium.org/group/clang/topics
  45
  46 ## Using plugins
  47
  48 The
  49 [chromium style plugin](http://dev.chromium.org/developers/coding-style/chromium-style-checker-errors)
  50 is used by default when clang is used.
  51
  52 If you're working on the plugin, you can build it locally like so:
  53
  54 1.  Run `./tools/clang/scripts/update.sh --force-local-build --without-android`
  55     to build the plugin.
  56 1.  Build with clang like described above.
  57
  58 TODO: writing_clang_plugins does not exist.
  59 To run [other plugins](writing_clang_plugins.md), add these to your
  60 `GYP_DEFINES`:
  61
  62 *   `clang_load`: Absolute path to a dynamic library containing your plugin
  63 *   `clang_add_plugin`: tells clang to run a specific PluginASTAction
  64
  65 So for example, you could use the plugin in this directory with:
  66
  67 *   `GYP_DEFINES='clang=1 clang_load=/path/to/libFindBadConstructs.so
  68     clang_add_plugin=find-bad-constructs' gclient runhooks`
  69
  70 ## Using the clang static analyzer
  71
  72 See [clang_static_analyser.md](clang_static_analyser.md).
  73
  74 ## Windows
  75
  76 **Experimental!**
  77
  78 clang can be used as compiler on Windows. Clang uses Visual Studio's linker and
  79 SDK, so you still need to have Visual Studio installed.
  80
  81 Things should compile, and all tests should pass. You can check these bots for
  82 how things are currently looking:
  83 http://build.chromium.org/p/chromium.fyi/console?category=win%20clang
  84
  85 ``` shell
  86 python tools\clang\scripts\update.py
  87 set GYP_DEFINES=clang=1
  88 python build\gyp_chromium
  89
  90 # or, if you use gn, run `gn args` and add `is_clang = true` to your args.gn
  91 ninja -C out\Debug chrome
  92 ```
  93
  94 Current brokenness:
  95
  96 *   Goma doesn't work.
  97 *   Debug info is very limited.
  98 *   To get colored diagnostics, you need to be running
  99     [ansicon](https://github.com/adoxa/ansicon/releases).
 100
 101 ## Using a custom clang binary
 102
 103 If you want to try building Chromium with your own clang binary that you've
 104 already built, set `make_clang_dir` to the directory containing `bin/clang`
 105 (i.e. the directory you ran cmake in, or your `Release+Asserts` folder if you
 106 use the configure/make build). You also need to disable chromium's clang plugin
 107 by setting `clang_use_chrome_plugins=0`, as it likely won't load in your custom
 108 clang binary.
 109
 110 Here's an example that also disables debug info and enables the component build
 111 (both not strictly necessary, but they will speed up your build):
 112
 113 ```shell
 114 GYP_DEFINES="clang=1 fastbuild=1 component=shared_library \
 115 clang_use_chrome_plugins=0 make_clang_dir=$HOME/src/llvm-build" \
 116 build/gyp_chromium
 117 ```
 118
 119 You can then run `head out/Release/build.ninja` and check that the first to
 120 lines set `cc` and `cxx` to your clang binary. If things look good, run `ninja
 121 -C out/Release` to build.
 122
 123 If your clang revision is very different from the one currently used in chromium
 124
 125 *   Check `tools/clang/scripts/update.sh` to find chromium's clang revision
 126 *   You might have to tweak warning flags. Or you could set `werror=` in the
 127     line above to disable warnings as errors (but this only works on Linux).