Skip to content
Closed
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions scripts/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -448,6 +448,7 @@ function parseArgs(argv: string[]): CliArgs {
"unifiedSources",
"archiveDeps",
"timeTrace",
"exceptionLint",
"ci",
"buildkite",
]);
Expand Down Expand Up @@ -593,6 +594,9 @@ Options:
vendored dep from a local checkout),
buildDir, mode (full|cpp-only|link-only),
unifiedSources, timeTrace, os, arch, abi,
exceptionLint (the jsc-exception-lint
compiler plugin; on in assertion builds
when clang's dev headers are installed),
winsysroot (Windows cross-compile SDK root)
--target=<name> Build a specific ninja target (repeatable)
--configure-only Emit build.ninja, don't run it
Expand Down
1 change: 1 addition & 0 deletions scripts/build/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,7 @@ Split CI modes: `rust-only` (path deps+codegen+cargo → libbun_runtime.a), `cpp
| `cargo-config.ts` | Generates the git-ignored `.cargo/config.toml` (per-target `linker` from `cfg.hostCxx`) |
| `bun.ts` | `emitBun()` — assembles deps+codegen+rust+compile+link |
| `shims.ts` | Platform/toolchain workaround dylibs, `emitShims()` |
| `exception-lint.ts` | jsc-exception-lint clang plugin: its build edge and the flags bun's cxx edges load it with, `emitExceptionLint()` |
| `workarounds.ts` | Self-obsoleting workaround registry, `checkWorkarounds()` |
| `macos-sdk.ts` | macOS SDK resolution/download for darwin cross-compiles — `resolveMacosSdkPath()`, `ensureMacosSdk()` |
| `features-json.ts` | Host-side `features.json` for cross lanes — `parsePackedFeaturesList()`, `crossFeaturesJson()` |
Expand Down
10 changes: 10 additions & 0 deletions scripts/build/bun.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ import { allDeps } from "./deps/index.ts";
import { lolhtml } from "./deps/lolhtml.ts";
import { rustArgon2 } from "./deps/rust-argon2.ts";
import { assert } from "./error.ts";
import { emitExceptionLint } from "./exception-lint.ts";
import { bunIncludes, computeFlags, extraFlagsFor, linkDepends, linkerMapOutputs } from "./flags.ts";
import { writeIfChanged } from "./fs.ts";
import type { BuildNode, Ninja } from "./ninja.ts";
Expand Down Expand Up @@ -384,6 +385,11 @@ export function emitBun(n: Ninja, cfg: Config, sources: Sources): BunOutput {
});
}

// jsc-exception-lint runs inside each of these compiles as a clang plugin
// (exception-lint.ts). Not on the PCH: it only has declarations to look
// at, and a PCH built without the plugin is valid for a TU built with it.
const lint = emitExceptionLint(n, cfg);

const cxxObjects: string[] = [];
for (const src of cxxSources) {
const relSrc = relative(cfg.cwd, src);
Expand All @@ -402,6 +408,10 @@ export function emitBun(n: Ninja, cfg: Config, sources: Sources): BunOutput {
opts.implicitInputs = depHeaderSignal;
opts.orderOnlyInputs = codegenOrderOnly;
}
if (lint !== undefined) {
opts.ninjaOnlyFlags = lint.flags;
opts.implicitInputs = [...(opts.implicitInputs ?? []), ...lint.implicitInputs];
}
cxxObjects.push(cxx(n, cfg, src, opts));
}

Expand Down
10 changes: 9 additions & 1 deletion scripts/build/compile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,14 @@ export function registerCompileRules(n: Ninja, cfg: Config): void {
export interface CompileOpts {
/** Compiler flags (including -I, -D — caller assembles). */
flags: string[];
/**
* Flags for the ninja command only, left out of compile_commands.json.
* For compiler plugins: clangd would try to load them, and the
* standalone jsc-exception-lint tool parses the compile database itself.
* Paths in here are buildDir-relative (the caller's job) so ccache keys
* are the same in every checkout.
*/
ninjaOnlyFlags?: string[];
/** PCH to use (absolute path to .pch/.gch output). */
pch?: string;
/** Original header the PCH was built from (needed for clang-cl /Yu). */
Expand Down Expand Up @@ -295,7 +303,7 @@ function compile(n: Ninja, cfg: Config, src: string, opts: CompileOpts, lang: "c

const implicitInputs: string[] = [...(opts.implicitInputs ?? [])];
const vars: Record<string, string> = {
[flagVar]: opts.flags.join(" "),
[flagVar]: [...opts.flags, ...(opts.ninjaOnlyFlags ?? [])].join(" "),
};

// PCH is always an implicit dep — if it changes, recompile.
Expand Down
53 changes: 52 additions & 1 deletion scripts/build/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import { NODEJS_ABI_VERSION, NODEJS_V8_VERSION, NODEJS_VERSION } from "./deps/no
import { WEBKIT_VERSION } from "./deps/webkit.ts";
import { assert, BuildError } from "./error.ts";
import { resolveMacosSdkPath } from "./macos-sdk.ts";
import { clangTargetArch, toolchainOverride } from "./tools.ts";
import { clangTargetArch, findLlvmDevDir, toolchainOverride } from "./tools.ts";
import { cyan, dim, green } from "./tty.ts";

export type OS = "linux" | "darwin" | "windows" | "freebsd";
Expand Down Expand Up @@ -158,6 +158,14 @@ export interface Config {
archiveDeps: boolean;
/** Emit clang -ftime-trace .json next to each .o for build profiling. */
timeTrace: boolean;
/**
* Load the jsc-exception-lint compiler plugin into every compile of bun's
* own C++ (scripts/jsc-exception-lint). A missing JSC exception check is a
* compile error. Default: on in assertion builds (debug, asan) when
* `llvmDevDir` is found and the target is not Windows (clang-cl does not
* load plugins). See resolveConfig for why assertion builds only.
*/
exceptionLint: boolean;

// ─── Environment ───
ci: boolean;
Expand Down Expand Up @@ -209,6 +217,14 @@ export interface Config {
* explicitly. undefined on Windows (nothing consumes it there).
*/
clangResourceDir: string | undefined;
/**
* Root of the host LLVM install that has the clang development headers
* (`include/clang/Frontend/FrontendPluginRegistry.h`) and libclang-cpp.
* Compiler plugins are built against it. undefined when the distro's dev
* package is not installed (apt: libclang-<N>-dev + libclang-cpp<N>-dev,
* both in `llvm.sh <N> all`; brew: part of llvm) or on Windows.
*/
llvmDevDir: string | undefined;
ar: string;
/** llvm-ranlib. undefined on windows (llvm-lib indexes itself). */
ranlib: string | undefined;
Expand Down Expand Up @@ -341,6 +357,7 @@ export interface PartialConfig {
unifiedSources?: boolean;
archiveDeps?: boolean;
timeTrace?: boolean;
exceptionLint?: boolean;
ci?: boolean;
buildkite?: boolean;
webkit?: WebKitMode;
Expand Down Expand Up @@ -1150,6 +1167,38 @@ export function resolveConfig(partial: PartialConfig, toolchain: Toolchain): Con
}
}

// ─── jsc-exception-lint compiler plugin ───
// The plugin is built for the host against the host LLVM's clang headers
// and loaded into the same clang. clang-cl (windows targets) has no plugin
// interface, and Windows LLVM exports no symbols for one to bind to.
//
// Assertion builds only: the check models the ThrowScope validator, which
// exists under ASSERT_ENABLED. Without it ThrowScope has a trivial
// destructor, so a function that returns with an unchecked exception has
// no destructor in its CFG for the analysis to report at, and the result
// would depend on the build type. The CI asan lane and every `bun bd`
// build have assertions on.
const llvmDevDir =
host.os === "windows" || windows
? undefined
: findLlvmDevDir(toolchain.hostCxx ?? toolchain.cxx, toolchain.clangResourceDir);
const exceptionLint = partial.exceptionLint ?? (llvmDevDir !== undefined && assertions);
if (exceptionLint && llvmDevDir === undefined) {
throw new BuildError("--exceptionLint=on needs the clang development headers", {
hint:
host.os === "windows" || windows
? "The plugin does not work with clang-cl. Build with --exceptionLint=off."
: host.os === "darwin"
? "brew's llvm ships them; the toolchain in use does not (include/clang/Frontend/FrontendPluginRegistry.h is missing next to clang++)."
: "apt: install libclang-<N>-dev and libclang-cpp<N>-dev for your clang (llvm.sh <N> all installs both).",
});
}
if (exceptionLint && !assertions) {
throw new BuildError("--exceptionLint=on needs --assertions=on", {
hint: "Without ASSERT_ENABLED the ThrowScope destructor is trivial, so the check cannot see a function that returns with an unchecked exception.",
});
}

return {
os,
arch,
Expand Down Expand Up @@ -1190,6 +1239,7 @@ export function resolveConfig(partial: PartialConfig, toolchain: Toolchain): Con
unifiedSources: partial.unifiedSources ?? true,
archiveDeps: partial.archiveDeps ?? false,
timeTrace: partial.timeTrace ?? false,
exceptionLint,
ci,
buildkite,
webkit: partial.webkit ?? "prebuilt",
Expand All @@ -1205,6 +1255,7 @@ export function resolveConfig(partial: PartialConfig, toolchain: Toolchain): Con
hostCxx: toolchain.hostCxx ?? toolchain.cxx,
clangVersion: toolchain.clangVersion,
clangResourceDir: toolchain.clangResourceDir,
llvmDevDir,
ar: toolchain.ar,
ranlib: toolchain.ranlib,
ld: ld64StripSwap?.ld ?? ld,
Expand Down
10 changes: 9 additions & 1 deletion scripts/build/configure.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import {
resolveConfig,
} from "./config.ts";
import { BuildError } from "./error.ts";
import { exceptionLintConfigureInputs } from "./exception-lint.ts";
import { orderFilePath, usesOrderFile } from "./flags.ts";
import { mkdirAll, writeIfChanged } from "./fs.ts";
import { ensureMacosSdk } from "./macos-sdk.ts";
Expand Down Expand Up @@ -125,7 +126,14 @@ function configureInputs(cwd: string): string[] {
.map(f => resolve(buildDir, f));
const deps = globSync("deps/*.ts", { cwd: buildDir }).map(f => resolve(buildDir, f));

return [...scripts, ...deps, resolve(cwd, "scripts", "glob-sources.ts"), resolve(cwd, "package.json")].sort();
return [
...scripts,
...deps,
resolve(cwd, "scripts", "glob-sources.ts"),
resolve(cwd, "package.json"),
// Their digest is a compiler flag (data-hash=, see exception-lint.ts).
...exceptionLintConfigureInputs(cwd),
].sort();
}

/**
Expand Down
176 changes: 176 additions & 0 deletions scripts/build/exception-lint.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
/**
* jsc-exception-lint as a compiler plugin.
*
* scripts/jsc-exception-lint/jsc-exception-lint.cpp checks that native code
* tests for a pending JavaScriptCore exception before it calls into JSC
* again or returns from a ThrowScope (what BUN_JSC_validateExceptionChecks=1
* asserts at run time, but for every path, at compile time). Built with
* -DJSC_EXCEPTION_LINT_PLUGIN it is a clang plugin: every cxx edge for bun's
* own sources loads it with -fplugin, it runs on the AST the compile already
* has, and a finding is a compile error. The analysis is a few tens of
* milliseconds per translation unit. See scripts/jsc-exception-lint/README.md.
*
* Inputs the plugin reads at run time (all under scripts/jsc-exception-lint):
* nothrow.txt hand-written classifications
* summaries/webkit.tsv how each JavaScriptCore function treats the
* summaries/bun.tsv exception state, computed by run.ts
* baseline.tsv findings tolerated while they are being fixed
*
* They are implicit inputs of every cxx edge, and a digest of them is passed
* as a plugin argument so ccache (which hashes the command line and the
* plugin binary, not what the plugin opens) misses when they change.
*/

import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, relative, resolve } from "node:path";
import type { Config } from "./config.ts";
import { assert } from "./error.ts";
import type { Ninja } from "./ninja.ts";
import { quote } from "./shell.ts";

const LINT_DIR = "scripts/jsc-exception-lint";
const PLUGIN_NAME = "jsc-exception-lint";

export interface ExceptionLintOpts {
/** For every cxx edge of bun's own sources. Ninja only, not compile_commands.json. */
flags: string[];
/** The plugin and its data files: a compile reruns when they change. */
implicitInputs: string[];
}

function lintSource(cwd: string): string {
return resolve(cwd, LINT_DIR, "jsc-exception-lint.cpp");
}

function lintDataFiles(cwd: string): { nothrow: string; summaries: string[]; baseline: string } {
return {
nothrow: resolve(cwd, LINT_DIR, "nothrow.txt"),
summaries: [resolve(cwd, LINT_DIR, "summaries/webkit.tsv"), resolve(cwd, LINT_DIR, "summaries/bun.tsv")],
baseline: resolve(cwd, LINT_DIR, "baseline.tsv"),
};
}

/**
* Everything `data-hash=` is computed from. These are also inputs of the
* regen rule (configure.ts): the hash is baked into build.ninja at configure
* time, so a direct `ninja` run after an edit to one of them has to
* reconfigure first, or ccache would answer the recompile from its cache
* with the old hash and the edit would never reach the plugin.
*/
export function exceptionLintConfigureInputs(cwd: string): string[] {
const data = lintDataFiles(cwd);
return [lintSource(cwd), data.nothrow, ...data.summaries, data.baseline];
}

/**
* The built plugin. The clang version is in the name: a plugin is bound to
* the exact LLVM it was built against, and an upgraded clang at the same
* path would otherwise pick up a stale one.
*/
export function exceptionLintPluginPath(cfg: Config): string {
const ext = cfg.host.os === "darwin" ? ".dylib" : ".so";
return resolve(cfg.buildDir, PLUGIN_NAME, `lib${PLUGIN_NAME}-${cfg.clangVersion ?? "unknown"}${ext}`);
}

/**
* Register the plugin build rule. Call once from rules.ts.
*/
export function registerExceptionLintRules(n: Ninja, cfg: Config): void {
if (!cfg.exceptionLint) return;
const q = (p: string) => quote(p, false);
// Compiled for the BUILD HOST (no --target/-isysroot) by the host clang++
// and loaded into the clang that compiles bun. The symbols it needs come
// from the compiler process at load time, so nothing is linked here;
// darwin needs -undefined dynamic_lookup to allow that, ELF allows it by
// default. The load test after the link turns "this LLVM cannot host
// plugins" into one clear error instead of one per translation unit.
const dynamicLookup = cfg.host.os === "darwin" ? " -Wl,-undefined,dynamic_lookup" : "";
n.rule("clang_plugin", {
command:
`${q(cfg.hostCxx)} $flags -MMD -MT $out -MF $out.d -shared${dynamicLookup} -o $out $in` +
` && (${q(cfg.cxx)} -fplugin=$out -fsyntax-only -x c++ /dev/null` +
` || (echo "${PLUGIN_NAME}: the plugin does not load into ${cfg.cxx}; build with --exceptionLint=off" >&2 && exit 1))`,
description: "clang-plugin $out",
depfile: "$out.d",
deps: "gcc",
});
}

/**
* Emit the plugin build edge. Returns the flags and implicit inputs every
* cxx edge of bun's own sources needs, or undefined when the lint is off.
*/
export function emitExceptionLint(n: Ninja, cfg: Config): ExceptionLintOpts | undefined {
if (!cfg.exceptionLint) return undefined;
assert(cfg.llvmDevDir !== undefined, "exceptionLint is on without an LLVM dev dir (resolveConfig checks this)");

const plugin = exceptionLintPluginPath(cfg);
const data = lintDataFiles(cfg.cwd);

// Output dirs are created at configure time, like the object dirs
// (configure.ts mkdirAll only sees output.objects).
mkdirSync(dirname(plugin), { recursive: true });

n.comment("─── jsc-exception-lint plugin ───");
n.blank();
n.build({
outputs: [plugin],
rule: "clang_plugin",
inputs: [lintSource(cfg.cwd)],
vars: {
// Same flags as run.ts uses for the standalone tool, plus -fPIC and the
// plugin define. -fno-rtti/-fno-exceptions are what LLVM itself is
// built with (`llvm-config --cxxflags`); code that subclasses its
// types has to agree.
flags: [
"-std=c++17",
"-O2",
"-fno-rtti",
"-fno-exceptions",
"-fPIC",
`-I${cfg.llvmDevDir}/include`,
"-D_GNU_SOURCE",
"-D__STDC_CONSTANT_MACROS",
"-D__STDC_FORMAT_MACROS",
"-D__STDC_LIMIT_MACROS",
"-DJSC_EXCEPTION_LINT_PLUGIN",
].join(" "),
},
});
n.phony(`${PLUGIN_NAME}-plugin`, [plugin]);

// Digest of everything the plugin reads that ccache does not see. The
// plugin source is included too, so a rebuilt plugin misses the cache even
// if ccache's own hashing of -fplugin= files is ever turned off.
const hash = createHash("sha256");
for (const file of exceptionLintConfigureInputs(cfg.cwd)) {
assert(existsSync(file), `jsc-exception-lint input missing: ${relative(cfg.cwd, file)}`, {
hint: "The summaries are generated by `bun scripts/jsc-exception-lint/run.ts --update-summaries`; the other files are committed.",
});
hash.update(relative(cfg.cwd, file));
hash.update(readFileSync(file));
}
const dataHash = hash.digest("hex").slice(0, 16);

// Every path is relative to the build dir, where ninja runs the compiler,
// so the command line is identical in every checkout (ccache shares
// entries across worktrees through CCACHE_BASEDIR; an absolute path here
// would undo that). The plugin resolves `root` itself.
const rel = (p: string) => relative(cfg.buildDir, p);
const pluginArg = (arg: string) => ["-Xclang", `-plugin-arg-${PLUGIN_NAME}`, "-Xclang", arg];
const flags = [
`-fplugin=${rel(plugin)}`,
...pluginArg(`root=${rel(cfg.cwd)}`),
...pluginArg(`nothrow=${rel(data.nothrow)}`),
...data.summaries.flatMap(s => pluginArg(`import=${rel(s)}`)),
...pluginArg(`baseline=${rel(data.baseline)}`),
...pluginArg("werror"),
...pluginArg(`data-hash=${dataHash}`),
];

return {
flags,
implicitInputs: [plugin, data.nothrow, ...data.summaries, data.baseline],
Comment thread
robobun marked this conversation as resolved.
Resolved
};
}
4 changes: 4 additions & 0 deletions scripts/build/rules.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
import { registerCodegenRules } from "./codegen.ts";
import { registerCompileRules, registerDirStamps } from "./compile.ts";
import type { Config } from "./config.ts";
import { registerExceptionLintRules } from "./exception-lint.ts";
import type { Ninja } from "./ninja.ts";
import { registerRustRules } from "./rust.ts";
import { registerShimRules } from "./shims.ts";
Expand Down Expand Up @@ -54,4 +55,7 @@ export function registerAllRules(n: Ninja, cfg: Config): void {

// shim_dylib (darwin+asan only)
registerShimRules(n, cfg);

// clang_plugin (when cfg.exceptionLint)
registerExceptionLintRules(n, cfg);
}
Loading
Loading