Downstream Packaging

Build Options

Run zig build --help in the root of the ZLS source directory to print usage information.

Here are some of the common build options:

• -Doptimize=ReleaseSafe
• -Dtarget
• -Dcpu=baseline (opposite of -march=native)
• --prefix

Resolve version string

When compiling a tagged release of ZLS, the version is hard coded. No further action is needed.

For development builds, the version string is determined by running git -C . describe --match "*.*.*" --tags and formatting the output as MAJOR.MINOR.PATCH-dev.COMMIT_HEIGHT+SHORT_COMMIT_HASH (e.g. 0.14.0-dev.365+6a16b27). If the version cannot be resolved, it defaults to MAJOR.MINOR.PATCH-dev (e.g. 0.14.0-dev). This logic is implemented in the getVersion function within build.zig.

If building ZLS without access to Git metadata (e.g., from a shallow clone or tarball), it is recommended to manually specify the version string using the -Dversion-string build option.

Dependency fetching

ZLS uses Zig’s builtin package manager to fetch dependencies and compile them from source. By default, Zig automatically downloads dependencies and stores them in a global cache directory. The global cache directory can be found by running zig env and inspecting the global_cache_dir field. Packages are stored in the p subdirectory.

Below is an example of how the package directory may look after building ZLS:

/home/me/.cache/zig/p
├── diffz-0.0.1-G2tlIQrOAQCfH15jdyaLyrMgV8eGPouFhkCeYFTmJaLk
│   ├── build.zig
│   ├── build.zig.zon
│   ├── DiffMatchPatch.zig
│   └── ...
├── known_folders-0.0.0-Fy-PJkfRAAAVdptXWXBspIIC7EkVgLgWozU5zIk5Zgcy
│   ├── build.zig
│   ├── build.zig.zon
│   ├── known-folders.zig
│   └── ...
└── lsp_kit-0.1.0-bi_PL04yCgAxLsF0hH2a5sZKT84MGQaKXouw2jvCE8Nl
    ├── build.zig
    ├── build.zig.zon
    ├── src
    └── ...

Dependencies are listed in the build.zig.zon file, where url specifies the canonical source and hash is used to pin and verify the package contents. Be aware that there may be additional transitive dependencies that are not listed in the build.zig.zon of the root project.

To support workflows in which dependency fetching is performed separately from the build process, the --system [pkgdir] option disables automatic package fetching and allows dependencies to be supplied from a pre-fetched package directory. Downstream vendors may choose their preferred method for fetching the required packages (for example, zig fetch, git clone, or curl source.tar.gz), provided that the resulting package contents match the specified hash.

Refer to zig fetch for instructions on acquiring packages and computing or verifying their hashes.