Guides agents in compiling and packaging C/C++ source code into dynamic or static libraries (Code Assets) using Dart's Native Assets hook system (via hook/build.dart and hook/link.dart utilizing package:hooks and package:native_toolchain_c). Use when a user asks to: 'setup native assets', 'compile C

Compiling C Code into Code Assets with Native Assets Hooks Integrate and automate the compilation and packaging of native C/C++ source code into Code Assets under Dart's overarching Native Assets feature using build and link hooks. Contents [Introduction]( introduction) [Constraints]( constraints) [Native Interop Packages]( native interop packages) [Step by Step Workflow]( step by step workflow) [Choosing an Integration Approach]( choosing an integration approach) [Method 1: Local Compilation with Linker Tree Shaking (Recommended)]( method 1 local compilation with linker tree shaking recommended) [Prerequisite Host Compiler Toolchains]( prerequisite host compiler toolchains) [C Source and Bindings Setup]( c source and bindings setup) [Defining the C Library Build Spec]( defining the c library build spec) [Implementing hook/build.dart]( implementing hookbuilddart) [Implementing hook/link.dart]( implementing hooklinkdart) [Method 2: Downloading Precompiled Dynamic Libraries]( method 2 downloading precompiled dynamic libraries) [Why Download Precompiled Binaries?]( why download precompiled binaries) [Implementing Precompiled Dynamic Downloads]( implementing precompiled dynamic downloads) [Verification Checklist]( verification checklist) [1. Local Execution Sandbox]( 1 local execution sandbox) [2. Verify Target Outputs]( 2 verify target outputs) [3. Verify Tree Shaking Stripping]( 3 verify tree shaking stripping) [4. Verify Offline Compliance (User Defines)]( 4 verify offline compliance user defines) Introduction Under Dart's Native Assets feature, packages can package native code (like C/C++ libraries) as Code Assets and bundle them automatically during standard development cycles (e.g., dart run , dart test , dart build , and flutter run ). The packaging of Code Assets is driven by two programmatic hook scripts placed inside a package's hook/ folder: 1. hook/build.dart : Compiles local C sources to machine code or bundles prebuilt native binaries as code assets for a specific host/target architecture. 2. hook/link.dart : Links built code assets, applying advanced tree shaking optimizations to strip unused native symbols and compress the runtime binary size. Constraints [!IMPORTANT] Keep all file resolving platform independent. Never hardcode absolute target paths, shell scripts, or system command variables. Always use Platform.script.resolve() or Uri based resolution to ensure scripts are fully portable. Hook Locations : Compiling and packaging hooks must reside strictly inside the hook/ directory at the package's root: hook/build.dart (Build execution phase) hook/link.dart (Optional packaging/linking/tree shaking phase) Compile Toolchain Standard : Use the programmatic APIs from package:native toolchain c (e.g. CBuilder and CLibrary ) to run compile toolchains. Never invoke raw gcc , clang , or msvc via shell commands. Preamble & License Headers : Every handcrafted and generated source file (including bindings, helpers, and hooks) must strictly contain the target package's copyright and licensing header. Tree Shaking Mapping : If utilizing compiler tree shaking, you must map the target Dart method names (e.g. Method.name ) back to their raw native C symbol names using a record use mapping generated by FFIgen. The mapping file must reside under lib/src/third party/ and strictly use the .g.dart extension (e.g., sqlite3.record use mapping.g.dart ). Integrity Safeguards for Precompiled Libraries : If adopting the dynamic download pattern: Cryptographic Verification : Downloaded prebuilt binaries must be checked against preconfigured lookup tables containing MD5 or SHA 256 hashes to guarantee binary integrity and prevent tampering. Graceful Recovery : Support offline developers by providing fallbacks (such as local compiler execution via flags like local build ). Native Interop Packages Programmatic build and link hooks for Code Assets leverage three specialized native interop packages: Dependency Purpose Key API Abstractions : : : package:hooks Main orchestrator defining execution bounds. build(args, callback) , link(args, callback) package:native toolchain c Detects local compilers (MSVC, Xcode/Clang, GCC) and executes build toolchains. CLibrary , CBuilder , LinkerOptions.treeshake package:code assets Models code metadata records passed to dynamic loaders. CodeAsset , DynamicLoadingBundled Step by Step Workflow Step 1: Add Dependencies Add Code Assets hook and toolchain dependencies to your package. You must fetch these dependencies directly from pub.dev . You can add it automatically using the CLI: Or manually declare them in your target package's pubspec.yaml : Step 2: Define C Specifications Define your target C library compilation metadata inside lib/src/c library.dart . This lets both the build and link hooks share a single source of truth for assets, names, and sources. Step 3: Implement Build and Link Hook Scripts Write the compilation orchestration script inside hook/build.dart and the dead code elimination logic inside hook/link.dart . Step 4: Run the Hook Cycle Running standard test suites dynamically launches the build and link hook lifecycle in the background: Choosing an Integration Approach There are two primary methods for integrating and delivering C/C++ native assets in Dart. Select the one that matches your project requirements: Aspect Method 1: Local Compilation & Tree Shaking Method 2: Precompiled Downloads : : : Primary Use Case When C/C++ source code is included directly in the package and you want maximum size optimization. When compiling locally is slow/complex, or when avoiding developer host toolchain requirements. Host Toolchain Requirements Requires pre installed platform C compiler (Xcode tools, MSVC, GCC). Zero compiler setup required on developer/user machines. Binary Optimization Premium. Unused symbols are completely tree shaken, decreasing library size. Standard. Standard compiled binaries are shipped as is. Offline Setup Fully compliant. Works completely offline. Requires network access to download libraries, with offline fallback. Method 1: Local Compilation with Linker Tree Shaking (Recommended) In this approach, the build hook invokes local toolchains (GCC, Clang, MSVC) to compile source files directly. The link hook subsequently filters output symbols utilizing compiler options, retaining only target methods invoked in user code. This represents the standard, robust SQLite pattern under pkgs/code assets/example/sqlite . Prerequisite Host Compiler Toolchains Since package:native toolchain c delegates actual dynamic compilation to the host operating system's default toolchain, the development machine must have one of the following compiler packages pre installed: macOS : Xcode Command Line Tools. Install via: Linux : GCC or Clang. Install via: Windows : MSVC (Microsoft Visual C++). Install the Visual Studio Installer and select the Desktop development with C++ workload. Note: If no compatible toolchain is discovered on the host path, the build hook script will throw a compilation execution exception. Ensure to specify compiler constraints or adopt Method 2 if toolchains cannot be guaranteed. C Source and Bindings Setup Assume a C source defining simple math functions at third party/sqlite/sqlite3.c with its entry point header at third party/sqlite/sqlite3.h : We utilize a programmatic FFIgen script ( tool/ffigen.dart ) to create FFI bindings in lib/src/third party/sqlite3.g.dart , enabling recorded usage tracking and producing the lookup metadata map in lib/src/third party/sqlite3.record use mapping.g.dart : Defining the C Library Build Spec Define the centralized library specification in lib/src/c library.dart : Implementing hook/build.dart Implement hook/build.dart using CLibrary.build . This builds the library to a dynamic library (e.g. .so , .dylib , or .dll ) inside the hook's target directory: Implementing hook/link.dart Implement the link optimization phase in hook/link.dart . This utilizes compiler tree shaking options ( LinkerOptions.treeshake ) to compile a minimized, dead code eliminated binary based on symbol usage records: Method 2: Downloading Precompiled Dynamic Libraries An alternative approach compiles binaries beforehand on a central build machine, archives them, and downloads the target binary during the build hook execution. This matches the paradigm demonstrated in the download asset hook package. Why Download Precompiled Binaries? Host Constraints : Compiling large C/C++ libraries locally requires a complete compiler setup (GCC, Xcode/SDKs, Visual Studio) that the end developer's host machine may not possess. Compile Speed : Precompiled downloads execute in milliseconds compared to potentially long multi minute compilation processes. Platform Bridging : Allows cross compiling constraints to be avoided if host architectures are limited. Implementing Precompiled Dynamic Downloads We configure our build hook to detect local compiler flags (e.g. local build ). If not specified, the hook utilizes HttpClient to pull down platform specific libraries, calculates the MD5 hash to confirm download safety against a configured hashes lookup table, and registers the binary file as a CodeAsset : 1. Defining Target Hashes ( lib/src/hook helpers/hashes.dart ) Define target MD5 hash checks per platform file in your package sources: 2. Hook Downloader Helper ( lib/src/hook helpers/download.dart ) Implement the downloading and integrity check logic using dynamic target filename matching: 3. Implementing hook/build.dart Write the final download build hook incorporating local compilation fallback: Verification Checklist Before declaring a build or link hook implementation complete, always perform the following checks: 1. Local Execution Sandbox Run unit tests and confirm the native assets compile/link process completes with no runtime or build tool exceptions: 2. Verify Target Outputs Navigate to your package target directory and verify that dynamic binary assets are created for the host system: macOS : Verify .dart tool/resources/ or target directories contain .dylib files. Linux : Verify .dart tool/resources/ or target directories contain .so files. Windows : Verify .dart tool/resources/ or target directories contain .dll files. 3. Verify Tree Shaking Stripping To ensure the link hook is actually stripping unused native symbols and compressing binary packaging, perform the following validation: 1. Compile a production bundle of the CLI/app: 2. Navigate to the compiled build directory containing the dynamic library. 3. Query the exported dynamic symbol tables: macOS : Linux : Windows (using MSVC Developer Command Prompt): 4. Confirm Target Exports : Verify that the command outputs only the explicitly kept entry point functions (e.g. sqlite3 libversion ) and does not output any unreferenced/stripped symbols. 5. No Bundle Scenario : If the application does not import or invoke any methods from the native library: Verify that the link hook logs: Skipping linking as no symbols are to be kept. Verify that no library was built/placed in the production bundle (the .dylib / .so / .dll file is not generated, saving bundle size). 4. Verify Offline Compliance (User Defines) Confirm offline compliance is fully active and the download fallback executes perfectly offline: 1. Configure the local build: true define for

dart-setup-ffi-assets