Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
225 changes: 225 additions & 0 deletions docs/superpowers/plans/2026-09-22-32-bit-x86-default-lib.md

Large diffs are not rendered by default.

96 changes: 84 additions & 12 deletions docs/superpowers/specs/2026-09-20-32-bit-compilation-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
Design for compiling TypeScript to 32-bit targets, with `i686-pc-windows-msvc`
as the proof target and width-correctness that generalizes to any 32-bit triple.

Status: approved design. Phases 1-4 implemented, except the x86 default library
(deferred; see Open issues).
Status: approved design. Phases 1-4 implemented.

## Why now

Expand Down Expand Up @@ -301,10 +300,10 @@ only, so phase 4 is three PRs:
because `--emit=jit` runs in the x64 compiler process and refuses a foreign
arch. Only one test file, `02funcs_vararg.ts`, is JIT-only at the file level;
every other file has a compile registration and so a twin. The cmake-script
tests have no twin either. There were 12 of them: `rc-debug-info`,
`gc-shared-auto`, the two default-library collector tests (the default
library has no x86 build) and the 8 ownership-verifier shards. The two
foreign-target import tests below make 14.
tests get no twin via `tslang_add_test` either. There were 12 of them:
`rc-debug-info`, `gc-shared-auto`, the two default-library collector tests
and the 8 ownership-verifier shards. The two foreign-target import tests
below make 14.
1395 twins pass; 3 are registered `DISABLED` in
`tslang/test/tester/x86-exclusions.cmake`: `internals` under gc, rc and
none, because its `inline_asm<i64>` with an `=r` constraint needs a 64-bit
Expand All @@ -329,6 +328,57 @@ only, so phase 4 is three PRs:
`/manifest:embed /manifestuac:...` for x86 exes. `check-x86-run.sh` builds
hello as `my_setup_patch.exe` and runs it.

**As built — the x86 default library (done; was deferred from 4c).**
`getDefaultLibSubDir` (`include/TypeScript/Defines.h`) gained a required `arch`
parameter and `DEFAULT_LIB_ARCH_X86`, giving the layout named above:
`defaultlib/{lib,dll}/x86/{debug,release}/{gc,rc,none}/`, with no `x86`
segment (and no change) for every other target, x64 included. `exe.cpp`
passes `DEFAULT_LIB_ARCH_X86` only for a Windows x86 target, names the arch
and the `TSLANG_ARCH=x86` build step in the missing-directory error, and
checks the COFF machine of `TypeScriptDefaultLib.lib` the same way it already
checked the collector and the runtime (an x64 default library in an x86
program is refused before the link, not left to become unresolved symbols).
`jit.cpp` and `defaultlib.cpp` pass `""` (host-only paths). In the separate
`TypeScriptCompilerDefaultLib` repository, `TSLANG_ARCH=x86` (set before
`build.bat`) switches `vcvarsall.bat` to `x86`, adds
`-mtriple=i686-pc-windows-msvc` to every `tslang.exe` invocation, and routes
every build and staging path through the same layout; `TSLANG_ARCH` unset or
`x64` produces the same output tree as before. That repository's own 150-test
suite passes at 150/150, release and debug, as i686 executables against the
static x86 tree (`tests.ps1`).

