buildGleamApplication

the buildGleamApplication function compiles and builds a gleam application project with all it’s dependencies, and produces an application package with a script that can run the application.

arguments

required arguments:

• pname: the derivation’s name
• version: the derivation’s version
• src: the location of the project source code. must be the root directory of a gleam project (ie. contains a gleam.toml and manifest.toml)
• gleamNix: a function returning an attrset with all of the project’s dependencies. note that this must be the function itself, and not just a path to the gleam.nix - make sure you import the file.

optional arguments:

• target: the compilation target language, either erlang (default) or javascript
• erlang: the erlang derivation to be used as the application runtime. defaults to erlang in nixpkgs
• gleam: the gleam derivation used to compile your project. defaults to gleam in nixpkgs
• jsRuntime: a derivation containing the javascript runtime used to run the application (one of nodejs, deno or bun). defaults to null (no runtime)
• buildGleamArgs: extra arguments to be passed to the buildGleam call for your project (not dependencies).
• gleamNixOverrides: an overlay-style function used to modify the dependencies specified in gleamNix. see the section on overriding dependencies for details.

any extra arguments not listed here will be passed to the underlying stdenv.mkDerivation call.

output

the built derivation wil include two folders:

• bin/: contains a script to run the application, named the same as the pname argument
• lib/: contains the compiled application and all of it’s dependencies, each in their own folder

the specific contents of these folders depend on the target being compiled for.

erlang

the lib directory also holds an entrypoint folder, which contains a very simple erlang module with a function used to start the app. the script in the bin directory will start the erlang vm with all compiled erlang files in lib loaded, and call the entrypoint function to do the following:

1. ensures all OTP applications required to run the program are started with application:ensure_all_started/1
2. runs the main method defined by the gleam project
3. shuts down the erlang vm when main returns

by default, every dependency of your gleam project will be started in step 1. if you need to load in additional applications, such as ones included in OTP, specify them in the [erlang] section of your gleam.toml file.

javascript

the lib directory contains the compiled application and each dependency in it’s own folder, as well as a gleam_entrypoint.mjs file that imports and calls the main function in the application.

by default, the bin directory is not created, and the built application is comprised solely of compiled javascript code. this is useful if your application is not meant to be run directly, and instead is meant to be loaded into a web application or imported as a library.

if your project is intended to be run as an application, you can pass a javascript runtime package to jsRuntime to generate a script for running the app. the script will execute the gleam_entrypoint.mjs file (ie. the application’s main function) using the provided runtime.

overriding dependencies

it’s not recommended to modify the gleam.nix file directly, as it’s automatically generated and any changes will be lost when it needs to be generated. instead, you can pass a function to gleamNixOverrides to make modifications to project dependencies. the function works similarly to a nixpkgs overlay - it accepts two arguments, final and prev, and returns an attribute set containing any changed/additional dependencies.

for example, if you have a path dependency named doohickey in your gleam.toml, but you need to fetch it from a git repo in your nix builds, you can define gleamNixOverrides as:

gleamNixOverrides = final: prev: {
  doohickey = prev.doohickey.override {
    src = pkgs.fetchgit {
      ...
    }
  }
}

examples

a basic application build:

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

build an application that runs under a specific version of erlang:

buildGleamApplication {
  pname = "twenty-eight";
  version = "1.0.0";
  src = ./.;
  gleamNix = import ./gleam.nix;

  erlang = pkgs.erlang_28;
}

build an application that targets javascript, and runs on deno:

buildGleamApplication {
  pname = "twenty-eight";
  version = "1.0.0";
  src = ./.;
  gleamNix = import ./gleam.nix;

  target = "javascript";
  jsRuntime = pkgs.deno;
}

add an extra script to the output:

buildGleamApplication {
  pname = "extra-bin-script";
  version = "1.0.0";
  src = ./.;
  gleamNix = import ./gleam.nix;

  postInstall = ''
    cat > $out/bin/colon-three <<EOF
    #!/usr/bin/env bash
    echo ":3"
    EOF
    chmod +x $out/bin/colon-three
  '';
}