| OLD | NEW |
| 1 # Clang Tool Refactoring | 1 # Clang Tool Refactoring |
| 2 | 2 |
| 3 [TOC] | 3 [TOC] |
| 4 | 4 |
| 5 ## Introduction | 5 ## Introduction |
| 6 | 6 |
| 7 Clang tools can help with global refactorings of Chromium code. Clang tools can | 7 Clang tools can help with global refactorings of Chromium code. Clang tools can |
| 8 take advantage of clang's AST to perform refactorings that would be impossible | 8 take advantage of clang's AST to perform refactorings that would be impossible |
| 9 with a traditional find-and-replace regexp: | 9 with a traditional find-and-replace regexp: |
| 10 | 10 |
| (...skipping 100 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 111 | 111 |
| 112 ## Running | 112 ## Running |
| 113 First, build all chromium targets to avoid failures due to missing dependecies | 113 First, build all chromium targets to avoid failures due to missing dependecies |
| 114 that are generated as part of the build: | 114 that are generated as part of the build: |
| 115 | 115 |
| 116 ```shell | 116 ```shell |
| 117 ninja -C out/Debug | 117 ninja -C out/Debug |
| 118 ``` | 118 ``` |
| 119 | 119 |
| 120 Then run the actual tool: | 120 Then run the actual tool: |
| 121 ``` | 121 |
| 122 ```shell |
| 122 tools/clang/scripts/run_tool.py <toolname> \ | 123 tools/clang/scripts/run_tool.py <toolname> \ |
| 123 --generate-compdb | 124 --generate-compdb |
| 124 out/Debug <path 1> <path 2> ... | 125 out/Debug <path 1> <path 2> ... |
| 125 ``` | 126 ``` |
| 126 | 127 |
| 127 `--generate-compdb` can be omitted if the compile DB was already generated and | 128 `--generate-compdb` can be omitted if the compile DB was already generated and |
| 128 the list of build flags and source files has not changed since generation. | 129 the list of build flags and source files has not changed since generation. |
| 129 | 130 |
| 130 `<path 1>`, `<path 2>`, etc are optional arguments to filter the files to run | 131 `<path 1>`, `<path 2>`, etc are optional arguments to filter the files to run |
| 131 the tool across. This is helpful when sharding global refactorings into smaller | 132 the tool across. This is helpful when sharding global refactorings into smaller |
| 132 chunks. For example, the following command will run the `empty_string` tool | 133 chunks. For example, the following command will run the `empty_string` tool |
| 133 across just the files in `//base`: | 134 across just the files in `//base`: |
| 134 | 135 |
| 135 ```shell | 136 ```shell |
| 136 tools/clang/scripts/run_tool.py empty_string \ | 137 tools/clang/scripts/run_tool.py empty_string \ |
| 137 --generated-compdb \ | 138 --generated-compdb \ |
| 138 out/Debug base | 139 out/Debug base |
| 139 ``` | 140 ``` |
| 140 | 141 |
| 141 ## Debugging | 142 ## Debugging |
| 142 Dumping the AST for a file: | 143 Dumping the AST for a file: |
| 144 |
| 143 ```shell | 145 ```shell |
| 144 clang++ -cc1 -ast-dump foo.cc | 146 clang++ -cc1 -ast-dump foo.cc |
| 145 ``` | 147 ``` |
| 146 | 148 |
| 147 Using `clang-query` to dynamically test matchers (requires checking out | 149 Using `clang-query` to dynamically test matchers (requires checking out |
| 148 and building [clang-tools-extras](https://github.com/llvm-mirror/clang-tools-ext
ra)): | 150 and building [clang-tools-extras](https://github.com/llvm-mirror/clang-tools-ext
ra)): |
| 151 |
| 149 ```shell | 152 ```shell |
| 150 clang-query -p path/to/compdb base/memory/ref_counted.cc | 153 clang-query -p path/to/compdb base/memory/ref_counted.cc |
| 151 ``` | 154 ``` |
| 152 | 155 |
| 153 `printf` debugging: | 156 `printf` debugging: |
| 157 |
| 154 ```c++ | 158 ```c++ |
| 155 clang::Decl* decl = result.Nodes.getNodeAs<clang::Decl>("decl"); | 159 clang::Decl* decl = result.Nodes.getNodeAs<clang::Decl>("decl"); |
| 156 decl->dumpColor(); | 160 decl->dumpColor(); |
| 157 clang::Stmt* stmt = result.Nodes.getNodeAs<clang::Stmt>("stmt"); | 161 clang::Stmt* stmt = result.Nodes.getNodeAs<clang::Stmt>("stmt"); |
| 158 stmt->dumpColor(); | 162 stmt->dumpColor(); |
| 159 ``` | 163 ``` |
| 164 |
| 160 By default, the script hides the output of the tool. The easiest way to change | 165 By default, the script hides the output of the tool. The easiest way to change |
| 161 that is to `return 1` from the `main()` function of the clang tool. | 166 that is to `return 1` from the `main()` function of the clang tool. |
| 162 | 167 |
| 163 ## Testing | 168 ## Testing |
| 164 Synposis: | 169 Synposis: |
| 170 |
| 165 ```shell | 171 ```shell |
| 166 test_tool.py <tool name> | 172 test_tool.py <tool name> |
| 167 ``` | 173 ``` |
| 168 | 174 |
| 169 The name of the tool binary and the subdirectory for the tool in | 175 The name of the tool binary and the subdirectory for the tool in |
| 170 `//tools/clang` must match. The test runner finds all files that match the | 176 `//tools/clang` must match. The test runner finds all files that match the |
| 171 pattern `//tools/clang/<tool name>/tests/*-original.cc`, runs the tool across | 177 pattern `//tools/clang/<tool name>/tests/*-original.cc`, runs the tool across |
| 172 those files, and compared it to the `*-expected.cc` version. If there is a | 178 those files, and compared it to the `*-expected.cc` version. If there is a |
| 173 mismatch, the result is saved in `*-actual.cc`. | 179 mismatch, the result is saved in `*-actual.cc`. |
| OLD | NEW |