C2CS

The Platform Matrix defines the compatibility between target operating systems, architectures, and the required Software Development Environments (SDE) for generating C# code.

Key columns in the matrix:

• Open (🔓 or 🔒): Indicates if system headers can be distributed to other platforms under an open-source license (🔓) or if they must be manually made accessible to C2CS on the host platform (🔒).
• OS: The target operating system (e.g., Windows, macOS, Linux, iOS, tvOS, Android).
• Arch: The target computer architecture (e.g., ARM64, X64, X86).
• SDE: The required software development environment to build native libraries (e.g., MinGW, MSVC, XCode, Android Studio).
• Clang Target: The specific Clang target triple used for the platform.
• .NET RID: The official .NET Runtime Identifier (RID) for the target platform.

To build the project from the repository, ensure you have the following prerequisites:

General Prerequisites:

• .NET 9 SDK
• Clone the repository with submodules: git clone --recurse-submodules https://github.com/bottlenoselabs/c2cs.git

Platform Specifics:

• Windows: Git Bash and Microsoft Visual C++ (MSVC) Build Tools + C/C++ SDK.
• macOS: Xcode Command Line Tools (xcode-select --install), Xcode (from App Store), Homebrew, and CMake (brew install cmake).
• Linux: Software build tools (GCC, Clang) and CMake.

Build Commands:

• CLI: dotnet build
• IDE: Open ./C2CS.sln in Visual Studio or Rider.

To generate C# bindings for a specific C library on a target platform, you must provide three key pieces of information to the generation process:

1. Clang target triple: A string in the format arch-vendor-os-environment (e.g., x86_64-pc-windows-msvc) that tells Clang how to interpret the C code for that specific platform.
2. System C header files: The .h files belonging to the target platform. You must provide the root directory of these files so Clang can resolve types and definitions correctly (e.g., ensuring uint64_t has the correct bit-width for the target OS).
3. NET Runtime Identifier (RID): A valid .NET RID (e.g., win-x64, linux-arm64) that matches the corresponding Clang target to ensure the resulting .NET application can run on the intended platform.

C2CS is distributed as a .NET global tool. You must have the .NET 9 SDK installed to use it.

To install the latest stable release:

dotnet tool install bottlenoselabs.c2cs.tool --global

To install the latest pre-release version (including builds from MyGet):

dotnet tool install bottlenoselabs.c2cs.tool --global --add-source https://www.myget.org/F/bottlenoselabs/api/v3/index.json --version "*-*"

If the dotnet tool command fails to find a specific version you expect, try clearing your NuGet caches:

dotnet nuget locals all --clear

To generate C# bindings for a C library, follow this workflow:

1. Extract Platform FFIs: Use c2ffi to extract platform-specific Foreign Function Interfaces (FFIs). Use the extract command with a configuration file. Example: c2ffi extract --config <config-file>.json

2. Merge FFIs: Once you have extracted the FFIs for all target platforms (e.g., Windows, macOS, Linux) into a directory, merge them into a single cross-platform FFI JSON file using c2ffi merge. Example: c2ffi merge --inputDirectoryPath <directory> --outputFilePath <output>.json

3. Execute C2CS: Run the c2cs tool with a configuration file to generate the final C# bindings. Example: c2cs --config <config-file>.json

c2cs --config config-generate-cs.json

When a platform is marked as locked (🔒), the system header files cannot be distributed. You must make them manually accessible to C2CS on the host machine to read C code for that target.

Windows (MSVC)

If using the MSVC SDE, you must download and install the Windows SDKs. The important directories are typically located at: %ProgramFiles(x86)%\Windows Kits\10\Include

macOS, iOS, and tvOS (XCode)

To access SDKs for Apple platforms, you must install XCode via the App Store on Apple-branded hardware.

Android (Android Studio)

To access Android SDKs, you must install Android Studio.

By default, C2CS logs at the Information level. To enable Debug level logging, create an appsettings.json file in the directory where C2CS is running. You can customize the log format and verbosity using the following structure:

{
    "Logging": {
        "Console": {
            "LogLevel": {
                "Default": "Warning",
                "C2CS": "Debug"
            },
            "FormatterOptions": {
                "ColorBehavior": "Enabled",
                "SingleLine": true,
                "IncludeScopes": true,
                "TimestampFormat": "yyyy-dd-MM HH:mm:ss ",
                "UseUtcTimestamp": true
            }
        }
    }
}