Bytecode-only runtime optimization for QuickJS#5
Conversation
This commit introduces a "bytecode-only" runtime mode for QuickJS, which allows for aggressive removal of the parser and compiler from embedded runtimes when features like eval, JSON.parse, and RegExp compilation are disabled. Key changes: - qjsc automatically detects when -fno-eval, -fno-regexp, -fno-json, and -fno-module-loader are all provided, and defines JS_BYTECODE_ONLY_RUNTIME in generated C code. - Heavy parser/compiler entry points are gated with this macro and replaced with stubs that throw a TypeError. - New intrinsics JS_AddIntrinsicBaseObjectsBytecode and JS_AddIntrinsicPromiseBytecode provide a clean initialization path that maintains core object functionality (Array, Error, etc.) while disabling compiler-dependent constructors. - Compiler-dependent libc helpers in quickjs-libc.c are appropriately gated. - Code duplication in intrinsics was avoided via refactoring to shared internal functions. This results in approximately a 33% reduction in stripped binary size (from ~930KB to ~620KB) for a typical minimal configuration using LTO. Co-authored-by: yumin-chen <10954839+yumin-chen@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
|
Please add automated tests to ensure the bytecode-only runtime is functional => parser/compiler no longer bundled and no dynamic code execution -- while precompiled bytecode embeded are working as expected |
I have added automated tests for the bytecode-only mode in |
|
QuickJS currently bundles the full engine — including the parser and compiler — into every binary, even when the binary only needs to execute pre-compiled bytecode. This feature introduces a safe, aggressive mechanism to strip the parser and compiler from runtime-only binaries, producing smaller embedded footprints, while keeping the full dev toolchain (parser + compiler via The key insight already present in the codebase is that when all four flags are set simultaneously — Glossary
Please validate that your implmentation meets below: RequirementsRequirement 1: Bytecode-Only Trigger ConditionUser Story: As an embedder, I want the runtime binary to automatically exclude the Parser/Compiler when I disable all parser-invoking features, so that I get the smallest possible binary without manually managing compile-time flags. Acceptance Criteria
Requirement 2: Parser/Compiler Exclusion from Bytecode-Only RuntimeUser Story: As an embedder, I want the Parser/Compiler to be physically absent from the bytecode-only runtime binary, so that the binary is measurably smaller and the attack surface is reduced. Acceptance Criteria
Requirement 3: Runtime Safety — No Silent Fallback to ParserUser Story: As an embedder, I want any attempt to invoke the Parser/Compiler at runtime in a bytecode-only build to produce a clear error, so that misconfiguration is caught immediately rather than silently succeeding or crashing. Acceptance Criteria
Requirement 4: Dev Toolchain UnaffectedUser Story: As a developer, I want Acceptance Criteria
Requirement 5: Hidden Dependency AuditUser Story: As a contributor, I want a verified audit confirming that no hidden Parser/Compiler dependencies exist in the bytecode execution path, so that I can trust the bytecode-only build is genuinely parser-free. Acceptance Criteria
Requirement 6: Build System IntegrationUser Story: As a developer, I want the Makefile to correctly build and test the bytecode-only runtime variant, so that the feature is continuously validated in CI. Acceptance Criteria
Requirement 7: Bytecode Serialization Round-Trip (Parser-Free Path)User Story: As an embedder, I want to verify that bytecode written by Acceptance Criteria
|
|
how can we test that => 1. we actually removed runtime parser/compiler? 2. The removal does not cause unexpected issues for programs that don't use any dynamic code parsing features like |
|
The -fno-* flags already handles the forbidden functions. You don't have to stub out any functionalities. I've updated the specs: The feature's scope is strictly the parser/compiler dead-stripping mechanism: detecting when all four flags are simultaneously set, building the minified library, and ensuring LTO can eliminate the unreachable parser/compiler code. The behavioral consequences of the individual flags — such as TypeError on eval, absent JSON global, etc. — are pre-existing behaviors of those flags and are explicitly out of scope for this feature. The feature formalises the existing "two-stage" qjsc workflow: Glossary
RequirementsRequirement 1: Bytecode-Only Trigger DetectionUser Story: As a developer embedding QuickJS in a resource-constrained target, I want Acceptance Criteria
Requirement 2: Runtime_Engine Build TargetsUser Story: As a build-system maintainer, I want dedicated Makefile targets for the bytecode-only runtime libraries, so that CI and downstream embedders can build and depend on them explicitly. Acceptance Criteria
Requirement 3: Parser/Compiler Absence from Runtime_Engine BinaryUser Story: As a security-conscious embedder, I want to verify that the parser and compiler are physically absent from the Runtime_Engine binary, so that I can guarantee no source-code execution path exists at runtime. Acceptance Criteria
Requirement 4: Build_Engine IntegrityUser Story: As a developer using Acceptance Criteria
Requirement 5: Hidden Dependency AuditUser Story: As a security auditor, I want all indirect parser call sites to be identified and guarded, so that no parser invocation can leak through edge-case language features in the Runtime_Engine. Acceptance Criteria
Requirement 6: Bytecode Round-Trip EquivalenceUser Story: As a developer deploying pre-compiled bytecode, I want programs compiled by the Build_Engine and executed on the Runtime_Engine to produce identical results to running the same programs on the full runtime, so that I can trust the minification does not alter program semantics. Acceptance Criteria
Requirement 7: CI IntegrationUser Story: As a CI maintainer, I want a dedicated test target that validates the bytecode-only runtime end-to-end, so that regressions in parser stripping or round-trip correctness are caught automatically. Acceptance Criteria
|
|
Please follow this updated specs: The feature's scope is strictly the parser/compiler dead-stripping mechanism: detecting when all four flags are simultaneously set, building the minified library, and ensuring LTO can eliminate the unreachable parser/compiler code. The behavioral consequences of the individual flags — such as TypeError on eval, absent JSON global, etc. — are pre-existing behaviors of those flags and are explicitly out of scope for this feature. The feature formalises the existing "two-stage" qjsc workflow: Glossary
RequirementsRequirement 1: Bytecode-Only Trigger DetectionUser Story: As a developer embedding QuickJS in a resource-constrained target, I want Acceptance Criteria
Requirement 2: Runtime_Engine Build TargetsUser Story: As a build-system maintainer, I want dedicated Makefile targets for the bytecode-only runtime libraries, so that CI and downstream embedders can build and depend on them explicitly. Acceptance Criteria
Requirement 3: Parser/Compiler Absence from Runtime_Engine BinaryUser Story: As a security-conscious embedder, I want to verify that the parser and compiler are physically absent from the Runtime_Engine binary, so that I can guarantee no source-code execution path exists at runtime. Acceptance Criteria
Requirement 4: Build_Engine IntegrityUser Story: As a developer using Acceptance Criteria
Requirement 5: Hidden Dependency AuditUser Story: As a security auditor, I want all indirect parser call sites to be identified and guarded, so that no parser invocation can leak through edge-case language features in the Runtime_Engine. Acceptance Criteria
Requirement 6: Bytecode Round-Trip EquivalenceUser Story: As a developer deploying pre-compiled bytecode, I want programs compiled by the Build_Engine and executed on the Runtime_Engine to produce identical results to running the same programs on the full runtime, so that I can trust the minification does not alter program semantics. Acceptance Criteria
Requirement 7: CI IntegrationUser Story: As a CI maintainer, I want a dedicated test target that validates the bytecode-only runtime end-to-end, so that regressions in parser stripping or round-trip correctness are caught automatically. Acceptance Criteria
Design Document: Bytecode-Only RuntimeOverviewThe bytecode-only runtime feature introduces a minified QuickJS library ( The key insight is that the four The only additional work is making the compiler call tree unreachable from the linker's perspective. Even though ArchitectureThe feature formalises a two-engine model: The Runtime_Engine ( Parser/Compiler Runtime Dependency AnalysisThis section documents the complete dependency graph of the parser/compiler and proves that the four trigger flags are necessary and sufficient to make All runtime paths to the parser/compilerThere are exactly four runtime paths that can invoke the parser or compiler: Why
|
| Flag | Gate killed | Effect |
|---|---|---|
-fno-eval |
ctx->eval_internal stays NULL |
All paths through JS_EvalInternal throw TypeError |
-fno-regexp |
ctx->compile_regexp stays NULL |
All RegExp compilation throws TypeError |
-fno-json |
JS_AddIntrinsicJSON not called |
JSON global absent from context |
-fno-module-loader |
rt->module_loader_func stays NULL |
Dynamic import throws ReferenceError |
Together they close every runtime path to the parser/compiler. No additional flags (-fno-promise, -fno-generator, etc.) are needed.
Why CONFIG_BYTECODE_ONLY_RUNTIME is still needed
The four flags handle behavioral safety — the parser is never called. But __JS_EvalInternal and its entire call tree (js_parse_program, js_create_function, and all parser functions) still exist as compiled machine code in the .o file. LTO cannot dead-strip them because:
ctx->eval_internalis a function pointer — LTO cannot prove it is always NULLJS_AddIntrinsicEvaltakes the address of__JS_EvalInternaland stores it — this is a direct reference that keeps__JS_EvalInternalalive in the linker's symbol table
The #ifndef CONFIG_BYTECODE_ONLY_RUNTIME guard around __JS_EvalInternal removes it from the translation unit entirely before the compiler sees it. With no definition, there is no symbol, and LTO has nothing to keep. The entire downstream call tree becomes unreachable and is eliminated.
Components and Interfaces
Trigger Predicate (qjsc.c)
The trigger is a predicate over feature_bitmap. The four relevant feature indices are:
| Index | Flag | feature_list entry |
|---|---|---|
| 1 | -fno-eval |
"eval" |
| 3 | -fno-regexp |
"regexp" |
| 4 | -fno-json |
"json" |
| 9 | -fno-module-loader |
"module-loader" |
#define FE_MASK(i) ((uint64_t)1 << (i))
#define BYTECODE_ONLY_TRIGGER_MASK \
(FE_MASK(1) | FE_MASK(3) | FE_MASK(4) | FE_MASK(FE_MODULE_LOADER))
static BOOL runtime_needs_parser(void) {
return (feature_bitmap & BYTECODE_ONLY_TRIGGER_MASK) != 0;
}output_executable() uses this to select the library suffix:
lib_suffix = runtime_needs_parser() ? "" : "-bytecode";
// produces: libquickjs[-bytecode][.lto].aqjsc.c also carries a compile-time guard to prevent accidental misconfiguration:
#ifdef CONFIG_BYTECODE_ONLY_RUNTIME
#error "qjsc must be built with the full QuickJS engine"
#endifThe One Source Change (quickjs.c)
The only change to quickjs.c is wrapping the compiler entry point and its direct callees:
#ifndef CONFIG_BYTECODE_ONLY_RUNTIME
static JSValue __JS_EvalInternal(JSContext *ctx, JSValueConst this_obj,
const char *input, size_t input_len,
const char *filename, int flags, int scope_idx)
{
/* ... full parser/compiler body ... */
}
static int js_parse_program(JSParseState *s, ...) { ... }
static JSFunctionDef *js_create_function(JSContext *ctx, ...) { ... }
#endif /* CONFIG_BYTECODE_ONLY_RUNTIME */Because __JS_EvalInternal is the sole entry point into the parser/compiler (it is only ever called via ctx->eval_internal, which is NULL when JS_AddIntrinsicEval is not called), guarding it makes the entire downstream call tree unreachable. LTO then eliminates all parser and compiler functions from the final binary.
JS_AddIntrinsicEval, JS_AddIntrinsicRegExpCompiler, and JS_AddIntrinsicJSON do not need guards — they are small stubs that set function pointers, and the generated JS_NewCustomContext simply never calls them when the corresponding -fno-* flags are active.
Makefile Targets
New .bytecode.o compile rules compile each source file with -DCONFIG_BYTECODE_ONLY_RUNTIME:
OBJDIR_RT=.obj-rt
$(OBJDIR_RT)/%.bytecode.o: %.c | $(OBJDIR_RT)
$(CC) $(CFLAGS_NOLTO) -DCONFIG_BYTECODE_ONLY_RUNTIME -c -o $@ $<
$(OBJDIR_RT)/%.bytecode.lto.o: %.c | $(OBJDIR_RT)
$(CC) $(CFLAGS_OPT) -DCONFIG_BYTECODE_ONLY_RUNTIME -c -o $@ $<
QJS_BYTECODE_OBJS=$(OBJDIR_RT)/quickjs.bytecode.o \
$(OBJDIR_RT)/dtoa.bytecode.o \
$(OBJDIR_RT)/libregexp.bytecode.o \
$(OBJDIR_RT)/libunicode.bytecode.o \
$(OBJDIR_RT)/cutils.bytecode.o \
$(OBJDIR_RT)/quickjs-libc.bytecode.o
QJS_BYTECODE_LTO_OBJS=$(OBJDIR_RT)/quickjs.bytecode.lto.o \
$(OBJDIR_RT)/dtoa.bytecode.lto.o \
$(OBJDIR_RT)/libregexp.bytecode.lto.o \
$(OBJDIR_RT)/libunicode.bytecode.lto.o \
$(OBJDIR_RT)/cutils.bytecode.lto.o \
$(OBJDIR_RT)/quickjs-libc.bytecode.lto.o
libquickjs-bytecode.a: $(QJS_BYTECODE_OBJS)
$(AR) rcs $@ $^
libquickjs-bytecode.lto.a: $(QJS_BYTECODE_LTO_OBJS)
$(AR) rcs $@ $^The test-bytecode-runtime CI target:
test-bytecode-runtime: libquickjs-bytecode.lto.a qjsc$(EXE)
$(QJSC) -fno-eval -fno-regexp -fno-json -fno-module-loader \
-o /tmp/test-bytecode-rt examples/hello.js
@nm /tmp/test-bytecode-rt | grep -E ' T (__JS_EvalInternal|js_parse_|js_compile_)' \
&& (echo "FAIL: parser symbols found in bytecode-only binary" && exit 1) \
|| echo "PASS: no parser symbols"
@/tmp/test-bytecode-rtData Models
feature_bitmap
A uint64_t bitmask in qjsc.c. Bit i is set when feature_list[i] is enabled. Starts as FE_ALL (-1, all bits set). Each -fno-X flag clears the corresponding bit.
BYTECODE_ONLY_TRIGGER_MASK is the OR of bits 1, 3, 4, and 9. runtime_needs_parser() returns FALSE iff all four bits are clear — i.e., (feature_bitmap & BYTECODE_ONLY_TRIGGER_MASK) == 0.
Library Selection in output_executable()
const char *lib_suffix;
lib_suffix = runtime_needs_parser() ? "" : "-bytecode";
// lto_suffix is "" or ".lto" depending on use_lto
snprintf(libjsname, sizeof(libjsname), "%s/libquickjs%s%s.a",
lib_dir, lib_suffix, lto_suffix);This produces one of four library names:
libquickjs.alibquickjs.lto.alibquickjs-bytecode.alibquickjs-bytecode.lto.a
Correctness Properties
A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.
Property 1: Trigger predicate exactness
For any combination of the 16 possible on/off states of the four flags (-fno-eval, -fno-regexp, -fno-json, -fno-module-loader), runtime_needs_parser() SHALL return FALSE if and only if all four flags are simultaneously disabled; it SHALL return TRUE for all other 15 combinations.
Validates: Requirements 1.1, 1.3
Property 2: Library selection follows trigger
For any feature_bitmap value, the library name suffix chosen by output_executable() SHALL be "-bytecode" when runtime_needs_parser() is FALSE, and "" when runtime_needs_parser() is TRUE.
Validates: Requirements 1.2
Property 3: Flag order independence
For any subset of the four trigger flags, applying them in any permutation to feature_bitmap SHALL produce the same final feature_bitmap value and therefore the same runtime_needs_parser() result.
Validates: Requirements 1.4
Property 4: Parser symbols absent from Runtime_Engine binary
For any executable linked against libquickjs-bytecode.lto.a, nm SHALL report no defined text symbols (T) matching __JS_EvalInternal, js_parse_*, or js_compile_*.
Validates: Requirements 3.2, 3.3
Property 5: Build_Engine retains full compiler
For any build of qjsc (regardless of which -fno-* flags are used at compile time of JS sources), nm on the qjsc binary SHALL show __JS_EvalInternal and JS_AddIntrinsicEval as defined symbols.
Validates: Requirements 4.1, 4.2
Property 6: Bytecode round-trip equivalence
For any valid JS program P, compiling P with the Build_Engine to bytecode B, then loading and executing B on the Runtime_Engine SHALL produce output identical to executing P on the full runtime.
Validates: Requirements 6.1, 6.3
Testing Strategy
Unit Tests
Focused on specific examples and edge cases:
- Symbol absence: run
nmon a binary linked withlibquickjs-bytecode.lto.a; assert no__JS_EvalInternal,js_parse_*,js_compile_*symbols are defined. - Build_Engine symbol presence: run
nmonqjsc; assert__JS_EvalInternalandJS_AddIntrinsicEvalare present. - Round-trip output: compile
examples/hello.jswith all four trigger flags; run the resulting binary; assert output matches expected string. Function.prototype.toStringsafety: in a Runtime_Engine context, call.toString()on a bytecode function; assert it returns a placeholder or stored source string without crashing.import.metasafety: compile a module that accessesimport.meta.url; run on Runtime_Engine; assert it returns the expected value without invoking the parser.- Compile-time guard: attempt to compile
qjsc.cwith-DCONFIG_BYTECODE_ONLY_RUNTIME; assert the build fails with the#errormessage.
Property-Based Tests
Each property test uses a property-based testing library (e.g., theft for C, or a shell-level harness with randomised inputs). Minimum 100 iterations per property.
Property 1 — Trigger predicate exactness
// Feature: bytecode-only-runtime, Property 1: trigger predicate exactness
// For all 16 combinations of the four trigger bits, verify runtime_needs_parser()
for each subset S of {eval=1, regexp=3, json=4, module-loader=9}:
set feature_bitmap = FE_ALL with bits in S cleared
expected = (S == all_four) ? FALSE : TRUE
assert runtime_needs_parser() == expected
Property 2 — Library selection follows trigger
// Feature: bytecode-only-runtime, Property 2: library selection follows trigger
// For all feature_bitmap values, lib_suffix == "-bytecode" iff !runtime_needs_parser()
for each of 16 flag combinations:
assert (lib_suffix == "-bytecode") == (!runtime_needs_parser())
Property 3 — Flag order independence
// Feature: bytecode-only-runtime, Property 3: flag order independence
// For any permutation of flag application order, feature_bitmap is the same
for each permutation of the four flags:
apply flags in that order to a fresh FE_ALL bitmap
assert result == (FE_ALL & ~BYTECODE_ONLY_TRIGGER_MASK)
Property 4 — Parser symbols absent from Runtime_Engine binary
// Feature: bytecode-only-runtime, Property 4: parser symbols absent
// Compile a representative JS program with all four trigger flags
// Run nm and assert no forbidden symbols appear
compile hello.js with -fno-eval -fno-regexp -fno-json -fno-module-loader
nm output | grep -E 'T (__JS_EvalInternal|js_parse_|js_compile_)' → must be empty
Property 5 — Build_Engine retains full compiler
// Feature: bytecode-only-runtime, Property 5: Build_Engine symbol presence
nm qjsc | grep '__JS_EvalInternal' → must be non-empty
nm qjsc | grep 'JS_AddIntrinsicEval' → must be non-empty
Property 6 — Bytecode round-trip equivalence
// Feature: bytecode-only-runtime, Property 6: bytecode round-trip equivalence
// For any valid JS program, Build_Engine output == Runtime_Engine output
for each test program P in {hello.js, pi_bigint.js, test_fib.js, ...}:
full_output = run P on qjs (full runtime)
bytecode_output = compile P with trigger flags, run resulting binary
assert full_output == bytecode_output
Both unit tests and property tests are required. Unit tests catch concrete bugs and edge cases; property tests verify universal correctness across all inputs. The test-bytecode-runtime Makefile target runs both.
1 participant
Aggressively reduce QuickJS runtime bundle size by enabling a bytecode-only mode that strips the parser and compiler when they are not needed. This is achieved by gating compiler entry points with a new
JS_BYTECODE_ONLY_RUNTIMEmacro and providing specialized minimal intrinsics.PR created automatically by Jules for task 17643968534238357240 started by @yumin-chen