/dart-setup-ffi-assets

name: dart-setup-ffi-assets
description: "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/C++ source code', 'bundle dynamic libraries', 'build native C code', 'link native assets', 'implement build.dart or link.dart hooks', or 'integrate C/C++ interop in Dart/Flutter'. Helps agents avoid manual toolchain orchestration and configures secure hash-validated binary downloads or advanced linker tree-shaking with package:record_use mapping."
metadata:
  model: models/gemini-3.1-pro-preview
  last_modified: Fri, 29 May 2026 09:10:00 GMT

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:

dart pub add code_assets hooks native_toolchain_c record_use dev:ffigen

Or manually declare them in your target package's `pubspec.yaml`:

dependencies:
  code_assets: ^1.0.0
  hooks: ^0.1.0
  native_toolchain_c: ^0.1.0
  record_use: ^0.6.0

dev_dependencies:
  ffigen: