Make public app declarations available from root (ZigEmbeddedGroup#775)

mattnite · web-flow · commit 910c530145c8 · 2025-12-23T13:41:29.000-08:00
Fixes ZigEmbeddedGroup#465. One of the weaknesses of MicroZig's build system is that packages that use root declarations for comptime-configuration don't work. We make the application a package to the real root of an executable, and break out useful stdlib options (namely logging) through `microzig_options`. This is also notable because MicroZig changes the defaults for logging because logging will cause compiler errors from not having an operating system. I want to avoid boiler-plate like the following: ```zig const microzig = @import("microzig"); comptime { microzig.cpu.export_startup_logic(); // would export startup logic } pub fn main() { // ... } ``` So this patch creates a code generation step in our build system that takes the existing `startup.zig` code that currently makes up the root of the executable and appends the public declarations from the application. This gives us everything we want, no boiler plate, and packages will now be able to use comptime-configuration. The special handling of the Standard Library logging function is temporary. This needs to be fixed upstream so that the regular logging function is a no-op on freestanding targets.
diff --git a/build.zig b/build.zig
@@ -558,6 +558,21 @@ pub fn MicroBuild(port_select: PortSelect) type {
             app_mod.addImport("microzig", core_mod);
             core_mod.addImport("app", app_mod);
 
+            const generate_root_exe = mb.builder.addExecutable(.{
+                .name = "generate_root",
+                .root_module = mb.builder.createModule(.{
+                    .root_source_file = mb.core_dep.path("src/generate_root.zig"),
+                    .target = mb.builder.graph.host,
+                    .optimize = .Debug,
+                    .imports = &.{
+                        .{ .name = "app", .module = app_mod },
+                    },
+                }),
+            });
+
+            const generate_root_run = mb.builder.addRunArtifact(generate_root_exe);
+            const root_file = generate_root_run.addOutputFileArg("main.zig");
+
             const fw = mb.builder.allocator.create(Firmware) catch @panic("out of memory");
             fw.* = .{
                 .mb = mb,
@@ -567,7 +582,7 @@ pub fn MicroBuild(port_select: PortSelect) type {
                     .root_module = b.createModule(.{
                         .optimize = options.optimize,
                         .target = zig_resolved_target,
-                        .root_source_file = mb.core_dep.path("src/start.zig"),
+                        .root_source_file = root_file,
                         .single_threaded = options.single_threaded orelse target.single_threaded,
                         .strip = options.strip,
                         .unwind_tables = options.unwind_tables,
@@ -588,6 +603,9 @@ pub fn MicroBuild(port_select: PortSelect) type {
             fw.artifact.link_data_sections = options.strip_unused_symbols;
             fw.artifact.entry = options.entry orelse target.entry orelse .default;
 
+            for (options.imports) |import|
+                fw.artifact.root_module.addImport(import.name, import.module);
+
             fw.artifact.root_module.addImport("microzig", core_mod);
             fw.artifact.root_module.addImport("app", app_mod);
 
diff --git a/core/src/generate_root.zig b/core/src/generate_root.zig
@@ -0,0 +1,31 @@
+const std = @import("std");
+const app = @import("app");
+
+pub fn main() !void {
+    const gpa = std.heap.page_allocator;
+    const args = try std.process.argsAlloc(gpa);
+    defer std.process.argsFree(gpa, args);
+
+    if (args.len < 2)
+        return error.InvalidArgs;
+
+    const output_path = args[1];
+    const file = try std.fs.cwd().createFile(output_path, .{});
+    defer file.close();
+
+    var buf: [4096]u8 = undefined;
+    var file_writer = file.writer(&buf);
+    const writer = &file_writer.interface;
+
+    try writer.writeAll(@embedFile("start.zig"));
+
+    inline for (@typeInfo(app).@"struct".decls) |decl| {
+        if (!std.mem.eql(u8, "panic", decl.name) and
+            !std.mem.eql(u8, "std_options", decl.name))
+        {
+            try writer.print("pub const {f} = app.{f};\n", .{ std.zig.fmtId(decl.name), std.zig.fmtId(decl.name) });
+        }
+    }
+
+    try writer.flush();
+}
diff --git a/core/src/start.zig b/core/src/start.zig
@@ -10,10 +10,29 @@ pub const panic = if (!@hasDecl(app, "panic")) microzig.panic else app.panic;
 // defined. Parts of microzig use the stdlib logging facility and
 // compilations will now fail on freestanding systems that use it but do
 // not explicitly set `root.std_options.logFn`
-pub const std_options: std.Options = .{
-    .log_level = microzig.options.log_level,
-    .log_scope_levels = microzig.options.log_scope_levels,
-    .logFn = microzig.options.logFn,
+pub const std_options: std.Options = blk: {
+    var options = if (@hasDecl(app, "std_options"))
+        app.std_options
+    else
+        std.Options{};
+
+    if (options.logFn != std.log.defaultLog)
+        @compileError("It seems that you're trying to change the stdlib's " ++
+            "logFn. Please set this in the microzig_options, we require this " ++
+            "so that embedded executables don't give compile errors by default.");
+
+    if (options.log_level != std.log.default_level)
+        @compileError("It seems that you're trying to change the stdlib's " ++
+            "log_level. Please set this in the microzig_options.");
+
+    if (options.log_scope_levels.len > 0)
+        @compileError("It seems that you're trying to change the stdlib's " ++
+            "log_scope_levels. Please set this in the microzig_options.");
+
+    options.logFn = microzig.options.logFn;
+    options.log_level = microzig.options.log_level;
+    options.log_scope_levels = microzig.options.log_scope_levels;
+    break :blk options;
 };
 
 // Startup logic:
@@ -40,8 +59,8 @@ export fn microzig_main() noreturn {
     if (!@hasDecl(app, "main"))
         @compileError("The root source file must provide a public function main!");
 
-    const main = @field(app, "main");
-    const info: std.builtin.Type = @typeInfo(@TypeOf(main));
+    const app_main = @field(app, "main");
+    const info: std.builtin.Type = @typeInfo(@TypeOf(app_main));
 
     const invalid_main_msg = "main must be either 'pub fn main() void' or 'pub fn main() !void'.";
     if (info != .@"fn" or info.@"fn".params.len > 0)
@@ -62,7 +81,7 @@ export fn microzig_main() noreturn {
         microzig.hal.init();
 
     if (@typeInfo(return_type) == .error_union) {
-        main() catch |err| {
+        app_main() catch |err| {
             // Although here we could use @errorReturnTrace similar to
             // `std.start` and just dump the trace (without panic), the user
             // might not use logging and have the panic handler just blink an
@@ -90,7 +109,7 @@ export fn microzig_main() noreturn {
             }
         };
     } else {
-        main();
+        app_main();
     }
 
     // Main returned, just hang around here a bit.
diff --git a/examples/raspberrypi/rp2xxx/src/rp2040_only/flash_id.zig b/examples/raspberrypi/rp2xxx/src/rp2040_only/flash_id.zig
@@ -15,9 +15,9 @@ pub fn panic(message: []const u8, _: ?*std.builtin.StackTrace, _: ?usize) noretu
     while (true) {}
 }
 
-pub const std_options = struct {
-    pub const log_level = .debug;
-    pub const logFn = rp2xxx.uart.log;
+pub const microzig_options: microzig.Options = .{
+    .log_level = .debug,
+    .logFn = rp2xxx.uart.log,
 };
 
 pub fn main() !void {
