# Build System

## Creating a Project

New projects can be created using the `new` command. This generates a new directory that contains
the basic structure of a Banjo project.

```sh
banjo new name
```

## Building a Project

Projects can be built using the `build` command. This invokes the compiler and linker to generate
the executable/library. The resulting binary can be found at `out/<target>-<config>/<name>`.

```sh
banjo build
```

To run an executable immediately after building, use the `run` command.

```sh
banjo run
```

Projects can be built with the `debug` (default) or `release` config.

```sh
banjo build --config debug
banjo build --config release
```

The `release` config enables compiler optimizations. These are still unstable and often lead to
incorrect code generation or even compiler crashes.

The optimization level can be controlled using the `--opt-level` option.

```sh
banjo build --opt-level 1
```

The available optimization levels are:
- `--opt-level 0`: No optimization except dead function elimination. The default for the `debug`
  config.
- `--opt-level 1`: Enables basic optimizations such as peephole optimizations or inlining. The
  default for the `release` config.
- `--opt-level 2`: Enables advanced optimizations that might produce incorrect code. Here be
  dragons.

## Cross-Compilation

```{note}
Cross-compilation requires the LLD linker to be installed.
```

The build system is capable of cross-compiling for targets (platforms) other than the host target.

```sh
banjo build --target x86_64-linux-gnu
banjo build --target aarch64-macos
```

These targets currently support cross-compilation from other machines:  
  - `x86_64-windows-gnu`
  - `x86_64-linux-gnu`
  - `x86_64-macos`
  - `aarch64-linux-gnu`
  - `aarch64-macos`

### Notes

Cross-compilation has some limitations depending on the target operating system.

**Windows** \
Cross-compilation is currently not possible for MSVC targets as this platform requires linking
proprietary static libraries distributed by Microsoft. You can use the GNU targets instead (e.g.
`x86_64-windows-gnu`). This automatically downloads the `llvm-mingw` toolchain.

**Linux** \
When cross-compiling for Linux, precompiled versions of `glibc` and `libgcc` are downloaded to the
toolchains directory. Some shared objects are missing from these libraries, which might cause linker
errors.

**macOS** \
When cross-compiling for macOS, a JSON file describing the macOS system APIs is downloaded. The
build system then generates a sysroot containing [TAPI
files](https://github.com/apple-oss-distributions/tapi) from this JSON file that the linker uses to
link macOS system libraries and frameworks. The sysroot generated is incomplete and some frameworks
cannot be linked for this reason.

## Toolchains

The build system requires a toolchain to build projects. This includes a linker and system
libraries.

When building for a target, the build system tries to auto-detect toolchains based on standard
paths, environment variables and the Windows registry. If a toolchain can't be found (for example if
you are cross-compiling), the build system tries to download it. You can print information about a
toolchain using the `toolchain info` command:

```sh
banjo toolchain info  # Print info for the host toolchain
banjo toolchain info aarch64-linux-gnu  # Print info for the toolchain for AArch64 Linux 
```

Toolchains can be listed using the `toolchain list` command:

```sh
banjo toolchain list
```

## Packages

There are some pre-built packages available that bind to native libraries. These can be
automatically downloaded by adding them to the `packages` list of `banjo.json`. Here's the current
list of available packages:

| Name      | Description                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `windows` | Bindings to pretty much the entire [Windows API](https://github.com/microsoft/win32metadata)                                |
| `sdl`     | Bindings to [SDL3](https://libsdl.org/)                                                                                     |
| `vulkan`  | Bindings to [Vulkan](https://en.wikipedia.org/wiki/Vulkan)                                                                  |
| `glfw`    | Bindings to [GLFW](https://www.glfw.org/)                                                                                   |
| `joltc`   | Bindings to a [C wrapper](https://github.com/amerkoleci/joltc/) for [Jolt Physics](https://github.com/jrouwe/JoltPhysics) |
| `webgpu`  | Bindings to [wgpu-native](https://github.com/gfx-rs/wgpu-native)                                                          |
| `stbi`    | Bindings to [stb_image](https://github.com/nothings/stb/blob/master/stb_image.h)                                          |