HomePhorge
Diffusion Ant (type-hints-typescript) Code

ant/BUILDING.md
899dad6b8a9etype-hints-typescript

Last Change
Raw File

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)
## 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 | darwin | No | macOS 15 (CI) |
| macOS | aarch64 | darwin | 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-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**
Dependencies are vendored as Meson subprojects under `vendor/`
and are fetched automatically:
- aklomp-base64 0.5.2
- argtable3 3.3.1
- BoringSSL `297b11798a0ed6bc7736aa57328909a4afbbf67a`
- crprintf `HEAD`
- google-brotli 1.1.0
- libffi 3.5.2
- libuv 1.52.0
- llhttp 9.3.1
- LMDB (OpenLDAP LMDB 0.9.33)
- minicoro `HEAD`
- MIR `HEAD`
- nghttp2 1.68.0
- PCRE2 10.47
- tlsuv 0.40.13
- uriparser 1.0.0
- utf8proc 2.10.0
- uthash 2.3.0
- uuidv7-h `HEAD`
- wasm-micro-runtime `92f40918bbfad35546a1512b10bd25eaa31add4d`
- yyjson 0.12.0
- zlib-ng 2.3.3
### 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 nodejs npm
pip3 install meson
```
- Fedora:
```bash
sudo dnf install python3 gcc gcc-c++ ninja-build cmake pkgconf \
nodejs npm
pip3 install meson
```
- Alpine (musl):
```sh
apk add clang lld llvm meson ninja cmake pkgconf nodejs npm \
musl-dev \
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 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-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
```
## 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) |
| `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 -Dstatic_link=true --prefer-static
```

Owner Packages

  • No Owners