docs/clang_tool_refactoring.md

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