foxgirl.engineering
tools for building gleam projects with nix
docs: document javascript targets
+34
-2
+5
-1
docs/src/content/docs/reference/buildGleam.md
+5
-1
docs/src/content/docs/reference/buildGleam.md
···
25
25
26
26
optional arguments:
27
27
28
+
- `target`: the compilation target language, either `erlang` (default) or `javascript`
28
29
- `beamDeps`: a list of derivations containing compiled dependencies of this project
29
30
- `erlang`: the erlang derivation to be used as the application runtime. defaults to `erlang` in nixpkgs
30
31
- `gleam`: the gleam derivation used to compile your project. defaults to `gleam` in nixpkgs
···
34
35
35
36
## output
36
37
37
-
the built derivation contains the compiled erlang bytecode and support files under `/lib/erlang/lib/<name>-<version>`, substituting `name` and `version` with the values passed as arguments.
38
+
the built derivation contains the compiled code and support files under the following directory, based on the provided `target`:
39
+
40
+
- erlang: `/lib/erlang/lib/<name>-<version>`
41
+
- javascript: `/<name>`
+29
-1
docs/src/content/docs/reference/buildGleamApplication.md
+29
-1
docs/src/content/docs/reference/buildGleamApplication.md
···
9
9
SPDX-License-Identifier: 0BSD
10
10
-->
11
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.
12
+
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.
13
13
14
14
## arguments
15
15
···
22
22
23
23
optional arguments:
24
24
25
+
- `target`: the compilation target language, either `erlang` (default) or `javascript`
25
26
- `erlang`: the erlang derivation to be used as the application runtime. defaults to `erlang` in nixpkgs
26
27
- `gleam`: the gleam derivation used to compile your project. defaults to `gleam` in nixpkgs
28
+
- `jsRuntime`: a derivation containing the javascript runtime used to run the application (one of nodejs, deno or bun). defaults to `null` (no runtime)
27
29
- `buildGleamArgs`: extra arguments to be passed to the `buildGleam` call for your project (not dependencies).
28
30
- `gleamNixOverrides`: an overlay-style function used to modify the dependencies specified in `gleamNix`. see the section on [overriding dependencies](#overriding-dependencies) for details.
29
31
···
35
37
36
38
- `bin/`: contains a script to run the application, named the same as the `pname` argument
37
39
- `lib/`: contains the compiled application and all of it's dependencies, each in their own folder
40
+
41
+
the specific contents of these folders depend on the `target` being compiled for.
42
+
43
+
### erlang
38
44
39
45
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:
40
46
···
44
50
45
51
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/).
46
52
53
+
### javascript
54
+
55
+
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.
56
+
57
+
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.
58
+
59
+
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.
60
+
47
61
## overriding dependencies
48
62
49
63
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.
···
83
97
gleamNix = import ./gleam.nix;
84
98
85
99
erlang = pkgs.erlang_28;
100
+
}
101
+
```
102
+
103
+
build an application that targets javascript, and runs on deno:
104
+
105
+
```nix
106
+
buildGleamApplication {
107
+
pname = "twenty-eight";
108
+
version = "1.0.0";
109
+
src = ./.;
110
+
gleamNix = import ./gleam.nix;
111
+
112
+
target = "javascript";
113
+
jsRuntime = pkgs.deno;
86
114
}
87
115
```
88
116