Add output_dir parameter to control where compile_commands.json is written

New macro/rule parameter `output_dir` (default empty == workspace root,
matching the historical behaviour). When set, both the pre-write unlink
and the open() target are rerouted to `<output_dir>/compile_commands.json`.

Backport of hedronvision#210 (ilev4ik).

Author: helly25

refresh.template.py

@@ -1454,16 +1454,19 @@ def main():
     There should be actionable warnings, above, that led to this.""")
         sys.exit(1)
 
+    # Resolve the output path; `output_dir` is the macro parameter (empty == cwd).
+    output_path = os.path.join({output_dir}, 'compile_commands.json')
+
     # Remove any existing compile_commands.json before opening; handles the common
     # case where it's a symlink (e.g. pointing into a cmake build dir), which would
     # otherwise produce an inscrutable open() error. https://github.com/hedronvision/bazel-compile-commands-extractor/issues/105
     try:
-        os.remove('compile_commands.json')
+        os.remove(output_path)
     except FileNotFoundError:
         pass
 
     # Chain output into compile_commands.json
-    with open('compile_commands.json', 'w') as output_file:
+    with open(output_path, 'w') as output_file:
         json.dump(
             compile_command_entries,
             output_file,

refresh_compile_commands.bzl

@@ -65,6 +65,7 @@ def refresh_compile_commands(
         targets = None,
         exclude_headers = None,
         exclude_external_sources = False,
+        output_dir = "",
         **kwargs):  # For the other common attributes. Tags, compatible_with, etc. https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes.
     # Convert the various, acceptable target shorthands into the dictionary format
     # In Python, `type(x) == y` is an antipattern, but [Starlark doesn't support inheritance](https://bazel.build/rules/language), so `isinstance` doesn't exist, and this is the correct way to switch on type.
@@ -90,7 +91,7 @@ def refresh_compile_commands(
 
     # Generate the core, runnable python script from refresh.template.py
     script_name = name + ".py"
-    _expand_template(name = script_name, labels_to_flags = targets, exclude_headers = exclude_headers, exclude_external_sources = exclude_external_sources, **kwargs)
+    _expand_template(name = script_name, labels_to_flags = targets, exclude_headers = exclude_headers, exclude_external_sources = exclude_external_sources, output_dir = output_dir, **kwargs)
 
     # Combine them so the wrapper calls the main script.
     # Tag "manual" so `bazel build //...` won't try to build this when
@@ -121,8 +122,9 @@ def _expand_template_impl(ctx):
             # Note, don't delete whitespace. Correctly doing multiline indenting.
             "        {target_flag_pairs}": "\n".join(["        {},".format(pair) for pair in ctx.attr.labels_to_flags.items()]),
             "        {windows_default_include_paths}": "\n".join(["        %r," % path for path in find_cpp_toolchain(ctx).built_in_include_directories]),  # find_cpp_toolchain is from https://docs.bazel.build/versions/main/integrating-with-rules-cc.html
-            "{exclude_headers}": repr(ctx.attr.exclude_headers),
             "{exclude_external_sources}": repr(ctx.attr.exclude_external_sources),
+            "{exclude_headers}": repr(ctx.attr.exclude_headers),
+            "{output_dir}": repr(ctx.attr.output_dir),
             "{print_args_executable}": repr(ctx.executable._print_args_executable.path),
         },
     )
@@ -133,6 +135,7 @@ _expand_template = rule(
         "labels_to_flags": attr.string_dict(mandatory = True),  # string keys instead of label_keyed because Bazel doesn't support parsing wildcard target patterns (..., *, :all) in BUILD attributes.
         "exclude_external_sources": attr.bool(default = False),
         "exclude_headers": attr.string(values = ["all", "external", ""]),  # "" needed only for compatibility with Bazel < 3.6.0
+        "output_dir": attr.string(default = ""),  # Empty means: write to the workspace root (cwd, the historical behaviour).
         "_script_template": attr.label(allow_single_file = True, default = "refresh.template.py"),
         "_print_args_executable": attr.label(executable = True, cfg = "target", default = "//:print_args"),
         # For Windows INCLUDE. If this were eliminated, for example by the resolution of https://github.com/clangd/clangd/issues/123, we'd be able to just use a macro and skylib's expand_template rule: https://github.com/bazelbuild/bazel-skylib/pull/330