DOCSEARCHbyAlgolia
Submit Docs

crossbind

repository·main·Indexed 40 days ago

https://github.com/bugra9/cpp.js

A tool that allows developers to import C++ and Rust libraries as standard JavaScript modules. It handles binding generation and native dependency resolution for runtimes including Browsers, Node.js, React Native, and WASI. It includes build integrations for Vite, Rollup, Webpack, and Metro, as well as prebuilt ports for libraries like OpenSSL, SQLite, and zlib.

Tokens
173.5K
Snippets
515
Records
815
Agent score
100%

What's inside crossbind

  1. Overview of @crossbind/docker image family

    main

    The @crossbind/docker package provides the toolchains required for crossbind builds. By using these images, a project only needs Docker and Node.js installed to perform complex native builds.

    Available Images

    ImageCarriesPlatforms
    baseDebian, Node, pinned Rust toolchain, swig, cmakeamd64, arm64
    webbase + Emscripten, wasi-sdk, prebuilt Rust sysrootsamd64, arm64
    androidbase + NDK and android Rust targetsamd64 only
    rust-sysrootST/MT Rust sysroots and their manifestamd64, arm64

    Note on Android: The android image is restricted to amd64 because the Google Linux NDK host tools are only available for x86_64. The CLI pins android builds to this platform even when running on an arm64 host.

  2. Overview of @crossbind/core-embind-rust

    main

    The @crossbind/core-embind-rust package is a Rust producer for the crossbind embind registration protocol. It allows you to write idiomatic Rust structs and methods that surface in JavaScript as real classes.

    Key features:

    • No generated C++ wrappers: It uses a flat C-ABI to talk directly to hosts (Web via Emscripten's embind-js, Mobile via @crossbind/core-embind-jsi).
    • No cbindgen headers required: The engine parses your Rust public surface to generate the necessary bridge.
    • Automatic JS mapping: Rust methods are automatically camelCased for JS, and types like Result and Option are mapped to JS exceptions and null respectively.

    Note: Status is currently research/spike. The architecture is validated, but it is not yet a general-purpose package and has specific constraints on class shapes and arities.

  3. Explore the crossbind project structure

    main

    The repository is organized into several functional areas:

    • core/: The primary code shipped to consumers, including the CLI/build orchestration (crossbind/), Embind/JSI helpers (embind-jsi/), and Rust producers (embind-rust/).
    • plugins/: Build integrations for Vite, Webpack, Rollup, React Native, and Metro.
    • ports/: Native libraries built for crossbind targets (e.g., @crossbind/port-<name>), organized by platform (wasm, android, ios, wasi).
    • tooling/: Developer-only helpers like create-app/ (scaffolder) and docker/ (pinned build images).
    • examples/: Reference integrations used as templates for create-crossbind.

  4. Manage Crossbind dependency and toolchain maintenance

    main

    Crossbind uses a multi-layered automation strategy to manage dependencies, separating discovery and validation from the actual release process. While bots can prepare reviewable source changes and draft PRs, they cannot publish npm packages, push GHCR images, or create releases; these remain protected manual workflows.

    Automation Layers

    • Dependabot: Handles routine pnpm, GitHub Actions, and Debian base-image updates.
    • dependency-watch.yml: A daily/manual workflow that manages repository-specific units like Node LTS pins, Rust/digest-pinned bootstrap images, Emscripten/emsdk (including the libembind.js fork), wasi-sdk archives, Android command-line tools, and the Crossbind SWIG fork.

    Security and Validation

    • Vulnerability Scanning: GHCR images are scanned daily via scan-toolchain-images.yml using Trivy. Security updates are proposed only when a replacement passes image builds, hardened-runtime smoke tests, and Trivy gates.
    • OSV Integration: For native sources, the planner resolves upstream tags to Git commits and queries OSV for vulnerabilities.
    • Manual Review Requirements: Certain libraries (e.g., libiconv, libspatialite, libtiff) require manual advisory review because they lack a stable release-tag-to-Git-commit identity for OSV queries.

  5. Use @crossbind/port-iconv-wasm for WebAssembly iconv support

    main

    @crossbind/port-iconv-wasm provides a WebAssembly build of the precompiled libiconv library, built using crossbind.

    Note: This package is a specific WASM target. For general installation and usage instructions, refer to the main package: @crossbind/port-iconv.

    Supported Targets

    • WebAssembly (wasm32): Single-threaded.
    • WebAssembly (wasm32): Multi-threaded. This requires SharedArrayBuffer support, which necessitates serving the application with COOP (Cross-Origin-Opener-Policy) and COEP (Cross-Origin-Embedder-Policy) HTTP headers.

  6. Understand the crossbind Package structure

    main

    The @crossbind/port-* npm packages are organized into 'recipe families'. Each family consists of:

    • The family (recipe) package (@crossbind/port-<name>): Contains the build recipe (build.mjs), upstream pins, and license metadata. It does not distribute upstream code itself.
    • Platform variants: Prebuilt archives for specific platforms, such as -wasm, -wasi, -android, or -ios.
    • -bin-wasi tool packages (optional): These provide the upstream CLI built as a WASI component, installable via npm with per-tool commands.

    Downstream products consuming these packages are consumers only; they do not depend on the recipe packages.

  8. Use @crossbind/port-geos-wasi for GEOS in WASI environments

    main

    This package provides a WASI build of the precompiled GEOS library, built using crossbind. It is specifically designed for single-threaded command modules running in WASI environments.

    Important: This repository contains the WASI-specific build. For general installation and usage instructions, you should refer to the main package: @crossbind/port-geos.

  9. Source acquisition options in `crossbind.build.js`

    main

    To fetch the upstream source, you must provide exactly one of the following methods in your crossbind.build.js export:

    • getURL(version): Returns a URL to a tarball. The version argument is the nativeVersion from package.json. The CLI handles downloading and extracting it into state.config.paths.build.
    • sha256: A string representing the checksum of the tarball returned by getURL. This is required for packages publishing binaries to ensure provenance.
    • getSource(state): An async function for custom acquisition (e.g., git clone, copying from a sibling dependency, or generating files). The staging directory is state.config.paths.build.

  11. Supported WebAssembly targets for @crossbind/port-lerc-wasm

    main

    The @crossbind/port-lerc-wasm package supports two WebAssembly (wasm32) targets:

    1. Single-threaded: Standard WASM execution.
    2. Multi-threaded: Requires SharedArrayBuffer. To use this target, you must serve your application with COOP (Cross-Origin Opener Policy) and COEP (Cross-Origin Embedder Policy) HTTP headers enabled.

  12. Execution model and supported project tools

    main

    The crossbind skill does not use a proprietary background server or protocol. Instead, it operates by invoking the standard tools and commands already present in your project. An agent using this skill will rely on:

    • Crossbind CLI: crossbind build and crossbind licenses.
    • Scaffolding: npm create crossbind for applications and standalone libraries.
    • Monorepo Commands: pnpm scaffold:port (used within the crossbind monorepo).
    • Standard Package Manager Commands: install, build, and test commands.
    • Repository Scripts: Scripts like pnpm doctor and pnpm check:native.

    The agent remains constrained by your existing filesystem, shell, and approval boundaries.