Skip to content

README.md

Latest commit

 

History

History
60 lines (54 loc) · 3.46 KB

README.md

File metadata and controls

60 lines (54 loc) · 3.46 KB
Raw

Spinel documentation

User documentation for Spinel, the whole-program ahead-of-time Ruby→C compiler. Start here, then open the topic you need.

For users

  • spin.md -- projects and packages with spin: scaffold, dependencies (path / git / index), lockfile, tests, vendoring, and native C in packages. Start here to build anything bigger than one file.
  • limitations.md -- what an AOT compiler can and cannot do. The honest catalogue of where Spinel differs from CRuby, and why. Read this first if something behaves unexpectedly.
  • require.md -- how require works: which stdlib needs which require, what an absent or unsatisfiable require does, and how to provide a feature of your own with -I.
  • FFI.md -- call C functions directly from Spinel Ruby, with no extension build step: declarations in the source become direct C call sites.
  • rbs-extract.md -- seed the type inferencer with .rbs signatures via spinel --rbs DIR: the supported RBS subset, what a seed buys, and why a seed is an assertion you are trusted to get right rather than a hint.
  • float-rounding.md -- the return type of Float#ceil/#floor/#round/#truncate, where Spinel's static typing meets CRuby's value-dependent rule.
  • int-overflow.md -- --int-overflow=raise|wrap|promote: what happens when an Integer crosses Spinel's machine-word boundary (64 bits on a 64-bit target, 32 on i386 and wasm32), and how the width follows the target.
  • emit-types.md -- --emit-types: every typed node's span, kind, name and RBS, and the diagnostics (the widened slot, the refusals) as JSON, for editor tools.
  • wasm.md -- --target=wasm32-wasi: the program as a WebAssembly module for wasmtime, Node or a browser, what it needs (the wasi-sdk, make wasm-rt) and what the target does without.
  • profiling.md -- where the time goes (--profile plus any frame-pointer sampler) and where the allocations come from (SPINEL_ALLOC_REPORT, with per-site attribution).
  • ../tools/README.md -- the in-tree companion tools: spinel-doctor (one health report per program: build, silent degradations, inference, and static performance advice), spinel-reduce (minimal-repro reducer), spinel-flatten.
  • thread.md -- Thread as true M:N parallelism with no GVL: the execution model, the supported API, and the data-race semantics that follow from having no global lock.

Internals

How the compiler is built and where it is going. Not needed to use Spinel.

  • internals/AST.md -- the text AST the parser emits and the rest of the compiler consumes.
  • internals/analyze-ir.md -- the analyze ↔ codegen contract (the shared in-memory Compiler model).
  • internals/gc.md -- the collector: two heaps, the marker byte that identifies a heap string, explicit roots, a full mark with a generational sweep, and the limits that follow from having no write barrier.
  • internals/thread-mn-design.md -- the M:N thread scheduler: green threads on the fiber substrate, per-worker run queues and work stealing, stop-the-world GC, the preemption monitor. A working document, not a user guarantee (the user contract is in thread.md).