Zig: add documentation for default panic handler

[adontz]

When I compile the following code with 0.5.0+652efe38b

const builtin = @import("builtin");

pub fn WinMainCRTStartup() callconv(.Stdcall) u32 {
return 0;
}

comptime {
    @export(WinMainCRTStartup, .{ .name = "WinMainCRTStartup" });
}

(You may note that I do not call ExitProcess, but simply return, it's OK for Win32)

I see that application imports a long list of completely unrelated functions
kernel32.dll
CloseHandle
ExitProcess
FormatMessageW
GetConsoleMode
GetConsoleScreenBufferInfo
GetCurrentDirectoryW
GetEnvironmentVariableW
GetFileInformationByHandleEx
GetFileSizeEx
GetLastError
GetModuleHandleW
ReadFile
RemoveVectoredExceptionHandler
RtlCaptureStackBackTrace
SetConsoleTextAttribute
SetFilePointerEx
VirtualAlloc
VirtualFree
WriteFile

ntdll.dll
NtCreateFile
NtCreateKeyedEvent
NtReleaseKeyedEvent
NtWaitForKeyedEvent

Looks like conditional compilation has not effect on linker.

[Sobeston]

Compile without runtime safety (try --release-small or --release-fast).
By default, runtime safety will be enabled in the binary (default being a debug build).
I suppose zig isn't smart enough to "know" that were are no possible errors here in which its runtime safety mechanics will do anything.
Compiling with --release-small and using cutter I can only see entry0 under functions, and nothing under imports and exports.

[adontz]

Thanks for the hint!

Even release-safe did the trick, so looks like it's not about safety, more about release.

I'm not sure how people use comptime in real projects. If I understand everything correctly, one cannot debug if not all of ever mentioned in code libraries are accessible. Which means no optional dependencies are possible for a developer.

[andrewrk]

These dependencies are brought in by the default panic handler. Apologies, the default panic handler is not documented yet. But you can override it like this:

const builtin = @import("builtin");

pub fn WinMainCRTStartup() callconv(.Stdcall) u32 {
return 0;
}

comptime {
    @export(WinMainCRTStartup, .{ .name = "WinMainCRTStartup" });
}

pub fn panic(msg: []const u8, error_return_trace: ?*builtin.StackTrace) noreturn {
    // put whatever you want here
    while (true) {}
}

You can see the default panic handler here: https://github.com/ziglang/zig/blob/6305ce828b0685ceb646fae87a963f034d3bcdf0/lib/std/builtin.zig#L465-L496

Note that it's calling std.debug.panicExtra which deals with loading PDB debug info, capturing a stack trace, printing to stderr, etc.

I'm not sure how people use comptime in real projects. If I understand everything correctly, one cannot debug if not all of ever mentioned in code libraries are accessible. Which means no optional dependencies are possible for a developer.

I'm sorry I didn't understand this at all. Can you elaborate? What does this have to do with comptime? ever mentioned what? What kind of optional dependencies?

[adontz]

Thanks for clarification! Now, with user defined panic handler import list is clear.

So, let's talk about optional dependencies. Imagine I write a screensaver (I don't why would I, but that's just an example) which displays floating 3D text (Actually windows already includes such screensaver).

For text rendering I can use GDI, GDI+, DirectWrite or Pango.

For 3D I can use various DirectX versions, OpenGL, OpenGL ES, Vulkan and ANGLE (which translates OpenGL ES calls into DirectX calls).

So I have code paths for four text rendering APIs and five 3D APIs. 20 different builds. Boy, that escalated quickly.

The issue I was talking about (before panic handler clarification, now it seems false) is that if I have Pango and ANGLE related code which is excluded compile time, will I have to still have this libraries available, just to build and run executable?