BUILDING.md
No OneTemporary
Actions

Size

13 KB

Referenced Files

None

Subscribers

None

BUILDING.md
View Options

	# Building Ant

	Depending on what platform or features you need, the build process may
	differ. After you've built a binary, running the
	test suite to confirm that the binary works as intended is a good next step.

	If you can reproduce a test failure, search for it in the <br>
	[Ant issue tracker](https://github.com/theMackabu/ant/issues) or file a new issue.

	## Table of contents

	- [Supported platforms](#supported-platforms)
	- [Platform list](#platform-list)
	- [Supported toolchains](#supported-toolchains)
	- [Official binary platforms and toolchains](#official-binary-platforms-and-toolchains)
	- [Building Ant on supported platforms](#building-ant-on-supported-platforms)
	- [Prerequisites](#prerequisites)
	- [Unix and macOS](#unix-and-macos)
	- [Unix prerequisites](#unix-prerequisites)
	- [macOS prerequisites](#macos-prerequisites)
	- [Building Ant](#building-ant-1)
	- [Installing Ant](#installing-ant)
	- [Running tests](#running-tests)
	- [Building a debug build](#building-a-debug-build)
	- [Building an ASan build](#building-an-asan-build)
	- [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing)
	- [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds)
	- [Windows](#windows)
	- [Windows prerequisites](#windows-prerequisites)
	- [Building Ant](#building-ant-2)
	- [Meson build options](#meson-build-options)
	- [TLS library selection](#tls-library-selection)

	## Supported platforms

	### Platform list

	Ant builds and runs on the following platforms. Official CI builds are
	produced for each platform listed below.

	\| Operating System \| Architectures \| Variant \| Static \| Notes \|
	\| ---------------- \| ------------- \| ---------- \| ------ \| ---------------------------- \|
	\| GNU/Linux \| x64 \| glibc \| No \| Ubuntu 22.04 (CI) \|
	\| GNU/Linux \| aarch64 \| glibc \| No \| Ubuntu 22.04 (CI) \|
	\| GNU/Linux \| x64 \| musl \| Yes \| Alpine Edge (CI) \|
	\| GNU/Linux \| aarch64 \| musl \| Yes \| Alpine Edge (CI) \|
	\| macOS \| x64 \| openssl \| No \| macOS 15 (CI) \|
	\| macOS \| aarch64 \| openssl \| No \| macOS 15 (CI) \|
	\| macOS \| x64 \| mbedtls \| No \| macOS 15 (CI) \|
	\| macOS \| aarch64 \| mbedtls \| No \| macOS 15 (CI) \|
	\| Windows \| x64 \| mingw/msys \| No \| MSYS2 MINGW64 toolchain (CI) \|

	### Supported toolchains

	Ant is built with the GNU C23 standard (`-std=gnu23`). A compiler with
	C23 support is required.

	\| Operating System \| Compiler Versions \|
	\| ---------------- \| ------------------------------------- \|
	\| Linux \| GCC >= 14 or Clang >= 18 \|
	\| macOS \| Xcode CLT (Apple Clang) or LLVM >= 18 \|
	\| Windows \| MinGW-w64 GCC via MSYS2 (MINGW64) \|

	### Official binary platforms and toolchains

	CI binaries are produced using:

	\| Binary package \| Platform and Toolchain \|
	\| -------------------------- \| -------------------------------------------- \|
	\| ant-linux-x64 \| Ubuntu 22.04 (glibc), LLVM/Clang \|
	\| ant-linux-aarch64 \| Ubuntu 22.04 (glibc), LLVM/Clang \|
	\| ant-linux-x64-musl \| Alpine Edge (musl), statically linked, Clang \|
	\| ant-linux-aarch64-musl \| Alpine Edge (musl), statically linked, Clang \|
	\| ant-darwin-x64 \| macOS 15 Intel, LLVM/Clang \|
	\| ant-darwin-aarch64 \| macOS 15 ARM, LLVM/Clang \|
	\| ant-darwin-x64-mbedtls \| macOS 15 Intel, LLVM/Clang, mbedTLS \|
	\| ant-darwin-aarch64-mbedtls \| macOS 15 ARM, LLVM/Clang, mbedTLS \|
	\| ant-windows-x64 \| MSYS2 MINGW64 toolchain \|

	## Building Ant on supported platforms

	### Prerequisites

	The following tools are required to build Ant regardless of platform:

	- C compiler with C23 support (GCC >= 14 or Clang >= 18)
	- [Meson](https://mesonbuild.com/) build system (and Ninja backend)
	- [CMake](https://cmake.org/) (for the tlsuv subproject)
	- pkg-config
	- Node.js >= 22 (used to generate the JS snapshot at build time)
	- [Rust](https://rustup.rs/) toolchain (stable) with `cargo` (builds the OXC type-strip library)
	- [Zig](https://ziglang.org/) >= 0.15 (builds the package manager component)
	- Git

	System libraries required:

	- OpenSSL (default) or mbedTLS (alternative TLS backend)
	- libsodium
	- libuuid (Linux/macOS)
	- llhttp (if not building from source via cmake)

	The remaining dependencies are vendored as Meson subprojects under `vendor/`
	and are fetched automatically:

	- libuv 1.52.0
	- yyjson 0.12.0
	- zlib-ng 2.3.3
	- nghttp2
	- pcre2
	- libffi
	- lmdb (OpenLDAP LMDB 0.9.33)
	- minicoro
	- argtable3
	- uthash
	- uuidv7
	- tlsuv (cmake subproject)

	### Unix and macOS

	#### Unix prerequisites

	Installation via package manager:

	- Ubuntu/Debian:

	```bash
	sudo apt-get install python3 python3-pip gcc-14 g++-14 ninja-build cmake \
	pkg-config uuid-dev libssl-dev libsodium-dev nodejs npm
	pip3 install meson
	```

	- Fedora:

	```bash
	sudo dnf install python3 gcc gcc-c++ ninja-build cmake pkgconf \
	libuuid-devel openssl-devel libsodium-devel nodejs npm
	pip3 install meson
	```

	- Alpine (musl):
	```sh
	apk add clang lld llvm meson ninja cmake pkgconf nodejs npm \
	musl-dev openssl-dev openssl-libs-static libsodium-dev libsodium-static \
	util-linux-dev util-linux-static linux-headers libunwind-dev libunwind-static
	```

	You will also need Rust and Zig installed. The recommended approach:

	```bash
	# Rust (via rustup)
	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh

	# Zig (download from https://ziglang.org/download/)
	# Or via package manager if available
	```

	#### macOS prerequisites

	- Xcode Command Line Tools (provides Apple Clang):

	```bash
	xcode-select --install
	```

	- Install remaining tools via [Homebrew](https://brew.sh):

	```bash
	brew install meson ninja llvm openssl@3 libsodium node
	```

	- Rust and Zig:

	```bash
	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh
	brew install zig
	```

	#### Building Ant

	> [!IMPORTANT]
	> If the path to your build directory contains a space, the build will likely
	> fail.

	To build Ant:

	```bash
	meson subprojects download
	meson setup build
	meson compile -C build
	```

	Alternatively, if you have [maid](https://github.com/exact-labs/maid) installed, <br>
	you can use the task runner:

	```bash
	maid setup # downloads subprojects + configures with ccache and lld
	maid build # compiles
	maid run <file> # builds and runs a JS file
	```

	> [!TIP]
	> `maid setup` automatically configures ccache and lld for faster builds.
	> Use `maid run <file>` during development to build and execute in one step.

	To verify the build:

	```bash
	./build/ant --version
	./build/ant -e "console.log('Hello from Ant ' + Ant.version)"
	```

	#### Installing Ant

	You can install the built binary using:

	```bash
	maid install
	```

	This copies the binary to the directory of an existing `ant` installation, or
	falls back to `~/.ant/bin/`. It also creates an `antx` symlink.

	Alternatively, copy the binary manually:

	```bash
	cp ./build/ant /usr/local/bin/ant
	```

	#### Running tests

	To run a single test:

	```bash
	./build/ant tests/test_async.cjs
	```

	To run the spec suite:

	```bash
	./build/ant examples/spec/run.js
	```

	> [!NOTE]
	> Remember to recompile with `meson compile -C build` (or `maid build`)
	> between test runs if you change code in the `src/` directory.

	#### Building a debug build

	A debug build disables optimizations and LTO, and preserves debug symbols:

	```bash
	meson subprojects download
	CC="ccache $(which clang)" \
	meson setup build --wipe --buildtype=debug \
	-Doptimization=0 -Db_lto=false -Dstrip=false -Db_lundef=false -Dunity=off
	meson compile -C build
	```

	Or with maid:

	```bash
	maid debug
	maid build
	```

	When using the debug build, core dumps will be generated in case of crashes.
	Use `lldb` or `gdb` with the debug binary to inspect them:

	```bash
	lldb ./build/ant core.ant
	(lldb) bt
	```

	#### Building an ASan build

	[ASan](https://github.com/google/sanitizers) can help detect memory bugs.

	> [!WARNING]
	> ASan builds are significantly slower than release builds. The debug flags
	> are not required but can produce clearer stack traces when ASan detects
	> an issue.

	```bash
	meson subprojects download
	CC="ccache $(which clang)" \
	meson setup build --wipe \
	-Db_sanitize=address -Doptimization=0 -Db_lto=false -Dstrip=false -Db_lundef=false
	meson compile -C build
	```

	Or with maid:

	```bash
	maid asan
	maid build
	```

	Then run tests against the ASan build:

	```bash
	./build/ant tests/test_gc.js
	```

	#### Speeding up frequent rebuilds when developing

	If you plan to frequently rebuild Ant, installing `ccache` can greatly
	reduce build times. The `maid setup` task configures ccache automatically.

	> [!TIP]
	> Using both `ccache` and `lld` together provides the best rebuild
	> performance. `ccache` caches compilation, while `lld` speeds up linking
	> (which cannot be cached).

	On GNU/Linux:

	```bash
	sudo apt install ccache
	export CC="ccache gcc" # add to your .profile
	```

	On macOS:

	```bash
	brew install ccache
	export CC="ccache cc" # add to ~/.zshrc
	```

	Using `lld` as the linker also speeds up link times:

	```bash
	export CC_LD="$(which ld64.lld)" # macOS with brew llvm
	# or
	export CC_LD="$(which lld)" # Linux
	```

	> [!NOTE]
	> LTO is enabled by default with 8 threads (`b_lto=true`,
	> `b_lto_threads=8`). Disable it with `-Db_lto=false` for faster iteration
	> during development.

	#### Troubleshooting Unix and macOS builds

	Stale builds can sometimes result in errors. Clean the build directory and
	reconfigure:

	```bash
	rm -rf build
	meson setup build
	meson compile -C build
	```

	If you encounter "file not found" errors for vendored dependencies:

	```bash
	meson subprojects download
	```

	If the build runs out of memory, reduce parallelism:

	```bash
	meson compile -C build -j2
	```

	### Windows

	#### Windows prerequisites

	Ant on Windows is built using the MSYS2 MINGW64 toolchain.

	> [!IMPORTANT]
	> Native MSVC builds are not currently supported. You must use the MSYS2
	> MINGW64 environment.

	1. Install [MSYS2](https://www.msys2.org/)
	2. Open the MINGW64 shell and install dependencies:
	```bash
	pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-meson \
	mingw-w64-x86_64-ninja mingw-w64-x86_64-cmake \
	mingw-w64-x86_64-openssl mingw-w64-x86_64-libsodium \
	mingw-w64-x86_64-lld mingw-w64-x86_64-nodejs git
	```
	3. Install Rust via [rustup](https://rustup.rs/) (select the
	`x86_64-pc-windows-gnu` target)
	4. Install [Zig](https://ziglang.org/download/)

	#### Building Ant

	From the MSYS2 MINGW64 shell:

	```bash
	git clone https://github.com/theMackabu/ant.git
	cd ant
	meson subprojects download
	meson setup build -Dc_std=gnu2x
	meson compile -C build
	```

	> [!NOTE]
	> Windows builds use `-Dc_std=gnu2x` instead of `gnu23` due to MinGW
	> toolchain compatibility.

	To verify:

	```bash
	./build/ant.exe --version
	```

	> [!WARNING]
	> Windows builds require bundling the following DLLs alongside `ant.exe`:
	>
	> - `libssl-3-x64.dll`
	> - `libcrypto-3-x64.dll`
	> - `libsodium-26.dll`
	>
	> These are found in the MSYS2 MINGW64 bin directory
	> (`/mingw64/bin/` or equivalent).

	## Meson build options

	Configure options are set via `meson setup` or `meson configure`:

	\| Option \| Type \| Default \| Description \|
	\| ------------------- \| ------- \| --------- \| ------------------------------------------ \|
	\| `static_link` \| boolean \| `false` \| Statically link the final binary \|
	\| `build_timestamp` \| string \| (auto) \| Build timestamp (defaults to current time) \|
	\| `tls_library` \| combo \| `openssl` \| TLS backend: `openssl` or `mbedtls` \|
	\| `deps_prefix_cmake` \| string \| (empty) \| Prefix path for cmake dependency lookup \|

	Standard Meson built-in options used by Ant:

	\| Option \| Default \| Description \|
	\| --------------- \| --------- \| --------------------------------- \|
	\| `buildtype` \| `release` \| Build type (release, debug, etc.) \|
	\| `optimization` \| `3` \| Optimization level (0-3) \|
	\| `c_std` \| `gnu23` \| C language standard \|
	\| `b_lto` \| `true` \| Link-time optimization \|
	\| `b_lto_threads` \| `8` \| LTO parallelism \|
	\| `strip` \| `true` \| Strip debug symbols from binary \|
	\| `b_sanitize` \| `none` \| Sanitizer (e.g. `address`) \|

	Example:

	```bash
	meson setup build -Dtls_library=mbedtls -Dstatic_link=true --prefer-static
	```

	## TLS library selection

	Ant supports two TLS backends:

	- OpenSSL (default): Widely available, used on all platforms by default.
	- mbedTLS: Lighter alternative, useful for embedded or constrained
	environments. Currently only tested on macOS CI.

	To build with mbedTLS:

	```bash
	meson setup build -Dtls_library=mbedtls
	```

	When using mbedTLS, the target triple in the version string will include
	`-mbedtls` as a suffix.

File Metadata

Mime Type: text/plain
Expires: Sun, May 3, 8:13 AM (1 d, 10 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 518055
Default Alt Text: BUILDING.md (13 KB)

BUILDING.mdNo OneTemporaryActions

BUILDING.mdView Options

File Metadata

Event Timeline

BUILDING.md
No OneTemporary
Actions

BUILDING.md
View Options