Merge remote-tracking branch 'origin/main' into roc-build-default-app

# Conflicts:
#	src/lir/lir_image.zig

Author: rtfeldman

.github/workflows/ci_zig_nix.yml

@@ -33,6 +33,10 @@ jobs:
       - uses: cachix/install-nix-action@02a151ada4993995686f9ed4f1be7cfbb229e56f # ratchet:cachix/install-nix-action@v31
         with:
           nix_path: nixpkgs=channel:nixos-25.05
+          extra_nix_config: |
+              min-free = 1073741824
+              max-free = 5368709120
+              # When free space drops below min-free (1 GB), nix GCs until max-free (5 GB) is available. This avoids "No space left on device" on CI.
 
       - name: Build inside a nix dev shell
         uses: ./.github/actions/flaky-retry

build.zig

@@ -3831,6 +3831,51 @@ pub fn build(b: *std.Build) void {
     );
     run_lir_inline_test_step.dependOn(&run_lir_inline_test.step);
 
+    const trmc_lir_test = b.addTest(.{
+        .name = "trmc_lir_test",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/eval/test/trmc_lir_test.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+        .filters = test_filters,
+    });
+    roc_modules.addAll(trmc_lir_test);
+    trmc_lir_test.root_module.addImport("compiled_builtins", compiled_builtins_module);
+    trmc_lir_test.step.dependOn(&write_compiled_builtins.step);
+    try addLlvmSupportToStep(
+        b,
+        trmc_lir_test,
+        target,
+        use_system_llvm,
+        user_llvm_path,
+        roc_modules,
+        llvm_codegen_module,
+        llvm_embedded_module,
+        zstd,
+    );
+    if (trmc_lir_test.root_module.resolved_target.?.result.os.tag != .windows or
+        trmc_lir_test.root_module.resolved_target.?.result.abi != .msvc)
+    {
+        trmc_lir_test.root_module.link_libcpp = true;
+    }
+    add_tracy(b, roc_modules.build_options, trmc_lir_test, target, true, flag_enable_tracy);
+    build_test_zig_step.dependOn(&trmc_lir_test.step);
+
+    const run_trmc_lir_test = b.addRunArtifact(trmc_lir_test);
+    if (run_args.len != 0) {
+        run_trmc_lir_test.addArgs(run_args);
+    }
+
+    tests_summary.addRun(&run_trmc_lir_test.step);
+
+    const run_trmc_lir_test_step = b.step(
+        "run-test-zig-trmc-lir",
+        "Run TRMC LIR Zig tests",
+    );
+    run_trmc_lir_test_step.dependOn(&run_trmc_lir_test.step);
+
     // Add CLI test
     const enable_cli_tests = b.option(bool, "cli-tests", "Enable cli tests") orelse true;
     if (enable_cli_tests) {

design.md

@@ -2740,12 +2740,11 @@ that value kind must be added explicitly here with a checked cache rule.
 - function values
 
 Compile-time evaluation failures are owned by checking finalization because the
-module has not been output yet. User-written compile-time crashes, exhausted
-compile-time limits, invalid compile-time host interaction, and unsupported
-compile-time operations become checking diagnostics attached to the checked root
-being finalized. OOM remains OOM. A post-check invariant failure while lowering
-or interpreting a compile-time root is still a compiler bug, not a user-facing
-diagnostic.
+module has not been output yet. User-written compile-time crashes, invalid
+compile-time host interaction, and unsupported compile-time operations become
+checking diagnostics attached to the checked root being finalized. OOM remains
+OOM. A post-check invariant failure while lowering or interpreting a
+compile-time root is still a compiler bug, not a user-facing diagnostic.
 
 While storing an eval result, the builder may reserve a `ConstNodeId` before
 storing its children so repeated references to the same acyclic runtime value

docs/langref/iterators.md

@@ -0,0 +1 @@
+# Iterators

docs/langref/loops.md

@@ -4,16 +4,37 @@ Loops let you run the same code multiple times, in...well, in a loop.
 
 ## `for` Loops
 
-A `for` loop iterates over each item in a list:
+A `for` loop lets you run code on each item in an [iterator](iterators). For example:
 
 ```roc
 var $sum = 0
+
+for n in 1.to(5) {
+    $sum = $sum + n
+}
+```
+
+> The `to` method returns a [range](numbers#ranges) which is an `Iter` of the number in question. For example, [`I64.to`](builtins/I64#to) returns `Iter(I64)`, and so `n` in this example would be an `I64`.
+
+A loop body only includes statements; it does not have a final expression. The loop itself evaluates to `{}`.
+
+### Iterating over types that have `iter`
+
+`for` can also be used on types that have an `iter` method, as long as that method returns an [`Iter`](builtins/Iter). For example, [`List`](builtins/list) has (`List.iter`)[builtins/List#iter], so you can do a `for` loop over a list:
+
+```roc
+var $sum = 0
+
 for n in [1, 2, 3, 4] {
     $sum = $sum + n
 }
 ```
 
-The item can be destructured inline:
+At runtime, this `[1, 2, 3, 4]` code snippet is exactly as efficient as the earlier `1.to(5)` one. In one case, `1.to(5)` will be evaluated to an `Iter` at compile time, and in the other, `[1, 2, 3, 4].iter()` will be evaluated at compile time to an identical `Iter`. By the time either program actually runs, they will have the same memory contents and will be executing the same instructions.
+
+### Pattern matching in `for`
+
+Whatever you put between `for` and `in` is treated as a [pattern](pattern-matching), meaning (for example) that the item can be destructured inline:
 
 ```roc
 var $total = 0
@@ -22,7 +43,7 @@ for (x, y) in [(1, 2), (3, 4), (5, 6)] {
 }
 ```
 
-Use `_` if you don't want to name the item:
+As usual, you can nest patterns as much as you like, and can use `_` if you don't want to name a pattern:
 
 ```roc
 var $count = 0
@@ -31,7 +52,16 @@ for _ in items {
 }
 ```
 
-A loop body only includes statements; it does not have a final expression. The loop itself evaluates to `{}`.
+Just like with [assignments](statements#assignments), the pattern you use here must be [exhaustive](pattern-matching#exhaustiveness). For example, the following would give an exhaustiveness error because the loop body couldn't know what value to use for `amount_to_add` if the item was ever `Err` at runtime:
+
+```roc
+var $count = 0
+for Ok(amount_to_add) in items {
+    $count = $count + amount_to_add
+}
+```
+
+If you can't write an exhaustive pattern-match, you can name the entire iterator item and then use [`match`](pattern-matching#match) on it inside the loop body.
 
 ## `while` Loops