EnglishFrançais

Amalgame — User Guide

A complete reference for users and contributors. If you just want to write Amalgame, start at chapter 1 and keep going. If you're here to hack on the compiler itself, jump to chapter 7.

🇬🇧 🇫🇷 The whole guide is bilingual: every chapter exists in English (NN-….md) and French (NN-….fr.md). On docs.amalgame.me the language is picked automatically, with a toggle on every page.

Table of contents

  1. Getting started — install, hello world, the compile-then-link rhythm.
  2. Language tour — every feature with runnable snippets: types, classes, generics, pattern matching, decorators…
  3. CLI reference — every amc flag, exit codes, typical workflows, debugging tips.
  4. Standard library — Console, File, Path, IO.FileWatcher, Math, Math.Vec (Vec3/Vec4/Mat4), String, List/Map/Set, Http, Tcp, Net.WebSocket, Json, Formats.Yaml, Formats.MsgPack, Random, Encoding, DateTime, Crypto, Regex, Compress, Logging, Service, Database.SQLite, Database.DuckDB.
  5. Runtime & C interop — memory model, bdwgc, mapping types to C, calling C from Amalgame, inline-C blocks (@c { … }) since v0.7.4.
  6. Build & tooling — build_amc.sh, the snapshot bootstrap, CI, releases, and the amc dap debugger (v0.8.0+).
  7. Compiler internals — how amc is structured, adding a builtin, adding a syntax form, adding a CGen rule.
  8. LLM commands — amc migrate, amc generate, amc explain: providers, env vars, caching, design rationale.
  9. amalgame-ui-web — desktop GUI binding over the OS webview (WebView2 / WKWebView / WebKitGTK). Five sub-chapters: getting started, widget catalogue, events + partial-DOM updates, layout + theming, escape hatches.
  10. Cookbook — idiomatic snippets for the patterns you'll need every day: strings, collections, files + JSON, CLI arg parsing, processes, networking, pattern matching, threads, inline-C primitives.
  11. Web framework (Mosaic) — the amalgame-web server framework: routing, WebContext/HttpResponse, middleware (security headers, CORS, CSRF, rate limit), sessions, static files, HTTP/1.1 + HTTPS. (Distinct from chapter 9's desktop GUI.)
  12. Using packages — the external-package workflow: find, add, use, update, lockfile + reproducible CI builds, and troubleshooting. (Reference lives in chapter 3.)
  13. Async & concurrency — async fn/await sugar (v0.8.70) and the amalgame-async runtime: fibers, channels, the cooperative scheduler, non-blocking I/O.
  14. Testing — the framework-free *_test.am / [PASS]/[FAIL]/[SKIP] convention, running amc test, and how to organise suites.
  15. Editor tooling & debugging — amc lsp (the language-server feature set + editor setup) and amc dap (breakpoints/stepping in .am source, the bridge, -g).
  16. Hosting with Mosaic — taking a Mosaic server to production: many sites on one host (dispatch by Host), Let's Encrypt certs + SNI, running under systemd, and cert renewal that actually works.

The repo's README has the elevator pitch and screenshots. The ROADMAP tracks what's planned next.