IF Commons GitHub

compile

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-013

A program built into one binary with the pinned Bun (commons 0001-system FR-013): bun build --compile, for this computer or for a target given (linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64), with the files it embeds, giving the binary's path and SHA-256. Bun is found as bun on PATH, or given by its path; where an expected version is given, a Bun of another version is refused, so a build is made only by the pinned one. Everything that can go wrong is a CompileError in a Result.

The argument vector is made by compileArgv, a pure function, so what is asked of Bun can be checked without running it; a program built this way runs itself again with proc.selfCommand() (FR-053).

import { compile } from "./compile.ts";
const r = await compile({ entry: "src/main.ts", outfile: "dist/tool", target: "windows-x64" });
if (r.kind === "ok") console.log(r.value.path, r.value.sha256); // dist/tool.exe, its SHA-256

Source: commons/system/src/compile.ts

21 of 23 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

compilenamespace
namespace compile
compile.Targettype
type Target = "linux-x64" | "linux-arm64" | "darwin-x64" | "darwin-arm64" | "windows-x64";

A system Bun builds a binary for.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.TARGETSconst
const TARGETS: readonly Target[]

Every target, in a fixed order.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.targetOffunction
function targetOf(os: Os, arch: Arch): Target | undefined

The target of a system, by proc.build's names; undefined where Bun builds for no such system.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.hostTargetfunction
function hostTarget(): Target | undefined

The target of this computer; undefined where Bun builds for no such system.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.isWindowsfunction
function isWindows(target: Target): boolean

Whether a target's binaries are Windows programs, named with .exe.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.CompileOptionstype
type CompileOptions = { /** The program's entry point (a `.ts` or `.js` file). */ readonly entry: string; /** Wher… (1011 characters)
type CompileOptions = {
  /** The program's entry point (a `.ts` or `.js` file). */
  readonly entry: string;
  /** Where the binary goes; `.exe` is added for Windows where it is not there, as Bun adds it. */
  readonly outfile: string;
  /** The system to build for; this computer where it is not given. */
  readonly target?: Target;
  /** Files embedded in the binary, beside the code its imports bring in. */
  readonly files?: readonly string[];
  /** Bun's path; `bun` on `PATH` where it is not given. */
  readonly bun?: string;
  /** The version Bun must be (the pin, such as `1.4.4`); any version where it is not given. */
  readonly bunVersion?: string;
  /** The folder the build runs in, against which relative paths are read; the process's working folder by default. */
  readonly cwd?: string;
  /** More of `bun build`'s options, put before the entry point (`--minify`, `--define=...`). */
  readonly extraArgs?: readonly string[];
  /** Stopping the build. */
  readonly signal?: AbortSignal;
};

What to build.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.Compiledtype
type Compiled = {
  /** Its path, absolute. */
  readonly path: string;
  /** Its SHA-256. */
  readonly sha256: Sha256;
  /** The system it is for. */
  readonly target: Target;
  /** The version of Bun that built it. */
  readonly bunVersion: string;
};

A binary built.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.CompileErrortype
type CompileError =
  | { readonly kind: "no-bun"; readonly message: string }
  | { readonly kind: "wrong-bun"; readonly expected: string; readonly found: string }
  | { readonly kind: "no-target"; readonly message: string }
  | { readonly kind: "failed"; readonly code: number; readonly stderr: string }
  | { readonly kind: "no-binary"; readonly path: string };

Why a binary was not built.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.describeCompileErrorfunction
function describeCompileError(e: CompileError): string

A sentence for a CompileError.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.binaryPathfunction
function binaryPath(outfile: string, target: Target): string

The binary's path for a target: outfile, with .exe added for Windows where it is not there.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.compileArgvfunction
function compileArgv(bun: string, options: CompileOptions, outfile: string): readonly string[]

The argument vector that builds the binary (pure): bun build --compile [--target=bun-<target>] --outfile=<path> [extra...] <entry> [files...]. A target is named only where one is given; without it Bun builds for the computer it runs on. The files after the entry point are embedded in the binary.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compile.compilefunction
function compile(options: CompileOptions): Promise<Result<Compiled, CompileError>>

Builds a program into one binary with Bun (FR-062) and gives its path and SHA-256; a CompileError where it cannot.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Targettype
type Target = "linux-x64" | "linux-arm64" | "darwin-x64" | "darwin-arm64" | "windows-x64";

A system Bun builds a binary for.

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

TARGETSconst
const TARGETS: readonly Target[]

Every target, in a fixed order.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

targetOffunction
function targetOf(os: Os, arch: Arch): Target | undefined

The target of a system, by proc.build's names; undefined where Bun builds for no such system.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

hostTargetfunction
function hostTarget(): Target | undefined

The target of this computer; undefined where Bun builds for no such system.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

isWindowsfunction
function isWindows(target: Target): boolean

Whether a target's binaries are Windows programs, named with .exe.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

CompileOptionstypeno test imports it
type CompileOptions = { /** The program's entry point (a `.ts` or `.js` file). */ readonly entry: string; /** Wher… (1011 characters)
type CompileOptions = {
  /** The program's entry point (a `.ts` or `.js` file). */
  readonly entry: string;
  /** Where the binary goes; `.exe` is added for Windows where it is not there, as Bun adds it. */
  readonly outfile: string;
  /** The system to build for; this computer where it is not given. */
  readonly target?: Target;
  /** Files embedded in the binary, beside the code its imports bring in. */
  readonly files?: readonly string[];
  /** Bun's path; `bun` on `PATH` where it is not given. */
  readonly bun?: string;
  /** The version Bun must be (the pin, such as `1.4.4`); any version where it is not given. */
  readonly bunVersion?: string;
  /** The folder the build runs in, against which relative paths are read; the process's working folder by default. */
  readonly cwd?: string;
  /** More of `bun build`'s options, put before the entry point (`--minify`, `--define=...`). */
  readonly extraArgs?: readonly string[];
  /** Stopping the build. */
  readonly signal?: AbortSignal;
};

What to build.

Compiledtypeno test imports it
type Compiled = {
  /** Its path, absolute. */
  readonly path: string;
  /** Its SHA-256. */
  readonly sha256: Sha256;
  /** The system it is for. */
  readonly target: Target;
  /** The version of Bun that built it. */
  readonly bunVersion: string;
};

A binary built.

CompileErrortype
type CompileError =
  | { readonly kind: "no-bun"; readonly message: string }
  | { readonly kind: "wrong-bun"; readonly expected: string; readonly found: string }
  | { readonly kind: "no-target"; readonly message: string }
  | { readonly kind: "failed"; readonly code: number; readonly stderr: string }
  | { readonly kind: "no-binary"; readonly path: string };

Why a binary was not built.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

describeCompileErrorfunction
function describeCompileError(e: CompileError): string

A sentence for a CompileError.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

binaryPathfunction
function binaryPath(outfile: string, target: Target): string

The binary's path for a target: outfile, with .exe added for Windows where it is not there.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

compileArgvfunction
function compileArgv(bun: string, options: CompileOptions, outfile: string): readonly string[]

The argument vector that builds the binary (pure): bun build --compile [--target=bun-<target>] --outfile=<path> [extra...] <entry> [files...]. A target is named only where one is given; without it Bun builds for the computer it runs on. The files after the entry point are embedded in the binary.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.