Modules: Switching `root_id`

Background and Motivation

Most projects consist of a small number of compile steps, with a subset of shared modules. This simplicity has been sufficient for many use cases. However, as projects grow in complexity, managing dependencies between modules becomes increasingly important.

The Limitations of Flat Module Lists

While a flat list of modules has worked well enough in the past (excluding "root" imports), it fails to account for nuanced relationships between modules. In particular, when multiple root modules depend on the same set of sub-modules, distinguishing between them becomes challenging.

Example Use Case: pico_custom-clock-config and pico2_custom-clock-config

Consider a project with two distinct root modules: pico_custom-clock-config and pico2_custom-clock-config. Both roots share a common dependency chain, but require different sets of sub-modules to function correctly. The output below illustrates the resulting module dependencies:

info: 21: pico_custom-clock-config @ /home/rad/lab/zta/microzig/core/src/start.zig
...
info:    * config @ /home/rad/lab/zta/microzig/examples/raspberrypi/rp2xxx/.zig-cache/c/dc2ba59aca93e42b31d06a17f3a3b984/options.zig
info:    * chip @ /home/rad/lab/zta/microzig/examples/raspberrypi/rp2xxx/.zig-cache/o/ad3f83562b3e6f54efbe49dfe0c23a80/chip.zig
...

info: 22: pico2_custom-clock-config @ /home/rad/lab/zta/microzig/core/src/start.zig
...
info:    * config @ /home/rad/lab/zta/microzig/examples/raspberrypi/rp2xxx/.zig-cache/c/cda7ba916bca7ef9bb3b1680200e8dc2/options.zig
info:    * chip @ /home/rad/lab/zta/microzig/examples/raspberrypi/rp2xxx/.zig-cache/o/6ce8af041f0d2f41c8ce10088e763a0e/chip.zig
...

Notice how config and chip differ in their dependencies, despite sharing the same root file. This is not possible to distinguish through path matching alone.

Solution: User-Configurable Root Module Setting

To address this challenge, we've implemented a solution that allows developers to explicitly select which root module fits their current session requirements.

Switching and Verifying the Root ID Value

Step-by-Step Guide

Open your project's root folder in your preferred editor.

1. Access build.zig: Open the build.zig file within the editor.
2. Wait for Module Collection: Allow a few seconds for the server to collect all modules from your project.

Viewing Current Root ID and Modules

3. Inspect build Function: Hover over the build function as shown below:

pub fn build(b: *std.Build) void { // $ls root_id [root ID]
//     ^^^^^ -- here

This should display current information about the root ID and its associated modules.

To View All Roots

Click on "See List of all roots" in the hover popup. Note the number assigned to each root (0-based indexing).

Switching Root IDs

Create/Modify the magic comment on the same line as pub fn build(b: *std.Build) void { // $ls root_id [root ID], specifying the new root ID, eg:

pub fn build(b: *std.Build) void { // $ls root_id 1

Re-hover over the build function to confirm that changes have taken effect without needing to save or keep the file open.