Alternative to #31095
Related #10392
Related #8508
Related #7243
Related #4166
Allows overriding multiple OS-dependent APIs with a single declaration in the root module. The aim is to allow OSes not supported by std to still be used by providing a single std.Options.OperatingSystem that provides API overrides without replacing them directly.
This allows compiling applications to unsupported OSes without having to use a forked std, e.g libraries using OS-independent APIs in std like std.process.protectMemory (JITs for example) can now be used anywhere without patching them. Furthermore, these options allow overriding the default start.zig code, the default handlers in std.debug and a lot of other niceties.
Bits of the new Io interface are also overrideable, these include:
std.Io.Operation.DeviceIoControlstd.Io.VTable -> ducktyping allows the VTable to be a ZST while still being able to implement all APIs, example std.Io.LockedStderr -> some platforms do have a debug console but it may not be a file, so this is mandatory unless lockStderr returns an std.Io.Terminalstd.Io.net -> has_unix_sockets, Socket.Handlestd.Io.File -> Handle, Flags, Permissions, stderr(), stdout(), stdin()std.Io.Dir -> Handle, min_path_bytes, min_name_bytes, Reader.min_buffer_len, cwd()
As this is breaking for the current BYOOS, here's an example how of to migrate:
pubconstpanic=// your panicpubconststd_options:std.Options=.{.page_size_min=4096,.page_size_max=4096,};pubconstos=struct{pubconstheap=struct{pubconstpage_allocator=// your allocator...};};comptime{_=myos;}
⬇️
pubconststd_os_options:std.Options.OperatingSystem=.{.heap=struct{pubconstpage_size_min=4096;pubconstpage_size_max=4096;pubconstpage_allocator=// your custom allocator...},// but also override start, debug (including the default panic handler), Thread, etc...};
However the intended use-case is to have your module provide a single decl to override the APIs:
pubconststd_os_options:std.Options.OperatingSystem=if(compiling_for_my_os)myos.default_std_os_optionselse.{};
Alternative to #31095
Related [#10392](https://github.com/ziglang/zig/issues/10392)
Related [#8508](https://github.com/ziglang/zig/issues/8508)
Related [#7243](https://github.com/ziglang/zig/issues/7243)
Related [#4166](https://github.com/ziglang/zig/issues/4166)
---
Allows overriding multiple OS-dependent APIs with a single declaration in the root module. The aim is to allow OSes not supported by `std` to still be used by providing a single `std.Options.OperatingSystem` that provides API overrides without *replacing* them directly.
This allows compiling applications to unsupported OSes without having to use a forked `std`, e.g libraries using OS-independent APIs in `std` like `std.process.protectMemory` (JITs for example) can now be used anywhere without patching them. Furthermore, these options allow overriding the default `start.zig` code, the default handlers in `std.debug` and a lot of other niceties.
Bits of the new `Io` interface are also overrideable, these include:
- `std.Io.Operation.DeviceIoControl`
- `std.Io.VTable` -> ducktyping allows the VTable to be a ZST while still being able to implement all APIs, [example](https://codeberg.org/GasInfinity/zitrus/src/commit/790b8cca865c45ad522441d72e80ba61f0aa91ec/src/horizon/Io.zig#L213)
- `std.Io.LockedStderr` -> some platforms *do* have a debug console but it may *not* be a file, so this is mandatory unless `lockStderr` returns an `std.Io.Terminal`
- `std.Io.net` -> `has_unix_sockets`, `Socket.Handle`
- `std.Io.File` -> `Handle`, `Flags`, `Permissions`, `stderr()`, `stdout()`, `stdin()`
- `std.Io.Dir` -> `Handle`, `min_path_bytes`, `min_name_bytes`, `Reader.min_buffer_len`, `cwd()`
As this is breaking for the current BYOOS, here's an example how of to migrate:
```zig
pub const panic = // your panic
pub const std_options: std.Options = .{
.page_size_min = 4096,
.page_size_max = 4096,
};
pub const os = struct {
pub const heap = struct {
pub const page_allocator = // your allocator...
};
};
comptime { _ = myos; }
```
⬇️
```zig
pub const std_os_options: std.Options.OperatingSystem = .{
.heap = struct {
pub const page_size_min = 4096;
pub const page_size_max = 4096;
pub const page_allocator = // your custom allocator...
},
// but also override start, debug (including the default panic handler), Thread, etc...
};
```
However the intended use-case is to have your module provide a single decl to override the APIs:
```zig
pub const std_os_options: std.Options.OperatingSystem = if (compiling_for_my_os) myos.default_std_os_options else .{};
```