OLD | NEW |
(Empty) | |
| 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 w
orking 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/12
746010/. Other useful resources might be the [basic tutorial for Clang's AST mat
chers](http://clang.llvm.org/docs/LibASTMatchersTutorial.html) or the [AST match
er 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-chrom
e-tools <tools> |
| 14 ``` |
| 15 `<tools>` is a semicolon delimited list of subdirectories in `tools/clang` to bu
ild. 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 t
he following: |
| 16 ``` |
| 17 tools/clang/scripts/update.sh --force-local-build --without-android --with-chrom
e-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 comma
nd: |
| 27 ``` |
| 28 cd $HOME/src/chrome/src |
| 29 ninja -C out/Debug -t compdb cc cxx objc objcxx > out/Debug/compile_commands.jso
n |
| 30 ``` |
| 31 |
| 32 This will dump the command lines used to build the C/C++ modules in all of Chrom
ium into the resulting file. Then run the following command to run your tool acr
oss all Chromium code: |
| 33 ``` |
| 34 # Make sure all chromium targets are built to avoid missing generated dependenci
es |
| 35 ninja -C out/Debug |
| 36 tools/clang/scripts/run_tool.py <toolname> <path/to/directory/with/compile_comma
nds.json> <path 1> <path 2> ... |
| 37 ``` |
| 38 |
| 39 `<path 1>`, `<path 2>`, etc are optional arguments you use to filter the files t
hat will be rewritten. For example, if you only want to run the `empty-string` t
ool 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 are
n't compiled on that platform won't be processed. That means if you want to appl
y a change across all Chromium platforms, you'll have to run the tool once on ea
ch 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/clan
g` must match. What the test harness does is find all files that match the patte
rn `*-original.cc` in your tool's tests subdirectory. It then runs the tool acro
ss those files and compares it to the expected result, stored in `*-expected.cc` |
OLD | NEW |