builtin function to expose additional build options

[andrewrk]

New builtin function:
@buildOption(comptime name: []const u8, comptime T: type, comptime default_value: T) T

This returns a comptime value, and exposes the option to the Zig command line interface:

zig build-exe --option name value

If the option is buried in a package:

zig build-exe --pkg-begin --option name value --pkg-end

To be decided: how to refer to the std package, since it is automatically added (not explicitly with --pkg-begin ...)

Here's a real life use case, from std/os/index.zig:

// TODO make this a build variable that you can set
const unexpected_error_tracing = false;

zig build-options would be another command similar to build-exe but instead of producing a build artifact, it would simply list all the build options available and their default values.

The zig build system would expose these options in the zig build --help menu. There would be API to set a build option for a given artifact, and thus suppressing it from being exposed as a zig build option.

Another use case for this feature is #1639. Code that calls a function pointer could have the number of stack bytes required be a build option, with a low value as the default. Code that needed a larger stack size could then set a build option to increase the size as necessary.

[Manuzor]

What about build.zig? Seems like it would feel more natural to set package options there.

I have to admit I'm with Jonathan Blow on this topic. I'd rather have fewer command-line options in favor of more code that controls the build. Build definitions can become complicated rather quickly and I'd rather express them in structured code than in a single flat command line.

[andrewrk]

What about build.zig?

This:

The zig build system would expose these options in the zig build --help menu. There would be API to set a build option for a given artifact, and thus suppressing it from being exposed as a zig build option.

So if you know what you want to do in your build script, you do it, and the option is not user-visible.

[Manuzor]

Oh, I misread the proposal the first time and thought the paragraph was describing how custom build options would just be documented via zig build --help. Thanks for clarifying.

[Sahnvour]

This would be very useful, for example to control the level of debug to use in the standard library. We could choose between none, light or heavy debugs (think for example iterator invalidation, allocator canaries and such) independently from the optimization flag (with sound default values).

[andrewrk]

Something like this is still planned but the idea needs to be reworked to take into account #943

[courajs]

Is this resolved by the addition of Builder.addOptions and OptionsStep?

[andrewrk]

The idea behind this was making it possible for the language itself to expose configuration options, and have those options bubble up to the CLI and build system. In the interest of simplicity, I think this is better managed via @import and configuration generated at build time.