Files
58c2c80401 Migrate from Yarn to pnpm (#246)
* Migrate from Yarn to pnpm

- Replace Yarn 4.0.2 with pnpm 10.29.3 as the package manager
- Add pnpm-workspace.yaml and .npmrc configuration
- Update all scripts to use pnpm commands
- Rename getYarnWorkspaces() to getWorkspaces() in scripts/helpers.ts
- Update CI workflow to use pnpm/action-setup@v4 with Node 22
- Add @jitl/tsconfig as root devDependency for proper resolution
- Add variant packages as devDependencies for test resolution
- Fix TypeScript 5.9 compatibility in memory.ts (Int32Array<ArrayBuffer>)
- Upgrade typedoc to 0.28.17 for TypeScript 5.9 support
- Upgrade typedoc-plugin-markdown to 4.10.0
- Regenerate documentation with new typedoc version

* Clarify git commit --amend rule in CLAUDE.md

* CI: Add --ignore-scripts to pnpm install

Equivalent to yarn's YARN_ENABLE_SCRIPTS=0 - prevents prepare scripts
from running during install, which would fail on a fresh checkout.

* Fix pnpm tarball naming in smoketest scripts

pnpm pack generates tarball names like jitl-quickjs-ffi-types-0.32.0.tgz
(without @ prefix, with version) instead of @jitl-quickjs-ffi-types.tgz

* Update examples to TypeScript 5.9 for compatibility

The library now requires TypeScript 5.9+ due to stricter typed array
generics (Int32Array<ArrayBuffer>). Update all TypeScript-using examples.

* Use --legacy-peer-deps for create-react-app smoketest

react-scripts@5 only supports TypeScript 3.x/4.x, but our library now
requires TypeScript 5.9+ for typed array generics. Use --legacy-peer-deps
to work around the peer dependency conflict.

* Fix formatting issues

* Fix remaining formatting issues

* Add reminder to run prettier and lint before pushing

* Document CI workflow in CLAUDE.md

* Add typedoc.json and remark plugins for in-page table of contents

- Add typedoc-plugin-remark, remark-toc, and remark-insert-headings
- Configure remark plugins to generate "Contents" section for Class,
  Interface, Enum, TypeAlias, and Function pages
- This restores the in-page TOC that lists methods/properties that was
  removed in typedoc-plugin-markdown 4.3.0

* Use custom remark plugin for headless TOC in docs

Replace remark-insert-headings + remark-toc with a custom plugin that
inserts the table of contents directly after the class description,
without a separate "Contents" heading.

* Revert to standard remark plugins for TOC with Contents heading

Use remark-insert-headings + remark-toc instead of custom plugin.
Remove mdast-util-toc dependency and custom remark-toc-headless.mjs.

* Fix lockfile - remove mdast-util-toc

* Ignore pnpm-lock.yaml in prettier, update .yarn to .pnpm

---------

Co-authored-by: Hanzo Dev <[email protected]>
2026-02-16 20:35:52 +00:00

950 lines
29 KiB
TypeScript
Executable File

#!/usr/bin/env -S npx tsx
/**
* This file defines all the different variants of the quickjs WASM library.
*/
import path from "node:path"
import fs from "node:fs"
import child_process from "node:child_process"
import type { TypeDocOptions } from "typedoc"
import type { PackageJson } from "./helpers"
import { writePretty, tryReadJson, repoRoot } from "./helpers"
import { Context, getMatches, buildFFI } from "./generate"
const CLEAN = Boolean(process.env.CLEAN)
// Variant variables.
enum ReleaseMode {
Debug = "debug",
Release = "release",
}
enum SyncMode {
Sync = "sync",
Asyncify = "asyncify",
}
enum CLibrary {
QuickJS = "quickjs",
NG = "quickjs-ng",
}
enum EmscriptenInclusion {
SingleFile = "singlefile",
Separate = "wasm",
AsmJs = "asmjs",
}
// https://github.com/emscripten-core/emscripten/blob/7bed0e2477000603c26766897e1f455c08bc3358/src/settings.js#L647
enum EmscriptenEnvironment {
web = "web",
webview = "webview",
worker = "worker",
node = "node",
}
const DEFAULT_EMSCRIPTEN_VERSION = "5.0.1"
// Use older emscripten for asmjs to avoid relying on newer browser APIs
const ASMJS_EMSCRIPTEN_VERSION = "3.1.43"
interface BuildVariant {
description: string
releaseMode: ReleaseMode
syncMode: SyncMode
library: CLibrary
emscriptenInclusion: EmscriptenInclusion
/** Emscripten SDK version. Defaults to DEFAULT_EMSCRIPTEN_VERSION. */
emscriptenVersion?: string
exports: {
browser?: {
emscriptenEnvironment: EmscriptenEnvironment[]
}
import?: {
emscriptenEnvironment: EmscriptenEnvironment[]
}
require?: {
emscriptenEnvironment: EmscriptenEnvironment[]
}
workerd?: {
emscriptenEnvironment: EmscriptenEnvironment[]
}
}
}
const SEPARATE_FILE_INCLUSION: BuildVariant["exports"] = {
require: {
emscriptenEnvironment: [EmscriptenEnvironment.node],
},
import: {
emscriptenEnvironment: [EmscriptenEnvironment.node],
},
browser: {
emscriptenEnvironment: [EmscriptenEnvironment.web, EmscriptenEnvironment.worker],
},
workerd: {
// note: EmscriptenEnvironment.worker is broken in Cloudflare Workers
// see https://github.com/cloudflare/worker-emscripten-template/blob/master/pre.js
emscriptenEnvironment: [EmscriptenEnvironment.web],
},
}
const buildMatrix = {
library: [CLibrary.QuickJS, CLibrary.NG],
releaseMode: [ReleaseMode.Debug, ReleaseMode.Release],
syncMode: [SyncMode.Sync, SyncMode.Asyncify],
} as const
// Targets: groups of variants.
const targets = {
wasmfile: makeTarget({
description: `Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.`,
emscriptenInclusion: EmscriptenInclusion.Separate,
exports: SEPARATE_FILE_INCLUSION,
}),
"singlefile-cjs": makeTarget({
description: `Variant with the WASM data embedded into a universal (Node and Browser compatible) CommonJS module.`,
emscriptenInclusion: EmscriptenInclusion.SingleFile,
exports: {
require: {
emscriptenEnvironment: [
EmscriptenEnvironment.web,
EmscriptenEnvironment.worker,
EmscriptenEnvironment.node,
],
},
},
}),
"singlefile-mjs": makeTarget({
description: `Variant with the WASM data embedded into a NodeJS ESModule.`,
emscriptenInclusion: EmscriptenInclusion.SingleFile,
exports: {
import: SEPARATE_FILE_INCLUSION.import,
},
}),
"singlefile-browser": makeTarget({
description: `Variant with the WASM data embedded into a browser ESModule.`,
emscriptenInclusion: EmscriptenInclusion.SingleFile,
exports: {
browser: SEPARATE_FILE_INCLUSION.browser,
},
}),
"asmjs-mjs": makeTarget({
description: `Compiled to pure Javascript, no WebAssembly required.`,
emscriptenInclusion: EmscriptenInclusion.AsmJs,
emscriptenVersion: ASMJS_EMSCRIPTEN_VERSION,
releaseMode: ReleaseMode.Release,
syncMode: SyncMode.Sync,
library: CLibrary.QuickJS,
exports: {
import: {
emscriptenEnvironment: [
EmscriptenEnvironment.web,
EmscriptenEnvironment.worker,
EmscriptenEnvironment.node,
],
},
},
}),
}
type TargetSpec = Partial<BuildVariant> &
Pick<BuildVariant, Exclude<keyof BuildVariant, keyof typeof buildMatrix>>
function makeTarget(partialVariant: TargetSpec): BuildVariant[] {
const allVariants = buildMatrix.library.flatMap<BuildVariant>((library) => {
return buildMatrix.releaseMode.flatMap((releaseMode) => {
return buildMatrix.syncMode.flatMap((syncMode) => {
const variant = {
library,
releaseMode,
syncMode,
...partialVariant,
}
// Eliminate singlefile builds for quickjs-ng
if (
variant.library === CLibrary.NG &&
variant.emscriptenInclusion === EmscriptenInclusion.SingleFile
) {
return []
}
return variant
})
})
})
const seen = new Set<string>()
return allVariants.filter((variant) => {
const key = JSON.stringify(variant)
if (seen.has(key)) {
return false
} else {
seen.add(key)
return true
}
})
}
// Build settings for variables
const ASYNCIFY_STACK_SIZE = 81920
const SyncModeFlags = {
[SyncMode.Sync]: [],
[SyncMode.Asyncify]: [
`-s ASYNCIFY=1`,
`-DQTS_ASYNCIFY=1`,
`-DQTS_ASYNCIFY_DEFAULT_STACK_SIZE=${ASYNCIFY_STACK_SIZE}`,
`-s ASYNCIFY_STACK_SIZE=${ASYNCIFY_STACK_SIZE}`,
`-s ASYNCIFY_REMOVE=@$(BUILD_WRAPPER)/asyncify-remove.json`,
`-s ASYNCIFY_IMPORTS=@$(BUILD_WRAPPER)/asyncify-imports.json`,
`-lasync.js`,
],
}
const ReleaseModeFlags = {
[ReleaseMode.Release]: [
`-Oz`,
`-flto`,
`--closure 1`,
`-s FILESYSTEM=0`,
`--pre-js $(TEMPLATES)/pre-extension.js`,
`--pre-js $(TEMPLATES)/pre-wasmMemory.js`,
],
[ReleaseMode.Debug]: [
`-O0`,
"-DQTS_DEBUG_MODE",
`-DDUMP_LEAKS=1`,
`-gsource-map`,
`-s ASSERTIONS=1`,
`--pre-js $(TEMPLATES)/pre-extension.js`,
`--pre-js $(TEMPLATES)/pre-sourceMapJson.js`,
`--pre-js $(TEMPLATES)/pre-wasmOffsetConverter.js`,
`--pre-js $(TEMPLATES)/pre-wasmMemory.js`,
],
}
const EmscriptenInclusionFlags = {
[EmscriptenInclusion.Separate]: [],
[EmscriptenInclusion.SingleFile]: [`-s SINGLE_FILE=1`],
[EmscriptenInclusion.AsmJs]: [`-s WASM=0`, `-s SINGLE_FILE=1`, `-s WASM_ASYNC_COMPILATION=0`],
}
function getCflags(targetName: string, variant: BuildVariant) {
const flags: string[] = []
flags.push(...SyncModeFlags[variant.syncMode])
flags.push(...ReleaseModeFlags[variant.releaseMode])
flags.push(...EmscriptenInclusionFlags[variant.emscriptenInclusion])
if (variant.releaseMode === ReleaseMode.Debug) {
switch (variant.syncMode) {
case SyncMode.Sync:
flags.push()
flags.push("-DQTS_SANITIZE_LEAK")
flags.push("-fsanitize=leak")
flags.push("-g2")
break
case SyncMode.Asyncify:
// flags.push("-s ASYNCIFY_ADVISE=1")
flags.push(
// # Need to use -O3 - otherwise ASYNCIFY leads to stack overflows (why?)
"-O3",
)
break
}
}
return flags
}
function getExportCflags(variant: BuildVariant, exportName: keyof BuildVariant["exports"]) {
const exportVariant = variant.exports[exportName]
if (!exportVariant) {
return []
}
const emscriptenEnvironment = exportVariant.emscriptenEnvironment.join(",")
const flags = [`-s ENVIRONMENT=${emscriptenEnvironment}`]
return flags
}
function getGenerateTsEnv(targetName: string, variant: BuildVariant): Record<string, string> {
const env: Record<string, string> = {}
if (variant.syncMode === SyncMode.Asyncify) {
env.ASYNCIFY = "true"
}
if (variant.releaseMode === ReleaseMode.Debug) {
env.DEBUG = "true"
}
return env
}
// Action
if (require.main === module) {
main().catch((error) => {
console.error(error)
process.exit(2)
})
}
interface TsConfig {
extends: string
include: string[]
files?: string[]
exclude: string[]
}
interface FinalVariant {
basename: string
targetName: string
dir: string
packageJson: PackageJson
variant: BuildVariant
}
async function main() {
const variantsJson: Record<string, FinalVariant> = {}
const coreReadmeVariantDescriptions: string[] = []
const ffiTypesDir = path.join(repoRoot, "packages/quickjs-ffi-types")
await writePretty(
path.join(ffiTypesDir, "src/ffi.ts"),
buildFFI(
...createContext({
TYPE_ONLY: true,
ASYNCIFY: false,
}),
),
)
await writePretty(
path.join(ffiTypesDir, "src/ffi-async.ts"),
buildFFI(
...createContext({
TYPE_ONLY: true,
ASYNCIFY: true,
}),
),
)
// Maintain license files
const coreDir = path.join(repoRoot, "packages/quickjs-emscripten-core")
const mainDir = path.join(repoRoot, "packages/quickjs-emscripten")
for (const ownPackage of [coreDir, mainDir, ffiTypesDir]) {
fs.copyFileSync(path.join(repoRoot, "LICENSE"), path.join(ownPackage, "LICENSE"))
}
for (const [targetName, variants] of Object.entries(targets)) {
for (const variant of variants) {
const basename = getTargetPackageSuffix(targetName, variant)
const dir = path.join(repoRoot, "packages", `variant-${basename}`)
const dist = path.join(dir, "dist")
const src = path.join(dir, "src")
const makeDirs = [dist, src]
for (const dirToMake of makeDirs) {
if (CLEAN) {
try {
fs.rmdirSync(dirToMake, { recursive: true })
} catch (e) {
console.log("ignore", e)
}
}
fs.mkdirSync(dirToMake, { recursive: true })
}
const rootPackageJson: PackageJson | undefined = tryReadJson(
path.join(repoRoot, "package.json"),
)
const packageJsonPath = path.join(dir, "package.json")
const existingPackageJson: PackageJson | undefined = tryReadJson(packageJsonPath)
const { js, mjs } = getTsupExtensions(variant)
const indexExports = {
types: js ? "./dist/index.d.ts" : "./dist/index.d.mts",
main: js ? "./dist/index.js" : "./dist/index.mjs",
module: mjs ? "./dist/index.mjs" : undefined,
}
const ffiExports = {
types: js ? "./dist/ffi.d.ts" : "./dist/ffi.d.mts",
import: mjs ? "./dist/ffi.mjs" : "./dist/ffi.js",
require: js ? "./dist/ffi.js" : undefined,
default: js ? "./dist/ffi.js" : "./dist/ffi.mjs",
}
const emscriptenExports = {
types: variant.exports.browser
? "./dist/emscripten-module.browser.d.ts"
: "./dist/emscripten-module.d.ts",
iife: variant.exports.require ? "./dist/emscripten-module.cjs" : undefined,
workerd: variant.exports.workerd ? "./dist/emscripten-module.cloudflare.cjs" : undefined,
browser: variant.exports.browser ? "./dist/emscripten-module.browser.mjs" : undefined,
import: variant.exports.import
? "./dist/emscripten-module.mjs"
: variant.exports.browser
? "./dist/emscripten-module.browser.mjs"
: "./dist/emscripten-module.cjs",
require: variant.exports.require ? "./dist/emscripten-module.cjs" : undefined,
default: variant.exports.require ? "./dist/emscripten-module.cjs" : undefined,
}
emscriptenExports.default =
emscriptenExports.default ??
emscriptenExports.require ??
emscriptenExports.import ??
emscriptenExports.browser
const packageJson: PackageJson = {
name: `@jitl/${basename}`,
license: rootPackageJson?.license,
version: existingPackageJson?.version ?? rootPackageJson?.version ?? "0.0.0",
description: `Variant of quickjs library: ${variant.description}`,
sideEffects: false,
repository: {
type: "git",
url: "https://github.com/justjake/quickjs-emscripten",
},
author: {
name: "Jake Teton-Landis",
url: "https://jake.tl",
},
scripts: {
build: "npm run build:c && npm run build:ts",
"build:c": variant.exports.import && variant.exports.require ? "make" : "make -j2",
"build:ts": "npx tsup",
"check:types": "npx tsc --project . --noEmit",
clean: "make clean",
prepare: "npm run clean && npm run build",
},
files: ["LICENSE", "README.md", "dist/**/*", "!dist/*.tsbuildinfo"],
types: indexExports.types,
main: indexExports.main,
module: indexExports.module,
browser: variant.exports.browser ? "./dist/index.mjs" : undefined,
exports: {
".": {
types: indexExports.types,
import: indexExports.module ?? indexExports.main,
require: js ? "./dist/index.js" : undefined,
default: indexExports.main,
},
"./package.json": "./package.json",
"./ffi":
variant.emscriptenInclusion !== EmscriptenInclusion.AsmJs ? ffiExports : undefined,
"./wasm":
variant.emscriptenInclusion === EmscriptenInclusion.Separate
? "./dist/emscripten-module.wasm"
: undefined,
"./emscripten-module": emscriptenExports,
},
dependencies: {
"@jitl/quickjs-ffi-types": "workspace:*",
},
}
const tsConfig: TsConfig = {
extends: "@jitl/tsconfig/tsconfig.json",
include: ["src/*"],
exclude: ["node_modules"],
}
const typedocConfig: Partial<TypeDocOptions> & { extends?: string; mergeReadme?: boolean } = {
extends: "../../typedoc.base.js",
entryPoints: ["./src/index.ts"],
mergeReadme: true,
}
const finalVariant: FinalVariant = {
basename,
targetName,
dir: path.relative(repoRoot, dir),
packageJson,
variant,
}
if (finalVariant.dir in variantsJson) {
throw new Error(`Duplicate variant dir ${finalVariant.dir}`)
}
variantsJson[finalVariant.dir] = {
...finalVariant,
packageJson: {
...finalVariant.packageJson,
version: "(omitted)",
},
}
await writePretty(path.join(dir, "package.json"), JSON.stringify(packageJson))
await writePretty(path.join(dir, "LICENSE"), renderLicense(targetName, variant))
await writePretty(path.join(dir, "tsconfig.json"), JSON.stringify(tsConfig))
await writePretty(path.join(dir, "typedoc.json"), JSON.stringify(typedocConfig))
await writePretty(path.join(dir, "README.md"), renderReadme(targetName, variant, packageJson))
await writePretty(path.join(dir, "Makefile"), renderMakefile(targetName, variant))
await writePretty(path.join(dir, "tsup.config.ts"), renderTsupConfig(variant, packageJson))
const readmeSummary = renderReadmeSummary(targetName, variant, packageJson)
await writePretty(
path.join(src, "index.ts"),
renderIndexTs(targetName, variant, readmeSummary, packageJson),
)
await writePretty(path.join(src, "ffi.ts"), renderFfiTs(targetName, variant))
coreReadmeVariantDescriptions.push(readmeSummary)
}
}
await writePretty(
path.join(repoRoot, "packages/quickjs-emscripten-core/README.md"),
renderCoreReadme(coreReadmeVariantDescriptions),
)
await writePretty(path.join(repoRoot, "variants.json"), JSON.stringify(variantsJson))
}
const describeInclusion = {
[EmscriptenInclusion.SingleFile]: `The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app.`,
[EmscriptenInclusion.Separate]: `Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant.`,
[EmscriptenInclusion.AsmJs]: `The C library code is compiled to Javascript, no WebAssembly used. Sometimes called "asmjs". This is the slowest possible option, and is intended for constrained environments that do not support WebAssembly, like quickjs-for-quickjs.`,
}
const describeMode = {
[ReleaseMode.Debug]: `Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs.`,
[ReleaseMode.Release]: `Optimized for performance; use when building/deploying your application.`,
}
const DOC_ROOT_URL = `https://github.com/justjake/quickjs-emscripten/blob/main/doc`
const describeSyncMode = {
[SyncMode.Sync]: `The default, normal build. Note that both variants support regular async functions.`,
[SyncMode.Asyncify]: `
Build run through the ASYNCIFY WebAssembly transform.
This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync).
In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host.
The extra magic makes this variant slower than sync variants.
Note that both variants support regular async functions.
Only adopt ASYNCIFY if you need to!
The [QuickJSAsyncRuntime](${DOC_ROOT_URL}/quickjs-emscripten/classes/QuickJSAsyncRuntime.md)
and [QuickJSAsyncContext](${DOC_ROOT_URL}/quickjs-emscripten/classes/QuickJSAsyncContext.md) classes expose the ASYNCIFY-specific APIs.
`
.trim()
.split("\n")
.join(" "),
}
const describeLibrary = {
[CLibrary.QuickJS]: `The original [bellard/quickjs](https://github.com/bellard/quickjs) library.`,
[CLibrary.NG]: `[quickjs-ng](https://github.com/quickjs-ng/quickjs) is a fork of quickjs that tends to add features more quickly.`,
}
const describeModuleFactory = {
[SyncMode.Sync]: `newQuickJSWASMModuleFromVariant`,
[SyncMode.Asyncify]: `newQuickJSAsyncWASMModuleFromVariant`,
}
const describeExport = {
browser: `Exports a browser-compatible ESModule, designed to work in browsers and browser-like environments.`,
require: `Exports a NodeJS-compatible CommonJS module, which is faster to load and run compared to an ESModule.`,
import: `Exports a NodeJS-compatible ESModule. Cannot be imported synchronously from a NodeJS CommonJS module.`,
workerd: `Targets Cloudflare Workers.`,
}
function renderCoreReadme(variantDescriptions: string[]): string {
const template = new TemplateFile(
fs.readFileSync(
path.join(repoRoot, "packages/quickjs-emscripten-core/README.template.md"),
"utf-8",
),
)
template.replace("<!-- __VARIANTS__ -->", variantDescriptions.join("\n\n"))
template.replace(
"__EDIT_THIS_FILE_NOT_README_MD__",
"DO NOT EDIT THIS FILE. Edit README.template.md instead.",
)
return template.text
}
function renderReadmeSummary(
targetName: string,
variant: BuildVariant,
packageJson: PackageJson,
): string {
const baseURL = "https://github.com/justjake/quickjs-emscripten/blob/main/doc"
const packageURL = `${baseURL}/${packageJson.name}/README.md`
const inclusion = describeInclusion[variant.emscriptenInclusion]
const hasExports = Object.keys(variant.exports).join(" ")
return `### ${packageJson.name}
[Docs](${packageURL}) |
${variant.description}
| Variable | Setting | Description |
| -- | -- | -- |
| library | ${variant.library} | ${
describeLibrary[variant.library]
} Version ${getLibraryVersionLink(variant.library)} |
| releaseMode | ${variant.releaseMode} | ${describeMode[variant.releaseMode]} |
| syncMode | ${variant.syncMode} | ${describeSyncMode[variant.syncMode]} |
| emscriptenInclusion | ${variant.emscriptenInclusion} | ${inclusion} |
| exports | ${hasExports} | Has these package.json export conditions |
`
}
function renderReadme(targetName: string, variant: BuildVariant, packageJson: PackageJson): string {
const codeFence = (lang: string, text: string) => `\`\`\`${lang}\n${text}\n\`\`\``
const json = (obj: any) => codeFence("json", JSON.stringify(obj, null, 2))
const create = describeModuleFactory[variant.syncMode]
const hasExports = Object.keys(variant.exports).join(" ")
const exportsList = (Object.keys(variant.exports) as Array<keyof (typeof variant)["exports"]>)
.map((exportName) => `- ${describeExport[exportName]}`)
.join("\n")
return `# ${packageJson.name}
${variant.description}
This generated package is part of [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten).
It contains a variant of the quickjs WASM library, and can be used with quickjs-emscripten-core.
${codeFence(
"typescript",
`
import variant from '${packageJson.name}'
import { ${create} } from 'quickjs-emscripten-core'
const QuickJS = await ${create}(variant)
`,
)}
This variant was built with the following settings:
## Library: ${variant.library}
${describeLibrary[variant.library]}
Version ${getLibraryVersionLink(variant.library)}
## Release mode: ${variant.releaseMode}
${describeMode[variant.releaseMode]}
## Exports: ${hasExports}
Exports the following in package.json for the package entrypoint:
${exportsList}
## Extra async magic? ${variant.syncMode === SyncMode.Asyncify ? "Yes" : "No"}
${describeSyncMode[variant.syncMode]}
## Single-file, or separate .wasm file? ${variant.emscriptenInclusion}
${describeInclusion[variant.emscriptenInclusion]}
## More details
Full variant JSON description:
${json(variant)}
Variant-specific Emscripten build flags:
${json(getCflags(targetName, variant))}
`
}
class TemplateFile {
constructor(public text: string) {}
replace(pattern: string | RegExp, replacement: string) {
const nextText = this.text.replace(pattern, replacement)
if (nextText === this.text) {
throw new Error(`Failed to replace ${pattern} with ${replacement}`)
}
this.text = nextText
}
toString() {
return this.text
}
}
function renderMakefile(targetName: string, variant: BuildVariant): string {
const template = new TemplateFile(
fs.readFileSync(path.join(repoRoot, "templates/Variant.mk"), "utf-8"),
)
const appendEnvVars = (varname: string, flags: string[]) =>
flags.map((flag) => `${varname}+=${flag}`).join("\n")
const emscriptenVersion = variant.emscriptenVersion ?? DEFAULT_EMSCRIPTEN_VERSION
template.replace("REPLACE_EMSDK_VERSION", emscriptenVersion)
template.replace("QUICKJS_LIB=REPLACE_THIS", `QUICKJS_LIB=${variant.library}`)
template.replace(
"CFLAGS_ALL=REPLACE_THIS",
appendEnvVars("CFLAGS_WASM", getCflags(targetName, variant)),
)
template.replace(
"CFLAGS_CJS=REPLACE_THIS",
appendEnvVars("CFLAGS_CJS", getExportCflags(variant, "require")),
)
template.replace(
"CFLAGS_MJS=REPLACE_THIS",
appendEnvVars("CFLAGS_MJS", getExportCflags(variant, "import")),
)
template.replace(
"CFLAGS_BROWSER=REPLACE_THIS",
appendEnvVars("CFLAGS_BROWSER", getExportCflags(variant, "browser")),
)
template.replace(
"CFLAGS_CLOUDFLARE=REPLACE_THIS",
appendEnvVars("CFLAGS_CLOUDFLARE", getExportCflags(variant, "workerd")),
)
template.replace(
"GENERATE_TS_ENV_VARIANT=REPLACE_THIS",
appendEnvVars(
"GENERATE_TS_ENV",
Object.entries(getGenerateTsEnv(targetName, variant)).map(
([key, value]) => `${key}=${value}`,
),
),
)
template.replace("SYNC=REPLACE_THIS", `SYNC=${variant.syncMode.toUpperCase()}`)
const targets: string[] = []
if (variant.exports.browser) {
targets.push("BROWSER")
}
if (variant.exports.import) {
targets.push("MJS")
}
if (variant.exports.require) {
targets.push("CJS")
}
if (variant.exports.workerd) {
targets.push("CLOUDFLARE")
}
template.replace(/^EXPORTS: __REPLACE_THIS__/gm, `EXPORTS: ${targets.join(" ")}`)
if (template.text.includes("REPLACE_THIS")) {
throw new Error(`Didn't replace all REPLACE_THIS in Variant.mk`)
}
return template.text
}
function renderIndexTs(
targetName: string,
variant: BuildVariant,
docCommentContents: string,
packageJson: PackageJson,
): string {
const docComment = docCommentContents
.split("\n")
.map((line) => ` * ${line}`)
.join("\n")
const className = {
[SyncMode.Sync]: "QuickJSFFI",
[SyncMode.Asyncify]: "QuickJSAsyncFFI",
}[variant.syncMode]
const modeName = {
[SyncMode.Sync]: "sync",
[SyncMode.Asyncify]: "async",
}[variant.syncMode]
const variantTypeName = {
[SyncMode.Sync]: "QuickJSSyncVariant",
[SyncMode.Asyncify]: "QuickJSAsyncVariant",
}[variant.syncMode]
if (variant.emscriptenInclusion === EmscriptenInclusion.AsmJs) {
// Eager loading please!
return `
import type { ${variantTypeName} } from '@jitl/quickjs-ffi-types'
import moduleLoader from '${packageJson.name}/emscripten-module'
import { ${className} } from './ffi.js'
/**
${docComment}
*/
const variant: ${variantTypeName} = {
type: '${modeName}',
importFFI: () => Promise.resolve(${className}),
importModuleLoader: () => Promise.resolve(moduleLoader),
} as const
export default variant
`
}
return `
import type { ${variantTypeName} } from '@jitl/quickjs-ffi-types'
/**
${docComment}
*/
const variant: ${variantTypeName} = {
type: '${modeName}',
importFFI: () => import('./ffi.js').then(mod => mod.${className}),
importModuleLoader: () => import('${packageJson.name}/emscripten-module').then(mod => mod.default),
} as const
export default variant
`
}
function renderFfiTs(targetName: string, variant: BuildVariant): string {
const env = getGenerateTsEnv(targetName, variant)
return buildFFI(...createContext(env))
}
function renderLicense(targetName: string, variant: BuildVariant): string {
const baseLicense = fs.readFileSync(path.join(repoRoot, "LICENSE"), "utf-8")
const libraryLicense = fs.readFileSync(
path.join(repoRoot, CLibrarySubtree[variant.library], "LICENSE"),
"utf-8",
)
return `quickjs-emscripten:\n${baseLicense}\n\n${variant.library}:\n${libraryLicense}`
}
function getTsupExtensions(variant: BuildVariant) {
const wantsESM = Boolean(variant.exports.import || variant.exports.browser)
const wantsCJS = Boolean(variant.exports.require)
return {
js: wantsCJS,
mjs: wantsESM,
}
}
function renderTsupConfig(variant: BuildVariant, packageJson: PackageJson): string {
const { js, mjs } = getTsupExtensions(variant)
const external: string[] = []
const needsExternal =
[variant.exports.browser, variant.exports.import, variant.exports.require].filter(Boolean)
.length > 1
if (needsExternal) {
external.push(`${packageJson.name}/emscripten-module`)
}
const entry = ["src/index.ts"]
if (variant.emscriptenInclusion !== EmscriptenInclusion.AsmJs) {
entry.push("src/ffi.ts")
}
const formats = [mjs && "esm", js && "cjs"].filter(Boolean)
return `
import { extendConfig } from "@jitl/tsconfig/tsup.base.config.js"
export default extendConfig({
entry: ${JSON.stringify(entry)},
external: ${JSON.stringify(external)},
format: ${JSON.stringify(formats)},
clean: false,
})
`
}
function createContext(merged: Partial<Context> = {}) {
const context = new Context()
Object.assign(context, merged)
const matches = getMatches(context).matches
return [context, matches] as const
}
function getTargetPackageSuffix(targetName: string, variant: BuildVariant): string {
const { releaseMode, syncMode, library } = variant
const filename = [
library, // quickjs
targetName, // node-cjs
releaseMode, // debug
syncMode, // sync
].join("-")
return filename
}
const CLibrarySubtree: Record<CLibrary, string> = {
quickjs: "vendor/quickjs",
"quickjs-ng": "vendor/quickjs-ng",
}
const CLibraryGithubRepo: Record<CLibrary, string> = {
quickjs: "bellard/quickjs",
"quickjs-ng": "quickjs-ng/quickjs",
}
// Libraries that use release tags (from VERSION file) instead of git subtree SHA
const CLibraryUsesTagVersion: Record<CLibrary, boolean> = {
quickjs: false,
"quickjs-ng": true,
}
function getLibraryVersionLink(library: CLibrary): string {
if (getLibraryVersionMemo.has(library)) {
return getLibraryVersionMemo.get(library)!
}
const subtreePath = CLibrarySubtree[library]
const githubRepo = CLibraryGithubRepo[library]
const usesTagVersion = CLibraryUsesTagVersion[library]
let version = "git"
try {
version = fs.readFileSync(path.join(subtreePath, "VERSION"), "utf-8").trim()
} catch (err) {
const error = err as NodeJS.ErrnoException
if (error.code === "ENOENT") {
// pass
} else {
throw error
}
}
let result: string
if (usesTagVersion && version !== "git") {
// Link to the release tag instead of a commit SHA
result = `[${version}](https://github.com/${githubRepo}/releases/tag/${version}) vendored to quickjs-emscripten.`
} else {
// Use git subtree SHA for commit link
const { sha, date } = getGitSubtreeSha(subtreePath)
result = `[${version}+${sha.slice(
0,
8,
)}](https://github.com/${githubRepo}/commit/${sha}) vendored to quickjs-emscripten on ${date}.`
}
getLibraryVersionMemo.set(library, result)
return result
}
const getLibraryVersionMemo = new Map<CLibrary, string>()
function getGitSubtreeSha(subtree: string) {
const log = child_process.execFileSync(
"git",
[
"log",
`--all-match`,
`--grep=git-subtree-dir: ${subtree}$`,
`--grep=git-subtree-split:`,
`--date=format:%Y-%m-%d`,
"-1",
],
{
encoding: "utf-8",
},
)
const sha = log.match(/git-subtree-split: ([^\n]+)/)?.[1]
const date = log.match(/Date: ([^\n]+)/)?.[1]
if (!sha || !date) {
throw new Error(`${subtree}: date or git-subtree-split not found in log: \n${log}`)
}
return { sha: sha.trim(), date: date.trim() }
}