mirror of
https://github.com/ziglang/zig.git
synced 2026-01-06 21:43:25 +00:00
e657b73f30
This introduces the concept of "IO mode" which is configurable by the root source file (e.g. next to `pub fn main`). Applications can put this in their root source file: ``` pub const io_mode = .evented; ``` This will populate `std.io.mode` to be `std.io.Mode.evented`. When I/O mode is evented, `std.os.read` handles EAGAIN by suspending until the file descriptor becomes available for reading. Although the std lib event loop supports epoll, kqueue, and Windows I/O Completion Ports, this integration with `std.os.read` currently only works on Linux. This integration is currently only hooked up to `std.os.read`, and not, for example, `std.os.write`, child processes, and timers. The fact that we can do this and still have a working master branch is thanks to Zig's lazy analysis, comptime, and inferred async. We can continue to make incremental progress on async std lib features, enabling more and more test cases and coverage. In addition to `std.io.mode` there is `std.io.is_async` which is equal to `std.io.mode == .evented`. In case I/O mode is async, `std.io.InStream` notices this and the read function pointer becomes an async function pointer rather than a blocking function pointer. Even in this case, `std.io.InStream` can *still be used as a blocking input stream*. Users of the API control whether it is blocking or async at runtime by whether or not the read function suspends. In case of file descriptors, for example, this might correspond to whether it was opened with `O_NONBLOCK`. The `noasync` keyword makes a function call or `await` assert that no suspension happens. This assertion has runtime safety enabled. `std.io.InStream`, in the case of async I/O, uses by default a 4 MiB frame size for calling the read function. If this is too large or too small, the application can globally increase the frame size used by declaring `pub const stack_size_std_io_InStream = 1234;` in their root source file. This way, `std.io.InStream` will only be generated once, avoiding bloat, and as long as this number is configured to be high enough, everything works fine. Zig has runtime safety to detect when `@asyncCall` is given too small of a buffer for the frame size. This merge introduces -fstack-report which can help identify large async function frame sizes and explain what is making them so big. Until #3069 is solved, it's recommended to stick with blocking IO mode. -fstack-report outputs JSON format, which can then be viewed in a GUI that represents the tree structure. As an example, Firefox does a decent job of this. One feature that is currently missing is detecting that the call stack upper bound is greater than the default for a given target, and passing this upper bound to the linker. As an example, if Zig detects that 20 MiB stack upper bound is needed - which would be quite reasonable - currently on Linux the application would only be given the default of 16 MiB. Unrelated miscellaneous change: added std.c.readv
A general-purpose programming language designed for robustness, optimality, and maintainability.
Resources
- Introduction
- Download & Documentation
- Community
- Contributing
- Frequently Asked Questions
- Community Projects
Building from Source
Note that you can download a binary of master branch.
Stage 1: Build Zig from C++ Source Code
Dependencies
POSIX
- cmake >= 2.8.5
- gcc >= 5.0.0 or clang >= 3.6.0
- LLVM, Clang, LLD development libraries == 8.x, compiled with the same gcc or clang version above
- Use the system package manager, or build from source.
Windows
- cmake >= 2.8.5
- Microsoft Visual Studio 2017 (version 15.8)
- LLVM, Clang, LLD development libraries == 8.x, compiled with the same MSVC version above
- Use the pre-built binaries or build from source.
Instructions
POSIX
mkdir build
cd build
cmake ..
make install
MacOS
brew install cmake llvm@8
brew outdated llvm@8 || brew upgrade llvm@8
mkdir build
cd build
cmake .. -DCMAKE_PREFIX_PATH=$(brew --prefix llvm)
make install
Windows
See https://github.com/ziglang/zig/wiki/Building-Zig-on-Windows
Stage 2: Build Self-Hosted Zig from Zig Source Code
Note: Stage 2 compiler is not complete. Beta users of Zig should use the Stage 1 compiler for now.
Dependencies are the same as Stage 1, except now you can use stage 1 to compile Zig code.
bin/zig build --prefix $(pwd)/stage2
This produces ./stage2/bin/zig which can be used for testing and development.
Once it is feature complete, it will be used to build stage 3 - the final compiler
binary.
Stage 3: Rebuild Self-Hosted Zig Using the Self-Hosted Compiler
Note: Stage 2 compiler is not yet able to build Stage 3. Building Stage 3 is not yet supported.
Once the self-hosted compiler can build itself, this will be the actual compiler binary that we will install to the system. Until then, users should use stage 1.
Debug / Development Build
./stage2/bin/zig build --prefix $(pwd)/stage3
Release / Install Build
./stage2/bin/zig build install -Drelease