Using Mach on nixOS

If you use nixOS and want to use Mach, this document is for you!

option 1: mach-flake

A generous member of the community maintains mach-flake, a flake that allows you to get started with Mach quickly.

option 2: usage via nix-ld

Use nix-ld following e.g. this article.

For example this shell:

with import <nixpkgs> {};
mkShell {
  NIX_LD_LIBRARY_PATH = lib.makeLibraryPath [
    pkgs.xorg.libX11
    pkgs.vulkan-loader
  ];
  NIX_LD = lib.fileContents "${stdenv.cc}/nix-support/dynamic-linker";
  shellHook = ''
    export LD_LIBRARY_PATH=$NIX_LD_LIBRARY_PATH
  '';
}

Then running zig build as usual:

zig build run-core-textured-cube

option 3: usage via shell

{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  buildInputs = [
    pkgs.xorg.libX11
    pkgs.vulkan-loader
  ];
  shellHook = ''
    export LD_LIBRARY_PATH=${pkgs.xorg.libX11}/lib:${pkgs.vulkan-loader}/lib:$LD_LIBRARY_PATH
  '';
}

option 4: usage via steam-run

You can also run Mach examples via steam-run, for this you will need to install Steam, then create a shell using steam-run, e.g.:

env NIXPKGS_ALLOW_UNFREE=1 nix-shell -p steam-run

(then zig build run-core-textured-cube as usual)

Known issues

Incorrect cursor behavior with cursormode set to disabled

If your cursor is not hidden and behaves “jumpy” after setting cursormode to disabled, you will need to add the pkgs.xorg.libXcursor package as an additional buildinput. This is required for both Xorg and Wayland.

If capturing the cursor is not required, libXcursor can be omitted.

Debugging tips

• Mach requires a functional Vulkan graphics driver by default, but you can also try OpenGL via MACH_GPU_BACKEND=opengl
• Poor vsync implementations on Linux may make the application appear laggy, you may need a frame rate limiter (please let us know if you run into this.
• OpenGL ES fallback is not yet supported
• VK_ERROR_INCOMPATIBLE_DRIVER may be encountered if your GPU does not support Vulkan / the version we require, please try MACH_GPU_BACKEND=opengl if so.