sm

specs.md

@@ -1582,6 +1582,58 @@ response :: format("HTTP/1.1 200 OK\r\nContent-Length: {}\r\n\r\n{}", body.len,
 
 This works for any function, not just `format`. The mechanism is general: the VM compiles the function body (including `#insert` directives, variadic `..Any` args, and calls to other functions) and executes it entirely at compile time. If the VM encounters something it cannot evaluate (e.g., foreign function calls, unsupported operations), it silently falls through to runtime codegen.
 
+### Build Configuration
+
+The `BuildOptions` struct (from `modules/compiler.sx`) provides compile-time build configuration via `#run`. Methods on `BuildOptions` are compiler builtins intercepted during compilation — they have no runtime cost.
+
+```sx
+#import "modules/compiler.sx";
+
+configure_build :: () {
+    opts := build_options();
+    opts.add_link_flag("-lm");
+    opts.set_output_path("out/my_program");
+
+    inline if OS == .wasm {
+        opts.set_output_path("sx-out/wasm/app.html");
+        opts.add_link_flag("-sUSE_SDL=3");
+        opts.add_link_flag("-sALLOW_MEMORY_GROWTH=1");
+    }
+}
+#run configure_build();
+```
+
+**API:**
+
+| Method | Description |
+|--------|-------------|
+| `build_options()` | Returns a `BuildOptions` value for the current compilation |
+| `opts.add_link_flag(flag)` | Appends a linker flag (merged with CLI flags) |
+| `opts.set_output_path(path)` | Sets the output binary path (overridden by CLI `-o`) |
+
+Build flags from `add_link_flag` are merged with any flags passed on the command line. Duplicate library flags (e.g., `-lSDL3` from multiple imports) are automatically deduplicated.
+
+### Compiler Constants
+
+The `modules/compiler.sx` module provides compile-time constants set by the compiler based on the target:
+
+| Constant | Type | Description |
+|----------|------|-------------|
+| `OS` | `OperatingSystem` | Target OS: `.macos`, `.linux`, `.windows`, `.wasm`, `.unknown` |
+| `ARCH` | `Architecture` | Target arch: `.aarch64`, `.x86_64`, `.wasm32`, `.unknown` |
+| `POINTER_SIZE` | `s64` | Pointer width in bytes (8 for 64-bit, 4 for wasm32) |
+
+These are used with `inline if` for compile-time conditional compilation:
+
+```sx
+inline if OS == .wasm {
+    // Only compiled when targeting wasm
+}
+inline if POINTER_SIZE == 8 {
+    // Only compiled on 64-bit platforms
+}
+```
+
 ---
 
 ## 9. Modules / Imports
@@ -1658,7 +1710,43 @@ main :: () -> s32 {
 
 ---
 
-## 10. Program Structure
+## 10. CLI & Cross-Compilation
+
+### Commands
+
+```
+sx run <file.sx>       Compile and run
+sx build <file.sx>     Compile to binary
+sx lsp                 Start language server (LSP)
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--target <target>` | Target triple or shorthand (default: host) |
+| `--cpu <name>` | CPU name (default: generic) |
+| `--opt <level>` | Optimization: `none`/`0`, `less`/`1`, `default`/`2`, `aggressive`/`3` |
+| `-o <path>` | Output path (overrides `set_output_path`) |
+
+### Target Shorthands
+
+The `--target` flag accepts shorthand aliases for common targets:
+
+| Shorthand | Expands to |
+|-----------|-----------|
+| `wasm`, `emscripten` | `wasm32-unknown-emscripten` |
+| `macos`, `macos-arm` | `aarch64-apple-macos` |
+| `macos-x86` | `x86_64-apple-macos` |
+| `linux`, `linux-x86` | `x86_64-unknown-linux-gnu` |
+| `linux-arm` | `aarch64-unknown-linux-gnu` |
+| `windows` | `x86_64-windows-msvc` |
+
+Full triples are also accepted and passed through as-is.
+
+---
+
+## 11. Program Structure
 
 A program is a sequence of top-level declarations and `#import` directives. Execution begins at `main`.
 
@@ -1672,7 +1760,7 @@ main :: () {
 
 ---
 
-## 11. Grammar (informal)
+## 12. Grammar (informal)
 
 ```
 program         = top_level*
@@ -1731,7 +1819,7 @@ type            = '$' IDENT | 's32' | 'f32' | 'f64' | 'bool' | 'string'
 
 ---
 
-## 12. Open Questions
+## 13. Open Questions
 
 - **Nested functions**: Can functions be defined inside other functions?
 - **Operator overloading**: Not shown — presumably no.