# FlClash FFI Plugin Build System: How to Compile the Go Core > Learn how to compile the FlClash Go core using its Dart driven FFI plugin build system. Understand platform specific compilation and Flutter integration. - Repository: [chen08209/FlClash](https://github.com/chen08209/FlClash) - Tags: how-to-guide - Published: 2026-05-31 --- **FlClash compiles its Go-based proxy core into native binaries using a Dart-driven build system located in the `plugins/setup` package, which orchestrates platform-specific compilation, SHA-256 hashing, and Flutter integration via the `setup.dart` script.** The build system bridges the Flutter UI and the ClashMeta core (written in Go) through a Foreign Function Interface (FFI) plugin. According to the chen08209/FlClash source code, this process handles everything from Git submodule initialization to embedding cryptographic hashes into the final application bundle. ## Build Architecture Overview The compilation pipeline is centered on two primary components: the **`setup.dart`** orchestration script at the repository root and the **`build_tool`** Dart package inside `plugins/setup/buildkit/`. **`setup.dart`** parses command-line arguments to determine the target platform, loads build configuration via `BuildConfig.load`, and delegates the actual compilation to the `build_tool` binary. The `build_tool` package contains `GoBuilder`, which executes the `go build` commands with platform-specific environment variables and flags. This separation allows the build logic to remain modular while supporting desktop executables, Android shared libraries, and Windows DLLs from a single entry point. ## Step-by-Step Build Process ### Repository Preparation and Configuration Loading Before compilation begins, the workflow checks out Git submodules containing the Go core source code using `git submodule update --init --recursive`, as defined in [`.github/workflows/build.yaml`](https://github.com/chen08209/FlClash/blob/main/.github/workflows/build.yaml). The script then invokes `BuildConfig.load` (found in `plugins/setup/buildkit/build_tool/lib/src/options.dart`) to read [`build_config.yaml`](https://github.com/chen08209/FlClash/blob/main/build_config.yaml). This configuration file specifies the core executable name, shared library identifiers, Go build tags (e.g., `with_gvisor`), linker flags (`-ldflags=-w -s`), and output directories. If no configuration file exists, the system falls back to sensible defaults for the FlClash project structure. ### Go Core Compilation with Environment Injection The `setup.dart` script calls `_buildGoCore`, which executes the `build_tool` Dart binary located at `plugins/setup/buildkit/build_tool/bin/build_tool.dart`. This tool constructs a list of **`Target`** objects (defined in `plugins/setup/buildkit/build_tool/lib/src/target.dart`) representing each platform and architecture combination. For every `Target`, the `GoBuilder.build` method (in `plugins/setup/buildkit/build_tool/lib/src/go_builder.dart`) injects critical environment variables: - **`GOOS`** and **`GOARCH`** for cross-compilation - **`CGO_ENABLED`** set to `1` for Android builds - **`CC`** and **`CFLAGS`** pointing to the Android NDK compiler (resolved via `Environment.androidNdk` for mobile targets) The actual Go command executed depends on the target type: - **Android**: `go build -ldflags=-w -s -tags=with_gvisor -buildmode=c-shared -o ` - **Desktop (macOS/Linux)**: `go build -buildmode=default` producing a plain executable - **Windows**: `go build -buildmode=c-shared` producing `libclash.dll` ### Android-Specific Post-Processing When building for Android, the `GoBuilder._adjustAndroidOutput` method (lines 100-138) automatically handles JNI integration. The builder copies the generated `.so` files into `android/core/src/main/jniLibs//` and extracts C header files (`*.h`) into `android/core/src/main/cpp/includes//`. This allows the Kotlin wrapper in the Android module to load the library via `System.loadLibrary("clash")`. ### Cryptographic Hashing and Flutter Integration After successful compilation, the script calculates a SHA-256 hash of the core binary using the `calcSha256` utility in `plugins/setup/buildkit/build_tool/lib/src/util.dart`. This hash is written to [`core_sha256.json`](https://github.com/chen08209/FlClash/blob/main/core_sha256.json) and subsequently embedded into [`env.json`](https://github.com/chen08209/FlClash/blob/main/env.json) along with `APP_ENV` variables. The `setup.dart` script then invokes `flutter_distributor` with the `--dart-define-from-file=env.json` argument, passing the hash as a compile-time constant. This allows the Flutter application to verify the integrity of the native core at runtime, particularly on Windows where the hash enables token-based verification with the `FlClashHelperService`. ## Platform-Specific Compilation Details ### Windows: Shared Library and Helper Service On Windows, the build system produces two artifacts: `libclash.dll` (the FFI-shared library) and `FlClashHelperService` (a Rust-based helper executable). The SHA-256 hash of the DLL is specifically used for secure IPC between the Flutter frontend and the helper service. ### macOS and Linux: Standalone Executables Desktop builds for macOS and Linux compile the Go core as a standalone executable named `FlClashCore`, placed in `libclash//`. These platforms do not use FFI shared libraries for the core communication; instead, the Flutter controller communicates with the binary over a local socket. ### Android: Multi-ABI Shared Libraries Android requires `c-shared` libraries for each supported ABI: `armeabi-v7a`, `arm64-v8a`, and `x86_64`. The build system iterates through these targets, setting the appropriate `GOARCH` values (`arm`, `arm64`, `amd64`) and ensuring the NDK toolchain is correctly configured via `Environment.androidNdk`. ## Build Commands and Usage Examples ### Build for the Current Host Desktop ```bash # From the repository root dart setup.dart ``` This defaults to the host OS (Linux, macOS, or Windows) and places the compiled binary in `libclash//`. ### Build Android Libraries for Specific Architectures ```bash # Build for a specific Android ABI dart setup.dart android --arch arm64 # Build for all supported Android ABIs dart setup.dart android ``` After completion, libraries are available at: ``` android/core/src/main/jniLibs/arm64-v8a/libclash.so android/core/src/main/cpp/includes/arm64-v8a/*.h ``` ### Manual Debug Build Using build_tool ```bash cd plugins/setup/buildkit/build_tool dart run build_tool windows --root-dir $(pwd)/../../../.. ``` This directly invokes the `GoBuilder` logic used by `setup.dart` with verbose output for debugging. ### Verify the Embedded SHA-256 Hash ```bash cat core_sha256.json ``` Example output: ```json {"CORE_SHA256":"c3f9e2b4f1a7…"} ``` ## Summary - **The build system** resides in `plugins/setup` and is driven by `setup.dart`, which orchestrates the `build_tool` Dart package to compile the Go core. - **Configuration** is loaded from [`build_config.yaml`](https://github.com/chen08209/FlClash/blob/main/build_config.yaml) via `BuildConfig.load` in `options.dart`, defining build flags, tags, and output paths. - **Cross-compilation** is handled by `GoBuilder.build` in `go_builder.dart`, which sets `GOOS`, `GOARCH`, and Android NDK environment variables. - **Android builds** produce `c-shared` libraries for multiple ABIs, automatically installing `.so` files and headers into the Android module's `jniLibs` and `cpp/includes` directories. - **Integrity verification** is enforced by calculating SHA-256 hashes via `calcSha256` in `util.dart`, embedding these values into [`env.json`](https://github.com/chen08209/FlClash/blob/main/env.json) for runtime verification, particularly on Windows. - **Packaging** is finalized by `flutter_distributor`, which bundles the native binaries into platform-specific formats (APK, DMG, EXE). ## Frequently Asked Questions ### How does FlClash handle cross-compilation for Android on different host machines? The `GoBuilder` class automatically detects the host OS and configures the Android NDK path using `Environment.androidNdk` in `environment.dart`. It sets the `CC` environment variable to the appropriate NDK compiler (e.g., `aarch64-linux-android21-clang` for `arm64`), allowing the Go toolchain to cross-compile `c-shared` libraries for ARM and x86 architectures regardless of whether the build runs on Linux, macOS, or Windows. ### Where are the compiled Go binaries located after running setup.dart? Desktop binaries are placed in `libclash//` (e.g., `libclash/windows/FlClashCore.exe`). Android shared libraries are copied to `android/core/src/main/jniLibs//libclash.so` with corresponding header files in `android/core/src/main/cpp/includes//`. Windows additionally generates `libclash.dll` in the root build output for FFI integration. ### What is the purpose of the core_sha256.json file generated during the build? The [`core_sha256.json`](https://github.com/chen08209/FlClash/blob/main/core_sha256.json) file contains the SHA-256 hash of the compiled Go core binary, calculated by the `calcSha256` function in `util.dart`. This hash is embedded into the Flutter application via [`env.json`](https://github.com/chen08209/FlClash/blob/main/env.json) and used at runtime to verify the integrity of the native library, preventing tampering and ensuring version compatibility between the Flutter UI and the Go backend, particularly for the Windows helper service authentication. ### Can I modify the Go build tags or linker flags used by the FFI plugin? Yes. The build system reads [`build_config.yaml`](https://github.com/chen08209/FlClash/blob/main/build_config.yaml) (or creates default settings) via `BuildConfig.load` in `options.dart`. You can create or edit this file in the project root to override parameters such as `goTags` (e.g., changing `with_gvisor`), `ldflags`, or the output directory structure without modifying the Dart source code in `build_tool`.