foxgirl.engineering
tools for building gleam projects with nix
readme: document anything at all
+84
README.md
+84
README.md
···
5
-->
6
7
# gleam2nix
8
+
[](https://github.com/fasterthanlime/free-of-syn)
9
+
10
11
tools for building [gleam](https://gleam.run) projects with [nix](https://nixos.org).
12
+
13
+
## quickstart
14
+
the general flow goes like:
15
+
1. use the `gleam2nix gen-nix` tool to generate a `gleam.nix` file from your gleam project's `manifest.toml`
16
+
2. call `buildGleamApplication` to produce a derivation for your project
17
+
18
+
to get gleam2nix important, pick one of the following based on your project structure:
19
+
20
+
<details>
21
+
<summary>plain nix</summary>
22
+
first, pull in this repo through whatever dependency management mechanism you prefer, such as [npins](https://github.com/andir/npins) or just a plain ol' `fetchTarball`. from the repo, you can import one of the following, based on how you want to use gleam2nix:
23
+
24
+
- `default.nix` (recommended): contains all the packages and functions you'll need
25
+
- `nix/overlay.nix`: an overlay function that can be added to nixpkgs. note that if you're using this, you'll also need to have [fenix](https://github.com/nix-community/fenix) added as an overlay - check their readme for setup instructions.
26
+
27
+
both options will define the following:
28
+
- `gleam2nix`: the `gleam2nix` cli tool
29
+
- `buildGleamApplicaton`: function for building a gleam application
30
+
- `buildGleam`: low-level function to compile a single gleam package
31
+
</details>
32
+
33
+
<details>
34
+
<summary>flake-based</summary>
35
+
first, add this repo as a flake input:
36
+
```nix
37
+
inputs = {
38
+
gleam2nix.url = "git+https://git.isincredibly.gay/srxl/gleam2nix";
39
+
gleam2nix.inputs.nixpkgs.follows = "nixpkgs"; # optional
40
+
}
41
+
```
42
+
43
+
the flake will have the following relevant outputs:
44
+
45
+
- `packages.<system>.gleam2nix`: the `gleam2nix` cli tool
46
+
- `lib.<system>.buildGleamApplicaton`: function for building a gleam application
47
+
- `lib.<system>.buildGleam`: low-level function to compile a single gleam package
48
+
- `overlays.gleam2nix`: a nixpkgs overlay that adds all of the above to `pkgs`. note that if you're using this, you'll also need to have [fenix](https://github.com/nix-community/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.
49
+
</details>
50
+
51
+
once setup, you can add `gleam2nix` whereever you need it, for example, in a nix shell:
52
+
```nix
53
+
pkgs.mkShell {
54
+
name = "devshell";
55
+
packages = [
56
+
gleam2nix
57
+
]
58
+
}
59
+
```
60
+
61
+
run `gleam2nix gen-nix` 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:
62
+
63
+
```nix
64
+
buildGleamApplication {
65
+
pname = "my-gleam-application";
66
+
version = "1.0.0";
67
+
src = ./.;
68
+
69
+
gleamNix = import ./gleam.nix;
70
+
}
71
+
```
72
+
73
+
## roadmap
74
+
- [x] build targeting the BEAM
75
+
- [x] `gleam export erlang-shipment` style packaging
76
+
- [ ] OTP releases
77
+
- [ ] escript packaging?
78
+
- [ ] build targeting JS
79
+
- [ ] nodejs
80
+
- [ ] deno
81
+
- [ ] bun
82
+
- [ ] upstream to nixpkgs
83
+
- [ ] `gleam2nix` cli
84
+
- [ ] builder functions
85
+
86
+
## contributing
87
+
the canonical home of this repo is on my [personal git forge](https://git.isincredibly.gay/srxl/gleam2nix), which doesn't have open signups. if you want to submit some changes or report bugs, you can either:
88
+
89
+
- open issues/PRs on the [tangled mirror](https://tangled.org/@foxgirl.engineering/gleam2nix)
90
+
- send me an email at `ruby@srxl.me` with issue reports or git patches
91
+
92
+
## licensing
93
+
all code in this repo is available under the very permissive terms of the [zero-clause bsd](./LICENSES/0BSD.txt) license.