Loading...
Loading...
Loading...
Loading...
Loading...
The Zig SDK is an MSBuild SDK that augments the .NET SDK with the ability to build Zig, C, and C++ projects.
With support for multiple programming languages, cross-compilation, NuGet packaging, and more, the Zig SDK makes it trivial to author native components as part of your .NET solution - without all the hassle that is usually part and parcel of building and packaging native code. These features are powered by the Zig toolchain.
Here are some of the Zig SDK highlights:
Multiple programming languages: Although Zig is a modern and pleasant systems programming language, you might prefer to use C or C++ instead. As it happens, the Zig compiler also embds a full C and C++ compiler - namely, Clang. So, whichever language you prefer, the Zig SDK has you covered.
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.
Multi-project solutions: Soon™.
Please note that the Zig SDK is not intended to be a full replacement for the Zig Build System. The goal of the Zig SDK is specifically to make it simple to integrate Zig, C, and C++ components into the .NET ecosystem. For that reason, the Zig SDK has no support for platforms that Zig supports but that .NET does not (yet) run on, such as linux-riscv64. The level of configuration that is possible for C and C++ is also somewhat limited compared to most build systems that support those languages.
The Zig SDK is capable of integrating with ZLS and clangd. This means that any editor with support for those language servers (e.g. Visual Studio Code) can be used to edit a project using the Zig SDK.
Start by installing ZLS. The Visual Studio Code extension is highly recommended.
At the moment, no further configuration is necessary.
Start by installing clangd. The Visual Studio Code extension is highly recommended.
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:
(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.
The following MSBuild items are used by the Zig SDK:
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.
To use the Zig SDK, first make sure that you have the .NET 6 SDK (or later) installed.
Next, create a global.json file in the root of your repository and add an entry for the Vezel.Zig.Sdk package under the msbuild-sdks property:
(Replace x.y.z with the actual NuGet package version.)
Next, create a project file. A library project is as simple as:
An executable project looks like:
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.
The MSBuild properties described on this page are used by the Zig SDK. These properties can all be set in PropertyGroups in your project file. Most of them should have sensible defaults for new projects; a few (such as TreatWarningsAsErrors and SymbolVisibility) have defaults that are not quite as sensible for unfortunate historical reasons.
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.
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.
Version: Package version in Semantic Versioning 2.0.0 form. Defaults to 1.0.0.
Copyright: Copyright notice for the package. Unset by default.
PackageLicenseExpression: SPDX license identifier 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.
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.
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.
AsyncExceptions (true, false): Enable/disable the ability to catch SEH exceptions with standard try/catch statements. This only applies when targeting Windows. Defaults to false.
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.
UnicodeEnvironment (true, false): Enable/disable compiling for a Unicode environment when targeting Windows in C/C++ projects. This causes the UNICODE and _UNICODE macros to be defined, and makes it so that wmain and wWinMain entry point functions must be used when building executables. Defaults to false.
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.
ConsumptionAnalysis (true, false): Enable/disable static analysis with consumption and type state annotations in C/C++ projects. Defaults to true.
DocumentationAnalysis (true, false): Enable/disable Doxygen documentation comment checking in C/C++ projects. Defaults to false.
NullabilityAnalysis (true, false): Enable/disable static analysis with nullability annotations in C/C++ projects. Defaults to true.
TagAnalysis (true, false): Enable/disable static analysis with type tag annotations in C/C++ projects. Defaults to true.
ThreadingAnalysis (true, false): Enable/disable static analysis with thread safety annotations in C/C++ projects. Defaults to true.
TrustAnalysis (true, false): Enable/disable static analysis with trusted computing base annotations in C/C++ projects. Defaults to true.
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.
DisableWarnings: A comma-separated list of warning names (e.g. cast-align) to disable in C/C++ projects. Unset by default.
TreatWarningsAsErrors (true, false): Enable/disable reporting warnings as errors in C/C++ projects. Defaults to false.
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.
ReleaseMode (Fast, Safe, Small): The build mode to use when Configuration is set to Release. Defaults to Fast.
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 true.
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.
DynamicImageBase (true, false): Enable/disable ASLR, i.e. randomization of the image base at run time. This only applies when targeting Windows. Defaults to true.
StackSize: Sets the stack size for the main thread. This only applies when building executables. Unset by default.
Sanitizers: A semicolon-separated list of sanitizers to instrument code with. Currently, only thread is supported. Unset by default.
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.