How to properly set up a zig project for vscode?

[devout solar]

I've spent the las few weeks on and off playing with zig and I quite like various aspects of it. But I'm having real trouble how to correctly set up the environment and the documentation doesn't seem to cover that:

• we have build.zig.zon which apparently lets you import dependencies, great. And from what I understood, you need to use the dependency api and then add it as imports to the root module? This is not what the docu and various posts say, that's reverse-engineered from, I believe, the zig compiler. So it may be wrong
• how are you supposed to run tests? when I integrate things in build.zig, it looks like they get somewhat picked up, but zig build test executes everything and caches the output so I can't even look at the errors / test results normally. On the other hand zig test seems to ignore build.zig and then fails to build a file.
• how do you debug a file with tests? both the official zig extension and zig language extras run zig test under the hood, so they won't compile, because they ignored build.zig. (I managed to run a single unit test with debugger no problem as long as it's a toy example without external dependencies).
• how to have the lsp eat build.zig? The same problem about missing libraries also happens in the LSP insofar as it gives compile errors for missing modules even though the same file compiles under zig build

It is so hard to set up, I'm almost certain I must be doing something deeply flawed, but I'm just not seeing any posts or docu explaining how to set it up.

Writing anything bigger than a toy example, I'd expect one to need a proper per-file debugging experience for tests, debugging the app with a main entry point and being able to depend on modules that are not part of the project but rather imported through build.zig.zon

[fossil egret]

Yeah the dev workflow isn't completely nailed down yet, I had similar challenges to you. Will try and give some deeds on each point.

• Yeah, the build.zig.zon lets you specify dependencies and such between differing libraries. The auto-generated one has commented docs that should explain how to use it. build.zig then picks up the config there, and you'll need to write build code to add the dependencies to your exe/lib. std.Build has changed a lot so googling answers can be wrong or unusable.

For a local example I have right now, by build.zig.zon for my game has this:

    .dependencies = .{
        .engine = .{
            .path = "../engine/",
        },
    },

Where ../engine/ has another zig project with a build.zig set up to make a library. Then I simply do this in the build.zig for the game before b.installArtifact(exe):

    const engine_dep = b.dependency("engine", .{
        .target = target,
        .optimize = optimize,
    });
    const engine = engine_dep.module("engine");
    exe.root_module.addImport("engine", engine);

Then I can just use const engine = @import("engine"); anywhere inside the game project.

But yeah, the project layout, build process and everything is in flux, so I don't think there's been a huge investment in documenting it in it's current state. You sort of have to figure it out from other projects on github.

• Tests are a bit weird still - for me the test integration "works" in VSCode for some definitions of that. It's worth nothing that zig test is quite different to zig build test, the former is quite basic and is what VSCode uses, and the latter uses the full build flow in build.zig, but also will only run tests it picks up, and due to Zig's lazy loading, you may not see tests run when you expect them to.

I can click the green tick next to a test to run it (VSCode does this with zig test) and it works given some caveats:

1. The code it uses cannot depend on any imports that are specified in the build.zig.
2. the code cannot use imports that escape the current file (e.g. no @import("../thing.zig").
3. Debugging did work at one point, but doesn't anymore for me 😦

With that in mind, running tests in VSCode is basically reserved for unit tests on pure Zig code, no extra dependencies.

To actually debug tests, I've used a launch.json that attaches to a zig build test run, and that does the trick. You can also debug a hanging test by just attaching to the process directly if need be.

• For getting ZLS to pick up the build.zig I've not had to do anything so I'm not sure what you've done wrong. Maybe sharing your project structure would help? I only have the "Zig Language" extension installed and that was enough.

But yeah, it's not a perfect workflow yet, mostly because I would assume folks don't want to invest too much with the build pipeline is still in flux, and ZLS itself is due to be replaced.

[fossil egret]

FWIW when you do a zig build test then in .zig-cache/something/ there'll be a test executable you can then run and debug, so there's that too 😆

Maybe someone else has some better current VSCode advice, but I hope that helps 🙂

[devout solar]

thx