clang tooling: Make script arguments more consistent and update docs

- all: Use -p consistently to specify a path to the compile db to match
  the convention of clang::tooling::ClangTool
- all: Default -p to out/Debug for convenience.
- docs: Update docs to reference renamed arguments
- docs: Update clang-tidy documentation to use the compile DB generation
  wrapper script
- run_tool.py: Change tool to a non-positional argument and make it a
  required argument.

Change-Id: I378402cab36e86da4b13fb43e26067cad4db1795
Reviewed-on: https://chromium-review.googlesource.com/494946
Commit-Queue: Daniel Cheng <dcheng@chromium.org>
Reviewed-by: Nico Weber <thakis@chromium.org>
Cr-Commit-Position: refs/heads/master@{#469409}

docs/clang_tidy.md

@@ -53,7 +53,7 @@ ninja -C out/Release chrome
 ```
 2.  Generate the compilation database
 ```
-ninja -C out/Release -t compdb objcxx cxx > compile_commands.json
+tools/clang/scripts/generate_compdb.py -p out/Release > compile_commands.json
 ```
 3.  Enter the build directory.
 ```

docs/clang_tool_refactoring.md

@@ -128,9 +128,9 @@ ninja -C out/Debug $gen_targets
 Then run the actual clang tool to generate a list of edits:
 
 ```shell
-tools/clang/scripts/run_tool.py <toolname> \
+tools/clang/scripts/run_tool.py --tool <path to tool> \
   --generate-compdb
-  out/Debug <path 1> <path 2> ... >/tmp/list-of-edits.debug
+  -p out/Debug <path 1> <path 2> ... >/tmp/list-of-edits.debug
 ```
 
 `--generate-compdb` can be omitted if the compile DB was already generated and
@@ -145,9 +145,9 @@ edits that apply to files outside of `//cc` (i.e. edits that apply to headers
 from `//base` that got included by source files in `//cc`).
 
 ```shell
-tools/clang/scripts/run_tool.py empty_string  \
+tools/clang/scripts/run_tool.py --tool empty_string  \
   --generated-compdb \
-  out/Debug net >/tmp/list-of-edits.debug
+  -p out/Debug net >/tmp/list-of-edits.debug
 ```
 
 Note that some header files might only be included from generated files (e.g.
@@ -162,7 +162,7 @@ Finally, apply the edits as follows:
 ```shell
 cat /tmp/list-of-edits.debug \
   | tools/clang/scripts/extract_edits.py \
-  | tools/clang/scripts/apply_edits.py out/Debug <path 1> <path 2> ...
+  | tools/clang/scripts/apply_edits.py -p out/Debug <path 1> <path 2> ...
 ```
 
 The apply_edits.py tool will only apply edits to files actually under control of

tools/clang/pylib/clang/compile_db.py

@@ -76,6 +76,9 @@ def GenerateWithNinja(path):
 
   Args:
     path: The build directory to generate a compile database for.
+
+  Returns:
+    A string containing the contents of the compile database.
   """
   # TODO(dcheng): Ensure that clang is enabled somehow.
 
@@ -90,8 +93,7 @@ def GenerateWithNinja(path):
   if sys.platform == 'win32':
     compile_db = _ProcessCompileDatabaseForWindows(compile_db)
 
-  with open(os.path.join(path, 'compile_commands.json'), 'w') as f:
-    f.write(json.dumps(compile_db, indent=2))
+  return json.dumps(compile_db, indent=2)
 
 
 def Read(path):

tools/clang/scripts/apply_edits.py

@@ -202,7 +202,8 @@ def _ExtendDeletionIfElementIsInList(contents, offset):
 def main():
   parser = argparse.ArgumentParser()
   parser.add_argument(
-      'build_directory',
+      '-p',
+      required=True,
       help='path to the build dir (dir that edit paths are relative to)')
   parser.add_argument(
       'path_filter',
@@ -211,7 +212,7 @@ def main():
   args = parser.parse_args()
 
   filenames = set(_GetFilesFromGit(args.path_filter))
-  edits = _ParseEditsFromStdin(args.build_directory)
+  edits = _ParseEditsFromStdin(args.p)
   return _ApplyEdits(
       {k: v for k, v in edits.iteritems()
             if os.path.realpath(k) in filenames})

tools/clang/scripts/apply_fixits.py

@@ -16,9 +16,7 @@
 # 2. Build everything and capture the output:
 #      ninja -C <build_directory> &> generated-fixits
 # 3. Apply the fixits with this script:
-#      python apply_fixits.py[ <build_directory>] < generated-fixits
-#    <build_directory> is optional and only required if your build directory is
-#    a non-standard location.
+#      python apply_fixits.py -p <build_directory> < generated-fixits
 
 import argparse
 import collections
@@ -41,9 +39,8 @@ FixIt = collections.namedtuple(
 def main():
   parser = argparse.ArgumentParser()
   parser.add_argument(
-      'build_directory',
-      nargs='?',
-      default='out/Debug',
+      '-p',
+      required=True,
       help='path to the build directory to complete relative paths in fixits')
   args = parser.parse_args()
 
@@ -63,7 +60,7 @@ def main():
             'end_line')), -int(m.group('end_col')), m.group('text')))
   for k, v in fixits.iteritems():
     v.sort()
-    with open(os.path.join(args.build_directory, k), 'rb+') as f:
+    with open(os.path.join(args.p, k), 'rb+') as f:
       lines = f.readlines()
       last_fixit = None
       for fixit in v:

tools/clang/scripts/build_file.py

@@ -22,8 +22,9 @@ _PROBABLY_CLANG_RE = re.compile(r'clang(?:\+\+)?$')
 def ParseArgs():
   parser = argparse.ArgumentParser(
       description='Utility to build one Chromium file for debugging clang')
-  parser.add_argument('-p', default='.', help='path to the compile database')
+  parser.add_argument('-p', required=True, help='path to the compile database')
   parser.add_argument('--generate-compdb',
+                      action='store_true',
                       help='regenerate the compile database')
   parser.add_argument('--prefix',
                       help='optional prefix to prepend, e.g. --prefix=lldb')
@@ -73,7 +74,8 @@ def main():
   args = ParseArgs()
   os.chdir(args.p)
   if args.generate_compdb:
-    compile_db.GenerateWithNinja('.')
+    with open('compile_commands.json', 'w') as f:
+      f.write(compile_db.GenerateWithNinja('.'))
   db = compile_db.Read('.')
   for record in db:
     if os.path.normpath(os.path.join(args.p, record[

tools/clang/scripts/generate_compdb.py

@@ -24,13 +24,12 @@ from clang import compile_db
 def main(argv):
   parser = argparse.ArgumentParser()
   parser.add_argument(
-      'build_path',
-      nargs='?',
-      help='Path to build directory',
-      default='out/Debug')
+      '-p',
+      required=True,
+      help='Path to build directory')
   args = parser.parse_args()
 
-  compile_db.GenerateWithNinja(args.build_path)
+  print compile_db.GenerateWithNinja(args.p)
 
 
 if __name__ == '__main__':

tools/clang/scripts/run_tool.py

@@ -188,7 +188,7 @@ class _CompilerDispatcher(object):
 
 def main():
   parser = argparse.ArgumentParser()
-  parser.add_argument('tool', help='clang tool to run')
+  parser.add_argument('--tool', required=True, help='clang tool to run')
   parser.add_argument('--all', action='store_true')
   parser.add_argument(
       '--generate-compdb',
@@ -198,7 +198,8 @@ def main():
       '--shard',
       metavar='<n>-of-<count>')
   parser.add_argument(
-      'compile_database',
+      '-p',
+      required=True,
       help='path to the directory that contains the compile database')
   parser.add_argument(
       'path_filter',
@@ -217,10 +218,11 @@ def main():
       os.environ['PATH'])
 
   if args.generate_compdb:
-    compile_db.GenerateWithNinja(args.compile_database)
+    with open(os.path.join(args.p, 'compile_commands.json'), 'w') as f:
+      f.write(compile_db.GenerateWithNinja(args.p))
 
   if args.all:
-    source_filenames = set(_GetFilesFromCompileDB(args.compile_database))
+    source_filenames = set(_GetFilesFromCompileDB(args.p))
   else:
     git_filenames = set(_GetFilesFromGit(args.path_filter))
     # Filter out files that aren't C/C++/Obj-C/Obj-C++.
@@ -243,7 +245,7 @@ def main():
         shard_number, shard_count, len(source_filenames), total_length)
 
   dispatcher = _CompilerDispatcher(args.tool, args.tool_args,
-                                   args.compile_database,
+                                   args.p,
                                    source_filenames)
   dispatcher.Run()
   return -dispatcher.failed_count

tools/clang/scripts/test_tool.py

@@ -58,28 +58,30 @@ def _RunToolAndApplyEdits(tools_clang_scripts_directory,
     args = ['python',
             os.path.join(tools_clang_scripts_directory, 'run_tool.py')]
     extra_run_tool_args_path = os.path.join(test_directory_for_tool,
-                                            "run_tool.args")
+                                            'run_tool.args')
     if os.path.exists(extra_run_tool_args_path):
-        with open(extra_run_tool_args_path, 'r') as extra_run_tool_args_file:
-            extra_run_tool_args = extra_run_tool_args_file.readlines()
-            args.extend([arg.strip() for arg in extra_run_tool_args])
-    args.extend([
-            tool_to_test,
-            test_directory_for_tool])
+      with open(extra_run_tool_args_path, 'r') as extra_run_tool_args_file:
+        extra_run_tool_args = extra_run_tool_args_file.readlines()
+        args.extend([arg.strip() for arg in extra_run_tool_args])
+    args.extend(['--tool', tool_to_test, '-p', test_directory_for_tool])
 
     args.extend(actual_files)
     run_tool = subprocess.Popen(args, stdout=subprocess.PIPE)
 
-    args = ['python',
-            os.path.join(tools_clang_scripts_directory, 'extract_edits.py')]
-    extract_edits = subprocess.Popen(args, stdin=run_tool.stdout,
-                                     stdout=subprocess.PIPE)
-
-    args = ['python',
-            os.path.join(tools_clang_scripts_directory, 'apply_edits.py'),
-            test_directory_for_tool]
-    apply_edits = subprocess.Popen(args, stdin=extract_edits.stdout,
-                                   stdout=subprocess.PIPE)
+    args = [
+        'python',
+        os.path.join(tools_clang_scripts_directory, 'extract_edits.py')
+    ]
+    extract_edits = subprocess.Popen(
+        args, stdin=run_tool.stdout, stdout=subprocess.PIPE)
+
+    args = [
+        'python',
+        os.path.join(tools_clang_scripts_directory, 'apply_edits.py'), '-p',
+        test_directory_for_tool
+    ]
+    apply_edits = subprocess.Popen(
+        args, stdin=extract_edits.stdout, stdout=subprocess.PIPE)
 
     # Wait for the pipeline to finish running + check exit codes.
     stdout, _ = apply_edits.communicate()