running dragonruby gtk on nixos

2025-05-29

oh god not the life story

Skip down to the good stuff if you are the “don’t bore us get to the chorus” type

I have recently made the jump to NixOS. It took me years but I finally caved in. Turns out it’s pretty neat! I have potentially found my Linux home and dare I hope, the cure to my insatiable distro-hopping. I won’t go into detail here about what I like about it and why I decided to give it a try (that’s a much longer post for a much less buzzed me).

Suffice to say, I’m pretty enamoured and look forward to becoming more familiar with it. Alas, you’re not here to read about my feelings for Linux distros. You’re here to learn how to run my favorite game toolkit in NixOS, which unapologetically does not support running dynamically linked executables intended for generic Linux environments.

Well, good news dearest reader: it’s pretty damn simple.

All we need to do is:

Configure Nix to run dynamically linked Linux executables.
Create a nix-shell environment containing the appropriate SDL libraries.

We’ll accomplish step 1 using the included nix-ld package to create a library path that only applies to unpackaged programs. Step 2 will declare a very simple nix-shell environment which adds necessary libraries to be used by SDL for both X11 and Wayland protocols.

Explaining nix-ld and nix-shell is a bit beyond the scope of this lil post but if you want to learn more, I strongly suggest checking out the official documentation linked above. It’s worth noting that there are multiple ways to accomplish this task and I’m presenting only one option for you to consider.

the good stuff

Let’s get down to the nitty gritty.

1) Configure Nix to run dynamically linked generic Linux executables. We’ll do this by adding the following to our Nix configuraiton (you will need to rebuild and reboot/logout in order for the nix-ld pacakge to enable and propagate):

programs.nix-ld.enable = true;
programs.nix-ld.libraries = with pkgs; [];

2) Plop the following into a file called “shell.nix” at the root of your DRGTK project folder:

{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  buildInputs = with pkgs; [
    xwayland
    SDL2
  ];
  shellHook = ''
    export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${
      with pkgs;
      lib.makeLibraryPath [
        libGL
        wayland
        wayland-protocols
        SDL2
        xorg.libX11
        xorg.libXi
        xwayland
      ]
    }"
    export SDL_VIDEODRIVER="wayland,x11"
  '';
}

3) cd into the root of your DRGTK project folder where you just created the shell.nix file and run the nix-shell command. This will drop you into a new shell instance containing the above configuraiton. If you have your prompt configured to display host information you will notice it update to display nix-shell instead of user@host.

4) All that’s left now is to run DragonRuby like you usually would!

$ ./dragonruby mygame

Et voilà! DragonRuby is running!

how the good stuff is made

So how does this work? Let’s walk through it together.

nix-ld

programs.nix-ld.enable = true;
# The following is not required but I keep it in case I ever want to make certain libraries globally accessible to all non-nix packages.
programs.nix-ld.libraries = with pkgs; [
  # Add any missing dynamic libraries for unpackaged programs
  # here, NOT in environment.systemPackages
];

You’ll notice we do not add our OpenGL and X11 libraries here. This is just a “design” decision I’ve made. I only want to make non-nix programs able to run via my system configuraiton. Any specific libraries I need I want to declare in environment-specific configuraitons. This keeps my system environment clean while allowing bespoke development environments to be created using nix-shell.

nix-shell

{ pkgs ? import <nixpkgs> {} }:
  ...
}

This bit defines an argument set with a default value of pkgs. If pkgs is not provided, it wil use nixpkgs.

...
pkgs.mkShell {
  ...
}
...

This next line creates the shell environment using the subsequent links as configuraiton.

...
  buildInputs = with pkgs; [
    xwayland
    SDL2
  ];
...

Here specific packages which should be available in the new shell environment are included. We’re specifying XWayland and SDL2 just in case they aren’t available in the global environment. XWayland allows X11 to be used as a fallaback and SDL2 is required for DragonRuby.

...
  shellHook = ''
    export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${
      with pkgs;
      lib.makeLibraryPath [
        libGL
        wayland
        wayland-protocols
        SDL2
        xorg.libX11
        xorg.libXi
        xwayland
      ]
    }"
    export SDL_VIDEODRIVER="wayland,x11"
  '';
...

This is where the magic happens. We’re creating a hook to be run each time we enter the new shell environment. Within that hook, we extend the LD_LIBRARY_PATH environment variable to include common Wayland and X11 libraries which are needed by SDL2. We include both so that environments running either Wayland or X11 will be able to use this single config. If you are on Wayland, it is recommended to keep the X libs as they provide an in-place fallback if for some Wayland fails to cooperate.

That’s it! All we needed was to enable nix-ld to handle generic Linux executables that rely on the FHS and a basic shell config for running GUI apps from the terminal!

wrap up

This is a pretty simple method for getting DragonRuby GTK running under NixOS. There are many different ways to do this but I just wanted to document the simplest method that works for my system. I’m still very new to Nix and I think this approach is pretty OK/ I don’t think I’m doing anything terribly unsafe or blasphemous.

If I end up changing my method or doing things differently I’ll leave this post for historical purposes and create a new post to document the new set up, with cross links for easy navigation.

credits

Thank you commandingdolphin@discord for sharing the X-compatible nix-shell snippet!

Thank you Iniyan@discord for requesting a Wayland-compatible version of this config!

The raw shell.nix config can be found at my sourcehut.