Skip to content

README.md

Latest commit

 

History

History
105 lines (87 loc) · 7.12 KB

README.md

File metadata and controls

105 lines (87 loc) · 7.12 KB

docs

The source-of-truth documentation for Sigil / Silicon. The published docs site under website/ renders these pages; keep edits here and let the sync script propagate them.

If you're new, start with getting-started.md.

Guide — learning materials

File What's in it
getting-started.md 15-minute install-to-running-program walkthrough
positioning.md What Silicon is for, who it's for, and where it's competitive — the elevator pitch (outward-facing companion to ADR 0023)
overview.md Language tour (Go-Tour / Odin-overview style) — types, control flow, data, generics, closures, async/await, host-API FFI (object handles + generated modules), stdlib, platforms, strata
stdlib.md Standard library reference — io / num / str / mem and the shipped data structures
targets.md WASM vs native targets — I/O, string layout, @extern patterns
memory.md Arenas, with_arena, parent-arena escape, Rc<T>
strata-authoring-guide.md Step-by-step for writing a new stratum

Reference — language and compiler

File What's in it
grammar.ebnf ISO/IEC 14977 EBNF grammar (authoritative)
automatic-semicolon-insertion.html Conservative automatic semicolon insertion rules and examples
hm-lite.md Type inference reference (HM restricted to declared polymorphism)
optional-signatures-inference.md Optional function signatures — monomorphic, call-site inference; per-compilation-unit scope; library-API guidance
diagnostics.md Error-code catalogue, caret rendering, hint format
strata.md Strata system — how @stratum dispatches to pipeline phases
strata-2.0-spec.html Strata 2.0 capability specification (implemented)
compiler-api.md The Compiler::* surface that strata bodies call
compiler-as-a-service.md The library-first compiler API (Roslyn-style)
caas-roslyn-parity.md CaaS gap tracker — what's left to reach Roslyn-level IDE API coverage
lsp-completion-plan.md Plan: LSP autocomplete for stdlib/modules + third-party libs + snippets (@fn stub-out)
lsp-completeness-plan.md What's left for a full LSP server — phased, prioritized tracker (correctness spine, missing methods, lifecycle, editor shipping) with file-level entry points
js-string-builtins.md The JSString type, WASM JS String Builtins, and the web/bun platform (--platform)
api-boundaries.md Per-subsystem import rules; public vs internal
struct-design.md @struct design and layout rules
extern-out-pointer.md @extern out-pointer ABI
struct-ffi.md Struct-by-value FFI design proposal (not yet implemented)
ffi-coverage-gaps.md The remaining ~7% of host-API bind coverage — per-category root cause + adapter work needed (mostly one classifier seam)
bun-shell-ffi-plan.md Plan: properly support Bun.$ (the last skip) via a general js::tagged primitive + a shell.si stdlib — security-driven (preserve the substitution boundary)
signature-lines.md Separate \\ name: type signature lines; bare params, externs-as-signatures (proposal)
signature-lines-migration.md Codemod + phased rollout plan for the signature-lines change (proposal)
use-includes.md @use 'path.si'; resolution semantics
comptime-via-compilation.md The Zig-style comptime engine design
lockfile-format.md sgl.lock format spec (story 6b-13)
qbe-self-host-plan.md The chosen long-term plan: self-host Silicon to native via QBE, retiring Bun (proposal)
replacing-bun.md Cheap interim: drop Bun from the shipped binary via Deno compile (proposal)

Stability — what's promised, what isn't

File What's in it
stability.md Stable / unstable / will-not-be-added surfaces per layer
security.md Threat model + disclosure address (story 10b-4)
performance.md 1.0 perf baseline + regression methodology (10b-5)
adr/ Architectural Decision Records (0001–0013)

Roadmap — what's planned

File What's in it
v1-feature-status.md Verified v1 feature/shipped-status table (critical path + broader surface + deferred), as of the current branch
v1.0-implementation-roadmap.html Ordered build plan for the FFI gate, monomorphization, and the capability model — critical-path timeline + per-item subtasks
v1-user-stories.html v1.0 story tracker — all closed as of 2026-05-28
v1.1-user-stories.html v1.1 work — LSP, package registry, interpreter, etc.
language-server-plan.html LSP — original v1-alpha design record (shipped + superseded; see caas-roslyn-parity.md E3)
silicon_standard_library_v_1.md Design target for the v1.x stdlib expansion
aaa-big-plan.md Short planning note (working draft)

Launch + release artefacts

File What's in it
launch/1.0-announcement.md Long-form blog post for the 1.0 launch
launch/submissions.md HN / Reddit / Lobste.rs / Mastodon distribution checklist
release/ Changesets workflow + per-release notes

Non-engineering

File What's in it
investor-pitch.html Pitch deck (non-engineering audience)

Historical / archived

archive/ holds documents that no longer describe how the compiler works — the boot/ era bootstrap plans, shipped-design docs whose content has been absorbed into the live reference, and explicit "brainstorming" docs that were never implemented. See archive/README.md for the index and the re-activation protocol.

Editing

  • All Markdown is GitHub-flavoured; HTML files are self-contained pages with inline styling (no external CSS).
  • The site at website/src/ re-renders these via website/scripts/sync-docs.ts; update that script's SYNCS table when you add a new page that should appear on the published site.
  • ADRs use the template at adr/0000-template.md.
  • For new launch / release notes, follow the structure of the existing files under launch/ and release/.