@xspect-build/cross-build 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# @xspect-build/cross-build
+
+Cross-compile Rust projects without Docker.
+
+This package extracts the cross-compilation logic from `@napi-rs/cli` into a standalone package that can be used by any Rust project, not just those using NAPI-RS.
+
+## Features
+
+- **Cross-compile for Linux targets** using `@napi-rs/cross-toolchain`
+- **Cross-compile for Windows** using `cargo-xwin`
+- **Cross-compile for other platforms** using `cargo-zigbuild`
+- **Android NDK support** for Android targets
+- **WASI support** for WebAssembly targets
+- **OpenHarmony support** for HarmonyOS targets
+
+## Installation
+
+```bash
+npm install @xspect-build/cross-build
+# or
+yarn add @xspect-build/cross-build
+# or
+pnpm add @xspect-build/cross-build
+```
+
+## Usage
+
+### Basic Build
+
+```typescript
+import { build } from '@xspect-build/cross-build'
+
+// Cross-compile for Linux ARM64
+const result = await build({
+  target: 'aarch64-unknown-linux-gnu',
+  release: true,
+  useNapiCross: true,
+})
+
+console.log('Build succeeded:', result.success)
+console.log('Environment variables used:', result.envs)
+```
+
+### Get Cross-Compile Environment Variables
+
+If you want to get the environment variables needed for cross-compilation without actually building, you can use `getCrossCompileEnv`:
+
+```typescript
+import { getCrossCompileEnv } from '@xspect-build/cross-build'
+
+const env = getCrossCompileEnv({
+  target: 'aarch64-unknown-linux-gnu',
+  useNapiCross: true,
+})
+
+console.log(env)
+// {
+//   CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: '...',
+//   TARGET_CC: '...',
+//   TARGET_CXX: '...',
+//   ...
+// }
+```
+
+### Parse Target Triple
+
+```typescript
+import { parseTriple } from '@xspect-build/cross-build'
+
+const target = parseTriple('aarch64-unknown-linux-gnu')
+console.log(target)
+// {
+//   triple: 'aarch64-unknown-linux-gnu',
+//   platform: 'linux',
+//   arch: 'arm64',
+//   abi: 'gnu',
+//   platformArchABI: 'linux-arm64-gnu'
+// }
+```
+
+## Options
+
+### `CrossBuildOptions`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `target` | `string` | Target triple (e.g., 'aarch64-unknown-linux-gnu') |
+| `cwd` | `string` | Working directory for the build |
+| `manifestPath` | `string` | Path to Cargo.toml manifest file |
+| `targetDir` | `string` | Directory for build artifacts |
+| `release` | `boolean` | Build in release mode |
+| `verbose` | `boolean` | Show verbose output |
+| `profile` | `string` | Build profile (e.g., 'release', 'dev') |
+| `useNapiCross` | `boolean` | Use @napi-rs/cross-toolchain for Linux cross-compilation |
+| `crossCompile` | `boolean` | Use cargo-zigbuild/cargo-xwin for cross-compilation |
+| `useCross` | `boolean` | Use cross-rs instead of cargo |
+| `strip` | `boolean` | Strip debug symbols |
+| `package` | `string` | Package name in workspace |
+| `bin` | `string` | Binary name to build |
+| `features` | `string[]` | Features to enable |
+| `allFeatures` | `boolean` | Enable all features |
+| `noDefaultFeatures` | `boolean` | Disable default features |
+| `cargoArgs` | `string[]` | Additional cargo arguments |
+| `env` | `Record<string, string>` | Additional environment variables |
+
+## Supported Targets
+
+### Linux Targets (via `@napi-rs/cross-toolchain`)
+
+- `aarch64-unknown-linux-gnu`
+- `aarch64-unknown-linux-musl`
+- `x86_64-unknown-linux-gnu`
+- `x86_64-unknown-linux-musl`
+- `armv7-unknown-linux-gnueabihf`
+- `riscv64gc-unknown-linux-gnu`
+- `powerpc64le-unknown-linux-gnu`
+- `s390x-unknown-linux-gnu`
+- And more...
+
+### Windows Targets (via `cargo-xwin`)
+
+- `x86_64-pc-windows-msvc`
+- `i686-pc-windows-msvc`
+- `aarch64-pc-windows-msvc`
+
+### Other Platforms (via `cargo-zigbuild`)
+
+- macOS (cross-arch)
+- FreeBSD
+- And more...
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,125 @@
+import { type Target } from './target.js';
+/**
+ * Options for cross-compiling Rust projects
+ */
+export interface CrossBuildOptions {
+    /**
+     * The target triple to build for (e.g., 'aarch64-unknown-linux-gnu')
+     */
+    target?: string;
+    /**
+     * Working directory for the build
+     */
+    cwd?: string;
+    /**
+     * Path to Cargo.toml manifest file
+     */
+    manifestPath?: string;
+    /**
+     * Directory for build artifacts
+     */
+    targetDir?: string;
+    /**
+     * Build in release mode
+     */
+    release?: boolean;
+    /**
+     * Show verbose output
+     */
+    verbose?: boolean;
+    /**
+     * Build profile (e.g., 'release', 'dev')
+     */
+    profile?: string;
+    /**
+     * Use @napi-rs/cross-toolchain for Linux cross-compilation
+     */
+    useNapiCrossToolChain?: boolean;
+    /**
+     * Use cargo-zigbuild/cargo-xwin for cross-compilation
+     */
+    crossCompile?: boolean;
+    /**
+     * Use cross-rs instead of cargo
+     */
+    useCross?: boolean;
+    /**
+     * Strip debug symbols
+     */
+    strip?: boolean;
+    /**
+     * Package name in workspace
+     */
+    package?: string;
+    /**
+     * Binary name to build
+     */
+    bin?: string;
+    /**
+     * Features to enable
+     */
+    features?: string[];
+    /**
+     * Enable all features
+     */
+    allFeatures?: boolean;
+    /**
+     * Disable default features
+     */
+    noDefaultFeatures?: boolean;
+    /**
+     * Additional cargo arguments
+     */
+    cargoArgs?: string[];
+    /**
+     * Additional environment variables
+     */
+    env?: Record<string, string>;
+}
+/**
+ * Result of the cross-build operation
+ */
+export interface CrossBuildResult {
+    /**
+     * Whether the build succeeded
+     */
+    success: boolean;
+    /**
+     * The target that was built
+     */
+    target: Target;
+    /**
+     * Environment variables that were set
+     */
+    envs: Record<string, string>;
+}
+/**
+ * Cross-compile a Rust project
+ *
+ * @example
+ * ```ts
+ * import { build } from '@xspect-build/cross-build'
+ *
+ * const result = await build({
+ *   target: 'aarch64-unknown-linux-gnu',
+ *   release: true,
+ *   useNapiCross: true,
+ * })
+ * ```
+ */
+export declare function build(options?: CrossBuildOptions): Promise<CrossBuildResult>;
+/**
+ * Get environment variables needed for cross-compilation without actually building
+ *
+ * @example
+ * ```ts
+ * import { getCrossCompileEnv } from '@xspect-build/cross-build'
+ *
+ * const env = getCrossCompileEnv({
+ *   target: 'aarch64-unknown-linux-gnu',
+ *   useNapiCross: true,
+ * })
+ * console.log(env)
+ * ```
+ */
+export declare function getCrossCompileEnv(options?: CrossBuildOptions): Record<string, string>;

