/ziguana

Zig learning

Primary LanguageNix

Ziguana (Zig learning material)

Getting started

Zig is still in development and the language, compiler, build system, and standard library are still changing. For this reason we use Nix to provide a development shell. This allows us to pin the Zig compiler to a specific version allowing us to restore a projects environment in the future.

We also allow you to create a docker container with the development shell if you don't want to install Nix on your system. The docker container uses Nix to setup the project dependencies.

Dependencies: Nix (optional): https://github.com/DeterminateSystems/nix-installer Docker (optional): https://www.docker.com/

We first want to initialize a new project. A project template is available in the ./templates/zigshell' folder. If you don't have Nix installed locally copy the files from the zigshell` folder into your project folder:

$ mkdir <new-project>
$ cd <new-project>
$ nix flake init -t github:urso/ziguana # alternatively copy the files from the templates/zigshell folder
$ git init
$ git add *

NOTE: We must initialize and add the nix files to the git repository, such that the Nix Flakes can find them.

(Optional build docker container):

$ chmod 700 ./dev/docker/*.sh # fix permissions
$ ./dev/docker/build.sh

Start the development shell

Choose between Nix, Nix with direnv, Docker:

  • Nix: $ nix develop
  • Nix with direnv: $ direnv allow
  • Docker: $ ./dev/docker/run.sh nix develop

KNOWN ISSUE (Docker on Desktop): When running Docker on Desktop the owner of the workdir might be the root user, which can lead to problems when running nix develop. In that case use dev/docker/run.sh and manually change the ownership via chmod dev ../workdir. Now nix develop will start the development shell.

Initialize a zig project

To create a project in the current folder run:

$ zig init

Optionally update the project name in the build.zig.zon and build.zig files.

Build the project

$ zig build -freference-trace

Zig uses the zig-cache folder to store project dependencies like generated source files or object files. Next it installs all artifacts into the zig-out folder (use -p <prefix> to change the install prefix path):

$ find zig-out

Run the sample application:

$ ./zig-out/bin/workdir
All your codebase are belong to us.
Run `zig build test` to run the tests.

Run testsuite:

$ zig build test

Zig references

Nix references