Project Setup

• AssemblyName: Name of the project. By default, this is set to the file name of the project file. Used to compute the final binary name (e.g. foo becomes libfoo.so).

• OutputType (Exe, WinExe, Library): Output binary type. When targeting Windows and building executables, Exe and WinExe will target the CUI and GUI subsystems, respectively. Defaults to Library.

• IsTestable (true, false): Enable/disable dotnet test for Zig projects. Defaults to true.

• IsPackable (true, false): Enable/disable dotnet pack. Defaults to true.

• IsPublishable (true, false): Enable/disable dotnet publish. Defaults to true.

• DefaultSources (true, false): Enable/disable default Compile item includes. Defaults to true.

• Deterministic (true, false): Enable/disable deterministic builds. Among other things, this will try to prevent the compiler from using absolute paths and will prevent usage of certain problematic language features like __TIME__. Defaults to true.

• EditorSupport (true, false): Enable/disable editor support. For C/C++ projects, this means generating a compile_commands.json compilation database in IntermediateOutputPath. Defaults to true.

• FormatOnBuild (true, false): Enable/disable formatting source code into canonical style on build in Zig projects. Defaults to false.

Package Information

• Product: Human-friendly product name for the package. Defaults to the value of AssemblyName.

• Authors: A list of package authors. Defaults to the value of AssemblyName.

• Description: Brief description of the package. Defaults to Package Description.

• Copyright: Copyright notice for the package. Unset by default.

• PackageProjectUrl: Website URL associated with the package. Unset by default.

• RepositoryUrl: Source code repository URL for the package. Unset by default.

Preprocessor

• PublicHeadersPath: Can be set to a directory containing public C/C++ headers. These headers will be included in the NuGet package and will flow to dependent projects. This directory will also be treated as an IncludeDirectory. Unset by default.

• DefineConstants: A comma-separated list of preprocessor macros to define. Each entry can be a simple name or an assignment of the form NAME=VALUE. These macros are passed to the compiler with the -D flag. Note that this applies to Zig as well, not just C/C++.

• CompilerDefines (true, false): Enable/disable adding some implicit DefineConstants macros that describe the Zig compiler version. Defaults to true.

• PlatformDefines (true, false): Enable/disable adding some implicit DefineConstants macros that describe the target platform characteristics. Defaults to true.

• ConfigurationDefines (true, false): Enable/disable adding some implicit DefineConstants macros that describe the build configuration (Debug, ReleaseFast, etc). Defaults to true.

• PackageDefines (true, false): Enable/disable adding some implicit DefineConstants macros that describe the project being built. Defaults to true.

Language Features

• ZigVersion (major.minor.patch): The version of the Zig compiler toolset to use. Defaults to the latest version known to the Zig SDK package that is in use.

• LanguageStandard: The language standard used for C/C++ projects. Passed to Clang's -std flag. Defaults to the latest standards known to the compiler version that ZigVersion defaults to.

• AccessControl (true, false): Enable/disable access control in C++ projects. Defaults to true.

• BlockExtensions (true, false): Enable/disable Clang's block language extensions. Defaults to false.

• CxxExceptions (true, false): Enable/disable C++ exceptions. In C projects, this controls whether the C code will be unwindable by C++ exceptions. Defaults to true.

• CxxReflection (true, false): Enable/disable generating C++ run-time type information. This feature is required for some uses of dynamic_cast. Defaults to true.

• MicrosoftExtensions (true, false): Enable/disable a variety of Microsoft C/C++ extensions. Defaults to false, but note that the compiler itself always enables some parts of this when targeting Windows as Win32 headers require it.

• NoEntryPoint (true, false): Enable/disable the omission of an entry point function when building executables. Defaults to false.

Static Analysis

• EnforceCodeStyleInBuild (true, false): Enable/disable checking that source code is in the canonical style during build in Zig projects. Defaults to false.

• BufferAnalysis (true, false): Enable/disable static analysis with unsafe buffer annotations in C/C++ projects. Defaults to false.

• WarningLevel (0-4): How aggressively the compiler should analyze C/C++ projects for potentially problematic code. 0 disables warnings completely; 4 enables all warnings, including a few controversial ones. Defaults to 3.

• TreatWarningsAsErrors (true, false): Enable/disable reporting warnings as errors in C/C++ projects. Defaults to false.

Code Generation

• Configuration (Debug, Release): Specifies the overarching configuration. When Release is specified, ReleaseMode comes into effect. Defaults to Debug. Usually specified by the user as e.g. dotnet build -c Release.

• DebugSymbols (true, false): Enable/disable emitting debug symbols. Defaults to true if Configuration is Debug; otherwise, false.

• ExecutionModel (Command, Reactor): Specifies the execution model to use when building WebAssembly executables. Defaults to Command.

• FastMath (true, false): Enable/disable certain lossy floating point optimizations that may not be standards-compliant. Defaults to false.

• LinkTimeOptimization (true, false): Enable/disable link-time optimization. Defaults to false.

• SymbolExports (Used, All): Specifies whether to export all public symbols or only those that are needed to link successfully. This only applies when building executables. Defaults to Used.

• SymbolVisibility (Default, Hidden): Specifies the symbol visibility in C/C++ projects when __attribute__((visibility(...))) is not specified. Default (the default 😉) means public, while Hidden means private.

• AllowUndefinedSymbols (true, false): Enable/disable permitting undefined symbols when linking. This usually only applies when building libraries. Defaults to false.

• EagerBinding (true, false): Enable/disable eager binding of symbols when performing dynamic linking at run time. Eager binding has security benefits, especially in combination with RelocationHardening. It is also more reliable if calling external functions from signal handlers. Defaults to true.

