Merge pull request 'Integrate file system I/O with the std.Io interface' (#339) from std_Io into main

Reviewed-on: https://codeberg.org/ziglings/exercises/pulls/339

README.md

@@ -86,6 +86,7 @@ that if you update one, you may need to also update the other.
 
 ### Version Changes
 
+* *2025-12-28 zig 0.16.0-dev.1859 - file system I/O integrated with the std.Io interface, see [#30232](https://codeberg.org/ziglang/zig/pulls/30232)
 * *2025-11-01* zig 0.16.0-dev.1204 - more changes due to new I/O API, see [#25592](https://github.com/ziglang/zig/pull/25592)
 * *2025-09-24* zig 0.16.0-dev.377 - Enable passing file content as args, see [#25228](https://github.com/ziglang/zig/pull/25228)
 * *2025-09-03* zig 0.16.0-dev.164 - changes in reader, see [#25077](https://github.com/ziglang/zig/pull/25077)
@@ -233,7 +234,7 @@ Zig Core Language
 * [x] Sentinel termination
 * [x] Quoted identifiers @""
 * [x] Anonymous structs/tuples/lists
-* [ ] Async <--- ironically awaiting upstream Zig updates
+* [ ] Async I/O
 * [X] Interfaces
 * [X] Bit manipulation
 * [X] Working with C

build.zig

@@ -15,7 +15,7 @@ const print = std.debug.print;
 //     1) Getting Started
 //     2) Version Changes
 comptime {
-    const required_zig = "0.16.0-dev.1204";
+    const required_zig = "0.16.0-dev.1859";
     const current_zig = builtin.zig_version;
     const min_zig = std.SemanticVersion.parse(required_zig) catch unreachable;
     if (current_zig.order(min_zig) == .lt) {
@@ -24,7 +24,7 @@ comptime {
             \\
             \\Ziglings requires development build
             \\
-            \\{}
+            \\{s}
             \\
             \\or higher.
             \\
@@ -34,7 +34,7 @@ comptime {
             \\
             \\
         ;
-        @compileError(std.fmt.comptimePrint(error_message, .{min_zig}));
+        @compileError(std.fmt.comptimePrint(error_message, .{required_zig}));
     }
 }
 
@@ -123,10 +123,12 @@ pub const logo =
 const progress_filename = ".progress.txt";
 
 pub fn build(b: *Build) !void {
+    const io = b.graph.io;
+
     if (!validate_exercises()) std.process.exit(2);
 
     use_color_escapes = false;
-    if (std.fs.File.stderr().supportsAnsiEscapeCodes()) {
+    if (try std.Io.File.stderr().supportsAnsiEscapeCodes(io)) {
         use_color_escapes = true;
     } else if (builtin.os.tag == .windows) {
         const w32 = struct {
@@ -245,9 +247,9 @@ pub fn build(b: *Build) !void {
     }
 
     if (reset) |_| {
-        std.fs.cwd().deleteFile(progress_filename) catch |err| {
+        std.Io.Dir.cwd().deleteFile(io, progress_filename) catch |err| {
             switch (err) {
-                std.fs.Dir.DeleteFileError.FileNotFound => {},
+                std.Io.Dir.DeleteFileError.FileNotFound => {},
                 else => {
                     print("Unable to remove progress file, Error: {}\n", .{err});
                     return err;
@@ -268,17 +270,20 @@ pub fn build(b: *Build) !void {
 
     var starting_exercise: u32 = 0;
 
-    if (std.fs.cwd().openFile(progress_filename, .{})) |progress_file| {
+    if (std.Io.Dir.cwd().openFile(io, progress_filename, .{})) |progress_file| {
-        defer progress_file.close();
+        defer progress_file.close(io);
 
-        const progress_file_size = try progress_file.getEndPos();
+        const progress_file_size = try progress_file.length(io);
 
         var gpa = std.heap.GeneralPurposeAllocator(.{}){};
         defer _ = gpa.deinit();
         const allocator = gpa.allocator();
         const contents = try allocator.alloc(u8, progress_file_size);
         defer allocator.free(contents);
-        const bytes_read = try progress_file.read(contents);
+        var file_buffer: [1024]u8 = undefined;
+        var file_reader = progress_file.reader(io, &file_buffer);
+        // try file_reader.interface.readSliceAll(contents);
+        const bytes_read = try file_reader.interface.readSliceShort(contents);
         if (bytes_read != progress_file_size) {
             return error.UnexpectedEOF;
         }
@@ -286,7 +291,7 @@ pub fn build(b: *Build) !void {
         starting_exercise = try std.fmt.parseInt(u32, contents, 10);
     } else |err| {
         switch (err) {
-            std.fs.File.OpenError.FileNotFound => {
+            std.Io.File.OpenError.FileNotFound => {
                 // This is fine, may be the first time tests are run or progress have been reset
             },
             else => {
@@ -382,15 +387,15 @@ const ZiglingStep = struct {
 
     fn run(self: *ZiglingStep, exe_path: []const u8, _: std.Progress.Node) !void {
         resetLine();
-        print("Checking: {s}\n", .{self.exercise.main_file});
-
         const b = self.step.owner;
+        const io = b.graph.io;
+
+        print("Checking: {s}\n", .{self.exercise.main_file});
 
         // Allow up to 1 MB of stdout capture.
         const max_output_bytes = 1 * 1024 * 1024;
 
-        const result = Child.run(.{
+        const result = Child.run(b.allocator, io, .{
-            .allocator = b.allocator,
             .argv = &.{exe_path},
             .cwd = b.build_root.path.?,
             .cwd_dir = b.build_root.handle,
@@ -409,6 +414,7 @@ const ZiglingStep = struct {
 
     fn check_output(self: *ZiglingStep, result: Child.RunResult) !void {
         const b = self.step.owner;
+        const io = b.graph.io;
 
         // Make sure it exited cleanly.
         switch (result.term) {
@@ -456,14 +462,15 @@ const ZiglingStep = struct {
         const progress = try std.fmt.allocPrint(b.allocator, "{d}", .{self.exercise.number()});
         defer b.allocator.free(progress);
 
-        const file = try std.fs.cwd().createFile(
+        const file = try std.Io.Dir.cwd().createFile(
+            io,
             progress_filename,
             .{ .read = true, .truncate = true },
         );
-        defer file.close();
+        defer file.close(io);
 
-        try file.writeAll(progress);
+        try file.writeStreamingAll(io, progress);
-        try file.sync();
+        try file.sync(io);
 
         print("{s}PASSED:\n{s}{s}\n\n", .{ green_text, output, reset_text });
     }
@@ -532,7 +539,7 @@ const ZiglingStep = struct {
             .exe => self.exercise.name(),
             .@"test" => "test",
         };
-        const sep = std.fs.path.sep_str;
+        const sep = std.Io.Dir.path.sep_str;
         const root_path = exe_dir.?.root_dir.path.?;
         const sub_path = exe_dir.?.subPathOrDot();
         const exe_path = b.fmt("{s}{s}{s}{s}{s}", .{ root_path, sep, sub_path, sep, exe_name });
@@ -558,6 +565,8 @@ const ZiglingStep = struct {
 
     fn printErrors(self: *ZiglingStep) void {
         resetLine();
+        const b = self.step.owner;
+        const io = b.graph.io;
 
         // Display error/warning messages.
         if (self.step.result_error_msgs.items.len > 0) {
@@ -575,7 +584,10 @@ const ZiglingStep = struct {
         else
             .off;
         if (self.step.result_error_bundle.errorMessageCount() > 0) {
-            self.step.result_error_bundle.renderToStdErr(.{}, color);
+            self.step.result_error_bundle.renderToStderr(io, .{}, color) catch |err| {
+                print("{}\n", .{err});
+                return;
+            };
         }
     }
 };

exercises/026_hello2.zig

@@ -5,6 +5,9 @@
 //
 const std = @import("std");
 
+// Instance for input/output operations, we'll learn how to create them later.
+const io = std.Options.debug_io;
+
 // Take note that this main() definition now returns "!void" rather
 // than just "void". Since there's no specific error type, this means
 // that Zig will infer the error type. This is appropriate in the case
@@ -15,13 +18,15 @@ const std = @import("std");
 // https://ziglang.org/documentation/master/#Inferred-Error-Sets
 //
 pub fn main() !void {
-    // We get a Writer for Standard Out so we can print() to it.
+    // We get a Writer for Standard Out...
-    var stdout = std.fs.File.stdout().writer(&.{});
+    var stdout_writer = std.Io.File.stdout().writer(io, &.{});
+    // ...and extract its interface so we can print() to it.
+    const stdout = &stdout_writer.interface;
 
     // Unlike std.debug.print(), the Standard Out writer can fail
     // with an error. We don't care _what_ the error is, we want
     // to be able to pass it up as a return value of main().
     //
     // We just learned of a single statement which can accomplish this.
-    stdout.interface.print("Hello world!\n", .{});
+    stdout.print("Hello world!\n", .{});
 }

exercises/034_quiz4.zig

@@ -6,15 +6,17 @@
 //     my_num=42
 //
 const std = @import("std");
+const io = std.Options.debug_io;
 
 const NumError = error{IllegalNumber};
 
 pub fn main() void {
-    var stdout = std.fs.File.stdout().writer(&.{});
+    var stdout_writer = std.Io.File.stdout().writer(io, &.{});
+    const stdout = &stdout_writer.interface;
 
     const my_num: u32 = getNumber();
 
-    try stdout.interface.print("my_num={}\n", .{my_num});
+    try stdout.print("my_num={}\n", .{my_num});
 }
 
 // This function is obviously weird and non-functional. But you will not be changing it for this quiz.

exercises/106_files.zig

@@ -12,23 +12,27 @@
 // Fortunately, the Zig Standard Library provides a simple API for interacting
 // with the file system, see the detail documentation here:
 //
-// https://ziglang.org/documentation/master/std/#std.fs
+// https://ziglang.org/documentation/master/std/#std.Io
 //
 // In this exercise, we'll try to:
 //   - create a new directory,
 //   - open a file in the directory,
 //   - write to the file.
 //
-// import std as always
+// Note: For simplicity, we write byte-by-byte without buffering.
+// In real applications, you'd typically use a buffer for better
+// performance. We'll learn about buffered I/O in a later exercise.
+//
 const std = @import("std");
+const io = std.Options.debug_io;
 
 pub fn main() !void {
     // first we get the current working directory
-    const cwd: std.fs.Dir = std.fs.cwd();
+    const cwd: std.Io.Dir = std.Io.Dir.cwd();
 
     // then we'll try to make a new directory /output/
     // to store our output files.
-    cwd.makeDir("output") catch |e| switch (e) {
+    cwd.createDir(io, "output", .default_dir) catch |e| switch (e) {
         // there is a chance you might want to run this
         // program more than once and the path might already
         // have been created, so we'll have to handle this error
@@ -44,21 +48,24 @@ pub fn main() !void {
     // wait a minute...
     // opening a directory might fail!
     // what should we do here?
-    var output_dir: std.fs.Dir = cwd.openDir("output", .{});
+    var output_dir: std.Io.Dir = try cwd.openDir(io, "output", .{});
-    defer output_dir.close();
+    defer output_dir.close(io);
 
     // we try to open the file `zigling.txt`,
     // and propagate any error up
-    const file: std.fs.File = try output_dir.createFile("zigling.txt", .{});
+    const file: std.Io.File = try output_dir.createFile(io, "zigling.txt", .{});
     // it is a good habit to close a file after you are done with it
     // so that other programs can read it and prevent data corruption
     // but here we are not yet done writing to the file
     // if only there were a keyword in Zig that
     // allowed you to "defer" code execution to the end of the scope...
-    file.close();
+    file.close(io);
 
-    // you are not allowed to move these two lines above the file closing line!
+    // you are not allowed to move these lines above the file closing line!
-    const byte_written = try file.write("It's zigling time!");
+    var file_writer = file.writer(io, &.{});
+    const writer = &file_writer.interface;
+
+    const byte_written = try writer.write("It's zigling time!");
     std.debug.print("Successfully wrote {d} bytes.\n", .{byte_written});
 }
 // to check if you actually write to the file, you can either,
@@ -71,8 +78,8 @@ pub fn main() !void {
 // More on Creating files
 //
 // notice in:
-// ... try output_dir.createFile("zigling.txt", .{});
+// ... try output_dir.createFile(io, "zigling.txt", .{});
-//                                              ^^^
+//                                                  ^^^
 //                 we passed this anonymous struct to the function call
 //
 // this is the struct `CreateFlag` with default fields
@@ -87,7 +94,7 @@ pub fn main() !void {
 //
 // Question:
 //   - what should you do if you want to also read the file after opening it?
-//   - go to the documentation of the struct `std.fs.Dir` here:
+//   - go to the documentation of the struct `std.Io.Dir` here:
 //     https://ziglang.org/documentation/master/std/#std.fs.Dir
 //       - can you find a function for opening a file? how about deleting a file?
 //       - what kind of options can you use with those functions?

exercises/107_files2.zig

@@ -15,20 +15,25 @@
 //    - Then, we initialize an array of characters with all letter 'A', and print it
 //    - After that, we read the content of the file into the array
 //    - Finally, we print out the content we just read
+//
+// Note: For simplicity, we read byte-by-byte without buffering.
+// In real applications, you'd typically use a buffer for better
+// performance. We'll learn about buffered I/O in a later exercise.
 
 const std = @import("std");
+const io = std.Options.debug_io;
 
 pub fn main() !void {
     // Get the current working directory
-    const cwd = std.fs.cwd();
+    const cwd = std.Io.Dir.cwd();
 
     // try to open ./output assuming you did your 106_files exercise
-    var output_dir = try cwd.openDir("output", .{});
+    var output_dir = try cwd.openDir(io, "output", .{});
-    defer output_dir.close();
+    defer output_dir.close(io);
 
     // try to open the file
-    const file = try output_dir.openFile("zigling.txt", .{});
+    const file = try output_dir.openFile(io, "zigling.txt", .{});
-    defer file.close();
+    defer file.close(io);
 
     // initialize an array of u8 with all letter 'A'
     // we need to pick the size of the array, 64 seems like a good number
@@ -37,10 +42,13 @@ pub fn main() !void {
     // this should print out : `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`
     std.debug.print("{s}\n", .{content});
 
+    var file_reader = file.reader(io, &.{});
+    const reader = &file_reader.interface;
+
     // okay, seems like a threat of violence is not the answer in this case
     // can you go here to find a way to read the content?
-    // https://ziglang.org/documentation/master/std/#std.fs.File
+    // https://ziglang.org/documentation/master/std/#std.Io.Reader
-    // hint: you might find two answers that are both valid in this case
+    // hint: look for a method that reads into a slice
     const bytes_read = zig_read_the_file_or_i_will_fight_you(&content);
 
     // Woah, too screamy. I know you're excited for zigling time but tone it down a bit.

patches/patches/026_hello2.patch

@@ -1,9 +1,9 @@
---- exercises/026_hello2.zig	2025-07-22 09:55:51.337832401 +0200
+--- exercises/026_hello2.zig	2025-12-28 01:51:16.537444980 +0100
-+++ answers/026_hello2.zig	2025-07-22 10:00:11.233348058 +0200
++++ answers/026_hello2.zig	2025-12-28 01:51:10.280322328 +0100
-@@ -23,5 +23,5 @@
+@@ -27,5 +27,5 @@
      // to be able to pass it up as a return value of main().
      //
      // We just learned of a single statement which can accomplish this.
--    stdout.interface.print("Hello world!\n", .{});
+-    stdout.print("Hello world!\n", .{});
-+    try stdout.interface.print("Hello world!\n", .{});
++    try stdout.print("Hello world!\n", .{});
  }

patches/patches/034_quiz4.patch

@@ -1,15 +1,16 @@
---- exercises/034_quiz4.zig	2025-07-22 09:55:51.337832401 +0200
+--- exercises/034_quiz4.zig	2025-12-28 14:43:41.087943476 +0100
-+++ answers/034_quiz4.zig	2025-07-22 10:05:08.320323184 +0200
++++ answers/034_quiz4.zig	2025-12-28 14:42:23.878472164 +0100
-@@ -9,10 +9,10 @@
+@@ -10,11 +10,11 @@
  
  const NumError = error{IllegalNumber};
  
 -pub fn main() void {
 +pub fn main() !void {
-     var stdout = std.fs.File.stdout().writer(&.{});
+     var stdout_writer = std.Io.File.stdout().writer(io, &.{});
+     const stdout = &stdout_writer.interface;
  
 -    const my_num: u32 = getNumber();
 +    const my_num: u32 = try getNumber();
  
-     try stdout.interface.print("my_num={}\n", .{my_num});
+     try stdout.print("my_num={}\n", .{my_num});
  }

patches/patches/106_files.patch

@@ -1,6 +1,6 @@
---- exercises/106_files.zig	2025-08-24 19:23:55.168565003 +0200
+--- exercises/106_files.zig	2025-12-28 20:38:53.005504479 +0100
-+++ answers/106_files.zig	2025-08-24 19:25:37.745597511 +0200
++++ answers/106_files.zig	2025-12-28 20:37:42.742154100 +0100
-@@ -35,7 +35,7 @@
+@@ -39,7 +39,7 @@
          // by doing nothing
          //
          // we want to catch error.PathAlreadyExists and do nothing
@@ -9,21 +9,12 @@
          // if there's any other unexpected error we just propagate it through
          else => return e,
      };
-@@ -44,7 +44,7 @@
+@@ -59,7 +59,7 @@
-     // wait a minute...
-     // opening a directory might fail!
-     // what should we do here?
--    var output_dir: std.fs.Dir = cwd.openDir("output", .{});
-+    var output_dir: std.fs.Dir = try cwd.openDir("output", .{});
-     defer output_dir.close();
- 
-     // we try to open the file `zigling.txt`,
-@@ -55,7 +55,7 @@
      // but here we are not yet done writing to the file
      // if only there were a keyword in Zig that
      // allowed you to "defer" code execution to the end of the scope...
--    file.close();
+-    file.close(io);
-+    defer file.close();
++    defer file.close(io);
  
-     // you are not allowed to move these two lines above the file closing line!
+     // you are not allowed to move these lines above the file closing line!
-     const byte_written = try file.write("It's zigling time!");
+     var file_writer = file.writer(io, &.{});

patches/patches/107_files2.patch

@@ -1,6 +1,6 @@
---- exercises/107_files2.zig	2025-08-24 19:15:17.789371332 +0200
+--- exercises/107_files2.zig	2025-12-28 21:17:29.658147954 +0100
-+++ answers/107_files2.zig	2025-08-24 19:17:58.897538288 +0200
++++ answers/107_files2.zig	2025-12-28 21:17:10.585787203 +0100
-@@ -33,7 +33,7 @@
+@@ -38,7 +38,7 @@
      // initialize an array of u8 with all letter 'A'
      // we need to pick the size of the array, 64 seems like a good number
      // fix the initialization below
@@ -9,12 +9,12 @@
      // this should print out : `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`
      std.debug.print("{s}\n", .{content});
  
-@@ -41,12 +41,12 @@
+@@ -49,12 +49,12 @@
      // can you go here to find a way to read the content?
-     // https://ziglang.org/documentation/master/std/#std.fs.File
+     // https://ziglang.org/documentation/master/std/#std.Io.Reader
-     // hint: you might find two answers that are both valid in this case
+     // hint: look for a method that reads into a slice
 -    const bytes_read = zig_read_the_file_or_i_will_fight_you(&content);
-+    const bytes_read = try file.read(&content);
++    const bytes_read = try reader.readSliceShort(&content);
  
      // Woah, too screamy. I know you're excited for zigling time but tone it down a bit.
      // Can you print only what we read from the file?

test/tests.zig

@@ -3,16 +3,14 @@ const root = @import("../build.zig");
 
 const debug = std.debug;
 const fmt = std.fmt;
-const fs = std.fs;
 const mem = std.mem;
 
 const Allocator = std.mem.Allocator;
 const Child = std.process.Child;
 const Build = std.Build;
-const LazyPath = std.Build.LazyPath;
-const Reader = fs.File.Reader;
-const RunStep = std.Build.RunStep;
 const Step = Build.Step;
+const RunStep = Build.RunStep;
+const LazyPath = Build.LazyPath;
 
 const Exercise = root.Exercise;
 
@@ -152,17 +150,17 @@ const CheckNamedStep = struct {
 
     fn make(step: *Step, _: Step.MakeOptions) !void {
         const b = step.owner;
+        const io = b.graph.io;
         const self: *CheckNamedStep = @alignCast(@fieldParentPtr("step", step));
         const ex = self.exercise;
 
-        const stderr_file = try fs.cwd().openFile(
+        const stderr_file = try std.Io.Dir.cwd().openFile(
+            io,
             self.stderr.getPath(b),
             .{ .mode = .read_only },
         );
-        defer stderr_file.close();
+        defer stderr_file.close(io);
 
-        var threaded: std.Io.Threaded = .init_single_threaded;
-        const io = threaded.io();
         var stderr = stderr_file.readerStreaming(io, &.{});
         {
             // Skip the logo.
@@ -206,17 +204,17 @@ const CheckStep = struct {
 
     fn make(step: *Step, _: Step.MakeOptions) !void {
         const b = step.owner;
+        const io = b.graph.io;
         const self: *CheckStep = @alignCast(@fieldParentPtr("step", step));
         const exercises = self.exercises;
 
-        const stderr_file = try fs.cwd().openFile(
+        const stderr_file = try std.Io.Dir.cwd().openFile(
+            io,
             self.stderr.getPath(b),
             .{ .mode = .read_only },
         );
-        defer stderr_file.close();
+        defer stderr_file.close(io);
 
-        var threaded: std.Io.Threaded = .init_single_threaded;
-        const io = threaded.io();
         var stderr = stderr_file.readerStreaming(io, &.{});
         for (exercises) |ex| {
             if (ex.number() == 1) {
@@ -234,7 +232,7 @@ const CheckStep = struct {
     }
 };
 
-fn check_output(step: *Step, exercise: Exercise, reader: *Reader) !void {
+fn check_output(step: *Step, exercise: Exercise, reader: *std.Io.File.Reader) !void {
     const b = step.owner;
 
     var buf: [1024]u8 = undefined;
@@ -301,7 +299,7 @@ fn check(
     }
 }
 
-fn readLine(reader: *fs.File.Reader, buf: []u8) !?[]const u8 {
+fn readLine(reader: *std.Io.File.Reader, buf: []u8) !?[]const u8 {
     try reader.interface.readSliceAll(buf);
     return mem.trimEnd(u8, buf, " \r\n");
 }
@@ -379,8 +377,9 @@ const HealStep = struct {
 
 /// Heals all the exercises.
 fn heal(allocator: Allocator, exercises: []const Exercise, work_path: []const u8) !void {
-    const sep = std.fs.path.sep_str;
+    const io = std.Options.debug_io;
-    const join = fs.path.join;
+    const sep = std.Io.Dir.path.sep_str;
+    const join = std.Io.Dir.path.join;
 
     const exercises_path = "exercises";
     const patches_path = "patches" ++ sep ++ "patches";
@@ -398,19 +397,17 @@ fn heal(allocator: Allocator, exercises: []const Exercise, work_path: []const u8
         const argv = &.{ "patch", "-i", patch, "-o", output, "-s", file };
 
         var child = Child.init(argv, allocator);
-        _ = try child.spawnAndWait();
+        _ = try child.spawnAndWait(io);
     }
 }
 
 /// This function is the same as the one in std.Build.makeTempPath, with the
 /// difference that returns an error when the temp path cannot be created.
 pub fn makeTempPath(b: *Build) ![]const u8 {
+    const io = b.graph.io;
     const rand_int = std.crypto.random.int(u64);
-    const rand_hex64 = std.fmt.hex(rand_int);
+    const tmp_dir_sub_path = "tmp" ++ std.Io.Dir.path.sep_str ++ std.fmt.hex(rand_int);
-    const tmp_dir_sub_path = "tmp" ++ fs.path.sep_str ++ rand_hex64;
+    const result_path = b.cache_root.join(b.allocator, &.{tmp_dir_sub_path}) catch @panic("OOM");
-    const path = b.cache_root.join(b.allocator, &.{tmp_dir_sub_path}) catch
+    try b.cache_root.handle.createDirPath(io, tmp_dir_sub_path);
-        @panic("OOM");
+    return result_path;
-    try b.cache_root.handle.makePath(tmp_dir_sub_path);
-
-    return path;
 }