cmake-zig

CMake integration for building Zig libraries. Provides functions to locate Zig, detect target platforms, and build Zig modules that can be linked into CMake projects.

npm i cmake-zig

Usage

In your CMakeLists.txt:

find_package(cmake-zig REQUIRED PATHS node_modules/cmake-zig)

add_zig_module(my_zig_lib)

target_link_libraries(my_target PRIVATE my_zig_lib)

API

add_zig_module

Builds a Zig project and creates an imported CMake library target.

add_zig_module(
  <name>
  [PATH <path>]
  [TARGET <target>]
  [OPTIMIZE <mode>]
  [ARTIFACT_NAME <artifact>]
  [BUILD_OPTIONS <options>...]
  [SHARED]
)

Arguments

| Argument | Default | Description | | --------------- | ------------------------------------- | ------------------------------------------ | | PATH | CMAKE_CURRENT_LIST_DIR | Path to directory containing build.zig | | TARGET | Same as name | CMake target name for the imported library | | OPTIMIZE | Auto-detected from CMAKE_BUILD_TYPE | Zig optimization mode | | ARTIFACT_NAME | Same as name | Name of the output library artifact | | BUILD_OPTIONS | - | Additional options passed to zig build | | SHARED | Off | Build as shared library instead of static |

Build Mode Mapping

| CMake Build Type | Zig Optimize Mode | | ---------------- | ----------------- | | Debug | Debug | | Release | ReleaseFast | | RelWithDebInfo | ReleaseSafe | | MinSizeRel | ReleaseSmall |

Example

add_zig_module(
  bare_addon_zig
  BUILD_OPTIONS -Dsome_option=value
)

find_zig

Locates the Zig executable.

find_zig(result)

message(STATUS "Zig found at: ${result}")

zig_target

Returns the Zig target triple for the current build configuration.

zig_target(triple)
# e.g., "aarch64-macos.14.0-none" or "x86_64-linux-gnu"

zig_arch

Returns the Zig architecture name.

zig_arch(arch)
# e.g., "aarch64", "x86_64", "arm"

Supported architectures:

• aarch64 (arm64)
• arm (armv7-a, armeabi-v7a)
• x86_64 (x64, amd64)
• x86 (i386, i486, i586, i686)
• mipsel, mips

zig_os

Returns the Zig OS name.

zig_os(os)
# e.g., "macos", "linux", "windows", "ios"

zig_abi

Returns the Zig ABI name.

zig_abi(abi)
# e.g., "none", "gnu", "msvc", "android", "simulator"

zig_optimize

Returns the Zig optimization mode for the current CMake build type.

zig_optimize(mode)
# e.g., "Debug", "ReleaseFast", "ReleaseSafe", "ReleaseSmall"

zig_version

Returns the installed Zig version.

zig_version(ver)
message(STATUS "Zig version: ${ver}")

Target Properties

After calling add_zig_module, the following properties are set on the target:

| Property | Description | | ------------------- | ---------------------- | | ZIG_MODULE_NAME | The module name | | ZIG_MODULE_PATH | Path to the Zig source | | ZIG_BUILD_DIR | Zig build directory | | ZIG_OUT_DIR | Zig output directory | | ZIG_ARTIFACT_NAME | Output artifact name |

Build Outputs

The Zig module is built to:

${CMAKE_CURRENT_BINARY_DIR}/_zig/${name}/out/lib/lib${name}.a

For shared libraries (SHARED option):

• Linux: lib${name}.so
• macOS: lib${name}.dylib
• Windows: ${name}.dll + ${name}.lib (import library)

Cross-Compilation

The module automatically detects the target platform from CMake variables:

• macOS/iOS: Uses CMAKE_OSX_ARCHITECTURES and CMAKE_OSX_DEPLOYMENT_TARGET
• Android: Uses CMAKE_ANDROID_ARCH_ABI
• Windows: Uses CMAKE_GENERATOR_PLATFORM
• Others: Uses CMAKE_SYSTEM_PROCESSOR and CMAKE_SYSTEM_NAME

Requirements

• CMake 4.0+
• Zig 0.14+

Related

• bare-zig - Zig bindings for Bare
• bare-addon-zig - Zig addon template
• cmake-cargo - Similar CMake integration for Rust

License

Apache-2.0