Dart Setup Ffi AssetsSAFE

An agent skill published by flutter.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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:
```bash
dart pub add code_assets hooks native_toolchain_c record_use dev:ffigen
```

Or manually declare them in your target package's `pubspec.yaml`:
```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: 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Dart Setup Ffi Assets](https://modelsatlas.com/skills/flutter/dart-setup-ffi-assets/badge.svg)](https://modelsatlas.com/skills/flutter/dart-setup-ffi-assets/)

Not your listing, or something out of date? Claim or update your listing.