BGCS.Intermediate 2.0.4

BindGen-CS

English | 简体中文

BindGen-CS is a cross-platform C/C++ to C# binding toolchain. It generates C# interop directly from C APIs, or turns C++ classes, template instances, and common STL types into a stable C ABI bridge with matching C# bindings.

What it does

• Generates DllImport, LibraryImport, or function-table bindings from C/C++ headers.
• Emits a raw ABI API plus string, Span<T>, ref, and out overloads where the required safety semantics are known.
• Handles structs, unions, packing, bitfields, fixed arrays, typedefs, opaque handles, callbacks, and target-dependent primitives.
• Builds C bridges for C++ classes, construction/destruction, methods, overloads, inheritance, template instances, common STL containers, smart pointers, paths, and chrono values.
• Discovers compilers, target triples, sysroots, and system includes, then writes a reproducible native build manifest.
• Verifies real shared-library exports, creates multi-RID native package layouts, and tests clean NuGet consumers.
• Manages multiple native libraries through one workspace with deterministic diffs, transactional output, and incremental caching.
• Extends project-specific semantics through declarative lowerings, independent plugins, or project-owned C shims—without adding library-specific branches to BGCS core.

BGCS does not translate arbitrary C++ source line by line into C#. Its job is to expose callable native capabilities to C# reliably. For C APIs, unproven ownership, allocator, buffer, or callback semantics produce a diagnostic and suppress inferred friendly overloads by default; the raw ABI remains available. Unsupported C++ lowerings stop bridge generation until a recipe, plugin, or shim supplies the missing semantics.

Getting started

You need .NET SDK 10.0 and the .NET 9 runtime: the repository targets net9.0, and the SDK 10 is what packs and installs the RID-specific bindgen-cs tool packages. The commands below run directly from a source checkout and do not require a published package. C++ bridges also need a local C/C++ compiler.

Generate C# from a C header

From the repository root, copy and run:

dotnet run --project src/BGCS.Tool -- init examples/QuickStart/native.h --config examples/QuickStart/bindgen.json
dotnet run --project src/BGCS.Tool -- generate examples/QuickStart/bindgen.json
dotnet run --project src/BGCS.Tool -- build examples/QuickStart/bindgen.json

The result is:

examples/QuickStart/Generated/
└─ Bindings.cs

init creates a runnable configuration beside the example header. generate writes the bindings, and build compiles them in a temporary consumer project with nullable analysis and warnings as errors. Replace the example header with your own and keep its configuration next to it. After the tool is published, dotnet tool install --global BindGen-CS will provide the shorter bindgen-cs command used below; until then, replace bindgen-cs with dotnet run --project src/BGCS.Tool --.

Want one C# bindings file? Set "MergeGeneratedFilesToSingleFile": true and optionally "SingleFileOutputName": "Bindings.cs" in bindgen.json. init already enables this for its C-library preset. The result is one Generated/Bindings.cs, with its ABI reference target noted in the generated header. If GenerateRuntimeSource=true, Runtime.cs remains a separate file.

For a first integration, run the complete check:

bindgen-cs doctor
bindgen-cs validate bindgen.json
bindgen-cs inspect bindgen.json
bindgen-cs build bindgen.json

Generate a C bridge and C# from C++

bindgen-cs init path/to/library.hpp
bindgen-cs bridge bridge.json
bindgen-cs native-build GeneratedBridge/bridge.manifest.json

The default configuration produces:

GeneratedBridge/        # C ABI headers, C++ wrappers, and build manifest
Generated/              # matching C# bindings

To stage the native library into a NuGet RID layout:

bindgen-cs native-build GeneratedBridge/bridge.manifest.json \
  --package-root artifacts/native-package

Generated directories are reproducible output; do not edit them. Put naming, type, marshalling, ownership, and function-selection rules in configuration. See Getting started for complete project layouts and troubleshooting.

The generated C# source has one output path, independent of the machine that runs it; native libraries still need RID-specific distribution. C/C++ headers and ABI details can vary by target (for example enum underlying types, long/wchar_t, struct layout, calling convention, and platform-gated declarations). The ABI reference target comment records the target used to parse the header; it does not certify other platforms. Validate the same binding with native ABI and consumer tests on every intended target. See target and output configuration.

Current support status

Legend: implemented and accepted on the current version ✅　implementation or host acceptance still pending ⚠️.

Platform acceptance

Every listed platform is a support target. ⚠️ means the current version does not yet have a complete independent host report; it does not mean permanently unsupported.

See Capabilities and boundaries and the Acceptance specification for detailed evidence.

Choose a workflow

C++ coverage and extension

Verified coverage includes construction/destruction, instance and static methods, overloads, namespace functions, exception boundaries, multiple-inheritance pointer adjustment, full and partial template specializations, explicit template instances, string, vector, span, array, map, set, optional, variant, expected, filesystem::path, chrono, unique_ptr, shared_ptr, and configured pure-virtual callback proxies.

There are three ways to add project-specific behavior:

1. TypeLowerings / CallableLowerings for stable conversions expressible in JSON.
2. A typed lowering plugin when matching needs AST inspection, target branches, or extra generated artifacts.
3. NativeShims when project C/C++ must define the stable C ABI boundary.

The C++ extension cookbook contains a runnable shim, an independent plugin project, callback/async/allocator patterns, and guidance for AllowUnsafe.

Common commands

Safety behavior

• Clear ABI and lifetime: generate and compile-check.
• Missing ownership, allocator, buffer length, or callback lifetime: emit a BGCS-SAFETY-* diagnostic, preserve raw ABI, and suppress unproven friendly overloads by default. Set StrictSafetySeverity=Error to reject the whole generation, or supply an explicit MarshallingMappings contract to restore the friendly API.
• No accepted C++ lowering: stop until a recipe, plugin, or shim is supplied.
• AllowUnsafe explicitly transfers risk and keeps an audit diagnostic; it cannot repair an invalid ABI.

Embed the generator

using BGCS;

CsCodeGenerator generator = CsCodeGenerator.Create("bindgen.json");
if (!generator.GenerateConfigured())
{
    foreach (var diagnostic in generator.Messages)
        Console.Error.WriteLine(diagnostic);
}

Use BGCS.Facade.BindingGenerator and the Binding IR in BGCS.Intermediate when structured results are required.

Testing and release

./scripts/run-full-test-matrix.sh

The full matrix covers managed tests, native ABI/runtime behavior, C++ semantics, real libraries, public APIs, deterministic snapshots, NuGet consumers, license/vulnerability policy, and performance. See the Acceptance specification for report details and Publishing for release and OIDC requirements.

Packages

• BindGen-CS — .NET tool providing the bindgen-cs command.
• BGCS — embeddable C/C++ to C# facade.
• BGCS.Cpp2C — C++ to C bridge generation.
• BGCS.Runtime — runtime used by generated bindings.
• BGCS.Intermediate — Binding IR and diagnostics contracts without generator dependencies.

Documentation

• Documentation index
• Getting started
• Configuration guide
• Capabilities and boundaries
• C++ extension cookbook
• Diagnostics guide
• Architecture
• Testing and acceptance
• Publishing and OIDC

License

BindGen-CS is licensed under the MIT License. See LICENSE. Portions derived from CppAst/HexaGen retain their original notices.