getting started

Note

this tutorial is written primarily for an audience unfamiliar with nix. if you’re already comfortable using nix and just want to setup gleam2nix in your project, you can skip over to the quickstart guide instead.

let’s walk through the process of setting up a brand new gleam project, and then building it with gleam2nix.

to follow along and use gleam2nix, you’ll need a working nix install. if you aren’t already on nixos, i recommend using the lix installer to get setup.

project setup

to start, we’ll need a gleam project to build. initialize a new project with the following command:

xenia@system $ nix run nixpkgs#gleam new fox_petting_machine
Your Gleam project fox_petting_machine has been successfully created.
The project can be compiled and tested by running these commands:

        cd fox_petting_machine
        gleam test

you can choose any other name for the project you want, although i’m not sure why you’d want to make anything else. more importantly, the nix run bit requires a little explanation.

one of nix’s many magic tricks is the ability to run a command from a package without fully installing it on your system. the nixpkgs#gleam syntax tells nix that we want to run the command in the gleam package from nixpkgs, the main package repository for nix. nix will go and download it’s gleam package, and run the command with the arguments we provided, all without actually needing to install gleam. neat, huh?

but surely we want a gleam install, so that we can actually use the gleam compiler, right?

make a development shell

nix-shell lets you create self-contained, isolated “development shells”, that contain all the packages you need for your development work. they’re great for keeping your global environment clean and free from random clutter and conflicts, and for sharing consistent development environments with all your collaborators.

instead of installing gleam globally, let’s create a development shell with gleam instead. development shells are defined with a shell.nix file. create a new one in the new project’s root with the following contents:

shell.nix

let
  pkgs = import <nixpkgs> { };
in

pkgs.mkShell {
  name = "fox_petting_machine-devshell";
  packages = with pkgs; [
    erlang
    gleam
  ];
}

Note

i won’t spend too much time going into nix syntax here - if you want to learn more, check out the resources on nix.dev, and the “learn” section of the nixos website.

in this shell, we’ve specified that we want a shell that contains the gleam and erlang packages. we’ll want to use gleam to compile our app, and we’ll need erlang as our runtime.

now, you can run nix-shell, and you’ll be dropped into a shell that has gleam and erlang ready to go!

xenia@system $ nix-shell
(some shell build logs...)

xenia@nix-shell $ gleam run
  Resolving versions
Downloading packages
 Downloaded 2 packages in 0.01s
  Compiling gleam_stdlib
  Compiling gleeunit
  Compiling fox_petting_machine
   Compiled in 0.45s
    Running fox_petting_machine.main
Hello from fox_petting_machine!

Tip

if you don’t want to remember to run nix-shell every time you open your project, take a look at nix-direnv, which can automatically load your development shells as soon as you enter the project directory.

create gleam.nix

great, we have a new project ready to go. you can start building whatever you want in here, just like you would in any other gleam project. we’re here to setup gleam2nix though, so that’s what we’ll do next.

in your shell.nix file, add the following:

shell.nix

let
  pkgs = import <nixpkgs> { };
  gleam2nix = import (builtins.fetchTarball "https://git.isincredibly.gay/srxl/gleam2nix/archive/main.tar.gz") { };
in

pkgs.mkShell {
  name = "fox_petting_machine-devshell";
  packages = with pkgs; [
    erlang
    gleam
    gleam2nix.gleam2nix
  ];
}

Note

this will use the latest main commit of gleam2nix every time you enter the shell. if you need to use a stable version, change main in the url to a specific commit hash, or a tag name. you can also consider using a tool like npins to help manage all your nix dependencies.

with this change, we now have the gleam2nix cli in our project’s development shell, which we can use to generate a gleam.nix file. it contains all of your project’s dependencies, converted into nix build specifications - we’ll use this next once we define the nix build for the whole project.

to generate the file, first exit and re-enter the development shell, so it picks up out latest changes. then, just run gleam2nix in your project root, like so:

xenia@nix-shell $ exit

xenia@system $ nix-shell

xenia@nix-shell $ gleam2nix
Successfully generated gleam.nix

Caution

you’ll need to rerun this command every time you add, remove or update a gleam dependency in your project - otherwise, your nix builds could start failing, or run with old versions of your dependencies! consider using a git commit hook to make sure gleam.nix is up-to-date before committing changes.

defining the nix build

we’re getting close! we have our development shell ready to go, and our gleam.nix file generated. there’s one last step before we can build our gleam project using nix - and that’s to specify the nix build.

in nix, we use functions to create build specifications called “derivations”. we pass in all the relevant information about our build, such as our build-time and runtime dependencies, where to find the source code, and what commands to run. gleam2nix provides a function called buildGleamApplication, which comes preloaded with all the steps to build a gleam application and produce an output very similar to what gleam export erlang-shipment creates.

let’s use that function to build our project. in a new default.nix file in the root of your project, add the following:

default.nix

let
  gleam2nix = import (builtins.fetchTarball "https://git.isincredibly.gay/srxl/gleam2nix/archive/main.tar.gz") { };
in

gleam2nix.buildGleamApplication {
  pname = "fox_petting_machine";
  version = "1.0.0";
  src = ./.;
  gleamNix = import ./gleam.nix;
}

we give the function a package name and version, pass it the path to the project root relative to the default.nix file (in this case, the same directory default.nix is in), and the function imported from the gleam.nix file.

running the nix build

finally, we get to run our nix build! simply run nix-build in the root of the repo:

xenia@nix-shell $ nix-build
(lots of build logs...)
/nix/store/0nbzh0r6a2q889m78xxm0dz53xx3a53l-fox_petting_machine-1.0.0

Note

the final path will probably look a bit different on your machine - that’s okay. as long as it printed a path in /nix/store at the end, and not an error message, it means the build was successful.

that folder will contain the build output! nix will also create a symlink to that folder called result in your current directory. the output should look like this:

• Directoryresult

  • Directorybin

    • fox_petting_machine
  • Directorylib

    • Directoryentrypoint/

      • …
    • Directoryfox_petting_machine-1.0.0/

      • …
    • Directorygleam_stdlib-0.63.2/

      • …
    • Directorygleeunit-1.6.1/

      • …

the bin folder has a script to run our application, and lib has all of our compiled application and dependency code. if we run the script in bin, we should see that it runs our application successfully!

xenia@nix-shell $ ./result/bin/fox_petting_machine
Hello from fox_petting_machine!

next steps

you’ve now got a working nix build for your application! have a look around at the rest of the pages on the site to see what else you can do with gleam2nix - or just get started on your cool new gleam application!