veloren/nix/README.md

Important

If you are going to call the derivations with a custom nixpkgs argument, make sure that the nixpkgs you pass is on at least the same commit or newer than it. Unexpected errors may pop up if you use an older version. Same goes for the sources argument.

How to use

To enter the development shell (which includes all tools mentioned in this readme + tools you'll need to develop Veloren), run:

nix-shell nix/shell.nix

It is recommended that you enter the dev shell before starting to build using nix-build or nix-env (anything which build stuff), since it will setup a Cachix cache for you. (you can configure this for your user's nix.conf by running cachix use veloren-nix once in the dev shell, which will make the cache available when you run commands outside of the dev shell).

If you have direnv setup on your system, it is also recommended to copy the envrc (or envrc-nvidia, if you have an Nvidia GPU) file to the root of the repository as .envrc:

cp nix/envrc .envrc

This will make your env have the dev env setup automatically.

To build and install Voxygen and the server CLI into user profile, run:

nix-env -f nix/default.nix -i

You can configure what to install by changing the cratesToBuild argument:

nix-env -f nix/default.nix --arg cratesToBuild '["veloren-voxygen"]'

For example, this will install Voxygen only.

You can configure the crates to be built with debug mode (not recommended, equals to opt-level = 0):

nix-env -f nix/default.nix --arg release false

If you aren't on NixOS, you can run veloren-voxygen using the provided nixGLIntel in the dev shell:

nixGLIntel veloren-voxygen

If you have an Nvidia GPU, you can enter the dev shell like so:

nix-shell nix/shell.nix --arg nvidia true

And you'll be able to use nixGLNvidia and nixGLNvidiaBumblebee.

Using the flake

Due to the nature of flakes' reliance on git and the way git-lfs is configured for this repo, you must already have git-lfs in your environment when running nix commands on a local checkout. Run this to enter a shell environment with git-lfs in your path:

nix shell nixpkgs#git-lfs

To enter a shell environment with the necessary tools:

nix develop

If you simply want to run the latest version without necessarily installing it, you can do so with

# Voxygen (the default):
nix run gitlab:veloren/veloren
# Server CLI:
nix run gitlab:veloren/veloren#veloren-server-cli

To install (for example) the game client on your system, the configuration could look something like this:

{ description = "NixOS configuration with flakes";

  inputs.veloren.url = gitlab:veloren/veloren;

  outputs = { self, nixpkgs, veloren }: {
    nixosConfigurations.<your-hostname> = nixpkgs.lib.nixosSystem rec {
      system = <your-system-arch>;
      # ...
      modules = [
        # add to your overlay so that the packages appear in pkgs
        # for subsequent modules
        ({...}: {
          nixpkgs.overlays = [
            # ...
            (final: prev: {
              inherit (veloren.packages."${system}") veloren-voxygen;
            })
          ];

          # You can also add the flake to your registry
          nix.registry.veloren.flake = veloren;
          # with this, you can run latest master
          # regardless of version installed like this:
          # nix run veloren/master
        })

        # some module
        ({ pkgs, ... }: {
          environment.systemPackages = [
            pkgs.veloren-voxygen
          ];
        })
        # ...
      ];
    };
  };
}

Managing Cargo.nix

Enter the development shell.

To update Cargo.nix (and crate-hashes.json) using latest Cargo.lock, run:

crate2nix generate -f ../Cargo.toml

Managing dependencies

Nix with flakes enabled

If a specific revision is specified in flake.nix, you will have to update that first, either by specifying a new desired revision or by removing it.

You can update the dependencies individually or all at once from the root of the project:

# only nixpkgs
nix flake update --update-input nixpkgs
# everything
nix flake update --recreate-lock-file

See the NixOS wiki for more information on how to use flakes.

Legacy nix

It is inadvised to update revisions without the use of nix flake update as it's both tedious and error-prone to attempt setting all fields to their correct values in both flake.nix and flake.lock, but if you need to do it for testing, flake.lock is where legacy nix commands get the input revisions from (through flake-compat), regardless of what is specified in flake.nix (see https://github.com/edolstra/flake-compat/issues/10).

Modify the relevant rev field in flake.lock to what you need - you can use nix-prefetch-git to find an up-to-date revision. Leave the narHash entry as is and attempt a rebuild to find out what its value should be.

Formatting

Use nixpkgs-fmt to format files.

To format every Nix file:

nixpkgs-fmt flake.nix nix/*.nix