Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Clarify compilation pipeline stages, partition thresholds, and build performance in documentation

Aperta
  • Qualcosa non va?
#1,340 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@espetro ci sta già lavorando.

Dal 18/10/2026.

  • #1343 di @espetro — aperta

Valutazione

Difficoltà
1/5
Tempo stimato
1-3 ore
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
typescript
Ambito
documentation

Direzione di ricerca

The proposed changes are in docs/content/docs/how-it-works.mdx and docs/content/docs/cli.mdx. Read the existing LLVM backend and --optimization sections, then check that the documentation explains the 4 MiB threshold, serial compilation cases, frontend and backend work, and the dev build speed trade-off. The issue links open PR #1343, so the work is already underway.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

docs/content/docs/how-it-works.mdx notes that "Large executables… are divided into partitions that are optimized and compiled in parallel", but the public documentation does not describe the operational details of when and how compilation scales.

Developers and AI coding agents trying to optimize build times or understand CPU/core utilization in CI and local development frequently assume that compilation is parallelized across cores or wonder why builds run serially (~100–120% CPU) on typical inputs.

Key Operational Characteristics

Investigation of the compilation pipeline highlights several operational realities that would be valuable to document:

  1. The 4 MiB Partition Threshold:
    Partitioning is controlled by nativeProgramPartitions (packages/compiler/src/backend/native-codegen-core.ts), which requires textual LLVM IR to exceed 4 MiB (required < 2 → 1).

    • Small-to-medium programs (and synthetics with up to thousands of functions) typically emit < 4 MiB of LLVM IR and run through a single serial module in the backend.
    • Non-executable emission (--emit=asm, --emit=obj) and library builds (scriptc build --lib) never partition regardless of size.

  2. Frontend vs Backend Distribution:
    The compiler frontend (TypeScript parsing, type checking, typed IR lowering, and .ll text serialization) runs serially in Node.js/V8. For typical applications, the frontend dominates compilation wall time. Concurrency in the backend LLVM helper does not affect this stage.

  3. Automatic Backend Concurrency & Optimization Trade-offs:
    When partitions do exist (> 4 MiB), the backend helper compiles them concurrently across the host's CPU cores automatically.

    • dev (-O0): Designed for fast local iteration. Skips heavy optimization passes, and when partitions exist, compiles them independently with near-linear multi-core scaling.
    • release (-O2): When an executable is small enough for a single partition, it imports precompiled runtime bitcode (--import-bitcode) to inline small runtime functions directly into application code. Executables large enough to be partitioned skip runtime bitcode inlining to bound build time and binary size, instead using ThinLTO summaries across partitions.
Proposed Documentation Updates

We can clarify these mechanics with surgical updates to existing documentation without adding new top-level pages:

  1. In docs/content/docs/how-it-works.mdx:

    • Clarify the 4 MiB LLVM IR threshold in step 3 ("LLVM backend") and state that smaller executables, --emit=asm|obj, and --lib compile serially as a single partition.
    • Add a concise ### Build performance and scaling subsection explaining frontend vs backend distribution, --optimization=dev for fast iteration, and release inlining trade-offs.

  2. In docs/content/docs/cli.mdx:

    • Under --optimization, emphasize that dev (-O0) optimizes for build speed and fast iteration.

I have prepared a PR with these contained doc updates and will link it below.

Lingua principale
TypeScript
Stelle
6.2k
Fork
183
Merge medio
2h 20m
PR unite (30g)
893

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di vercel-labs/scriptc

Tutte le issue di vercel-labs/scriptc

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.