docs/clang_tool_refactoring.md

   1 # Clang Tool Refactoring
   2
   3 [TOC]
   4
   5 ## Caveats
   6
   7 *   The current workflow requires git.
   8 *   This doesn't work on Windows... yet. I'm hoping to have a proof-of-concept
   9     working on Windows as well ~~in a month~~ several centuries from now.
  10
  11 ## Prerequisites
  12
  13 Everything needed should be in a default Chromium checkout using gclient.
  14 `third_party/llvm-build/Release+Asserts/bin` should be in your `$PATH`.
  15
  16 ## Writing the Tool
  17
  18 An example clang tool is being implemented in
  19 https://codereview.chromium.org/12746010/. Other useful resources might be the
  20 [basic tutorial for Clang's AST matchers](http://clang.llvm.org/docs/LibASTMatchersTutorial.html)
  21 or the
  22 [AST matcher reference](http://clang.llvm.org/docs/LibASTMatchersReference.html).
  23
  24 Build your tool by running the following command (requires cmake version 2.8.10
  25 or later):
  26
  27 ```shell
  28 tools/clang/scripts/update.sh --force-local-build --without-android \
  29 --with-chrome-tools <tools>
  30 ```
  31
  32 `<tools>` is a semicolon delimited list of subdirectories in `tools/clang` to
  33 build. The resulting binary will end up in
  34 `third_party/llvm-build/Release+Asserts/bin`. For example, to build the Chrome
  35 plugin and the empty\_string tool, run the following:
  36
  37 ```shell
  38 tools/clang/scripts/update.sh --force-local-build --without-android \
  39 --with-chrome-tools "plugins;empty_string"
  40 ```
  41
  42 When writing AST matchers, the following can be helpful to see what clang thinks
  43 the AST is:
  44
  45 ```shell
  46 clang++ -cc1 -ast-dump foo.cc
  47 ```
  48
  49 ## Running the tool
  50
  51 First, you'll need to generate the compilation database with the following
  52 command:
  53
  54 ```shell
  55 cd $HOME/src/chrome/src
  56 ninja -C out/Debug -t compdb cc cxx objc objcxx > \
  57 out/Debug/compile_commands.json
  58 ```
  59
  60 This will dump the command lines used to build the C/C++ modules in all of
  61 Chromium into the resulting file. Then run the following command to run your
  62 tool across all Chromium code:
  63
  64 ```shell
  65 # Make sure all chromium targets are built to avoid missing generated
  66 # dependencies
  67 ninja -C out/Debug
  68 tools/clang/scripts/run_tool.py <toolname> \
  69 <path/to/directory/with/compile_commands.json> <path 1> <path 2> ...
  70 ```
  71
  72 `<path 1>`, `<path 2>`, etc are optional arguments you use to filter the files
  73 that will be rewritten. For example, if you only want to run the `empty-string`
  74 tool on files in `chrome/browser/extensions` and `sync`, you'd do something like:
  75
  76 ```shell
  77 tools/clang/scripts/run_tool.py empty_string out/Debug \
  78 chrome/browser/extensions sync
  79 ```
  80
  81 ## Limitations
  82
  83 Since the compile database is generated by ninja, that means that files that
  84 aren't compiled on that platform won't be processed. That means if you want to
  85 apply a change across all Chromium platforms, you'll have to run the tool once
  86 on each platform.
  87
  88 ## Testing
  89
  90 `test_tool.py` is the test harness for running tests. To use it, simply run:
  91
  92 ```shell
  93 test_tool.py <tool name>
  94 ```
  95
  96 Note that name of the built tool and the subdirectory it lives in at
  97 `tools/clang` must match. What the test harness does is find all files that
  98 match the pattern `*-original.cc` in your tool's tests subdirectory. It then
  99 runs the tool across those files and compares it to the expected result, stored
 100 in `*-expected.cc`