MIRROR: javascript for 馃悳's, a tiny runtime with big ambitions
1# Building Ant
2
3Depending on what platform or features you need, the build process may
4differ. After you've built a binary, running the
5test suite to confirm that the binary works as intended is a good next step.
6
7If you can reproduce a test failure, search for it in the <br>
8[Ant issue tracker](https://github.com/theMackabu/ant/issues) or file a new issue.
9
10## Table of contents
11
12- [Supported platforms](#supported-platforms)
13 - [Platform list](#platform-list)
14 - [Supported toolchains](#supported-toolchains)
15 - [Official binary platforms and toolchains](#official-binary-platforms-and-toolchains)
16- [Building Ant on supported platforms](#building-ant-on-supported-platforms)
17 - [Prerequisites](#prerequisites)
18 - [Unix and macOS](#unix-and-macos)
19 - [Unix prerequisites](#unix-prerequisites)
20 - [macOS prerequisites](#macos-prerequisites)
21 - [Building Ant](#building-ant-1)
22 - [Installing Ant](#installing-ant)
23 - [Running tests](#running-tests)
24 - [Building a debug build](#building-a-debug-build)
25 - [Building an ASan build](#building-an-asan-build)
26 - [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing)
27 - [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds)
28 - [Windows](#windows)
29 - [Windows prerequisites](#windows-prerequisites)
30 - [Building Ant](#building-ant-2)
31- [Meson build options](#meson-build-options)
32
33## Supported platforms
34
35### Platform list
36
37Ant builds and runs on the following platforms. Official CI builds are
38produced for each platform listed below.
39
40| Operating System | Architectures | Variant | Static | Notes |
41| ---------------- | ------------- | ---------- | ------ | ---------------------------- |
42| GNU/Linux | x64 | glibc | No | Ubuntu 22.04 (CI) |
43| GNU/Linux | aarch64 | glibc | No | Ubuntu 22.04 (CI) |
44| GNU/Linux | x64 | musl | Yes | Alpine Edge (CI) |
45| GNU/Linux | aarch64 | musl | Yes | Alpine Edge (CI) |
46| macOS | x64 | darwin | No | macOS 15 (CI) |
47| macOS | aarch64 | darwin | No | macOS 15 (CI) |
48| Windows | x64 | mingw/msys | No | MSYS2 MINGW64 toolchain (CI) |
49
50### Supported toolchains
51
52Ant is built with the GNU C23 standard (`-std=gnu23`). A compiler with
53C23 support is required.
54
55| Operating System | Compiler Versions |
56| ---------------- | ------------------------------------- |
57| Linux | GCC >= 14 or Clang >= 18 |
58| macOS | Xcode CLT (Apple Clang) or LLVM >= 18 |
59| Windows | MinGW-w64 GCC via MSYS2 (MINGW64) |
60
61### Official binary platforms and toolchains
62
63CI binaries are produced using:
64
65| Binary package | Platform and Toolchain |
66| ---------------------- | -------------------------------------------- |
67| ant-linux-x64 | Ubuntu 22.04 (glibc), LLVM/Clang |
68| ant-linux-aarch64 | Ubuntu 22.04 (glibc), LLVM/Clang |
69| ant-linux-x64-musl | Alpine Edge (musl), statically linked, Clang |
70| ant-linux-aarch64-musl | Alpine Edge (musl), statically linked, Clang |
71| ant-darwin-x64 | macOS 15 Intel, LLVM/Clang |
72| ant-darwin-aarch64 | macOS 15 ARM, LLVM/Clang |
73| ant-windows-x64 | MSYS2 MINGW64 toolchain |
74
75## Building Ant on supported platforms
76
77### Prerequisites
78
79The following tools are required to build Ant regardless of platform:
80
81- **C compiler** with C23 support (GCC >= 14 or Clang >= 18)
82- **[Meson](https://mesonbuild.com/)** build system (and Ninja backend)
83- **[CMake](https://cmake.org/)** (for the tlsuv subproject)
84- **pkg-config**
85- **Node.js** >= 22 (used to generate the JS snapshot at build time)
86- **[Rust](https://rustup.rs/)** toolchain (stable) with `cargo` (builds the OXC type-strip library)
87- **[Zig](https://ziglang.org/)** >= 0.15 (builds the package manager component)
88- **Git**
89
90Dependencies are vendored as Meson subprojects under `vendor/`
91and are fetched automatically:
92
93- aklomp-base64 0.5.2
94- argtable3 3.3.1
95- BoringSSL `297b11798a0ed6bc7736aa57328909a4afbbf67a`
96- crprintf `HEAD`
97- google-brotli 1.1.0
98- libffi 3.5.2
99- libuv 1.52.0
100- llhttp 9.3.1
101- LMDB (OpenLDAP LMDB 0.9.33)
102- minicoro `HEAD`
103- MIR `HEAD`
104- nghttp2 1.68.0
105- PCRE2 10.47
106- tlsuv 0.40.13
107- uriparser 1.0.0
108- utf8proc 2.10.0
109- uthash 2.3.0
110- uuidv7-h `HEAD`
111- wasm-micro-runtime `92f40918bbfad35546a1512b10bd25eaa31add4d`
112- yyjson 0.12.0
113- zlib-ng 2.3.3
114
115### Unix and macOS
116
117#### Unix prerequisites
118
119Installation via package manager:
120
121- Ubuntu/Debian:
122
123 ```bash
124 sudo apt-get install python3 python3-pip gcc-14 g++-14 ninja-build cmake \
125 pkg-config nodejs npm
126 pip3 install meson
127 ```
128
129- Fedora:
130
131 ```bash
132 sudo dnf install python3 gcc gcc-c++ ninja-build cmake pkgconf \
133 nodejs npm
134 pip3 install meson
135 ```
136
137- Alpine (musl):
138 ```sh
139 apk add clang lld llvm meson ninja cmake pkgconf nodejs npm \
140 musl-dev \
141 util-linux-dev util-linux-static linux-headers libunwind-dev libunwind-static
142 ```
143
144You will also need Rust and Zig installed. The recommended approach:
145
146```bash
147# Rust (via rustup)
148curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
149
150# Zig (download from https://ziglang.org/download/)
151# Or via package manager if available
152```
153
154#### macOS prerequisites
155
156- Xcode Command Line Tools (provides Apple Clang):
157
158 ```bash
159 xcode-select --install
160 ```
161
162- Install remaining tools via [Homebrew](https://brew.sh):
163
164 ```bash
165 brew install meson ninja llvm node
166 ```
167
168- Rust and Zig:
169
170 ```bash
171 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
172 brew install zig
173 ```
174
175#### Building Ant
176
177> [!IMPORTANT]
178> If the path to your build directory contains a space, the build will likely
179> fail.
180
181To build Ant:
182
183```bash
184meson subprojects download
185meson setup build
186meson compile -C build
187```
188
189Alternatively, if you have [maid](https://github.com/exact-labs/maid) installed, <br>
190you can use the task runner:
191
192```bash
193maid setup # downloads subprojects + configures with ccache and lld
194maid build # compiles
195maid run <file> # builds and runs a JS file
196```
197
198> [!TIP]
199> `maid setup` automatically configures ccache and lld for faster builds.
200> Use `maid run <file>` during development to build and execute in one step.
201
202To verify the build:
203
204```bash
205./build/ant --version
206./build/ant -e "console.log('Hello from Ant ' + Ant.version)"
207```
208
209#### Installing Ant
210
211You can install the built binary using:
212
213```bash
214maid install
215```
216
217This copies the binary to the directory of an existing `ant` installation, or
218falls back to `~/.ant/bin/`. It also creates an `antx` symlink.
219
220Alternatively, copy the binary manually:
221
222```bash
223cp ./build/ant /usr/local/bin/ant
224```
225
226#### Running tests
227
228To run a single test:
229
230```bash
231./build/ant tests/test_async.cjs
232```
233
234To run the spec suite:
235
236```bash
237./build/ant examples/spec/run.js
238```
239
240> [!NOTE]
241> Remember to recompile with `meson compile -C build` (or `maid build`)
242> between test runs if you change code in the `src/` directory.
243
244#### Building a debug build
245
246A debug build disables optimizations and LTO, and preserves debug symbols:
247
248```bash
249meson subprojects download
250CC="ccache $(which clang)" \
251 meson setup build --wipe --buildtype=debug \
252 -Doptimization=0 -Db_lto=false -Dstrip=false -Db_lundef=false -Dunity=off
253meson compile -C build
254```
255
256Or with maid:
257
258```bash
259maid debug
260maid build
261```
262
263When using the debug build, core dumps will be generated in case of crashes.
264Use `lldb` or `gdb` with the debug binary to inspect them:
265
266```bash
267lldb ./build/ant core.ant
268(lldb) bt
269```
270
271#### Building an ASan build
272
273[ASan](https://github.com/google/sanitizers) can help detect memory bugs.
274
275> [!WARNING]
276> ASan builds are significantly slower than release builds. The debug flags
277> are not required but can produce clearer stack traces when ASan detects
278> an issue.
279
280```bash
281meson subprojects download
282CC="ccache $(which clang)" \
283 meson setup build --wipe \
284 -Db_sanitize=address -Doptimization=0 -Db_lto=false -Dstrip=false -Db_lundef=false
285meson compile -C build
286```
287
288Or with maid:
289
290```bash
291maid asan
292maid build
293```
294
295Then run tests against the ASan build:
296
297```bash
298./build/ant tests/test_gc.js
299```
300
301#### Speeding up frequent rebuilds when developing
302
303If you plan to frequently rebuild Ant, installing `ccache` can greatly
304reduce build times. The `maid setup` task configures ccache automatically.
305
306> [!TIP]
307> Using both `ccache` and `lld` together provides the best rebuild
308> performance. `ccache` caches compilation, while `lld` speeds up linking
309> (which cannot be cached).
310
311On GNU/Linux:
312
313```bash
314sudo apt install ccache
315export CC="ccache gcc" # add to your .profile
316```
317
318On macOS:
319
320```bash
321brew install ccache
322export CC="ccache cc" # add to ~/.zshrc
323```
324
325Using `lld` as the linker also speeds up link times:
326
327```bash
328export CC_LD="$(which ld64.lld)" # macOS with brew llvm
329# or
330export CC_LD="$(which lld)" # Linux
331```
332
333> [!NOTE]
334> LTO is enabled by default with 8 threads (`b_lto=true`,
335> `b_lto_threads=8`). Disable it with `-Db_lto=false` for faster iteration
336> during development.
337
338#### Troubleshooting Unix and macOS builds
339
340Stale builds can sometimes result in errors. Clean the build directory and
341reconfigure:
342
343```bash
344rm -rf build
345meson setup build
346meson compile -C build
347```
348
349If you encounter "file not found" errors for vendored dependencies:
350
351```bash
352meson subprojects download
353```
354
355If the build runs out of memory, reduce parallelism:
356
357```bash
358meson compile -C build -j2
359```
360
361### Windows
362
363#### Windows prerequisites
364
365Ant on Windows is built using the MSYS2 MINGW64 toolchain.
366
367> [!IMPORTANT]
368> Native MSVC builds are not currently supported. You must use the MSYS2
369> MINGW64 environment.
370
3711. Install [MSYS2](https://www.msys2.org/)
3722. Open the **MINGW64** shell and install dependencies:
373 ```bash
374 pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-meson \
375 mingw-w64-x86_64-ninja mingw-w64-x86_64-cmake \
376 mingw-w64-x86_64-lld mingw-w64-x86_64-nodejs git
377 ```
3783. Install Rust via [rustup](https://rustup.rs/) (select the
379 `x86_64-pc-windows-gnu` target)
3804. Install [Zig](https://ziglang.org/download/)
381
382#### Building Ant
383
384From the MSYS2 MINGW64 shell:
385
386```bash
387git clone https://github.com/theMackabu/ant.git
388cd ant
389meson subprojects download
390meson setup build -Dc_std=gnu2x
391meson compile -C build
392```
393
394> [!NOTE]
395> Windows builds use `-Dc_std=gnu2x` instead of `gnu23` due to MinGW
396> toolchain compatibility.
397
398To verify:
399
400```bash
401./build/ant.exe --version
402```
403
404## Meson build options
405
406Configure options are set via `meson setup` or `meson configure`:
407
408| Option | Type | Default | Description |
409| ------------------- | ------- | ------- | ------------------------------------------ |
410| `static_link` | boolean | `false` | Statically link the final binary |
411| `build_timestamp` | string | (auto) | Build timestamp (defaults to current time) |
412| `deps_prefix_cmake` | string | (empty) | Prefix path for cmake dependency lookup |
413
414Standard Meson built-in options used by Ant:
415
416| Option | Default | Description |
417| --------------- | --------- | --------------------------------- |
418| `buildtype` | `release` | Build type (release, debug, etc.) |
419| `optimization` | `3` | Optimization level (0-3) |
420| `c_std` | `gnu23` | C language standard |
421| `b_lto` | `true` | Link-time optimization |
422| `b_lto_threads` | `8` | LTO parallelism |
423| `strip` | `true` | Strip debug symbols from binary |
424| `b_sanitize` | `none` | Sanitizer (e.g. `address`) |
425
426Example:
427
428```bash
429meson setup build -Dstatic_link=true --prefer-static
430```