quickstart

Note

this guide assumes pre-existing familiarity with nix. if you’re new to nix, check out the getting started tutorial for a gentler introduction.

the general flow goes like:

1. use the gleam2nix tool to generate a gleam.nix file from your gleam project’s manifest.toml
2. call buildGleamApplication to produce a derivation for your project

initial setup

to get gleam2nix imported, pick one of the following based on your project structure:

plain nix

first, pull in this repo through whatever dependency management mechanism you prefer, such as npins, niv or just a plain ol’ fetchTarball. from the repo, you can import one of the following, based on how you want to use gleam2nix:

• default.nix (recommended): contains all the packages and functions you’ll need
• nix/overlay.nix: an overlay function that can be added to nixpkgs.

Caution

if you’re using the overlay, you’ll also need to have fenix added as an overlay - check their readme for setup instructions.

both options will define the following:

• gleam2nix: the gleam2nix cli tool
• buildGleamApplication: function for building a gleam application
• buildGleam: low-level function to compile a single gleam package
• gleam-tool: helper tool used by buildGleam and buildGleamApplication

flakes

first, add this repo as a flake input:

flake.nix

inputs = {
  gleam2nix.url = "git+https://git.isincredibly.gay/srxl/gleam2nix";
  gleam2nix.inputs.nixpkgs.follows = "nixpkgs"; # optional
}

the flake will have the following relevant outputs:

• packages.<system>.gleam2nix: the gleam2nix cli tool
• lib.<system>.buildGleamApplication: function for building a gleam application
• lib.<system>.buildGleam: low-level function to compile a single gleam package
• gleam-tool: helper tool used by buildGleam and buildGleamApplication
• overlays.gleam2nix: a nixpkgs overlay that adds all of the above to pkgs.

Caution

if you use the overlay, you’ll also need to have fenix added as an overlay. gleam2nix re-exports the overlay from it’s input as overlays.fenix if you need it, otherwise you can set that up however you like.

usage

once setup, you can add gleam2nix whereever you need it. for example, in a nix shell:

pkgs.mkShell {
  name = "devshell";
  packages = [
    gleam2nix
  ]
}

run gleam2nix in the root of your project (ie. the folder containing your manifest.toml) to get a gleam.nix file. you can then pass it to a buildGleamApplication call to get your derivation:

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