Additional polish while adding bzlmod support

Author: cpsauer

ImplementationReadme.md

@@ -12,14 +12,25 @@ Hello, and thanks for your interest in the codebase :)
 
 We'd recommend setting up for rapid iteration as follows:
 
-Get a local copy. (e.g. `git clone git@github.com:hedronvision/bazel-compile-commands-extractor.git`)
+Get a local copy. (e.g. `git clone https://github.com/hedronvision/bazel-compile-commands-extractor`, though you probably want to make a fork and clone that so you can easily contribute back.)
 
-Then point your main repo (from which you're seeing issues) to use your local development copy of the compile commands. To do that, open `WORKSPACE`, and swap out the `http_archive` loading `hedron_compile_commands` with the following.
+Then point your main repo (from which you're seeing issues) to use your local development copy of the compile commands by doing the following.
+
+If you're bringing in this tool via your `MODULE.bazel` file, swap out the `git_override` loading `hedron_compile_commands` with the following.
+```Starlark
+local_path_override(
+    module_name = "hedron_compile_commands",
+    path = "../bazel-compile-commands-extractor" # Assuming this tool is cloned next to your project's repo
+)
+``````
+
+
+If you're bringing in this tool via your `WORKSPACE` file, swap out the `http_archive` loading `hedron_compile_commands` with the following.
 
 ```Starlark
 local_repository(
     name = "hedron_compile_commands",
-    path = "../bazel-compile-commands-extractor", # Or wherever you put it.
+    path = "../bazel-compile-commands-extractor", # Assuming this tool is cloned next to your project's repo
 )
 ```
 

MODULE.bazel

@@ -1,15 +1,3 @@
-"""bzlmod implementation for bazel-compile-commands-extractor
-This allows people using the new bzlmod system to add bazel-compile-commands-extractor as a module directly
-
-Local Development Note:
-Rather than using the git override method in the README.md, you can use the local_path_override method: (Add this to the MODULE.bazel of your project)
-
-bazel_dep(name = "hedron_compile_commands", dev_dependency = True)
-local_path_override(
-    module_name = "hedron_compile_commands",
-    path = "../bazel-compile-commands-extractor" # Assuming this repo is cloned next to your project
-)
-"""
 module(
     name = "hedron_compile_commands",
     version = "1.0.0",

README.md

@@ -42,9 +42,27 @@ Howdy, Bazel user 🤠. Let's get you set up fast with some awesome tooling for
 
 There's a bunch of text here but only because we're trying to spell things out and make them easy. If you have issues, let us know; we'd love your help making things even better and more complete—and we'd love to help you!
 
-### If you're using the WORKSPACE system (you probably are), do the usual WORKSPACE setup:
+### First, add this tool to your Bazel setup.
 
-Copy this into your Bazel `WORKSPACE` file to add this repo as an external dependency, making sure to update to the [latest commit](https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main) per the instructions below.
+#### If you have a MODULE.bazel file and are using the new [bzlmod](https://bazel.build/external/migration) system
+Copy this into your `MODULE.bazel`, making sure to update to the [latest commit](https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main) per the instructions below.
+
+```Starlark
+# Hedron's Compile Commands Extractor for Bazel
+# https://github.com/hedronvision/bazel-compile-commands-extractor
+bazel_dep(name = "hedron_compile_commands", dev_dependency = True)
+git_override(
+    module_name = "hedron_compile_commands",
+    remote = "https://github.com/hedronvision/bazel-compile-commands-extractor.git",
+    commit = "25ac20bc2b9b491c22798a54a1c9ecbc6b026749",
+    # Replace the commit hash (above) with the latest (https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main); the stale one here is too old to work with bzlmod.
+    # Even better, set up Renovate and let it do the work for you (see "Suggestion: Updates" in the README).
+)
+```
+
+#### If you're using the traditional WORKSPACE system
+
+Copy this into your Bazel `WORKSPACE` file, making sure to update to the [latest commit](https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main) per the instructions below.
 
 ```Starlark
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
@@ -55,7 +73,7 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 http_archive(
     name = "hedron_compile_commands",
 
-    # Replace the commit hash in both places (below) with the latest, rather than using the stale one here.
+    # Replace the commit hash (ed994039a951b736091776d677f324b3903ef939) in both places (below) with the latest (https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main), rather than using the stale one here.
     # Even better, set up Renovate and let it do the work for you (see "Suggestion: Updates" in the README).
     url = "https://github.com/hedronvision/bazel-compile-commands-extractor/archive/ed994039a951b736091776d677f324b3903ef939.tar.gz",
     strip_prefix = "bazel-compile-commands-extractor-ed994039a951b736091776d677f324b3903ef939",
@@ -65,29 +83,15 @@ load("@hedron_compile_commands//:workspace_setup.bzl", "hedron_compile_commands_
 hedron_compile_commands_setup()
 ```
 
-### If you're using Bazel's new [bzlmod](https://bazel.build/external/migration) system:
-You're probably using bzlmod if you have `common --enable_bzlmod` in your `.bazelrc` (or are using Bazel v7+). If so, copy this into your Bazel `MODULE.bazel` file to add this repo as an external dependency, making sure to update to the [latest commit](https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main) per the instructions below.
-
-```Starlark
-bazel_dep(name = "hedron_compile_commands", dev_dependency = True)
-git_override(
-    module_name = "hedron_compile_commands",
-    remote = "https://github.com/hedronvision/bazel-compile-commands-extractor.git",
-    commit = "25ac20bc2b9b491c22798a54a1c9ecbc6b026749",
-    # Replace the commit hash (above) with the latest, the stale one here is too old to work with bzlmod.
-    # Even better, set up Renovate and let it do the work for you (see "Suggestion: Updates" in the README).
-)
-```
-
-#### Suggestion: Updates
+#### Either way: Get Updates via Renovate
 
 Improvements come frequently, so we'd recommend keeping up-to-date.
 
 We'd strongly recommend you set up [Renovate](https://github.com/renovatebot/renovate) (or similar) at some point to keep this dependency (and others) up-to-date by default. [We aren't affiliated with Renovate or anything, but we think it's awesome. It watches for new versions and sends you PRs for review or automated testing. It's free and easy to set up. It's been astoundingly useful in our codebase, and we've worked with the wonderful maintainer to make things great for Bazel use. And it's used in official Bazel repositories.] Here's a [Renovate configuration example from one of our projects](https://github.com/hedronvision/bazel-cc-filesystem-backport/blob/main/renovate.json5), in the hope that it might save you time.
 
 If not now, maybe come back to this step later, or watch this repo for updates. [Or hey, maybe give us a quick star, while you're thinking about watching.] Like Abseil, we live at head; the latest commit to the main branch is the commit you want. So don't rely on release notifications; use [Renovate](https://github.com/renovatebot/renovate) or poll manually for new commits.
 
-### Get the extractor running.
+### Second, get the extractor running.
 
 We'll generate a `compile_commands.json` file in the root of the Bazel workspace.
 
@@ -236,8 +240,6 @@ If you're using Bazel for the C language family, you'll likely also want some of
 1. A good way of making secure network requests: [hedronvision/bazel-make-cc-https-easy](https://github.com/hedronvision/bazel-make-cc-https-easy)
 2. A way to use std::filesystem across platforms: [hedronvision/bazel-cc-filesystem-backport](https://github.com/hedronvision/bazel-cc-filesystem-backport)
 
-If so, please check out our other project, [hedronvision/bazel-make-cc-https-easy](https://github.com/hedronvision/bazel-make-cc-https-easy).
-
 ---
 *Looking for implementation details instead? Want to dive into the codebase?*
 See [ImplementationReadme.md](./ImplementationReadme.md).

workspace_setup.bzl

@@ -1,20 +1,27 @@
 # Do not change the filename; it is part of the user interface.
 
-def hedron_compile_commands_setup(ctx = None):
-    """Set up a WORKSPACE to have hedron_compile_commands used within it."""
+def hedron_compile_commands_setup(module_ctx = None):
+    """Set up a WORKSPACE to have hedron_compile_commands used within it.
+
+    module_ctx is for automatic-implicit use by bzlmod only.
+    """
 
     # Unified setup for users' WORKSPACES and this workspace when used standalone.
     # See invocations in:
-    #     README.md (for users)
+    #     README.md (for WORKSPACE users)
+    #     MODULE.bazel (for bzlmod users)
     #     WORKSPACE (for working on this repo standalone)
 
+    # If adding dependencies available via bzlmod, consider adding them to MODULE.bazel, too, and only loading them the WORKSPACE way when needed.
+    # if not module_ctx:
+    #     # Load bzlmod-available packages.
+
     # Currently nothing to do -> no-op.
     # So why is this even here? Enables future expansion (e.g to add transitive dependencies) without changing the user interface.
     pass
 
-hedron_compile_commands_extension = module_extension(
+hedron_compile_commands_extension = module_extension( # Note: Doesn't break loading from WORKSPACE as far back as Bazel 5.0.0
     implementation = hedron_compile_commands_setup,
-    # This extension is loaded when using bzlmod (MODULE.bazel) and will run the same function as WORKSPACE,
-    # but passes in a module_ctx object for advanced context of the whole project, allowing for complex, project wide modifiying extensions
-    # It's not currently used but is always passed in. ctx is defaulted to None for compatibility with workspace setup.
+    # This extension is automatically loaded when using bzlmod (from MODULE.bazel) and will run the same function as WORKSPACE,
+    # but passes in a module_ctx object for advanced context of the whole project, allowing for complex, project wide modifiying extensions and distinguishing between WORKSPACE and bzlmod setups.
 )