foxgirl.engineering
tools for building gleam projects with nix
docs: add reference for buildGleamApplication
+1
-1
docs/astro.config.mjs
+1
-1
docs/astro.config.mjs
+106
docs/src/content/docs/reference/buildGleamApplication.md
+106
docs/src/content/docs/reference/buildGleamApplication.md
···
1
+
---
2
+
title: buildGleamApplication
3
+
description: gleam2nix command line arguments and usage
4
+
---
5
+
6
+
<!--
7
+
SPDX-FileCopyrightText: 2025 Ruby Iris Juric <ruby@srxl.me>
8
+
9
+
SPDX-License-Identifier: 0BSD
10
+
-->
11
+
12
+
the `buildGleamApplication` function compiles and builds a gleam application project with all it's dependencies, and produces an application package similar to what `gleam export erlang-shipment` creates.
13
+
14
+
## output
15
+
16
+
the built derivation wil include two folders:
17
+
18
+
- `bin/`: contains a script to run the application, named the same as the `pname` argument
19
+
- `lib/`: contains the compiled application and all of it's dependencies, each in their own folder
20
+
21
+
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:
22
+
23
+
1. ensures all OTP applications required to run the program are started with [`application:ensure_all_started/1`](https://www.erlang.org/doc/apps/kernel/application#ensure_all_started/1)
24
+
2. runs the `main` method defined by the gleam project
25
+
3. shuts down the erlang vm when `main` returns
26
+
27
+
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](https://gleam.run/writing-gleam/gleam-toml/).
28
+
29
+
## overriding dependencies
30
+
31
+
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](https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition) - it accepts two arguments, `final` and `prev`, and returns an attribute set containing any changed/additional dependencies.
32
+
33
+
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:
34
+
35
+
```nix
36
+
gleamNixOverrides = final: prev: {
37
+
doohickey = prev.doohickey.override {
38
+
src = pkgs.fetchgit {
39
+
...
40
+
}
41
+
}
42
+
}
43
+
```
44
+
45
+
## arguments
46
+
47
+
required arguments:
48
+
49
+
- `pname`: the derivation's name
50
+
- `version`: the derivation's version
51
+
- `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`)
52
+
- `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.
53
+
54
+
optional arguments:
55
+
56
+
- `erlang`: the erlang derivation to be used as the application runtime. defaults to `erlang` in nixpkgs
57
+
- `gleam`: the gleam derivation used to compile your project. defaults to `gleam` in nixpkgs
58
+
- `buildGleamArgs`: extra arguments to be passed to the `buildGleam` call for your project (not dependencies).
59
+
- `gleamNixOverrides`: an overlay-style function used to modify the dependencies specified in `gleamNix`. see the section on [overriding dependencies](#overriding-dependencies) for details.
60
+
61
+
any extra arguments not listed here will be passed to the underlying `stdenv.mkDerivation` call.
62
+
63
+
## examples
64
+
65
+
a basic application build:
66
+
67
+
```nix
68
+
buildGleamApplication {
69
+
pname = "basic";
70
+
version = "1.0.0";
71
+
src = ./.;
72
+
gleamNix = import ./gleam.nix;
73
+
}
74
+
```
75
+
76
+
build an application that runs under a specific version of erlang:
77
+
78
+
```nix
79
+
buildGleamApplication {
80
+
pname = "twenty-eight";
81
+
version = "1.0.0";
82
+
src = ./.;
83
+
gleamNix = import ./gleam.nix;
84
+
85
+
erlang = pkgs.erlang_28;
86
+
}
87
+
```
88
+
89
+
add an extra script to the output:
90
+
91
+
```nix
92
+
buildGleamApplication {
93
+
pname = "extra-bin-script";
94
+
version = "1.0.0";
95
+
src = ./.;
96
+
gleamNix = import ./gleam.nix;
97
+
98
+
postInstall = ''
99
+
cat > $out/bin/colon-three <<EOF
100
+
#!/usr/bin/env bash
101
+
echo ":3"
102
+
EOF
103
+
chmod +x $out/bin/colon-three
104
+
'';
105
+
}
106
+
```