How does std_options work?

Explain
,
1

Questions

I was looking into how std_options works, so I pulled up std.zig:

const root = @import("root");

/// Stdlib-wide options that can be overridden by the root file.
pub const options: Options = if (@hasDecl(root, "std_options")) root.std_options else .{};
  1. This suggests there’s some sort of circular dependency. My code invokes std, but std invokes my code. How is this resolved?
  2. How is root defined?

More on Q2. Let’s say I compile a zig library, and link my code against that library. Does std get compiled twice? Once for the library, and once for my top-level code? Or is std compiled once against the top level code?

Background

I’m using a 3rd party library and running tests with the zig build system (zig build test not zig test). In my tests I set it up so that the library will fail, and my code handles the failure. However, this third party library invokes std.log with an error. I don’t want it to do this during my tests, because I handle the error. For my test, I was trying to suppress log output by setting:

pub const std_options = {
    // Logging function I defined which throws away the input.
    .logFn = noopLog,
};

My custom logging function never gets called, which led me to suspect that std_options doesn’t change std globally as I initially thought.

2

Zig allows circular dependencies between modules.

root is the root_module that you build as executable or dynamic/static library.

No, it is compiled once.

For executables, zig expects the root module to declare the main function.
You always specify which is the root_module in your build.zig addExecutable, addStaticLibrary, etc.

When declaring std_options, always specify the type std.Options and initialize using .{}.

You can also set the logging level in root_module std_options.
A complex log settings example:

const builtin = @import("builtin");

pub const std_options: std.Options = .{
    .log_level = if (builtin.mode == .Debug) .debug else .info,
    .log_scope_levels = &.{
        .{ .scope = .decimal, .level = .info },
        .{ .scope = .proper, .level = .info },
    },
    .logFn = log,
};

@mcdow welcome to ziggit :slight_smile:

7 Likes
3

The naming choice is unfortunate, it takes a convenient name std_options away from the user. I think that zig_std_options or std.zig_options or even std.options would be be better.

4

Fwiw I think it’s fine for some names to be reserved, and I’m curious wheee you think that name is convenient. I’d probably just name my variable options.

5

Sorry for necro-posting, but I believe the original question was valid, and it was never answered. std_options exhibit behavior during tests that I cannot explain. Consider an example:

const std = @import("std");

pub const std_options: std.Options = .{
    .fmt_max_depth = 10,
};

pub fn main() void {
    const root = @import("root");
    std.debug.print("fmt_max_depth is {}\n", .{root.std_options.fmt_max_depth});
}

test {
    const root = @import("root");
    try std.testing.expectEqual(3, root.std_options.fmt_max_depth);
}

Put this code into a standalone file. If you run it with zig run it prints 10. However if you run it with zig test the test passes. The Options.fmt_max_depth stays 3 as if the custom initializer was ignored. What kind of black magic is this?

6

If you add:

@compileLog(root);

That prints:

@as(type, test_runner)

for the test case, while it prints the name of your file for the run case.

This happens because the test runner is the main executable that runs your tests, it uses the information from @import("builtin").test_functions to construct a program that runs the tests.

So you are testing the std_options set by the test_runner.

And you can create a custom implementation of that test runner.

3 Likes