• RelocationHardening (true, false): Enable/disable marking relocations as read-only. This has security benefits, especially in combination with EagerBinding. Defaults to true.

• ImageBase: The location in memory that the binary should be loaded at. Only takes effect at run time if DynamicImageBase is false. Unset by default.

• StackSize: Sets the stack size for the main thread. This only applies when building executables. Unset by default.

Cross-Compilation

• RuntimeIdentifier: Specifies the runtime identifier (i.e. platform) to target. When unset, Build and Clean will run for all runtime identifiers specified in RuntimeIdentifiers. Usually specified by the user as e.g. dotnet build -r linux-x64. Unset by default.

• RuntimeIdentifiers: A semicolon-separated list of runtime identifiers that the project supports. All targets in this list will be cross-compiled as necessary. Defaults to all targets that the Zig compiler has known-good support for.

• UseMicrosoftAbi (true, false): Enable/disable using the Microsoft ABI when targeting Windows. This may be necessary when linking to static libraries containing C++ code that was compiled for the Microsoft ABI. Note that it is currently not possible to cross-compile from non-Windows platforms when using the Microsoft ABI. Unset by default.

• UseEmulator (true, false): Enable/disable usage of an appropriate binary emulator when cross-compiling. Defaults to true.

ZLS

At the moment, no further configuration is necessary.

clangd

You have to tell clangd where to find the compile_commands.json compilation database. The Zig SDK creates these files in IntermediateOutputPath, i.e. obj/Debug/linux-x64 if you build with Configuration=Debug and RuntimeIdentifier=linux-x64. Due to the nature of C/C++ compilation, these compilation databases have to be dependent on build flags. So, you will have to pick one of them to use for your editing experience. The good news is that you can change which compilation database you use at any point if you need to.

To tell clangd where to find the compilation database, create a file called .clangd in your project directory with the following contents:

CompileFlags:
    CompilationDatabase: obj/Debug/linux-x64

(You may want to add this file to .gitignore.)

You can now restart the clangd language server. You should start to see rich editor features like code completion, hover widgets, navigation, etc.

{
  "msbuild-sdks": {
    "Vezel.Zig.Sdk": "x.y.z"
  }
}

(Replace x.y.z with the actual NuGet package version.)

Next, create a project file. A library project is as simple as:

<Project Sdk="Vezel.Zig.Sdk" />

An executable project looks like:

<Project Sdk="Vezel.Zig.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
    </PropertyGroup>
</Project>

The project file extension determines the language your code will be compiled as - .cproj for C, .cxxproj for C++, and .zigproj for Zig.

The convention used by the Zig SDK is that C projects should use a .c extension for source files and .h for header files, while C++ projects should use .cxx and .hxx. Zig projects use .zig.

For C/C++ projects, it does not matter what you name your source and header files. For Zig executable projects, your root source file should be named main.zig. Zig library projects should use the project name for the root source file; that is, if your project file is mylib.zigproj, your root source file should be mylib.zig.

Once you have written some code, you can use dotnet build, dotnet run, etc.

• Compile: Source code files passed to the Zig compiler. By default, the Zig SDK will populate this item type according to the project type.

• PreludeHeader: C/C++ header files that will be automatically #included in every C/C++ source file by way of Clang's -include flag.

• IncludeDirectory: Header include directories passed to the compiler with the -I flag. Note that this applies to Zig as well, not just C/C++.

• LibraryIncludeDirectory: Header include directories passed to the compiler with the -isystem flag. Note that this applies to Zig as well, not just C/C++.

• LinkerDirectory: Library search directories passed to the linker with the -L flag.

• LinkerReference: Names of native libraries that should be linked using the -l flag. These can be either static or dynamic.

• LibraryReference: Direct paths to native library files that should be linked, ignoring library search directories. These can be either static or dynamic.

• CHeader: Prepopulated by the Zig SDK with all files in the project directory ending in .h.

• CSource: Prepopulated by the Zig SDK with all files in the project directory ending in .c.

• CxxHeader: Prepopulated by the Zig SDK with all files in the project directory ending in .hxx.

• CxxHeader: Prepopulated by the Zig SDK with all files in the project directory ending in .cxx.

• ZigSource: Prepopulated by the Zig SDK with all files in the project directory ending in .zig.

• Watch: Files that are monitored by dotnet watch for code changes. The Zig SDK will automatically populate this with all C, C++, and Zig source and header files in the project directory.

Features

Here are some of the Zig SDK highlights:

• Cross-compilation: Thanks to the Zig compiler's excellent cross-targeting support, cross-compilation is a first-class citizen in the Zig SDK. Gone are the days of having to do overly complicated cross toolchain setup, or resorting to building on multiple platforms for releases - just type dotnet build to compile for all targets supported by your project.

• Unit testing: The Zig language provides built-in unit testing constructs. The Zig SDK allows you to run your project's unit tests with the familiar dotnet test command. Test name filters are supported - e.g. dotnet test --filter foo.

• Code change monitoring: The Zig SDK integrates with dotnet watch so that e.g. dotnet watch build, dotnet watch run, and dotnet watch test work as expected, enabling a rapid development loop.

• Sensible NuGet packaging: Out of the box, dotnet pack with the Zig SDK will produce NuGet packages containing cross-built binaries for all platforms that your project supports. Also, your public C and C++ header files will be bundled, as will your Zig source code. This makes the resulting NuGet package easy to consume both in .NET projects and in other projects using the Zig SDK.