This section covers the internal structure of the ZLinq repository for contributors and developers working on the library itself. It addresses how the source is organized, how projects depend on one another, how to run tests, and how to write extensions.
The repository is divided into three top-level directories with distinct roles:
| Directory | Purpose |
|---|---|
src/ | All publishable library and tool projects |
tests/ | Automated test projects |
sandbox/ | Exploratory console apps and the benchmark project |
Repository structure — projects mapped to directories:
Sources: src/ZLinq/ZLinq.csproj1-63 src/ZLinq.Json/ZLinq.Json.csproj1-36 src/ZLinq.FileSystem/ZLinq.FileSystem.csproj1-32 src/ZLinq.Godot/ZLinq.Godot.csproj1-31 src/ZLinq.DropInGenerator/ZLinq.DropInGenerator.csproj1-53 src/FileGen/FileGen.csproj1-28 tests/ZLinq.Tests/ZLinq.Tests.csproj1-96 tests/System.Linq.Tests/System.Linq.Tests.csproj1-65 sandbox/Benchmark/Benchmark.csproj1-78
Source projects:
| Project | Role | NuGet Packable | Target Frameworks |
|---|---|---|---|
ZLinq | Core library — all operators, IValueEnumerator<T>, ValueEnumerable<TEnumerator,T> | ✓ | netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0 |
ZLinq.Json | LINQ to Tree for System.Text.Json JsonNode | ✓ | netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0 |
ZLinq.FileSystem | LINQ to Tree for FileSystemInfo directories | ✓ | netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0 |
ZLinq.Godot | LINQ to Tree for Godot Node hierarchies | ✓ | net8.0, net9.0, net10.0 |
ZLinq.DropInGenerator | Roslyn IIncrementalGenerator — drop-in source generator | ✓ (analyzer) | netstandard2.0 |
FileGen | Internal CLI tool — generates primitive type overloads and drop-in templates | ✗ | net10.0 |
Test projects:
| Project | Role | Framework |
|---|---|---|
ZLinq.Tests | Primary test suite (xunit.v3 + Shouldly) | net6.0, net8.0, net9.0, net10.0, net48 (Windows) |
System.Linq.Tests | Compatibility verification using ZLinqDropInAttribute with Everything | net9.0, net10.0 |
Sandbox projects:
| Project | Role | Framework |
|---|---|---|
Benchmark | BenchmarkDotNet suite comparing ZLinq vs System.Linq vs LinqAF/LinqGen/StructLinq/SpanLinq | net8.0, net9.0, net10.0 |
ConsoleApp | Manual exploration; links Benchmark code for profiling | net10.0 |
ConsoleAppNet6 | Validates drop-in generator on .NET 6 | net6.0 |
ConsoleAppNativeAOT | Validates trimming/NativeAOT compatibility | net10.0 |
Sources: src/ZLinq/ZLinq.csproj4 src/ZLinq.Json/ZLinq.Json.csproj4 src/ZLinq.FileSystem/ZLinq.FileSystem.csproj4 src/ZLinq.Godot/ZLinq.Godot.csproj4 src/ZLinq.DropInGenerator/ZLinq.DropInGenerator.csproj4 src/FileGen/FileGen.csproj4 tests/ZLinq.Tests/ZLinq.Tests.csproj7-22 tests/System.Linq.Tests/System.Linq.Tests.csproj8 sandbox/Benchmark/Benchmark.csproj5
Inter-project references (ProjectReference) — maps to actual .csproj files:
Sources: tests/ZLinq.Tests/ZLinq.Tests.csproj56-58 tests/System.Linq.Tests/System.Linq.Tests.csproj47-55 sandbox/Benchmark/Benchmark.csproj51-52 sandbox/ConsoleApp/ConsoleApp.csproj22-29 sandbox/ConsoleAppNet6/ConsoleAppNet6.csproj11-18 sandbox/ConsoleAppNativeAOT/ConsoleAppNativeAOT.csproj14-16
All projects inherit from Directory.Build.props at the repository root. Key settings applied to every project:
| Property | Value | Effect |
|---|---|---|
SignAssembly | true | Strong-name signing via opensource.snk |
AssemblyOriginatorKeyFile | opensource.snk | Key file at repository root |
IsPackable | false (default) | Overridden to true in publishable src/ projects |
GenerateDocumentationFile | true | XML doc output for all projects |
Deterministic | true | Reproducible builds |
ContinuousIntegrationBuild | true when CI=true | Enables TreatWarningsAsErrors in CI |
IncludeSymbols | true | Produces .snupkg symbol packages |
SymbolPackageFormat | snupkg | NuGet symbol server format |
NoWarn | 1591 | Suppresses missing XML doc warnings globally |
The PackageVersion is driven by a $(Version) property, intended to be supplied externally during release builds.
Sources: Directory.Build.props1-47
ZLinq Core Project — Build NotesThe core ZLinq.csproj has several build-time characteristics worth knowing when modifying it:
LangVersion=14 and AllowUnsafeBlocks=true are required because some internal paths use pointer arithmetic and ref manipulation.IsTrimmable=true is set for all non-netstandard TFMs, enabling NativeAOT and trimming compatibility.PolySharp is a PrivateAssets=all build dependency used on netstandard2.0 and netstandard2.1 to backport newer C# language features.netstandard2.0, additional packages are included: Microsoft.Bcl.Memory, System.Buffers, System.Memory, and System.Runtime.CompilerServices.Unsafe.Using directives in ZLinq.csproj include ZLinq, ZLinq.Internal, ZLinq.Traversables, ZLinq.Linq, System.Runtime.CompilerServices, System.Runtime.InteropServices, and System.ComponentModel.Sources: src/ZLinq/ZLinq.csproj4-62
ZLinq.DropInGenerator — Build NotesThe source generator project has an unusual build setup:
netstandard2.0 (required for Roslyn analyzer packaging).IncludeBuildOutput=false and DevelopmentDependency=true mark it as an analyzer-only package.analyzers/dotnet/cs/ within the NuGet package.src/FileGen/DropIn/**/*.cs are embedded as EmbeddedResource items — this is the mechanism by which the generator reads its code templates at runtime.ZLinqDropInAttribute.cs is shared via <Compile Include="..."> link from src/ZLinq/.Microsoft.CodeAnalysis.CSharp version 4.3.0 minimum (to support SyntaxValueProvider.ForAttributeWithMetadataName, and for Unity 2022.3.12f1+ compatibility).Sources: src/ZLinq.DropInGenerator/ZLinq.DropInGenerator.csproj1-53
FileGen Toolsrc/FileGen/FileGen.csproj is a developer-only CLI tool (not a NuGet package) that generates:
src/ZLinq/src/FileGen/DropIn/ that are then embedded by ZLinq.DropInGeneratorIt references ZLinq.csproj directly and uses reflection over ValueEnumerableExtensions to derive the operator signatures it needs to replicate. It uses ConsoleAppFramework as its CLI host.
For more detail on what FileGen generates and how it feeds into the drop-in generator, see Code Generation Implementation.
Sources: src/FileGen/FileGen.csproj1-28 src/ZLinq.DropInGenerator/ZLinq.DropInGenerator.csproj33-35
| Page | Title | What it covers |
|---|---|---|
| 8.1 | Project Structure and Build System | Detailed directory layout, Directory.Build.props, .editorconfig, internal polyfill utilities (CollectionsMarshal, BitOperations, RefBox, etc.) |
| 8.2 | Testing Infrastructure | ZLinq.Tests and System.Linq.Tests project setup, xunit.v3 + Shouldly configuration, TestUtil helpers, how to add new tests |
| 8.3 | Creating Custom Extensions | Implementing ITraverser<TTraverser,T> for new node types, using ZLinqDropInExtensionAttribute, writing a custom IValueEnumerator<T> struct |