Skip to content

Commit 1993ec2

Browse files
alexrpalexrp
committed
Move documentation to GitBook.
Closes #48.
1 parent aa86514 commit 1993ec2

File tree

9 files changed

+365
-349
lines changed

9 files changed

+365
-349
lines changed

‎Directory.Build.props‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ part of your .NET solution - without all the hassle that is usually part and
3232
parcel of building and packaging native code.</PackageDescription>
3333
<PackageLicenseExpression>0BSD</PackageLicenseExpression>
3434
<PackageOutputPath>$(MSBuildThisFileDirectory)pkg/feed/</PackageOutputPath>
35-
<PackageProjectUrl>https://ziglang.org</PackageProjectUrl>
35+
<PackageProjectUrl>https://docs.vezel.dev/zig-sdk</PackageProjectUrl>
3636
<PublishRepositoryUrl>true</PublishRepositoryUrl>
3737
<RepositoryUrl>https://github.com/vezel-dev/zig-sdk.git</RepositoryUrl>
3838
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

‎PACKAGE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,4 @@ This project offers the following packages:
1515
MSBuild SDK and associated tasks.
1616

1717
For more information, please visit the
18-
[project page](https://github.com/vezel-dev/zig-sdk).
18+
[project home page](https://docs.vezel.dev/zig-sdk).

‎README.md‎

Lines changed: 4 additions & 347 deletions
Large diffs are not rendered by default.

‎doc/configuration/editor.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Editor
2+
3+
The Zig SDK is capable of integrating with
4+
[ZLS](https://github.com/zigtools/zls) and [clangd](https://clangd.llvm.org).
5+
This means that any editor with support for those language servers (e.g.
6+
[Visual Studio Code](https://code.visualstudio.com)) can be used to edit a
7+
project using the Zig SDK.
8+
9+
## ZLS
10+
11+
Start by
12+
[installing ZLS](https://github.com/zigtools/zls/blob/master/README.md#installation).
13+
The
14+
[Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=AugusteRame.zls-vscode)
15+
is highly recommended.
16+
17+
At the moment, no further configuration is necessary.
18+
19+
## clangd
20+
21+
Start by
22+
[installing clangd](https://clangd.llvm.org/installation). The
23+
[Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd)
24+
is highly recommended.
25+
26+
You have to tell clangd where to find the `compile_commands.json` compilation
27+
database. The Zig SDK creates these files in `IntermediateOutputPath`, i.e.
28+
`obj/Debug/linux-x64` if you build with `Configuration=Debug` and
29+
`RuntimeIdentifier=linux-x64`. Due to the nature of C/C++ compilation, these
30+
compilation databases have to be dependent on build flags. So, you will have to
31+
pick one of them to use for your editing experience. The good news is that you
32+
can change which compilation database you use at any point if you need to.
33+
34+
To tell clangd where to find the compilation database, create a file called
35+
`.clangd` in your project directory with the following contents:
36+
37+
```yaml
38+
CompileFlags:
39+
CompilationDatabase: obj/Debug/linux-x64
40+
```
41+
42+
(You may want to add this file to `.gitignore`.)
43+
44+
You can now restart the clangd language server. You should start to see rich
45+
editor features like code completion, hover widgets, navigation, etc.

‎doc/configuration/items.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# MSBuild Items
2+
3+
The following
4+
[MSBuild items](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-items)
5+
are used by the Zig SDK:
6+
7+
* `Compile`: Source code files passed to the Zig compiler. By default, the Zig
8+
SDK will populate this item type according to the project type.
9+
* `IncludeDirectory`: Header include directories passed to the compiler with the
10+
`-I` flag. Note that this applies to Zig as well, not just C/C++.
11+
* `PreludeHeader`: C/C++ header files that will be automatically `#include`d in
12+
every C/C++ source file by way of Clang's `-include` flag.
13+
* `CHeader`: Prepopulated by the Zig SDK with all files in the project directory
14+
ending in `.h`.
15+
* `CSource`: Prepopulated by the Zig SDK with all files in the project directory
16+
ending in `.c`.
17+
* `CxxHeader`: Prepopulated by the Zig SDK with all files in the project
18+
directory ending in `.hxx`.
19+
* `CxxHeader`: Prepopulated by the Zig SDK with all files in the project
20+
directory ending in `.cxx`.
21+
* `ZigSource`: Prepopulated by the Zig SDK with all files in the project
22+
directory ending in `.zig`.
23+
* `Watch`: Files that are monitored by `dotnet watch` for code changes. The Zig
24+
SDK will automatically populate this with all C, C++, and Zig source and
25+
header files in the project directory.

‎doc/configuration/properties.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Properties
2+
3+
The
4+
[MSBuild properties](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-properties)
5+
described on this page are used by the Zig SDK. These properties can all be set
6+
in `PropertyGroup`s in your project file. Most of them should have sensible
7+
defaults for new projects; a few (such as `TreatWarningsAsErrors` and
8+
`SymbolVisibility`) have defaults that are not quite as sensible for unfortunate
9+
historical reasons.
10+
11+
## Project Setup
12+
13+
* `CompilerMode` (`C`, `Cxx`, `Zig`): The language to compile the project as.
14+
This is inferred from the project file extension by default.
15+
* `AssemblyName`: Name of the project. By default, this is set to the file name
16+
of the project file. Used to compute the final binary name (e.g. `foo` becomes
17+
`libfoo.so`).
18+
* `OutputType` (`Exe`, `Library`): Output binary type. Defaults to `Library`.
19+
* `IsTestable` (`true`, `false`): Enable/disable `dotnet test` for Zig projects.
20+
Defaults to `true`.
21+
* `IsPackable` (`true`, `false`): Enable/disable `dotnet pack`. Defaults to
22+
`true`.
23+
* `IsPublishable` (`true`, `false`): Enable/disable `dotnet publish`. Defaults
24+
to `true`.
25+
* `DefaultSources` (`true`, `false`): Enable/disable default `Compile` item
26+
includes. Defaults to `true`.
27+
* `Deterministic` (`true`, `false`): Enable/disable deterministic builds. Among
28+
other things, this will try to prevent the compiler from using absolute paths
29+
and will prevent usage of certain problematic language features like
30+
`__TIME__`. Defaults to `true`.
31+
* `EditorSupport` (`true`, `false`): Enable/disable editor support. For C/C++
32+
projects, this means generating a `compile_commands.json` compilation database
33+
in `IntermediateOutputPath`. Defaults to `true`.
34+
* `FormatOnBuild` (`true`, `false`): Enable/disable formatting source code into
35+
canonical style on build in Zig projects. Defaults to `false`.
36+
37+
## Package Information
38+
39+
* `Product`: Human-friendly product name for the package. Defaults to the value
40+
of `AssemblyName`.
41+
* `Authors`: A list of package authors. Defaults to the value of `AssemblyName`.
42+
* `Description`: Brief description of the package. Defaults to
43+
`Package Description`.
44+
* `Version`: Package version in [Semantic Versioning 2.0.0](https://semver.org)
45+
form. Defaults to `1.0.0`.
46+
* `Copyright`: Copyright notice for the package. Unset by default.
47+
* `PackageLicenseExpression`: [SPDX](https://spdx.org/licenses) license
48+
identifier for the package. Unset by default.
49+
* `PackageProjectUrl`: Website URL associated with the package. Unset by
50+
default.
51+
* `RepositoryUrl`: Source code repository URL for the package. Unset by default.
52+
53+
## Preprocessor
54+
55+
* `PublicHeadersPath`: Can be set to a directory containing public C/C++
56+
headers. These headers will be included in the NuGet package and will flow to
57+
dependent projects. This directory will also be treated as an
58+
`IncludeDirectory`. Unset by default.
59+
* `DefineConstants`: A comma-separated list of preprocessor macros to define.
60+
Each entry can be a simple name or an assignment of the form `NAME=VALUE`.
61+
These macros are passed to the compiler with the `-D` flag. Note that this
62+
applies to Zig as well, not just C/C++.
63+
* `CompilerDefines` (`true`, `false`): Enable/disable adding some implicit
64+
`DefineConstants` macros that describe the Zig compiler version. Defaults to
65+
`true`.
66+
* `PlatformDefines` (`true`, `false`): Enable/disable adding some implicit
67+
`DefineConstants` macros that describe the target platform characteristics.
68+
Defaults to `true`.
69+
* `ConfigurationDefines` (`true`, `false`): Enable/disable adding some implicit
70+
`DefineConstants` macros that describe the build configuration (`Debug`,
71+
`ReleaseFast`, etc). Defaults to `true`.
72+
* `PackageDefines` (`true`, `false`): Enable/disable adding some implicit
73+
`DefineConstants` macros that describe the project being built. Defaults to
74+
`true`.
75+
76+
## Language Features
77+
78+
* `ZigVersion` (`major.minor.patch`): The version of the Zig compiler toolset to
79+
use. Defaults to the latest version known to the Zig SDK package that is in
80+
use.
81+
* `LanguageStandard`: The language standard used for C/C++ projects. Passed to
82+
Clang's `-std` flag. Defaults to the latest standards known to the compiler
83+
version that `ZigVersion` defaults to.
84+
* `AccessControl` (`true`, `false`): Enable/disable access control in C++
85+
projects. Defaults to `true`.
86+
* `BlockExtensions` (`true`, `false`): Enable/disable Clang's block language
87+
extensions. Defaults to `false`.
88+
* `CxxExceptions` (`true`, `false`): Enable/disable C++ exceptions. In C
89+
projects, this controls whether the C code will be unwindable by C++
90+
exceptions. Defaults to `true`.
91+
* `CxxReflection` (`true`, `false`): Enable/disable generating C++ run-time type
92+
information. This feature is required for some uses of `dynamic_cast`.
93+
Defaults to `true`.
94+
* `MicrosoftExtensions` (`true`, `false`): Enable/disable a variety of
95+
Microsoft C/C++ extensions. Defaults to `false`, but note that the compiler
96+
itself always enables some parts of this when targeting Windows as Windows
97+
headers require it.
98+
99+
## Static Analysis
100+
101+
* `EnforceCodeStyleInBuild` (`true`, `false`): Enable/disable checking that
102+
source code is in the canonical style during build in Zig projects. Defaults
103+
to `false`.
104+
* `ConsumptionAnalysis` (`true`, `false`): Enable/disable static analysis with
105+
[consumption and type state annotations](https://clang.llvm.org/docs/AttributeReference.html#consumed-annotation-checking)
106+
in C/C++ projects. Defaults to `true`.
107+
* `DocumentationAnalysis` (`true`, `false`): Enable/disable
108+
[Doxygen](https://doxygen.nl) documentation comment checking in C/C++
109+
projects. Defaults to `false`.
110+
* `NullabilityAnalysis` (`true`, `false`): Enable/disable static analysis with
111+
[nullability annotations](https://clang.llvm.org/docs/analyzer/developer-docs/nullability.html)
112+
in C/C++ projects. Defaults to `true`.
113+
* `TagAnalysis` (`true`, `false`): Enable/disable static analysis with
114+
[type tag annotations](https://clang.llvm.org/docs/AttributeReference.html#type-safety-checking)
115+
in C/C++ projects. Defaults to `true`.
116+
* `ThreadingAnalysis` (`true`, `false`): Enable/disable static analysis with
117+
[thread safety annotations](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html)
118+
in C/C++ projects. Defaults to `true`.
119+
* `TrustAnalysis` (`true`, `false`): Enable/disable static analysis with
120+
[trusted computing base annotations](https://clang.llvm.org/docs/AttributeReference.html#enforce-tcb)
121+
in C/C++ projects. Defaults to `true`.
122+
* `WarningLevel` (`0`-`4`): How aggressively the compiler should analyze C/C++
123+
projects for potentially problematic code. `0` disables warnings completely;
124+
`4` enables all warnings, including a few controversial ones. Defaults to `3`.
125+
* `DisableWarnings`: A comma-separated list of
126+
[warning names](https://clang.llvm.org/docs/DiagnosticsReference.html) (e.g.
127+
`cast-align`) to disable in C/C++ projects. Unset by default.
128+
* `TreatWarningsAsErrors` (`true`, `false`): Enable/disable reporting warnings
129+
as errors in C/C++ projects. Defaults to `false`.
130+
131+
## Code Generation
132+
133+
* `Configuration` (`Debug`, `Release`): Specifies the overarching configuration.
134+
When `Release` is specified, `ReleaseMode` comes into effect. Defaults to
135+
`Debug`. Usually specified by the user as e.g. `dotnet build -c Release`.
136+
* `DebugSymbols` (`true`, `false`): Enable/disable emitting debug symbols.
137+
Defaults to `true` if `Configuration` is `Debug`; otherwise, `false`.
138+
* `ReleaseMode` (`Fast`, `Safe`, `Small`): The
139+
[build mode](https://ziglang.org/documentation/master/#Build-Mode) to use when
140+
`Configuration` is set to `Release`. Defaults to `Fast`.
141+
* `FastMath` (`true`, `false`): Enable/disable certain lossy floating point
142+
optimizations that may not be standards-compliant. Defaults to `false`.
143+
* `LinkTimeOptimization` (`true`, `false`): Enable/disable link-time
144+
optimization. Note that link-time optimization is known not to work well on
145+
some targets and so should be used selectively. Defaults to `false`.
146+
* `SymbolExports` (`Used`, `All`): Specifies whether to export all public
147+
symbols or only those that are needed to link successfully. This only applies
148+
when building executables. Defaults to `Used`.
149+
* `SymbolVisibility` (`Default`, `Hidden`): Specifies the symbol visibility in
150+
C/C++ projects when `__attribute__((visibility(...)))` is not specified.
151+
`Default` (the default 😉) means public, while `Hidden` means private.
152+
* `ExecutableStack` (`true`, `false`): Enables/disables marking the stack as
153+
executable for the resulting binary. Executable stack memory is a significant
154+
security risk. Defaults to `false`.
155+
* `EagerBinding` (`true`, `false`): Enables/disables eager binding of symbols
156+
when performing dynamic linking at run time. Eager binding has security
157+
benefits, especially in combination with `RelocationHardening`. It is also
158+
more reliable if calling external functions from signal handlers. Defaults to
159+
`true`.
160+
* `RelocationHardening` (`true`, `false`): Enables/disables marking relocations
161+
as read-only. This has security benefits, especially in combination with
162+
`EagerBinding`. Defaults to `true`.
163+
* `Sanitizers`: A semicolon-separated list of
164+
[sanitizers](https://github.com/google/sanitizers) to instrument code with.
165+
Currently, only `thread` is supported. Unset by default.
166+
167+
## Cross-Compilation
168+
169+
* `RuntimeIdentifier`: Specifies the runtime identifier (i.e. platform) to
170+
target. When unset, `Build` and `Clean` will run for all runtime identifiers
171+
specified in `RuntimeIdentifiers`. Usually specified by the user as e.g.
172+
`dotnet build -r linux-x64`. Unset by default.
173+
* `RuntimeIdentifiers`: A semicolon-separated list of runtime identifiers that
174+
the project supports. All targets on this list will be cross-compiled as
175+
necessary. Defaults to all targets that the Zig compiler has known-good
176+
support for.
177+
* `UseEmulator` (`true`, `false`): Enable/disable usage of an appropriate binary
178+
emulator when cross-compiling. Defaults to `true`.

‎doc/index.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,56 @@ With support for multiple programming languages, cross-compilation, NuGet
88
packaging, and more, the **Zig SDK** makes it trivial to author native
99
components as part of your .NET solution - without all the hassle that is
1010
usually part and parcel of building and packaging native code.
11+
12+
## Features
13+
14+
Here are some of the **Zig SDK** highlights:
15+
16+
* **Multiple programming languages:** Although Zig is a modern and pleasant
17+
systems programming language, you might prefer to use C or C++ instead. As it
18+
happens, the Zig compiler also embds a full C and C++ compiler - namely,
19+
[Clang](https://clang.llvm.org). So, whichever language you prefer, the
20+
**Zig SDK** has you covered.
21+
* **Cross-compilation:** Thanks to the Zig compiler's excellent cross-targeting
22+
support, cross-compilation is a first-class citizen in the **Zig SDK**. Gone
23+
are the days of having to do overly complicated cross toolchain setup, or
24+
resorting to building on multiple platforms for releases - just type
25+
`dotnet build` to compile for all targets supported by your project.
26+
* **Binary emulator support:** When cross-compiling, the **Zig SDK** will look
27+
at the host and target platforms and try to pick an appropriate emulator. In
28+
the majority of cases, this allows you to run and unit test the foreign
29+
binary. [Darling](https://darlinghq.org), [QEMU](https://qemu.org),
30+
[Wine](https://winehq.org), and
31+
[WSL](https://docs.microsoft.com/en-us/windows/wsl) are recognized.
32+
* **Unit testing:** The Zig language provides built-in unit testing constructs.
33+
The **Zig SDK** allows you to run your project's unit tests with the familiar
34+
`dotnet test` command. Test name filters are supported - e.g.
35+
`dotnet test --filter foo`.
36+
* **Code change monitoring:** The **Zig SDK** integrates with `dotnet watch` so
37+
that e.g. `dotnet watch build`, `dotnet watch run`, and `dotnet watch test`
38+
work as expected, enabling a rapid development loop.
39+
* **Sensible NuGet packaging:** Out of the box, `dotnet pack` with the
40+
**Zig SDK** will produce NuGet packages containing cross-built binaries for
41+
all platforms that your project supports. Also, your public C and C++ header
42+
files will be bundled, as will your Zig source code. This makes the resulting
43+
NuGet package easy to consume both in .NET projects and in other projects
44+
using the **Zig SDK**.
45+
* **Multi-project solutions:**
46+
[Soon™.](https://github.com/vezel-dev/zig-sdk/issues/8)
47+
* **Editor integration:** The **Zig SDK** can generate files needed by language
48+
servers, resulting in an IDE-like experience when editing code. For C/C++,
49+
[clangd](https://clangd.llvm.org) is fully supported, while for Zig projects,
50+
there is limited [ZLS](https://github.com/zigtools/zls) support.
51+
* **Easy to use:** Just add an entry to your `global.json`, and create a project
52+
file ending in `.cproj`, `.cxxproj`, or `.zigproj`, with an
53+
`Sdk="Vezel.Zig.Sdk"` attribute. Then start writing code and use
54+
`dotnet build`, `dotnet run`, `dotnet test`, etc as you normally would.
55+
56+
Please note that the **Zig SDK** is *not* intended to be a full replacement for
57+
[Zig's build system](https://ziglearn.org/chapter-3). The goal of the
58+
**Zig SDK** is specifically to make it simple to integrate Zig, C, and C++
59+
components into the .NET ecosystem. For that reason, the **Zig SDK** has no
60+
support for platforms that Zig supports but that .NET does not (yet) run on,
61+
such as `linux-riscv64`. The level of configuration that is possible for C and
62+
C++ is also somewhat limited compared to most build systems that support those
63+
languages.

‎doc/toc.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
11
# Table of Contents
22

33
* [Home](index.md)
4+
* [Usage](usage.md)
5+
6+
## Configuration
7+
8+
* [Editor](configuration/editor.md)
9+
* [Properties](configuration/properties.md)
10+
* [Items](configuration/items.md)

‎doc/usage.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Usage
2+
3+
To use the Zig SDK, first make sure that you have the
4+
[.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0) (or later)
5+
installed.
6+
7+
Next, create a
8+
[`global.json`](https://docs.microsoft.com/en-us/dotnet/core/tools/global-json)
9+
in the root of your repository and add the `Vezel.Zig.Sdk` entry under the
10+
`msbuild-sdks` property:
11+
12+
```json
13+
{
14+
"msbuild-sdks": {
15+
"Vezel.Zig.Sdk": "x.y.z"
16+
}
17+
}
18+
```
19+
20+
(Replace `x.y.z` with the actual NuGet package version.)
21+
22+
Next, create a project file. A library project is as simple as:
23+
24+
```xml
25+
<Project Sdk="Vezel.Zig.Sdk" />
26+
```
27+
28+
An executable project looks like:
29+
30+
```xml
31+
<Project Sdk="Vezel.Zig.Sdk">
32+
<PropertyGroup>
33+
<OutputType>Exe</OutputType>
34+
</PropertyGroup>
35+
</Project>
36+
```
37+
38+
The project file extension determines the language your code will be compiled
39+
as - `.cproj` for C, `.cxxproj` for C++, and `.zigproj` for Zig.
40+
41+
The convention used by the **Zig SDK** is that C projects should use a `.c`
42+
extension for source files and `.h` for header files, while C++ projects should
43+
use `.cxx` and `.hxx`. Zig projects use `.zig`.
44+
45+
For C/C++ projects, it does not matter what you name your source and header
46+
files. For Zig executable projects, your root source file should be named
47+
`main.zig`. Zig library projects should use the project name for the root source
48+
file; that is, if your project file is `mylib.zigproj`, your root source file
49+
should be `mylib.zig`.
50+
51+
Once you have written some code, you can use `dotnet build`, `dotnet run`, etc.

0 commit comments

Comments
 (0)