zig-main-runner README

Run or Debug zig main function in-place.

Also, Run or Debug test cases, build the whole workspace.

What's New?

See the CHANGELOG.

• v1.0.2
  • NOTE while you're debugging main(), kept its binary target name samed with its directory name.
  • Fix debugType === 'auto'

Features

This extension adds few commands for Zig development:

• Run/Debug main()
• Run/Debug a Single Test
• Run tests in a file
• Run tests in the workspace
• Build workspace
• Debug test

We add some codelens links at the top of function main(), tests, and first line of a zig file, like the following

Our inspirations are from go-main-runner, and zig-language-extras.

Requirements

• Visual Studio Code 1.79 or newer (or editors compatible with VS Code 1.79+ APIs)
• Zig 0.10 or newer any version and Zls
• Visual Studio Code Extensions:
  • VS Code Zig Language extension

Extension Settings

Enable Code Lens

You may disable or enable vscode codelens totally.

With settings:

  "zig-main-runner.main.enableCodeLens": false,

Default is true.

Enable Code Lens

You may enable or disable vscode codelen for test cases.

With settings:

  "zig-main-runner.main.enableCodeLensForTests": true,

Default is false(disabled).

Test Args

You may add additional test command arguments.

With settings

{
    "zig-main-runner.test.args": "--deps zlib=zlib --mod zlib::../zig-zlib/src/main.zig --library z",
}

But why?

Guide

The launching of main() function will be emitted to a Terminal window (as a vscode Task or a normal terminal session). By default, launching it as a Task allows you reinvoke it easily (by using vscode command Tasks: Rerun Last Task)

TIP

Requesting a keybinding to it is a good hit. Our private keybindings.json is a reference:

[
    {
      "key": "cmd+; cmd+;",
      "command": "workbench.action.tasks.reRunTask"
    }
]

It is useful while you are invoking main.zig again and again.

When you're debugging with Zig build.zig, only a main() whom has same name with its directory name can be supported because we have no plan to analysis build.zig for multiple executables. This structure is good:

<root>
  - src/
    - example/
      main.zig  # exe target should be named to 'example'
    main.zig    # exe target should be named to '<root>'
    build.zig

Build the Workspace

This works by running zig build.

Test the Workspace

This works by running zig build test.

Debugging

We assume the debugger is in your PATH to debug main() function or test cases.

To avoid unnecessary dependencies, our extension has only one dep to zig laguage. Here's some extensions for debugging:

• Native Debug for debugging on Linux
• CodeLLDB for debugging on MacOS
• C/C++ for debugging on Windows

But, you could manage the debuggers with OS package managers.

The default debugger types for each platform are as follows:

• "lldb" for darwin platform
• "cppvsdbg" for win32 platform
• "gdb" for other platforms

Release Notes

Users appreciate release notes as you update your extension.

1.0.1

First public release

---

REFs

• https://code.visualstudio.com/api/working-with-extensions/publishing-extension

• VS Code Extension Guidelines
• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

Enjoy!