Split run_tool.py into run_tool.py, extract_edits.py and apply_edits.py

docs/clang_tool_refactoring.md

Index: docs/clang_tool_refactoring.md
diff --git a/docs/clang_tool_refactoring.md b/docs/clang_tool_refactoring.md
index 40a8dae053463b6ef894eb8111fe905a4fe3c8c8..44543e535c5b2e5171c0585cb66050a2412938ef 100644
--- a/docs/clang_tool_refactoring.md
+++ b/docs/clang_tool_refactoring.md
@@ -69,7 +69,7 @@ represents one edit. Fields are separated by `:::`, and the first field must
 be `r` (for replacement). In the future, this may be extended to handle header
 insertion/removal. A deletion is an edit with no replacement text.
 
-The edits are applied by [`run_tool.py`](#Running), which understands certain
+The edits are applied by [`apply_edits.py`](#Running), which understands certain
 conventions:
 
 *   The tool should munge newlines in replacement text to `\0`. The script
@@ -118,6 +118,12 @@ that are generated as part of the build:
 ```shell
 ninja -C out/Debug  # For non-Windows
 ninja -d keeprsp -C out/Debug  # For Windows
+
+# experimental:
+$gen_targets = $(ninja -C out/gn -t targets all \
+                 | grep '^gen/[^: ]*\.[ch][pc]*:' \
+                 | cut -f 1 -d :`)
+ninja -C out/Debug $gen_targets
 ```
 
 On Windows, generate the compile DB first, and after making any source changes.
@@ -127,12 +133,12 @@ Then omit the `--generate-compdb` in later steps.
 tools/clang/scripts/generate_win_compdb.py out/Debug
 ```
 
-Then run the actual tool:
+Then run the actual clang tool to generate a list of edits:
 
 ```shell
 tools/clang/scripts/run_tool.py <toolname> \
   --generate-compdb
-  out/Debug <path 1> <path 2> ...
+  out/Debug <path 1> <path 2> ... >/tmp/list-of-edits

[danakj, 2016/12/23 15:45:06]

suggest putting debug in the output file name for good role modelling

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

 ```
 
 `--generate-compdb` can be omitted if the compile DB was already generated and
@@ -146,7 +152,15 @@ across just the files in `//base`:
 ```shell
 tools/clang/scripts/run_tool.py empty_string  \
   --generated-compdb \
-  out/Debug base
+  out/Debug base >/tmp/list-of-edits

[danakj, 2016/12/23 15:45:06]

same

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+```
+
+Finally - apply the edits as follows:

[dcheng, 2016/12/27 07:30:14]

Super minor nit: comma instead of a dash

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+
+```shell
+cat /tmp/list-of-edits \

[danakj, 2016/12/23 15:45:06]

same

[Łukasz Anforowicz, 2016/12/27 22:33:26]

Done.

+  | tools/clang/scripts/extract_edits.py \
+  | tools/clang/scripts/apply_edits.py out/Debug <optional paths to filter by>

[danakj, 2016/12/23 15:45:06]

Why are there filter paths here and for run_tool.py, i guess this can only be a
subset of those? If so maybe mention this in the text above when saying "apply
the edits"

[Łukasz Anforowicz, 2016/12/27 22:33:26]

I tried to explain this better in the newest patchset.

1. filters passed to run_tool.py control which source files the clang tool is
run against.  the tool can emit edits that apply to *any* files anywhere
(run_tool.py doesn't look at the output of the clang tool at all - the tool can
legitimately produce edits somewhere "outside" [e.g. when processing a .cc file
under //net it can generate edits for an included header file under //base]).

2. filters passed to apply_edits.py controls which files get edited

 ```
 
 ## Debugging