libtailscale-zig

This is libtailscale, packaged for Zig with cross-compilation support for Linux and macOS.

libtailscale is a C library that allows embedding Tailscale connectivity into applications. This wrapper uses Zig's cross-compilation toolchain to build shared libraries for multiple platforms from a single host.

• Fetches upstream libtailscale source automatically via zig's package manager
• Uses zig cc as the C compiler for Go's cgo, enabling cross-compilation
• Outputs shared libraries (.so / .dylib) with corresponding C headers

Supported targets:

• x86_64-linux (libtailscale_linux_amd64.so)
• aarch64-linux (libtailscale_linux_arm64.so)
• aarch64-macos (libtailscale_darwin_arm64.dylib)

Quick start

1. Install zig and go
2. zig build

Output will be in zig-out/:

zig-out/
├── bin/
│   └── echo_server
├── tailscale.h
├── libtailscale_darwin_arm64.dylib
├── libtailscale_darwin_arm64.h
├── libtailscale_linux_amd64.so
├── libtailscale_linux_amd64.h
├── libtailscale_linux_arm64.so
└── libtailscale_linux_arm64.h

Prerequisites

You need the following installed:

• Zig 0.15.2
• Go 1.21+

If you have nix you can use the dev shell provided by the flake in this repo:

nix develop
zig build

Build Commands

# Build all shared libraries (default)
zig build

# Or explicitly
zig build all

# Build specific target
zig build libtailscale_linux_amd64.so
zig build libtailscale_linux_arm64.so
zig build libtailscale_darwin_arm64.dylib

# Build example (echo_server linked against native shared lib)
zig build example

Cross-Compilation to macOS

When cross-compiling from Linux to macOS, the build requires the APPLE_SDK_PATH environment variable to be set. This points to the macOS SDK that provides system headers and libraries.

Using Nix (Recommended):

The provided nix flake automatically sets up APPLE_SDK_PATH when you enter the development shell:

nix develop
zig build

Manual Setup:

If not using nix, you'll need to obtain a macOS SDK and set the environment variable:

export APPLE_SDK_PATH=/path/to/MacOSX.sdk
zig build libtailscale_darwin_arm64.dylib

The SDK must contain usr/include with macOS system headers and System/Library/Frameworks with CoreFoundation, Security, and IOKit frameworks.

License

Copyright 2026 Casey Link

This zig build wrapper is distributed under the BSD-3-Clause license.

libtailscale is distributed under the BSD-3-Clause license by Tailscale Inc.