ant/BUILDING.md
8755416ca476master

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.

Owner Packages

No Owners

ant/BUILDING.md8755416ca476master

BUILDING.mdView Options

Owner Packages

ant/BUILDING.md
8755416ca476master

BUILDING.md
View Options