One probe-only failure needed a real fix: `paragraph.replaceAll(/Dog/gi,
"ferret")` segfaulted after its first `console.log` at i686 (149/150; x64
passed). Root cause: `RegExp.replaceAll` in `lib.ts` called the native
`declare function regexp_replace` with 3 of its 4 parameters; tslang does not
check declare-function call arity (TypeScript's TS2554), so the omitted
argument read whatever a register or a stack slot happened to hold - luck
that held at x64 and did not at i686. Fixed in the default library, not in
the compiler: `RegExp.replaceAll`'s regex branch in `lib.ts` now passes the
replacement string as the native call's 4th argument instead of omitting it.

Compiler-side coverage: `check-x86-libs.sh` gained the default-library
error-path cases (no x86 tree; an x64 `TypeScriptDefaultLib.lib` staged where
the x86 one belongs; an x64 control case). `check-x86-run.sh` gained a
default-library section, skipped (not failed) when
`TypeScriptCompilerDefaultLib`'s x86 tree is absent: `defaultlib_smoke.ts`
(Array, Map, string, Date and RegExp, including `replaceAll(regex, ...)`)
under gc, rc and none release, the gc case again against the debug tree
(`--di`), and a gc `--emit=dll` library linking the default library plus an
exe that imports it (the shape of `defaultlib-collector.cmake`'s compile
mode, reused in bash), with `TypeScriptDefaultLib.dll` and the x86 `gc.dll`
copied beside the importing exe. `tester/CMakeLists.txt` hand-registers
`test-x86-compile-gc-defaultlib-collector` (labelled `x86`) as the x86 twin
of the existing compile-mode default-library collector test, extending
`defaultlib-collector.cmake`'s own skip test to look under the `x86` tree
when an `X86` flag is passed; there is still no JIT twin (the JIT refuses an
x86 target, unrelated to the default library). With `-DTSLANG_TEST_X86=ON`:
1396 of the 1399 x86-labelled tests pass (the 1395 `tslang_add_test` twins
plus the new collector twin), 3 stay `DISABLED`. With it `OFF`,
`CTestTestfile.cmake` is unchanged except for `_BACKTRACE_TRIPLES` line
numbers (this file added lines above existing `add_test` calls), and the
default suite stays 2771/2771.

Remaining i686-only probe failures after 4b: `internals` (an `inline_asm<i64>` with an `=r` constraint, which no single
i686 register can satisfy); `02funcs_vararg` (unresolved `_printf`; it is
commented out of the suite).
Expand Down Expand Up @@ -360,12 +410,34 @@ confusion:
`MLIRGenImpl::mlirGenImportSharedLib` loaded the DLL into the x64 compiler to
read its `__decls`. For a foreign target (arch or OS) it now reads the string from
the file (`Dump::readExportedCString`); the x86 `-shared` twins pass.
- **The x86 default library (deferred from phase 4).** `getDefaultLibSubDir`
in `include/TypeScript/Defines.h` still has no arch segment, and the default
library, built in the separate `TypeScriptCompilerDefaultLib` repository, has
no x86 build. Both are needed before an x86 program can link the default
library; until then x86 programs use `--no-default-lib`, and the collector
test that links the real default library has no x86 twin.
- **The x86 default library — closed (phase 4, "As built" note above).**
`getDefaultLibSubDir` has the arch segment, the `TypeScriptCompilerDefaultLib`
repository builds the x86 tree under `TSLANG_ARCH=x86`, and
`test-x86-compile-gc-defaultlib-collector` gives the compile-mode collector
test its x86 twin. x86 programs no longer need `--no-default-lib`.
- **tslang does not check declare-function call arity (TypeScript's TS2554).**
Found while root-causing the x86 `replaceAll(regex, ...)` segfault above: a
call to a `declare function` with fewer arguments than it declares compiles
regardless, and the callee reads whatever a register or stack slot happens
to hold for the missing ones. That hid the `RegExp.replaceAll` bug at x64
(the garbage argument happened to be usable) until the x86 build read a
garbage stack slot instead. No arity check exists for `declare function`
calls generally, only for the specific case this one bug surfaced.
- **`"xxx".replaceAll("", "_")` gives `___` instead of `_x_x_x_` (pre-existing,
both architectures).** An empty-pattern `replaceAll` should insert the
replacement between every character; it currently inserts once per
distinct-looking match instead. Confirmed unchanged at x64 and i686; not
investigated further here.
- **Neither CI nor the release workflows build an x86 default library.** Both
build x64 only, so `-DTSLANG_TEST_X86=ON` and `check-x86-run.sh`'s
default-library section are local-only checks today; the x86-labelled ctest
run and the default suite's x64-only default-library collector tests never
run together in the same CI job. The `test-runner -x86` twins (the 1395
`tslang_add_test` twins) still pass `--no-default-lib` unconditionally, the
same as their x64 counterparts - `test-runner.cpp` was not changed by this
work - so they cover the arch/ABI matrix, not the default library; only
`test-x86-compile-gc-defaultlib-collector` and `check-x86-run.sh` exercise
the x86 default library itself.
- **Per-test flags miss the entry file of multi-file tests (not 32-bit;
pre-existing).** Found in phase 4c: in `test-runner`, `-mm`, `-fast-math`
and `--gctors-as-method` reach only the non-entry files of a multi-file test,
Expand Down
19 changes: 15 additions & 4 deletions tslang/include/TypeScript/Defines.h
Original file line number Diff line number Diff line change
Expand Up @@ -253,15 +253,26 @@
// warns about, and it is the largest instance of it, since every program that does not pass
// `--no-default-lib` links this one.
//
// Layout: defaultlib/{lib,dll}/{debug,release}/{gc,rc,none}/. The model name is exactly
// Layout: defaultlib/{lib,dll}/[x86/]{debug,release}/{gc,rc,none}/. The model name is exactly
// `memoryModelName()`, so the directory and the `-mm=` flag cannot drift apart.
#define DEFAULT_LIB_KIND_STATIC "lib"
#define DEFAULT_LIB_KIND_SHARED "dll"

inline std::string getDefaultLibSubDir(bool shared, bool debugBuild, const char *memoryModel)
// ...and, for a Windows x86 target, per arch, outermost under lib/ or dll/ like every other x86
// library (spec "Arch in the library layout"). Every other target, x64 included, has no arch
// segment, so existing trees keep their shape. There is no fallback to the x64 tree: an x64
// library links into an x86 program only to fail on every symbol.
#define DEFAULT_LIB_ARCH_X86 "x86"

inline std::string getDefaultLibSubDir(bool shared, bool debugBuild, const char *memoryModel, const char *arch)
{
return std::string(DEFAULT_LIB_DIR "/") + (shared ? DEFAULT_LIB_KIND_SHARED : DEFAULT_LIB_KIND_STATIC) + "/" +
(debugBuild ? DEFAULT_LIB_BUILD_DIR_DEBUG : DEFAULT_LIB_BUILD_DIR_RELEASE) + "/" + memoryModel;
std::string subDir = std::string(DEFAULT_LIB_DIR "/") + (shared ? DEFAULT_LIB_KIND_SHARED : DEFAULT_LIB_KIND_STATIC) + "/";
if (arch && *arch)
{
subDir += std::string(arch) + "/";
}

return subDir + (debugBuild ? DEFAULT_LIB_BUILD_DIR_DEBUG : DEFAULT_LIB_BUILD_DIR_RELEASE) + "/" + memoryModel;
}

#define DEBUG_SCOPE "current"
Expand Down
97 changes: 96 additions & 1 deletion tslang/test/check-x86-libs.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ GCDLL_X86_LIB="$REPO/3rdParty/gcdll/x86/release/lib/gc.lib"
GCDLL_X86_DLL="$REPO/3rdParty/gcdll/x86/release/bin/gc.dll"
GCDLL_X64_DLL="$REPO/3rdParty/gcdll/x64/release/bin/gc.dll"
RT_X86="$REPO/__build/tslang-runtime/release/x86/TypeScriptAsyncRuntime.lib"
# The default-lib repo is a sibling checkout; when its x64 build exists, its release/gc static lib
# stands in for "a default library, but the wrong one" below and is the only thing the x64-control
# case can run against. It is optional, unlike the libraries in the prerequisite loop below: a
# machine with no TypeScriptCompilerDefaultLib x64 build still runs every other case in this file
# (the "x64 lib in x86 tree" case below needs only some x64 COFF archive, not a real default
# library); only the x64-control case is SKIPPED. There is no x86 default library staged here -
# the x86 default library (spec Phase 4, As built) has its own run coverage in check-x86-run.sh's
# default-library section - so this file has no positive x86 case.
DEFAULTLIB_X64_LIB="$REPO/../TypeScriptCompilerDefaultLib/__build/defaultlib/lib/release/gc/TypeScriptDefaultLib.lib"

for f in "$GC_X64" "$GC_X86" "$GCDLL_X86_LIB" "$GCDLL_X86_DLL" "$GCDLL_X64_DLL" "$RT_X64" "$RT_X86"; do
if [ ! -f "$f" ]; then
Expand All @@ -32,7 +41,9 @@ mkdir -p "$work/empty" \
"$work/gc-good/x86" "$work/gc-x64-in-x86/x86" "$work/gc-x86-flat" \
"$work/gcdll-good/x86" "$work/gcdll-x64-dll/x86" \
"$work/rt-good/x86" "$work/rt-x64-in-x86/x86" \
"$work/gcdll-x86-flat" "$work/rt-x86-flat"
"$work/gcdll-x86-flat" "$work/rt-x86-flat" \
"$work/defaultlib-x64-only/defaultlib/lib/release/gc" \
"$work/defaultlib-x64-in-x86/defaultlib/lib/x86/release/gc"
cp "$GC_X86" "$work/gc-good/x86/gc.lib"
cp "$GC_X64" "$work/gc-x64-in-x86/x86/gc.lib"
cp "$GC_X86" "$work/gc-x86-flat/gc.lib"
Expand All @@ -45,6 +56,14 @@ cp "$RT_X64" "$work/rt-x64-in-x86/x86/TypeScriptAsyncRuntime.lib"
cp "$GCDLL_X86_LIB" "$work/gcdll-x86-flat/gc.lib"
cp "$GCDLL_X86_DLL" "$work/gcdll-x86-flat/gc.dll"
cp "$RT_X86" "$work/rt-x86-flat/TypeScriptAsyncRuntime.lib"
# defaultlib-x64-only/defaultlib/lib/release/gc: a stand-in file. The "no x86 tree" case below
# never opens it - it fails on the missing x86 subdirectory before reading any file - and the
# "x64 control" case only runs against this tree, with the real x64 default library copied over
# it, when one is staged (see below). defaultlib-x64-in-x86 needs only *some* x64 COFF archive:
# the machine check reads the file's COFF header before ever trying to link it as a default
# library, so $GC_X64 stands in without this file depending on a TypeScriptCompilerDefaultLib build.
cp "$GC_X64" "$work/defaultlib-x64-only/defaultlib/lib/release/gc/TypeScriptDefaultLib.lib"
cp "$GC_X64" "$work/defaultlib-x64-in-x86/defaultlib/lib/x86/release/gc/TypeScriptDefaultLib.lib"

X86="i686-pc-windows-msvc"
X64="x86_64-pc-windows-msvc"
Expand Down Expand Up @@ -99,6 +118,60 @@ expect_no_flat_error() {
fi
}

# The default library resolution below only runs without --no-default-lib, unlike every case
# above, so it is a separate pair of helpers rather than a reuse of expect_error/expect_no_flat_error.
# A distinct -o per call: unlike the --no-default-lib cases above, these can produce a real linked
# .exe, and Windows (AV scan) can briefly hold a lock on one just written, which would otherwise
# spuriously fail the next case's read of the shared work dir.
dl_case_n=0

# expect_default_lib_error <name> <triple> <default-lib-path> <substring>... -- <extra tslang args>...
expect_default_lib_error() {
local name="$1" triple="$2" dlpath="$3"
shift 3
local needles=()
while [ "$1" != "--" ]; do
needles+=("$1")
shift
done
shift
dl_case_n=$((dl_case_n + 1))
local err status
err="$("$TSLANG" --emit=exe --opt -mm=gc -mtriple="$triple" --default-lib-path="$dlpath" "$@" \
"$work/x.ts" -o "$work/out-dl-$dl_case_n.exe" 2>&1 >/dev/null)"
status=$?
if [ "$status" -eq 0 ]; then
echo "FAIL $name: expected a non-zero exit, got 0"
fail=1
return
fi
for needle in "${needles[@]}"; do
if ! printf '%s' "$err" | grep -q -F -- "$needle"; then
echo "FAIL $name: expected the error to contain '$needle', got: $err"
fail=1
return
fi
done
echo "ok $name"
}

# expect_default_lib_ok <name> <triple> <default-lib-path> <extra tslang args>...
expect_default_lib_ok() {
local name="$1" triple="$2" dlpath="$3"
shift 3
dl_case_n=$((dl_case_n + 1))
local err status
err="$("$TSLANG" --emit=exe --opt -mm=gc -mtriple="$triple" --default-lib-path="$dlpath" "$@" \
"$work/x.ts" -o "$work/out-dl-$dl_case_n.exe" 2>&1 >/dev/null)"
status=$?
if [ "$status" -ne 0 ]; then
echo "FAIL $name: expected a zero exit, got $status: $err"
fail=1
else
echo "ok $name"
fi
}

GOOD_RT="--tslang-lib-path=$work/rt-good"
GOOD_GC="--gc-lib-path=$work/gc-good"

Expand All @@ -124,4 +197,26 @@ expect_error "x64: x86 runtime lib in flat path" "$X64" exe "TypeScriptAsyncRunt
expect_no_flat_error "exe: correct x86 layout" exe "$GOOD_GC" "$GOOD_RT"
expect_no_flat_error "dll: correct x86 layout" dll "--gc-shared-lib-path=$work/gcdll-good" "$GOOD_GC" "$GOOD_RT"

# Default library, without --no-default-lib: it takes the same x86-tree/machine-check treatment
# as the collector and the runtime above. There is no positive x86 case here (no x86 default
# library is staged for this script to find); check-x86-run.sh's default-library section adds run
# coverage once one is built.
expect_default_lib_error "default lib: no x86 tree" "$X86" "$work/defaultlib-x64-only" \
"no x86 default library built for -mm=gc" "defaultlib" "x86" "release" "gc" -- \
"$GOOD_GC" "$GOOD_RT"
expect_default_lib_error "default lib: x64 lib in x86 tree" "$X86" "$work/defaultlib-x64-in-x86" \
"is built for x64" -- \
"$GOOD_GC" "$GOOD_RT"
# Only this case needs a real, linkable x64 default library (an actual TypeScriptCompilerDefaultLib
# build); the two error cases above are satisfied by the stand-in files staged above. SKIPPED, not
# FAILed, when none is staged, matching check-x86-run.sh's skip style for the same situation.
if [ -f "$DEFAULTLIB_X64_LIB" ]; then
cp "$DEFAULTLIB_X64_LIB" "$work/defaultlib-x64-only/defaultlib/lib/release/gc/TypeScriptDefaultLib.lib"
expect_default_lib_ok "default lib: x64 control" "$X64" "$work/defaultlib-x64-only" \
"--gc-lib-path=$(dirname "$GC_X64")" "--tslang-lib-path=$(dirname "$RT_X64")"
else
echo "SKIPPED: default lib: x64 control (no x64 default library built at $DEFAULTLIB_X64_LIB;" \
"build it in TypeScriptCompilerDefaultLib)"
fi

exit "$fail"
Loading
Loading