package/dist/cargo.d.ts

@@ -0,0 +1,2 @@
+export declare function tryInstallCargoBinary(name: string, bin: string): void;
+export declare function ensureRustTarget(target: string): void;

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cac } from "cac";
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { bgGreen, bgRed, bgYellow, black, green, red, white } from "colorette";
+import { createDebug } from "obug";
+const debugFactory = (namespace)=>{
+    const debug = createDebug(`cross-build:${namespace}`, {
+        formatters: {
+            i (v) {
+                return green(v);
+            }
+        }
+    });
+    debug.info = (...args)=>console.error(black(bgGreen(' INFO ')), ...args);
+    debug.warn = (...args)=>console.error(black(bgYellow(' WARNING ')), ...args);
+    debug.error = (...args)=>console.error(white(bgRed(' ERROR ')), ...args.map((arg)=>arg instanceof Error ? arg.stack ?? arg.message : arg));
+    return debug;
+};
+const log_debug = debugFactory('core');
+function tryInstallCargoBinary(name, bin) {
+    if (detectCargoBinary(bin)) return void log_debug('Cargo binary already installed: %s', name);
+    try {
+        log_debug('Installing cargo binary: %s', name);
+        execSync(`cargo install ${name}`, {
+            stdio: 'inherit'
+        });
+    } catch (e) {
+        throw new Error(`Failed to install cargo binary: ${name}`, {
+            cause: e
+        });
+    }
+}
+function detectCargoBinary(bin) {
+    log_debug('Detecting cargo binary: %s', bin);
+    try {
+        execSync(`cargo help ${bin}`, {
+            stdio: 'ignore'
+        });
+        log_debug('Cargo binary detected: %s', bin);
+        return true;
+    } catch  {
+        log_debug('Cargo binary not detected: %s', bin);
+        return false;
+    }
+}
+function ensureRustTarget(target) {
+    try {
+        const installedTargets = execSync('rustup target list --installed', {
+            encoding: 'utf8'
+        });
+        if (installedTargets.includes(target)) return;
+        log_debug('Installing rust target: %s', target);
+        execSync(`rustup target add ${target}`, {
+            stdio: 'inherit'
+        });
+    } catch (e) {
+        log_debug.warn(`Failed to check or install rust target ${target}. Make sure rustup is installed and available in PATH.`, e);
+    }
+}
+const SUB_SYSTEMS = new Set([
+    'android',
+    'ohos'
+]);
+const CpuToNodeArch = {
+    x86_64: 'x64',
+    aarch64: 'arm64',
+    i686: 'ia32',
+    armv7: 'arm',
+    loongarch64: 'loong64',
+    riscv64gc: 'riscv64',
+    powerpc64le: 'ppc64'
+};
+const SysToNodePlatform = {
+    linux: 'linux',
+    freebsd: 'freebsd',
+    darwin: 'darwin',
+    windows: 'win32',
+    ohos: 'openharmony'
+};
+const TARGET_LINKER = {
+    'aarch64-unknown-linux-musl': 'aarch64-linux-musl-gcc',
+    'loongarch64-unknown-linux-gnu': 'loongarch64-linux-gnu-gcc-13',
+    'riscv64gc-unknown-linux-gnu': 'riscv64-linux-gnu-gcc',
+    'powerpc64le-unknown-linux-gnu': 'powerpc64le-linux-gnu-gcc',
+    's390x-unknown-linux-gnu': 's390x-linux-gnu-gcc'
+};
+function parseTriple(rawTriple) {
+    if ('wasm32-wasi' === rawTriple || 'wasm32-wasi-preview1-threads' === rawTriple || rawTriple.startsWith('wasm32-wasip')) return {
+        triple: rawTriple,
+        platformArchABI: 'wasm32-wasi',
+        platform: 'wasi',
+        arch: 'wasm32',
+        abi: 'wasi'
+    };
+    const triple = rawTriple.endsWith('eabi') ? `${rawTriple.slice(0, -4)}-eabi` : rawTriple;
+    const triples = triple.split('-');
+    let cpu;
+    let sys;
+    let abi = null;
+    if (2 === triples.length) [cpu, sys] = triples;
+    else [cpu, , sys, abi = null] = triples;
+    if (abi && SUB_SYSTEMS.has(abi)) {
+        sys = abi;
+        abi = null;
+    }
+    const platform = SysToNodePlatform[sys] ?? sys;
+    const arch = CpuToNodeArch[cpu] ?? cpu;
+    return {
+        triple: rawTriple,
+        platformArchABI: abi ? `${platform}-${arch}-${abi}` : `${platform}-${arch}`,
+        platform,
+        arch,
+        abi
+    };
+}
+function getSystemDefaultTarget() {
+    const host = execSync("rustc -vV", {
+        env: process.env
+    }).toString('utf8').split('\n').find((line)=>line.startsWith('host: '));
+    const triple = host?.slice('host: '.length);
+    if (!triple) throw new TypeError("Can not parse target triple from host");
+    return parseTriple(triple);
+}
+function getTargetLinker(target) {
+    return TARGET_LINKER[target];
+}
+function targetToEnvVar(target) {
+    return target.replace(/-/g, '_').toUpperCase();
+}
+const build_debug = debugFactory('build');
+const build_require = createRequire(import.meta.url);
+async function build(options = {}) {
+    const builder = new CrossBuilder(options);
+    return builder.build();
+}
+class CrossBuilder {
+    options;
+    args = [];
+    envs = {};
+    target;
+    cwd;
+    constructor(options){
+        this.options = options;
+        this.target = options.target ? parseTriple(options.target) : process.env.CARGO_BUILD_TARGET ? parseTriple(process.env.CARGO_BUILD_TARGET) : getSystemDefaultTarget();
+        this.cwd = options.cwd ?? process.cwd();
+    }
+    getEnvs() {
+        this.pickCrossToolchain();
+        this.setEnvs();
+        return {
+            ...this.envs
+        };
+    }
+    async build() {
+        this.pickBinary().setPackage().setFeatures().setTarget().ensureTarget().pickCrossToolchain().setEnvs().setBypassArgs();
+        return this.exec();
+    }
+    ensureTarget() {
+        if (this.target.triple) ensureRustTarget(this.target.triple);
+        return this;
+    }
+    pickCrossToolchain() {
+        if (false === this.options.useNapiCrossToolChain) return this;
+        if (!this.target.triple.includes('linux')) {
+            if (true === this.options.useNapiCrossToolChain) build_debug.warn(`Skipping @napi-rs/cross-toolchain because target ${this.target.triple} is not Linux.`);
+            return this;
+        }
+        if (this.options.useCross) build_debug.warn('You are trying to use both `useCross` and `useNapiCross` options, `useCross` will be ignored.');
+        if (this.options.crossCompile) build_debug.warn('You are trying to use both `crossCompile` and `useNapiCross` options, `crossCompile` will be ignored.');
+        try {
+            const { version, download } = build_require('@napi-rs/cross-toolchain');
+            const alias = {
+                's390x-unknown-linux-gnu': 's390x-ibm-linux-gnu'
+            };
+            const toolchainPath = join(homedir(), '.napi-rs', 'cross-toolchain', version, this.target.triple);
+            mkdirSync(toolchainPath, {
+                recursive: true
+            });
+            if (existsSync(join(toolchainPath, 'package.json'))) build_debug(`Toolchain ${toolchainPath} exists, skip extracting`);
+            else {
+                const tarArchive = download(process.arch, this.target.triple);
+                tarArchive.unpack(toolchainPath);
+            }
+            const upperCaseTarget = targetToEnvVar(this.target.triple);
+            const crossTargetName = alias[this.target.triple] ?? this.target.triple;
+            const linkerEnv = `CARGO_TARGET_${upperCaseTarget}_LINKER`;
+            this.setEnvIfNotExists(linkerEnv, join(toolchainPath, 'bin', `${crossTargetName}-gcc`));
+            this.setEnvIfNotExists('TARGET_SYSROOT', join(toolchainPath, crossTargetName, 'sysroot'));
+            this.setEnvIfNotExists('TARGET_AR', join(toolchainPath, 'bin', `${crossTargetName}-ar`));
+            this.setEnvIfNotExists('TARGET_RANLIB', join(toolchainPath, 'bin', `${crossTargetName}-ranlib`));
+            this.setEnvIfNotExists('TARGET_READELF', join(toolchainPath, 'bin', `${crossTargetName}-readelf`));
+            this.setEnvIfNotExists('TARGET_C_INCLUDE_PATH', join(toolchainPath, crossTargetName, 'sysroot', 'usr', 'include/'));
+            this.setEnvIfNotExists('TARGET_CC', join(toolchainPath, 'bin', `${crossTargetName}-gcc`));
+            this.setEnvIfNotExists('TARGET_CXX', join(toolchainPath, 'bin', `${crossTargetName}-g++`));
+            this.envs[`CXX_${upperCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-g++`);
+            const snakeCaseTarget = this.target.triple.replace(/-/g, '_');
+            this.envs[`CC_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-gcc`);
+            this.envs[`CXX_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-g++`);
+            this.envs[`AR_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-ar`);
+            this.setEnvIfNotExists('BINDGEN_EXTRA_CLANG_ARGS', `--sysroot=${this.envs.TARGET_SYSROOT}`);
+            if (process.env.TARGET_CC?.startsWith('clang') || process.env.CC?.startsWith('clang') && !process.env.TARGET_CC) {
+                const TARGET_CFLAGS = process.env.TARGET_CFLAGS ?? '';
+                this.envs.TARGET_CFLAGS = `--sysroot=${this.envs.TARGET_SYSROOT} --gcc-toolchain=${toolchainPath} ${TARGET_CFLAGS}`;
+            }
+            if (process.env.CXX?.startsWith('clang++') && !process.env.TARGET_CXX || process.env.TARGET_CXX?.startsWith('clang++')) {
+                const TARGET_CXXFLAGS = process.env.TARGET_CXXFLAGS ?? '';
+                this.envs.TARGET_CXXFLAGS = `--sysroot=${this.envs.TARGET_SYSROOT} --gcc-toolchain=${toolchainPath} ${TARGET_CXXFLAGS}`;
+            }
+            this.envs.PATH = this.envs.PATH ? `${toolchainPath}/bin:${this.envs.PATH}:${process.env.PATH}` : `${toolchainPath}/bin:${process.env.PATH}`;
+        } catch (e) {
+            build_debug.warn('Pick cross toolchain failed', e);
+        }
+        return this;
+    }
+    pickBinary() {
+        if (this.options.crossCompile) if ('win32' === this.target.platform) if ('win32' === process.platform) build_debug.warn('You are trying to cross compile to win32 platform on win32 platform which is unnecessary.');
+        else {
+            build_debug('Use %i', 'cargo-xwin');
+            tryInstallCargoBinary('cargo-xwin', 'xwin');
+            this.args.push('xwin', 'build');
+            if ('ia32' === this.target.arch) this.envs.XWIN_ARCH = 'x86';
+            return this;
+        }
+        else if ('linux' === this.target.platform && 'linux' === process.platform && this.target.arch === process.arch && function(abi) {
+            const glibcVersionRuntime = process.report?.getReport()?.header?.glibcVersionRuntime;
+            const libc = glibcVersionRuntime ? 'gnu' : 'musl';
+            return abi === libc;
+        }(this.target.abi)) build_debug.warn('You are trying to cross compile to linux target on linux platform which is unnecessary.');
+        else if ('darwin' === this.target.platform && 'darwin' === process.platform) build_debug.warn('You are trying to cross compile to darwin target on darwin platform which is unnecessary.');
+        else {
+            build_debug('Use %i', 'cargo-zigbuild');
+            tryInstallCargoBinary('cargo-zigbuild', 'zigbuild');
+            this.args.push('zigbuild');
+            return this;
+        }
+        this.args.push('build');
+        return this;
+    }
+    setPackage() {
+        const args = [];
+        if (this.options.package) args.push('--package', this.options.package);
+        if (this.options.bin) args.push('--bin', this.options.bin);
+        if (args.length) {
+            build_debug('Set package flags: ');
+            build_debug('  %O', args);
+            this.args.push(...args);
+        }
+        return this;
+    }
+    setTarget() {
+        build_debug('Set compiling target to: ');
+        build_debug('  %i', this.target.triple);
+        this.args.push('--target', this.target.triple);
+        return this;
+    }
+    setEnvs() {
+        let rustflags = process.env.RUSTFLAGS ?? process.env.CARGO_BUILD_RUSTFLAGS ?? '';
+        if (this.target.abi?.includes('musl') && !rustflags.includes('target-feature=-crt-static')) rustflags += ' -C target-feature=-crt-static';
+        if (this.options.strip && !rustflags.includes('link-arg=-s')) rustflags += ' -C link-arg=-s';
+        if (rustflags.length) this.envs.RUSTFLAGS = rustflags;
+        const linker = this.options.crossCompile ? void 0 : getTargetLinker(this.target.triple);
+        const linkerEnv = `CARGO_TARGET_${targetToEnvVar(this.target.triple)}_LINKER`;
+        if (linker && !process.env[linkerEnv] && !this.envs[linkerEnv]) this.envs[linkerEnv] = linker;
+        if ('android' === this.target.platform) this.setAndroidEnv();
+        if ('wasi' === this.target.platform) this.setWasiEnv();
+        if ('openharmony' === this.target.platform) this.setOpenHarmonyEnv();
+        if (this.options.env) Object.assign(this.envs, this.options.env);
+        build_debug('Set envs: ');
+        Object.entries(this.envs).forEach(([k, v])=>{
+            build_debug('  %i', `${k}=${v}`);
+        });
+        return this;
+    }
+    setAndroidEnv() {
+        const { ANDROID_NDK_LATEST_HOME } = process.env;
+        if (!ANDROID_NDK_LATEST_HOME) build_debug.warn(`${red('ANDROID_NDK_LATEST_HOME')} environment variable is missing`);
+        if ('android' === process.platform) return;
+        const targetArch = 'arm' === this.target.arch ? 'armv7a' : 'aarch64';
+        const targetPlatform = 'arm' === this.target.arch ? 'androideabi24' : 'android24';
+        const hostPlatform = 'darwin' === process.platform ? 'darwin' : 'win32' === process.platform ? 'windows' : 'linux';
+        Object.assign(this.envs, {
+            CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-android24-clang`,
+            CARGO_TARGET_ARMV7_LINUX_ANDROIDEABI_LINKER: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-androideabi24-clang`,
+            TARGET_CC: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-${targetPlatform}-clang`,
+            TARGET_CXX: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-${targetPlatform}-clang++`,
+            TARGET_AR: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/llvm-ar`,
+            TARGET_RANLIB: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/llvm-ranlib`,
+            ANDROID_NDK: ANDROID_NDK_LATEST_HOME,
+            PATH: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin${'win32' === process.platform ? ';' : ':'}${process.env.PATH}`
+        });
+    }
+    setWasiEnv() {
+        const { WASI_SDK_PATH } = process.env;
+        if (WASI_SDK_PATH && existsSync(WASI_SDK_PATH)) {
+            this.envs.CARGO_TARGET_WASM32_WASI_PREVIEW1_THREADS_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP1_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP1_THREADS_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP2_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.setEnvIfNotExists('TARGET_CC', join(WASI_SDK_PATH, 'bin', 'clang'));
+            this.setEnvIfNotExists('TARGET_CXX', join(WASI_SDK_PATH, 'bin', 'clang++'));
+            this.setEnvIfNotExists('TARGET_AR', join(WASI_SDK_PATH, 'bin', 'ar'));
+            this.setEnvIfNotExists('TARGET_RANLIB', join(WASI_SDK_PATH, 'bin', 'ranlib'));
+            this.setEnvIfNotExists('TARGET_CFLAGS', `--target=wasm32-wasi-threads --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot -pthread -mllvm -wasm-enable-sjlj`);
+            this.setEnvIfNotExists('TARGET_CXXFLAGS', `--target=wasm32-wasi-threads --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot -pthread -mllvm -wasm-enable-sjlj`);
+            this.setEnvIfNotExists("TARGET_LDFLAGS", `-fuse-ld=${WASI_SDK_PATH}/bin/wasm-ld --target=wasm32-wasi-threads`);
+        }
+    }
+    setOpenHarmonyEnv() {
+        const { OHOS_SDK_PATH, OHOS_SDK_NATIVE } = process.env;
+        const ndkPath = OHOS_SDK_PATH ? `${OHOS_SDK_PATH}/native` : OHOS_SDK_NATIVE;
+        if (!ndkPath && 'openharmony' !== process.platform) return void build_debug.warn(`${red('OHOS_SDK_PATH')} or ${red('OHOS_SDK_NATIVE')} environment variable is missing`);
+        const linkerName = `CARGO_TARGET_${this.target.triple.toUpperCase().replace(/-/g, '_')}_LINKER`;
+        const ranPath = `${ndkPath}/llvm/bin/llvm-ranlib`;
+        const arPath = `${ndkPath}/llvm/bin/llvm-ar`;
+        const ccPath = `${ndkPath}/llvm/bin/${this.target.triple}-clang`;
+        const cxxPath = `${ndkPath}/llvm/bin/${this.target.triple}-clang++`;
+        const asPath = `${ndkPath}/llvm/bin/llvm-as`;
+        const ldPath = `${ndkPath}/llvm/bin/ld.lld`;
+        const stripPath = `${ndkPath}/llvm/bin/llvm-strip`;
+        const objDumpPath = `${ndkPath}/llvm/bin/llvm-objdump`;
+        const objCopyPath = `${ndkPath}/llvm/bin/llvm-objcopy`;
+        const nmPath = `${ndkPath}/llvm/bin/llvm-nm`;
+        const binPath = `${ndkPath}/llvm/bin`;
+        const libPath = `${ndkPath}/llvm/lib`;
+        this.setEnvIfNotExists('LIBCLANG_PATH', libPath);
+        this.setEnvIfNotExists('DEP_ATOMIC', 'clang_rt.builtins');
+        this.setEnvIfNotExists(linkerName, ccPath);
+        this.setEnvIfNotExists('TARGET_CC', ccPath);
+        this.setEnvIfNotExists('TARGET_CXX', cxxPath);
+        this.setEnvIfNotExists('TARGET_AR', arPath);
+        this.setEnvIfNotExists('TARGET_RANLIB', ranPath);
+        this.setEnvIfNotExists('TARGET_AS', asPath);
+        this.setEnvIfNotExists('TARGET_LD', ldPath);
+        this.setEnvIfNotExists('TARGET_STRIP', stripPath);
+        this.setEnvIfNotExists('TARGET_OBJDUMP', objDumpPath);
+        this.setEnvIfNotExists('TARGET_OBJCOPY', objCopyPath);
+        this.setEnvIfNotExists('TARGET_NM', nmPath);
+        this.envs.PATH = `${binPath}${'win32' === process.platform ? ';' : ':'}${process.env.PATH}`;
+    }
+    setFeatures() {
+        const args = [];
+        if (this.options.allFeatures && this.options.noDefaultFeatures) throw new Error('Cannot specify --all-features and --no-default-features together');
+        if (this.options.allFeatures) args.push('--all-features');
+        else if (this.options.noDefaultFeatures) args.push('--no-default-features');
+        if (this.options.features) args.push('--features', ...this.options.features);
+        build_debug('Set features flags: ');
+        build_debug('  %O', args);
+        this.args.push(...args);
+        return this;
+    }
+    setBypassArgs() {
+        if (this.options.release) this.args.push('--release');
+        if (this.options.verbose) this.args.push('--verbose');
+        if (this.options.targetDir) this.args.push('--target-dir', this.options.targetDir);
+        if (this.options.profile) this.args.push('--profile', this.options.profile);
+        if (this.options.manifestPath) this.args.push('--manifest-path', this.options.manifestPath);
+        if (this.options.cargoArgs?.length) this.args.push(...this.options.cargoArgs);
+        return this;
+    }
+    async exec() {
+        build_debug('Start cross-building');
+        build_debug('  %i', `cargo ${this.args.join(' ')}`);
+        if (this.options.useCross && this.options.crossCompile) throw new Error('`useCross` and `crossCompile` cannot be used together');
+        const command = process.env.CARGO ?? (this.options.useCross ? 'cross' : 'cargo');
+        return new Promise((resolve, reject)=>{
+            const buildProcess = spawn(command, this.args, {
+                env: {
+                    ...process.env,
+                    ...this.envs
+                },
+                stdio: 'inherit',
+                cwd: this.cwd
+            });
+            buildProcess.once('exit', (code)=>{
+                if (0 === code) {
+                    build_debug('%i', 'Build completed successfully!');
+                    resolve({
+                        success: true,
+                        target: this.target,
+                        envs: {
+                            ...this.envs
+                        }
+                    });
+                } else reject(new Error(`Build failed with exit code ${code}`));
+            });
+            buildProcess.once('error', (e)=>{
+                reject(new Error(`Build failed with error: ${e.message}`, {
+                    cause: e
+                }));
+            });
+        });
+    }
+    setEnvIfNotExists(env, value) {
+        if (!process.env[env]) this.envs[env] = value;
+    }
+}
+const cli_require = createRequire(import.meta.url);
+const pkg = cli_require('../package.json');
+const cli = cac('cross-build');
+cli.command('[...args]', 'Build the project').option('--target <target>', 'Target triple (e.g., aarch64-unknown-linux-gnu)').option('--cwd <cwd>', 'Working directory').option('--manifest-path <path>', 'Path to Cargo.toml manifest file').option('--target-dir <dir>', 'Directory for build artifacts').option('--release', 'Build in release mode').option('--verbose', 'Show verbose output').option('--profile <profile>', 'Build profile (e.g., release, dev)').option('--use-napi-cross-toolchain', 'Use @napi-rs/cross-toolchain for Linux cross-compilation', {
+    default: true
+}).option('--cross-compile', 'Use cargo-zigbuild/cargo-xwin for cross-compilation').option('--use-cross', 'Use cross-rs instead of cargo').option('--strip', 'Strip debug symbols').option('--package <package>', 'Package name in workspace').option('--bin <bin>', 'Binary name to build').option('--features <features>', 'Features to enable (comma separated)').option('--all-features', 'Enable all features').option('--no-default-features', 'Disable default features').option('--cargo-args <args>', 'Additional cargo arguments (comma separated)').option('--env <env>', 'Additional environment variables (key=value, comma separated)').action(async (_args, options)=>{
+    try {
+        const features = options.features ? options.features.split(',') : void 0;
+        const cargoArgs = options.cargoArgs ? options.cargoArgs.split(',') : void 0;
+        const env = options.env ? options.env.split(',').reduce((acc, curr)=>{
+            const [key, value] = curr.split('=');
+            if (key && value) acc[key] = value;
+            return acc;
+        }, {}) : void 0;
+        const result = await build({
+            ...options,
+            features,
+            cargoArgs,
+            env,
+            noDefaultFeatures: false === options.defaultFeatures ? true : void 0
+        });
+        if (!result.success) process.exit(1);
+    } catch (e) {
+        console.error(e);
+        process.exit(1);
+    }
+});
+cli.help();
+cli.version(pkg.version);
+cli.parse();

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @xspect-build/cross-build
+ *
+ * Cross-compile Rust projects without Docker
+ *
+ * @example
+ * ```ts
+ * import { build, getCrossCompileEnv } from '@xspect-build/cross-build'
+ *
+ * // Cross-compile for Linux ARM64
+ * const result = await build({
+ *   target: 'aarch64-unknown-linux-gnu',
+ *   release: true,
+ *   useNapiCross: true,
+ * })
+ *
+ * // Or just get the environment variables needed
+ * const env = getCrossCompileEnv({
+ *   target: 'aarch64-unknown-linux-gnu',
+ *   useNapiCross: true,
+ * })
+ * ```
+ */
+export { build, getCrossCompileEnv, type CrossBuildOptions, type CrossBuildResult, } from './build';
+export { parseTriple, getSystemDefaultTarget, getTargetLinker, targetToEnvVar, TARGET_LINKER, type Target, type Platform, } from './target.js';
+export { tryInstallCargoBinary } from './cargo';
+export { debugFactory, debug } from './log.js';

package/dist/index.js

@@ -0,0 +1,403 @@
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { bgGreen, bgRed, bgYellow, black, green, red, white } from "colorette";
+import { createDebug } from "obug";
+const debugFactory = (namespace)=>{
+    const debug = createDebug(`cross-build:${namespace}`, {
+        formatters: {
+            i (v) {
+                return green(v);
+            }
+        }
+    });
+    debug.info = (...args)=>console.error(black(bgGreen(' INFO ')), ...args);
+    debug.warn = (...args)=>console.error(black(bgYellow(' WARNING ')), ...args);
+    debug.error = (...args)=>console.error(white(bgRed(' ERROR ')), ...args.map((arg)=>arg instanceof Error ? arg.stack ?? arg.message : arg));
+    return debug;
+};
+const log_debug = debugFactory('core');
+function tryInstallCargoBinary(name, bin) {
+    if (detectCargoBinary(bin)) return void log_debug('Cargo binary already installed: %s', name);
+    try {
+        log_debug('Installing cargo binary: %s', name);
+        execSync(`cargo install ${name}`, {
+            stdio: 'inherit'
+        });
+    } catch (e) {
+        throw new Error(`Failed to install cargo binary: ${name}`, {
+            cause: e
+        });
+    }
+}
+function detectCargoBinary(bin) {
+    log_debug('Detecting cargo binary: %s', bin);
+    try {
+        execSync(`cargo help ${bin}`, {
+            stdio: 'ignore'
+        });
+        log_debug('Cargo binary detected: %s', bin);
+        return true;
+    } catch  {
+        log_debug('Cargo binary not detected: %s', bin);
+        return false;
+    }
+}
+function ensureRustTarget(target) {
+    try {
+        const installedTargets = execSync('rustup target list --installed', {
+            encoding: 'utf8'
+        });
+        if (installedTargets.includes(target)) return;
+        log_debug('Installing rust target: %s', target);
+        execSync(`rustup target add ${target}`, {
+            stdio: 'inherit'
+        });
+    } catch (e) {
+        log_debug.warn(`Failed to check or install rust target ${target}. Make sure rustup is installed and available in PATH.`, e);
+    }
+}
+const SUB_SYSTEMS = new Set([
+    'android',
+    'ohos'
+]);
+const CpuToNodeArch = {
+    x86_64: 'x64',
+    aarch64: 'arm64',
+    i686: 'ia32',
+    armv7: 'arm',
+    loongarch64: 'loong64',
+    riscv64gc: 'riscv64',
+    powerpc64le: 'ppc64'
+};
+const SysToNodePlatform = {
+    linux: 'linux',
+    freebsd: 'freebsd',
+    darwin: 'darwin',
+    windows: 'win32',
+    ohos: 'openharmony'
+};
+const TARGET_LINKER = {
+    'aarch64-unknown-linux-musl': 'aarch64-linux-musl-gcc',
+    'loongarch64-unknown-linux-gnu': 'loongarch64-linux-gnu-gcc-13',
+    'riscv64gc-unknown-linux-gnu': 'riscv64-linux-gnu-gcc',
+    'powerpc64le-unknown-linux-gnu': 'powerpc64le-linux-gnu-gcc',
+    's390x-unknown-linux-gnu': 's390x-linux-gnu-gcc'
+};
+function parseTriple(rawTriple) {
+    if ('wasm32-wasi' === rawTriple || 'wasm32-wasi-preview1-threads' === rawTriple || rawTriple.startsWith('wasm32-wasip')) return {
+        triple: rawTriple,
+        platformArchABI: 'wasm32-wasi',
+        platform: 'wasi',
+        arch: 'wasm32',
+        abi: 'wasi'
+    };
+    const triple = rawTriple.endsWith('eabi') ? `${rawTriple.slice(0, -4)}-eabi` : rawTriple;
+    const triples = triple.split('-');
+    let cpu;
+    let sys;
+    let abi = null;
+    if (2 === triples.length) [cpu, sys] = triples;
+    else [cpu, , sys, abi = null] = triples;
+    if (abi && SUB_SYSTEMS.has(abi)) {
+        sys = abi;
+        abi = null;
+    }
+    const platform = SysToNodePlatform[sys] ?? sys;
+    const arch = CpuToNodeArch[cpu] ?? cpu;
+    return {
+        triple: rawTriple,
+        platformArchABI: abi ? `${platform}-${arch}-${abi}` : `${platform}-${arch}`,
+        platform,
+        arch,
+        abi
+    };
+}
+function getSystemDefaultTarget() {
+    const host = execSync("rustc -vV", {
+        env: process.env
+    }).toString('utf8').split('\n').find((line)=>line.startsWith('host: '));
+    const triple = host?.slice('host: '.length);
+    if (!triple) throw new TypeError("Can not parse target triple from host");
+    return parseTriple(triple);
+}
+function getTargetLinker(target) {
+    return TARGET_LINKER[target];
+}
+function targetToEnvVar(target) {
+    return target.replace(/-/g, '_').toUpperCase();
+}
+const build_debug = debugFactory('build');
+const build_require = createRequire(import.meta.url);
+async function build(options = {}) {
+    const builder = new CrossBuilder(options);
+    return builder.build();
+}
+function getCrossCompileEnv(options = {}) {
+    const builder = new CrossBuilder(options);
+    return builder.getEnvs();
+}
+class CrossBuilder {
+    options;
+    args = [];
+    envs = {};
+    target;
+    cwd;
+    constructor(options){
+        this.options = options;
+        this.target = options.target ? parseTriple(options.target) : process.env.CARGO_BUILD_TARGET ? parseTriple(process.env.CARGO_BUILD_TARGET) : getSystemDefaultTarget();
+        this.cwd = options.cwd ?? process.cwd();
+    }
+    getEnvs() {
+        this.pickCrossToolchain();
+        this.setEnvs();
+        return {
+            ...this.envs
+        };
+    }
+    async build() {
+        this.pickBinary().setPackage().setFeatures().setTarget().ensureTarget().pickCrossToolchain().setEnvs().setBypassArgs();
+        return this.exec();
+    }
+    ensureTarget() {
+        if (this.target.triple) ensureRustTarget(this.target.triple);
+        return this;
+    }
+    pickCrossToolchain() {
+        if (false === this.options.useNapiCrossToolChain) return this;
+        if (!this.target.triple.includes('linux')) {
+            if (true === this.options.useNapiCrossToolChain) build_debug.warn(`Skipping @napi-rs/cross-toolchain because target ${this.target.triple} is not Linux.`);
+            return this;
+        }
+        if (this.options.useCross) build_debug.warn('You are trying to use both `useCross` and `useNapiCross` options, `useCross` will be ignored.');
+        if (this.options.crossCompile) build_debug.warn('You are trying to use both `crossCompile` and `useNapiCross` options, `crossCompile` will be ignored.');
+        try {
+            const { version, download } = build_require('@napi-rs/cross-toolchain');
+            const alias = {
+                's390x-unknown-linux-gnu': 's390x-ibm-linux-gnu'
+            };
+            const toolchainPath = join(homedir(), '.napi-rs', 'cross-toolchain', version, this.target.triple);
+            mkdirSync(toolchainPath, {
+                recursive: true
+            });
+            if (existsSync(join(toolchainPath, 'package.json'))) build_debug(`Toolchain ${toolchainPath} exists, skip extracting`);
+            else {
+                const tarArchive = download(process.arch, this.target.triple);
+                tarArchive.unpack(toolchainPath);
+            }
+            const upperCaseTarget = targetToEnvVar(this.target.triple);
+            const crossTargetName = alias[this.target.triple] ?? this.target.triple;
+            const linkerEnv = `CARGO_TARGET_${upperCaseTarget}_LINKER`;
+            this.setEnvIfNotExists(linkerEnv, join(toolchainPath, 'bin', `${crossTargetName}-gcc`));
+            this.setEnvIfNotExists('TARGET_SYSROOT', join(toolchainPath, crossTargetName, 'sysroot'));
+            this.setEnvIfNotExists('TARGET_AR', join(toolchainPath, 'bin', `${crossTargetName}-ar`));
+            this.setEnvIfNotExists('TARGET_RANLIB', join(toolchainPath, 'bin', `${crossTargetName}-ranlib`));
+            this.setEnvIfNotExists('TARGET_READELF', join(toolchainPath, 'bin', `${crossTargetName}-readelf`));
+            this.setEnvIfNotExists('TARGET_C_INCLUDE_PATH', join(toolchainPath, crossTargetName, 'sysroot', 'usr', 'include/'));
+            this.setEnvIfNotExists('TARGET_CC', join(toolchainPath, 'bin', `${crossTargetName}-gcc`));
+            this.setEnvIfNotExists('TARGET_CXX', join(toolchainPath, 'bin', `${crossTargetName}-g++`));
+            this.envs[`CXX_${upperCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-g++`);
+            const snakeCaseTarget = this.target.triple.replace(/-/g, '_');
+            this.envs[`CC_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-gcc`);
+            this.envs[`CXX_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-g++`);
+            this.envs[`AR_${snakeCaseTarget}`] = join(toolchainPath, 'bin', `${crossTargetName}-ar`);
+            this.setEnvIfNotExists('BINDGEN_EXTRA_CLANG_ARGS', `--sysroot=${this.envs.TARGET_SYSROOT}`);
+            if (process.env.TARGET_CC?.startsWith('clang') || process.env.CC?.startsWith('clang') && !process.env.TARGET_CC) {
+                const TARGET_CFLAGS = process.env.TARGET_CFLAGS ?? '';
+                this.envs.TARGET_CFLAGS = `--sysroot=${this.envs.TARGET_SYSROOT} --gcc-toolchain=${toolchainPath} ${TARGET_CFLAGS}`;
+            }
+            if (process.env.CXX?.startsWith('clang++') && !process.env.TARGET_CXX || process.env.TARGET_CXX?.startsWith('clang++')) {
+                const TARGET_CXXFLAGS = process.env.TARGET_CXXFLAGS ?? '';
+                this.envs.TARGET_CXXFLAGS = `--sysroot=${this.envs.TARGET_SYSROOT} --gcc-toolchain=${toolchainPath} ${TARGET_CXXFLAGS}`;
+            }
+            this.envs.PATH = this.envs.PATH ? `${toolchainPath}/bin:${this.envs.PATH}:${process.env.PATH}` : `${toolchainPath}/bin:${process.env.PATH}`;
+        } catch (e) {
+            build_debug.warn('Pick cross toolchain failed', e);
+        }
+        return this;
+    }
+    pickBinary() {
+        if (this.options.crossCompile) if ('win32' === this.target.platform) if ('win32' === process.platform) build_debug.warn('You are trying to cross compile to win32 platform on win32 platform which is unnecessary.');
+        else {
+            build_debug('Use %i', 'cargo-xwin');
+            tryInstallCargoBinary('cargo-xwin', 'xwin');
+            this.args.push('xwin', 'build');
+            if ('ia32' === this.target.arch) this.envs.XWIN_ARCH = 'x86';
+            return this;
+        }
+        else if ('linux' === this.target.platform && 'linux' === process.platform && this.target.arch === process.arch && function(abi) {
+            const glibcVersionRuntime = process.report?.getReport()?.header?.glibcVersionRuntime;
+            const libc = glibcVersionRuntime ? 'gnu' : 'musl';
+            return abi === libc;
+        }(this.target.abi)) build_debug.warn('You are trying to cross compile to linux target on linux platform which is unnecessary.');
+        else if ('darwin' === this.target.platform && 'darwin' === process.platform) build_debug.warn('You are trying to cross compile to darwin target on darwin platform which is unnecessary.');
+        else {
+            build_debug('Use %i', 'cargo-zigbuild');
+            tryInstallCargoBinary('cargo-zigbuild', 'zigbuild');
+            this.args.push('zigbuild');
+            return this;
+        }
+        this.args.push('build');
+        return this;
+    }
+    setPackage() {
+        const args = [];
+        if (this.options.package) args.push('--package', this.options.package);
+        if (this.options.bin) args.push('--bin', this.options.bin);
+        if (args.length) {
+            build_debug('Set package flags: ');
+            build_debug('  %O', args);
+            this.args.push(...args);
+        }
+        return this;
+    }
+    setTarget() {
+        build_debug('Set compiling target to: ');
+        build_debug('  %i', this.target.triple);
+        this.args.push('--target', this.target.triple);
+        return this;
+    }
+    setEnvs() {
+        let rustflags = process.env.RUSTFLAGS ?? process.env.CARGO_BUILD_RUSTFLAGS ?? '';
+        if (this.target.abi?.includes('musl') && !rustflags.includes('target-feature=-crt-static')) rustflags += ' -C target-feature=-crt-static';
+        if (this.options.strip && !rustflags.includes('link-arg=-s')) rustflags += ' -C link-arg=-s';
+        if (rustflags.length) this.envs.RUSTFLAGS = rustflags;
+        const linker = this.options.crossCompile ? void 0 : getTargetLinker(this.target.triple);
+        const linkerEnv = `CARGO_TARGET_${targetToEnvVar(this.target.triple)}_LINKER`;
+        if (linker && !process.env[linkerEnv] && !this.envs[linkerEnv]) this.envs[linkerEnv] = linker;
+        if ('android' === this.target.platform) this.setAndroidEnv();
+        if ('wasi' === this.target.platform) this.setWasiEnv();
+        if ('openharmony' === this.target.platform) this.setOpenHarmonyEnv();
+        if (this.options.env) Object.assign(this.envs, this.options.env);
+        build_debug('Set envs: ');
+        Object.entries(this.envs).forEach(([k, v])=>{
+            build_debug('  %i', `${k}=${v}`);
+        });
+        return this;
+    }
+    setAndroidEnv() {
+        const { ANDROID_NDK_LATEST_HOME } = process.env;
+        if (!ANDROID_NDK_LATEST_HOME) build_debug.warn(`${red('ANDROID_NDK_LATEST_HOME')} environment variable is missing`);
+        if ('android' === process.platform) return;
+        const targetArch = 'arm' === this.target.arch ? 'armv7a' : 'aarch64';
+        const targetPlatform = 'arm' === this.target.arch ? 'androideabi24' : 'android24';
+        const hostPlatform = 'darwin' === process.platform ? 'darwin' : 'win32' === process.platform ? 'windows' : 'linux';
+        Object.assign(this.envs, {
+            CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-android24-clang`,
+            CARGO_TARGET_ARMV7_LINUX_ANDROIDEABI_LINKER: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-androideabi24-clang`,
+            TARGET_CC: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-${targetPlatform}-clang`,
+            TARGET_CXX: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/${targetArch}-linux-${targetPlatform}-clang++`,
+            TARGET_AR: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/llvm-ar`,
+            TARGET_RANLIB: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin/llvm-ranlib`,
+            ANDROID_NDK: ANDROID_NDK_LATEST_HOME,
+            PATH: `${ANDROID_NDK_LATEST_HOME}/toolchains/llvm/prebuilt/${hostPlatform}-x86_64/bin${'win32' === process.platform ? ';' : ':'}${process.env.PATH}`
+        });
+    }
+    setWasiEnv() {
+        const { WASI_SDK_PATH } = process.env;
+        if (WASI_SDK_PATH && existsSync(WASI_SDK_PATH)) {
+            this.envs.CARGO_TARGET_WASM32_WASI_PREVIEW1_THREADS_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP1_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP1_THREADS_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.envs.CARGO_TARGET_WASM32_WASIP2_LINKER = join(WASI_SDK_PATH, 'bin', 'wasm-ld');
+            this.setEnvIfNotExists('TARGET_CC', join(WASI_SDK_PATH, 'bin', 'clang'));
+            this.setEnvIfNotExists('TARGET_CXX', join(WASI_SDK_PATH, 'bin', 'clang++'));
+            this.setEnvIfNotExists('TARGET_AR', join(WASI_SDK_PATH, 'bin', 'ar'));
+            this.setEnvIfNotExists('TARGET_RANLIB', join(WASI_SDK_PATH, 'bin', 'ranlib'));
+            this.setEnvIfNotExists('TARGET_CFLAGS', `--target=wasm32-wasi-threads --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot -pthread -mllvm -wasm-enable-sjlj`);
+            this.setEnvIfNotExists('TARGET_CXXFLAGS', `--target=wasm32-wasi-threads --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot -pthread -mllvm -wasm-enable-sjlj`);
+            this.setEnvIfNotExists("TARGET_LDFLAGS", `-fuse-ld=${WASI_SDK_PATH}/bin/wasm-ld --target=wasm32-wasi-threads`);
+        }
+    }
+    setOpenHarmonyEnv() {
+        const { OHOS_SDK_PATH, OHOS_SDK_NATIVE } = process.env;
+        const ndkPath = OHOS_SDK_PATH ? `${OHOS_SDK_PATH}/native` : OHOS_SDK_NATIVE;
+        if (!ndkPath && 'openharmony' !== process.platform) return void build_debug.warn(`${red('OHOS_SDK_PATH')} or ${red('OHOS_SDK_NATIVE')} environment variable is missing`);
+        const linkerName = `CARGO_TARGET_${this.target.triple.toUpperCase().replace(/-/g, '_')}_LINKER`;
+        const ranPath = `${ndkPath}/llvm/bin/llvm-ranlib`;
+        const arPath = `${ndkPath}/llvm/bin/llvm-ar`;
+        const ccPath = `${ndkPath}/llvm/bin/${this.target.triple}-clang`;
+        const cxxPath = `${ndkPath}/llvm/bin/${this.target.triple}-clang++`;
+        const asPath = `${ndkPath}/llvm/bin/llvm-as`;
+        const ldPath = `${ndkPath}/llvm/bin/ld.lld`;
+        const stripPath = `${ndkPath}/llvm/bin/llvm-strip`;
+        const objDumpPath = `${ndkPath}/llvm/bin/llvm-objdump`;
+        const objCopyPath = `${ndkPath}/llvm/bin/llvm-objcopy`;
+        const nmPath = `${ndkPath}/llvm/bin/llvm-nm`;
+        const binPath = `${ndkPath}/llvm/bin`;
+        const libPath = `${ndkPath}/llvm/lib`;
+        this.setEnvIfNotExists('LIBCLANG_PATH', libPath);
+        this.setEnvIfNotExists('DEP_ATOMIC', 'clang_rt.builtins');
+        this.setEnvIfNotExists(linkerName, ccPath);
+        this.setEnvIfNotExists('TARGET_CC', ccPath);
+        this.setEnvIfNotExists('TARGET_CXX', cxxPath);
+        this.setEnvIfNotExists('TARGET_AR', arPath);
+        this.setEnvIfNotExists('TARGET_RANLIB', ranPath);
+        this.setEnvIfNotExists('TARGET_AS', asPath);
+        this.setEnvIfNotExists('TARGET_LD', ldPath);
+        this.setEnvIfNotExists('TARGET_STRIP', stripPath);
+        this.setEnvIfNotExists('TARGET_OBJDUMP', objDumpPath);
+        this.setEnvIfNotExists('TARGET_OBJCOPY', objCopyPath);
+        this.setEnvIfNotExists('TARGET_NM', nmPath);
+        this.envs.PATH = `${binPath}${'win32' === process.platform ? ';' : ':'}${process.env.PATH}`;
+    }
+    setFeatures() {
+        const args = [];
+        if (this.options.allFeatures && this.options.noDefaultFeatures) throw new Error('Cannot specify --all-features and --no-default-features together');
+        if (this.options.allFeatures) args.push('--all-features');
+        else if (this.options.noDefaultFeatures) args.push('--no-default-features');
+        if (this.options.features) args.push('--features', ...this.options.features);
+        build_debug('Set features flags: ');
+        build_debug('  %O', args);
+        this.args.push(...args);
+        return this;
+    }
+    setBypassArgs() {
+        if (this.options.release) this.args.push('--release');
+        if (this.options.verbose) this.args.push('--verbose');
+        if (this.options.targetDir) this.args.push('--target-dir', this.options.targetDir);
+        if (this.options.profile) this.args.push('--profile', this.options.profile);
+        if (this.options.manifestPath) this.args.push('--manifest-path', this.options.manifestPath);
+        if (this.options.cargoArgs?.length) this.args.push(...this.options.cargoArgs);
+        return this;
+    }
+    async exec() {
+        build_debug('Start cross-building');
+        build_debug('  %i', `cargo ${this.args.join(' ')}`);
+        if (this.options.useCross && this.options.crossCompile) throw new Error('`useCross` and `crossCompile` cannot be used together');
+        const command = process.env.CARGO ?? (this.options.useCross ? 'cross' : 'cargo');
+        return new Promise((resolve, reject)=>{
+            const buildProcess = spawn(command, this.args, {
+                env: {
+                    ...process.env,
+                    ...this.envs
+                },
+                stdio: 'inherit',
+                cwd: this.cwd
+            });
+            buildProcess.once('exit', (code)=>{
+                if (0 === code) {
+                    build_debug('%i', 'Build completed successfully!');
+                    resolve({
+                        success: true,
+                        target: this.target,
+                        envs: {
+                            ...this.envs
+                        }
+                    });
+                } else reject(new Error(`Build failed with exit code ${code}`));
+            });
+            buildProcess.once('error', (e)=>{
+                reject(new Error(`Build failed with error: ${e.message}`, {
+                    cause: e
+                }));
+            });
+        });
+    }
+    setEnvIfNotExists(env, value) {
+        if (!process.env[env]) this.envs[env] = value;
+    }
+}
+export { TARGET_LINKER, build, log_debug as debug, debugFactory, getCrossCompileEnv, getSystemDefaultTarget, getTargetLinker, parseTriple, targetToEnvVar, tryInstallCargoBinary };

package/dist/log.d.ts

@@ -0,0 +1,9 @@
+declare module 'obug' {
+    interface Debugger {
+        info: typeof console.error;
+        warn: typeof console.error;
+        error: typeof console.error;
+    }
+}
+export declare const debugFactory: (namespace: string) => import("obug").Debugger;
+export declare const debug: import("obug").Debugger;

package/dist/target.d.ts

@@ -0,0 +1,25 @@
+export type Platform = NodeJS.Platform | 'wasm' | 'wasi' | 'openharmony';
+type NodeJSArch = 'arm' | 'arm64' | 'ia32' | 'loong64' | 'mips' | 'mipsel' | 'ppc' | 'ppc64' | 'riscv64' | 's390' | 's390x' | 'x32' | 'x64' | 'universal' | 'wasm32';
+export declare const TARGET_LINKER: Record<string, string>;
+export interface Target {
+    triple: string;
+    platformArchABI: string;
+    platform: Platform;
+    arch: NodeJSArch;
+    abi: string | null;
+}
+/**
+ * A triple is a specific format for specifying a target architecture.
+ * Triples may be referred to as a target triple which is the architecture for the artifact produced, and the host triple which is the architecture that the compiler is running on.
+ * The general format of the triple is `<arch><sub>-<vendor>-<sys>-<abi>` where:
+ *   - `arch` = The base CPU architecture, for example `x86_64`, `i686`, `arm`, `thumb`, `mips`, etc.
+ *   - `sub` = The CPU sub-architecture, for example `arm` has `v7`, `v7s`, `v5te`, etc.
+ *   - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `nvidia`, etc.
+ *   - `sys` = The system name, for example `linux`, `windows`, `darwin`, etc. none is typically used for bare-metal without an OS.
+ *   - `abi` = The ABI, for example `gnu`, `android`, `eabi`, etc.
+ */
+export declare function parseTriple(rawTriple: string): Target;
+export declare function getSystemDefaultTarget(): Target;
+export declare function getTargetLinker(target: string): string | undefined;
+export declare function targetToEnvVar(target: string): string;
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xspect-build/cross-build",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "cross-build": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "check": "biome check --write",
+    "dev": "rslib build --watch",
+    "format": "biome format --write",
+    "test": "rstest"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@rslib/core": "^0.18.6",
+    "@rstest/core": "^0.7.5",
+    "@types/node": "^24.10.4",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@napi-rs/cross-toolchain": "^1.0.3",
+    "cac": "^6.7.14",
+    "colorette": "^2.0.20",
+    "obug": "^2.1.1"
+  }
+}