dart-setup-ffi-assets

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha db37821a6b02 · 28 Oct 2026Report an issue or request a re-scan

• Publisherdart-lang GitHub organizationOwner of the repository this skill is read from
• Source folderdart-lang/skills/skills/dart-setup-ffi-assetsThe exact folder we audited
• LicenceBSD-3-ClauseAs the repository states it
• Commit pinned for this verdictdb37821a6b02A new audit runs when the source changes
• Repository statusNot archivedLast push 11 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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: 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/dart-lang/skills
git -C skills checkout db37821a6b02

Works in

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source db37821a6b02

Questions about dart-setup-ffi-assets

• github.com/dart-lang/skills/tree/main/skills/dart-setup-ffi-asse — the audited source at commit db37821a6b02 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology