Zig Tutorial: Every Snippet Verified Against Master · Zig Guide Live

Showcase
,
1

Zig Guide Live

I have been writing a Zig guide at ziglang.in and it is far enough along to be worth showing.

I have created this for me and my two member zig team. But as the content is tested and all code is working, I thought it is worthwhile to share here.

Systems Requirements:
Minimum for the playgrounds Chrome 75, Firefox 79, Safari 15; bulk memory is the binding constraint, not SIMD. Some SIMD instructions might fail in the browser.

The reason this content is generated is we are planning to move some of our internal systems related projects from c#, c to zig and we want the minimal breaking changes.

I have been recently using LLM a lot as a learning tool. Sometimes it worked great other times it failed.

I understand the term AI slop comes to mind the moment we see LLM generated code, content or even image.

And it’s fair. But for me it has been a good experience so far and also seeing some bad practice along the way, then referring to zig source code and then direct to fix things.

But the last 6 months, I got it working the way I wanted almost 100% of the time. Interestingly all code developed is under review by my team who are learning as well (and they are not experts).

The full review hasn’t happened as this is a side hustle, yet but slowly we are progressing and improving along the way.

I have been an application/business systems programmer for about 30 years now and also do some graphics, game, DB , framework development in spare time. LLM allows to learn a new programming language much faster.

I am no systems or zig expert

The problem this guide solve is the one most of us have hit: you find a tutorial, copy the example, and it does not compile, because it was written against 0.11 and nobody noticed.

Here the build is the guide. Every snippet on the site is a real .zig file in the repo. zig build verify compiles each one, runs it, and diffs its stdout against a checked-in .expected file. CI runs that on every push and again at 06:00 UTC nightly against current Zig master. If master changes something a snippet depends on, the nightly goes red on an unchanged tree and I go fix the chapter.

Many of the systems, graphics, database I ported from my old code which was in nodejs, c#, Elixir, Custom web frameworks I developed in the past and some in C.

The part I care about most: the .wasm artifact CI verified is the exact one your browser downloads and runs in the playground. There is no second code path, no separately maintained “example” that drifted from the text.

Clicking Run executes the binary that passed CI. The footer of every page names the compiler version that verified it, currently 0.17.0-dev.1454+5faa79730.

What is in it

145 chapters across 11 sections, grouped into four tracks:

  • Foundations: Getting Started, Language Basics, Standard Library, Data Structures
  • Systems: Networking, Build System, Working with C, WebAssembly, Graphics (software rendering from scratch, ending at a real X11 window)
  • Cookbook: 24 task-shaped recipes, each a complete program
  • Projects: an Ecto-style ORM built one decision per chapter

139 snippets total.

Two pages are deliberately unverified and say so on the page: the @cImport chapter needs real headers, and the “coming from older Zig” page is full of examples that are supposed to not compile.

8 Likes
2

Always welcoming new people to zig. Not very fond of AI personnaly but if it works for you.

Do you want a review of the content or are you sharing it ? Aka. Is it in a usable state yet ?

Unrelated : it seems there is an error in you zig compiler on wasm as I’m getting an error for running snippets :

wasm validation error: at offset 27476: unrecognized opcode: fd 0

On your first page with them : Hello World · Zig Guide Live

3

Yes, its usable. Let me check. May I know which browser/OS you are working with. I have tested this mostly on IE edge and chrome on Ubuntu.

Also all reviews are welcome.

PS: Please check now. The bug is fixed. As long as the browser I updated in the requirements is used most examples will work in browser. By default I have enabled SIMD instructions for all examples which now is only applicable to the relevant chapters.

4

It works now !

Good luck on your endeavor !

1 Like
5

Nice work Zig is in need of more docs/tutorials. Only pitfall with a pre-1.0 lang that changes daily the docs go out of date pretty quick.

3 Likes
6

Just read the Hello World page, and I think it’s talking about a lot of concepts before they’ve been introduced.

Hello World

Here is a complete Zig program. Press Run; it executes in your browser as WebAssembly.

Why does main take a parameter?

If you have seen Zig before, you probably expect pub fn main() !void. On current Zig master, main receives a std.process.Init:
That init carries an Io instance, init.io. This is the same idea as Allocator,

What’s an Io? What’s an Allocator?

You’ve lost your new Zig acolyte in the 3rd or 4th sentence.

I think Hello World is a good place to start, but it needs care. There’s a lot in there if you’re going to do a “Juicy Main”.

An alternative approach might be to start with std.debug.print and then introduce juicy main once you’ve covered the concepts that it packages up.

5 Likes
7

Appreciate your feedback. Thanks.

PS: The tutorial has been updated. And more importantly when to use which is clarified as well. For debugging std.debug.print and for production output, logs etc the Io interface, which will be introduced in more detail in subsequent chapters.

1 Like