generate compile_commands.json for use by language servers like clangd (#196)

### Improving Vere developer experience

This PR enables a `bazel run //bazel:refresh_compile_commands` command
that generates a `compile_commands.json` file in the root of the repo.
This file can be used by popular C/C++ editor plugins/extensions to
automatically enable modern IDE features like auto-completion,
cross-references, hovering, refactoring, etc.

To enable this, we add
[this](https://github.com/hedronvision/bazel-compile-commands-extractor)
"compile commands extractor" program to our `BUILD.bazel` file.

If you want to try this yourself with your own installation of vscode
with the official `clangd` extension (for example)...
```
git checkout i/195/better-ide-support

# uninstall any c/c++ extensions you might already have
code --install-extension llvm-vs-code-extensions.vscode-clangd
code --uninstall-extension ms-vscode.cpptools

# add these `clangd` settings to your *user* json:
  "clangd.arguments": [
    "--header-insertion=never",
    "--compile-commands-dir=${workspaceFolder}/",
    "--query-driver=**",
  ],
  
# generate the `compile_commands.json` file
bazel run //bazel:refresh_compile_commands

# finally, reload your vscode window
```

Enjoy no red squigglies, plus lots more.

Resolves #195.

CONTRIBUTING.md

@@ -114,3 +114,37 @@ $ ./urbit <ship>
 
 
 [^1]: Unless you specify the pier using the `-c` flag.
+
+### Enable Language Server Processing
+
+We support the [`clangd`](https://clangd.llvm.org/installation) 
+language server, which can be installed directly on your system or 
+via one of the official editor plugins.
+
+After installing `clangd`, configure it to use the following arguments 
+(location of these arguments may vary depending on your editor plugin or 
+if you've installed `clangd` directly on your system).
+
+For example, if you use Visual Studio Code, you can add the following to your
+user settings:
+
+```json
+{
+  "clangd.arguments": [
+    "--header-insertion=never",
+    "--compile-commands-dir=${workspaceFolder}/",
+    "--query-driver=**",
+  ],
+}
+```
+
+For other editors, please refer to the 
+[editor plugin documentation](https://clangd.llvm.org/installation.html#editor-plugins).
+
+Finally, run the following command to generate a `compile_commands.json` file, 
+which is used by `clangd` to enable all of its features (e.g. code completion, 
+jump to definition, cross-references, hovering, symbol renaming, etc.):
+
+```console
+bazel run //bazel:refresh_compile_commands
+```

WORKSPACE.bazel

@@ -350,6 +350,24 @@ versioned_http_archive(
     version = "1.2.13",
 )
 
+#
+# HEDRON COMPILE COMMANDS SETUP
+#
+
+# Hedron's Compile Commands Extractor for Bazel
+# https://github.com/hedronvision/bazel-compile-commands-extractor
+versioned_http_archive(
+    name = "hedron_compile_commands",
+    strip_prefix = "bazel-compile-commands-extractor-{version}",
+    sha256 = "d7ba7708816132f86f02864b9dba0c5abf249cc0fb035a34c430e4e538c87867",
+    url = "https://github.com/hedronvision/bazel-compile-commands-extractor/archive/{version}.tar.gz",
+    version = "d3afb5dfadd4beca48bb027112d029f2d34ff0a0",
+)
+
+load("@hedron_compile_commands//:workspace_setup.bzl", "hedron_compile_commands_setup")
+
+hedron_compile_commands_setup()
+
 #
 # DOCKER SETUP
 #
@@ -360,7 +378,9 @@ load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_depe
 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
 
 go_rules_dependencies()
+
 go_register_toolchains(version = "1.18")
+
 gazelle_dependencies(go_repository_default_config = "//:WORKSPACE.bazel")
 
 load(
@@ -371,19 +391,21 @@ load("@io_bazel_rules_docker//repositories:deps.bzl", _container_deps = "deps")
 load("@io_bazel_rules_docker//cc:image.bzl", _cc_image_repos = "repositories")
 
 _container_repositories()
+
 _container_deps(
     # See https://github.com/bazelbuild/rules_docker/issues/1902.
     go_repository_default_config = "@//:WORKSPACE.bazel",
 )
+
 _cc_image_repos()
 
 load("@io_bazel_rules_docker//container:container.bzl", "container_pull")
 
 container_pull(
     name = "alpine_linux_x86_64",
+    timeout = 300,  # [seconds]
     architecture = "amd64",
     digest = "sha256:93d5a28ff72d288d69b5997b8ba47396d2cbb62a72b5d87cd3351094b5d578a0",
     registry = "docker.io",
     repository = "alpine",
-    timeout = 300, # [seconds]
 )

bazel/BUILD.bazel

@@ -0,0 +1,22 @@
+load("@hedron_compile_commands//:refresh_compile_commands.bzl", "refresh_compile_commands")
+
+# gazelle:exclude external
+
+refresh_compile_commands(
+    name = "refresh_compile_commands",
+
+    # Specify the targets of interest.
+    # For example, specify a dict of targets and any flags required to build.
+    targets = [
+        "//pkg/ent",
+        "//pkg/noun",
+        "//pkg/ur",
+        "//pkg/urcrypt",
+        "//pkg/vere:urbit",
+    ],
+    # No need to add flags already in .bazelrc. They're automatically picked up.
+    # If you don't need flags, a list of targets is also okay, as is a single target string.
+    # Wildcard patterns, like //... for everything, *are* allowed here, just like a build.
+    # As are additional targets (+) and subtractions (-), like in bazel query https://docs.bazel.build/versions/main/query.html#expressions
+    # And if you're working on a header-only library, specify a test or binary target that compiles it.
+)