Zls Integration

ZLS Integration Skill

Zig Language Server (ZLS) provides IDE features for Zig development. This skill covers installation, configuration, build-on-save diagnostics, and troubleshooting.

Quick Reference

Installation

Via Package Manager (Recommended)

# macOS (Homebrew)
brew install zls

# Nix/Flox
flox install zls

# Arch Linux
pacman -S zls

# From source (any platform)
git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

Version Compatibility

Always match ZLS version to Zig version.

Configuration

zls.json Location

~/.config/zls.json           # Linux/macOS
%APPDATA%\zls.json           # Windows
<project>/.zls.json          # Project-specific

Essential Configuration

{
  "zig_exe_path": "/path/to/zig",
  "enable_autofix": true,
  "enable_import_access": true,
  "highlight_global_var_declarations": true,
  "warn_style": true,
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Build-On-Save Diagnostics

ZLS can run your build script on save to catch semantic errors (type mismatches, wrong argument counts) that parser-level analysis misses.

Step 1: Add Check Step to build.zig

// build.zig
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    b.installArtifact(exe);

    // ZLS check step - runs on save
    const check = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    
    const check_step = b.step("check", "Check compilation (for ZLS)");
    check_step.dependOn(&check.step);
}

Step 2: Configure ZLS

{
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Step 3: Editor Setup

VS Code (zls extension):

// settings.json
{
  "zig.zls.path": "/path/to/zls",
  "zig.zls.enableBuildOnSave": true
}

Neovim (nvim-lspconfig):

require('lspconfig').zls.setup({
  settings = {
    zls = {
      enable_build_on_save = true,
      build_on_save_step = "check"
    }
  }
})

Emacs (lsp-mode):

(setq lsp-zig-zls-executable "/path/to/zls")
(setq lsp-zig-enable-build-on-save t)

Troubleshooting

No Diagnostics Appearing

1. Verify ZLS is running: pgrep -l zls
2. Check ZLS log: ~/.cache/zls/zls.log
3. Ensure Zig version matches: zig version vs zls --version
4. Test build manually: zig build check

Slow Completions

{
  "skip_std_references": true,
  "prefer_ast_check_as_child_process": true
}

Import Resolution Failures

{
  "enable_import_access": true,
  "additional_module_paths": ["deps/", "vendor/"]
}

Build-On-Save Not Working

1. Verify check step exists in build.zig
2. Run zig build check manually
3. Check ZLS config: enable_build_on_save: true
4. Restart language server

GF(3) Integration

ZLS diagnostics map to triadic workflow:

Conservation: errors + warnings + hints → 0 as code improves.

Editor Integration Matrix

Related Skills

• zig-programming - Core Zig language and stdlib
• zig-async-io - Async/concurrent patterns (0.16.0+)
• tree-sitter - AST-based code analysis

Resources

• ZLS GitHub
• ZLS Configuration Guide
• Build-On-Save Guide
• Zig BBQ Cookbook

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

• networkx [○] via bicomodule
  • Universal graph hub

Bibliography References

• general: 734 citations in bib.duckdb

SDF Interleaving

This skill connects to Software Design for Flexibility (Hanson & Sussman, 2021):

Primary Chapter: 4. Pattern Matching

Concepts: unification, match, segment variables, pattern

GF(3) Balanced Triad

zls-integration (−) + SDF.Ch4 (+) + [balancer] (○) = 0

Skill Trit: -1 (MINUS - verification)

Secondary Chapters

• Ch6: Layering
• Ch2: Domain-Specific Languages

Connection Pattern

Pattern matching extracts structure. This skill recognizes and transforms patterns.

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 0 (ERGODIC)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #26D826

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.