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 |