Allow defining compile error notes with `@compileError`

[Vexu]

Why?

With #12044 compile error notes can now be printed more compactly enabling long, multi sentence errors to be broken down into the main error, the reason for the error, and suggestions for what to do about it. I think generic interface validation for example could also benefit from this with hash_map.zig being a good example: https://github.com/ziglang/zig/blob/7090f0471c0169c60a9476b537b09eebe1bdf6af/lib/std/hash_map.zig#L17-L22

How?

Syntax suggestions include:

1. making it variadic @compileError(err: []const u8, ...)
   • this has all the same issues as regular variadic function in that comptime logic can't control how many notes there are
2. adding a note list parameter @compileError(err: []const u8, notes: []const []const u8)
   • this breaks all existing usage, most of which won't even need notes
3. adding a second optional note list paramter @compileError(err: []const u8, ...)
   • same as above but the function is variadic so the second parameter can be omitted
   • this is my favorite
4. adding a new builtin specifically for this use case @compileErrorWithNotes(err: []const u8, notes: []const []const u8)

[silversquirl]

Option 2 seems like the most Zig-ish to me, and existing usage can be fixed by zig fmt.

I think it's worth noting that there's no precedent for option 3: all existing builtins are either non-variadic or can take any number of arguments, all of which are variadic. This would make @compileError the only builtin to take two different fixed numbers of arguments, as well as the first to treat those arguments differently from each other.

[clickingbuttons]

I'm in favor of matching @compileLog(args: ...) void.

Right now I'm having to workaround this by using @compileError(std.fmt.comptimePrint("", .{}))

[InKryption]

Option 2 makes more sense for code that actually needs notes - just take a look at std.hash_map.verifyContext. Variadic arguments aren't friendly to programmatically-built error notes.

[Vexu]

One possible addition to this (or a separate proposal) I've thought about is to also add a src: ?builtin.SourceLocation parameter.

That combined with a new @calleeSrc builtin that behaves like @src but for the location of an inline function's call site would enable the standard library (and all other libraries) to make it immediately clear where the error was caused:

a.zig:7:16: error: missing closing }
    std.debug.print("Hello {s\n", .{"world"});
              ^~~~~
lib/std/fmt.zig:144:13: note: error created here
            @compileError("missing closing }");
            ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using these would look somewhat like this:

pub inline fn std.debug.print(fmt, args) {
    std.fmt.formatExtra(fmt, args, @calleeSrc());
}
pub fn std.fmt.formatExtra(fmt, args, comptime src: ?SourceLocation) {
    // depending on the selected syntax
    @compileError("missing closing }", src);
}

..which would require quite a lot of small edits and might increase the amount of functions generated by formatted printing but should not be a breaking change.

[tjheeta]

I just wanted to comment on this from #13621 since I ran into this issue by upgrading from 0.9 to 0.11 for code I wrote close to 2 years ago. Essentially, to make a long story short, the error message:

fmt.zig:499:17: error: cannot format optional without a specifier (i.e. {?} or {any})
    @compileError("cannot format optional without a specifier (i.e. {?} or {any})");

made me think I had issues with bufPrint and allocPrint on upgrade.

After failing to solve this issue repeatedly for several hours, I commented out all usage of fmt...and I still had the problem. That led me down a rabbit hole to a Russian blog which pointed me to these two GH issues.

As I'm completely unqualified to write a patch, pretty please with a cherry on top, if compile failures can have source files + line numbers associated, that would be fantastic. :)