# How to Build BitNet from Source with CMake and Clang: A Complete Guide

> Build BitNet from source using CMake and Clang. Follow our guide to clone the repository, configure your build, and compile the binary for optimal performance.

- Repository: [Microsoft/BitNet](https://github.com/microsoft/BitNet)
- Tags: how-to-guide
- Published: 2026-03-13

---

**Build BitNet from source by cloning the microsoft/BitNet repository recursively, configuring CMake with Clang 18+ as the compiler, and enabling platform-specific kernel options before compiling the binary.**

BitNet is Microsoft's C/C++ inference framework for 1-bit large language models (LLMs) that leverages a streamlined CMake build system. When you build BitNet from source with CMake and Clang, you compile highly optimized kernels for the I2_S quantization format that enable efficient CPU inference on both x86 and ARM architectures.

## Prerequisites for Building BitNet

Before compiling, ensure your system meets the toolchain requirements specified in the repository documentation. You will need:

- **Clang 18 or newer** – The BitNet kernels rely on modern C++ features and intrinsics that Clang implements consistently across platforms.
- **CMake 3.22 or newer** – Required for the configuration scripts in the top-level [`CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/CMakeLists.txt).
- **Ninja** (recommended) or Make – For driving the build process efficiently.

On Windows, install the Visual Studio 2022 "Desktop development with C++" workload, which provides the Clang toolset as the *C/C++ Clang Compiler for Windows*.

## Clone the Repository and Submodules

BitNet depends on llama.cpp as a submodule for the underlying GGML runtime. Clone the repository recursively to ensure all dependencies are present:

```bash
git clone --recursive https://github.com/microsoft/BitNet.git
cd BitNet

```

The `--recursive` flag pulls the [`3rdparty/llama.cpp`](https://github.com/microsoft/BitNet/blob/main/3rdparty/llama.cpp) submodule that the build system integrates via `add_subdirectory` in the root [`CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/CMakeLists.txt).

## Configure the Build with CMake

Create a separate build directory to keep generated files isolated from the source tree. Configure the project using Clang as the C and C++ compiler:

```bash
mkdir build && cd build

cmake -G Ninja \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_BUILD_TYPE=Release \
      ..

```

The top-level [`CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/CMakeLists.txt) processes these variables to set `CMAKE_EXPORT_COMPILE_COMMANDS` and add the `src/` directory, which contains the BitNet-specific kernel implementations in [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp) and [`src/ggml-bitnet-lut.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-lut.cpp).

### Platform-Specific Kernel Options

BitNet provides optimized kernel paths for different CPU architectures. Enable these via CMake options when you build BitNet from source with CMake and Clang:

- **`-DBITNET_ARM_TL1=ON`** – Compiles the TL1 kernel path for ARM NEON (optimal for Apple Silicon and ARM servers).
- **`-DBITNET_X86_TL2=ON`** – Compiles the TL2 kernel path for x86 AVX-512 (optimal for Intel/AMD servers with AVX-512 support).

Example configuration with TL2 enabled:

```bash
cmake -G Ninja \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DBITNET_X86_TL2=ON \
      -DCMAKE_BUILD_TYPE=Release \
      ..

```

The [`src/CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/src/CMakeLists.txt) checks `CMAKE_C_COMPILER_ID` to ensure you are using Clang or GCC before applying these kernel-specific flags.

## Compile the BitNet Binary

Once configuration completes without errors, build the executable:

```bash
cmake --build . --target bitnet

```

This compiles:
- The generic GGML sources from [`3rdparty/llama.cpp`](https://github.com/microsoft/BitNet/blob/main/3rdparty/llama.cpp)
- The BitNet-specific kernels from [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp) and [`src/ggml-bitnet-lut.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-lut.cpp)
- The main entry point defined in the `src` target

The resulting binary appears at `build/bin/bitnet` (or `build\bin\bitnet.exe` on Windows).

## Verify and Run Inference

Confirm the build succeeded by checking the binary's help output:

```bash
./bin/bitnet --help

```

You should see CLI options for model path (`-m`), prompt (`-p`), thread count (`-t`), and other inference parameters.

To run a complete inference test, first download a compatible GGUF model (the I2_S format), then execute:

```bash
./bin/bitnet \
  -m ../models/BitNet-b1.58-2B-4T/ggml-model-i2_s.gguf \
  -p "Hello, BitNet!" \
  -t 4

```

## Key Source Files and Architecture

Understanding the source layout helps when modifying build flags or debugging compilation issues:

| Component | Role | Source Path |
|-----------|------|-------------|
| **Root CMakeLists.txt** | Sets global policies, adds `src/` and [`3rdparty/llama.cpp`](https://github.com/microsoft/BitNet/blob/main/3rdparty/llama.cpp) subdirectories, defines install rules | [`CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/CMakeLists.txt) |
| **src/CMakeLists.txt** | Defines the `bitnet` executable target, includes `include/` and ggml headers, enforces compiler checks | [`src/CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/src/CMakeLists.txt) |
| **ggml-bitnet-mad.cpp** | Core matrix-multiply kernel for I2_S quantization with AVX/ARM NEON intrinsics | [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp) |
| **ggml-bitnet-lut.cpp** | Lookup-table kernel used by the I2_S implementation | [`src/ggml-bitnet-lut.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-lut.cpp) |
| **ggml-bitnet.h** | Public API header for BitNet-specific ggml extensions | [`include/ggml-bitnet.h`](https://github.com/microsoft/BitNet/blob/main/include/ggml-bitnet.h) |
| **llama.cpp submodule** | Provides generic GGML runtime, tokenizer, and model loading utilities | [`3rdparty/llama.cpp`](https://github.com/microsoft/BitNet/blob/main/3rdparty/llama.cpp) |

The build system selects platform-specific code paths at compile-time using preprocessor guards (`#if defined(__AVX2__)` and `#if defined(__ARM_NEON)`) within the kernel source files.

## Summary

- **Clone recursively** to fetch the [`llama.cpp`](https://github.com/microsoft/BitNet/blob/main/llama.cpp) submodule required by the build system.
- **Use Clang 18+** as the compiler to ensure proper support for the intrinsics used in [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp) and [`src/ggml-bitnet-lut.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-lut.cpp).
- **Configure with CMake** using out-of-source builds, specifying `-DCMAKE_C_COMPILER=clang` and `-DCMAKE_CXX_COMPILER=clang++`.
- **Enable kernel options** (`BITNET_ARM_TL1` or `BITNET_X86_TL2`) to optimize for your specific CPU architecture.
- **Build the target** `bitnet` to produce the inference binary at `build/bin/bitnet`.

## Frequently Asked Questions

### What version of Clang is required to build BitNet?

BitNet requires **Clang 18 or newer**. The kernel implementations in [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp) rely on modern C++ features and intrinsics that are fully supported in Clang 18 and later versions. While GCC may work, the repository documentation specifically recommends Clang for consistent cross-platform behavior.

### Can I build BitNet on Windows with Visual Studio?

Yes, but you must use the **Clang toolset** rather than the default MSVC compiler. Install Visual Studio 2022 with the "Desktop development with C++" workload, which includes the *C/C++ Clang Compiler for Windows*. Then configure CMake with `-T ClangCL` or use Ninja with `-DCMAKE_C_COMPILER=clang` and `-DCMAKE_CXX_COMPILER=clang++` pointing to the Clang binaries installed with Visual Studio.

### What is the difference between BITNET_ARM_TL1 and BITNET_X86_TL2?

**BITNET_ARM_TL1** enables optimized kernels for ARM NEON architectures, delivering best performance on Apple Silicon and ARM-based servers. **BITNET_X86_TL2** enables the AVX-512 kernel path for x86-64 processors, maximizing throughput on Intel and AMD servers with AVX-512 support. These options are defined in [`src/CMakeLists.txt`](https://github.com/microsoft/BitNet/blob/main/src/CMakeLists.txt) and control which intrinsics are compiled from [`src/ggml-bitnet-mad.cpp`](https://github.com/microsoft/BitNet/blob/main/src/ggml-bitnet-mad.cpp).

### Where is the compiled binary located after building?

After running `cmake --build . --target bitnet`, the executable is placed at **`build/bin/bitnet`** (relative to the repository root). On Windows, this will be `build\bin\bitnet.exe`. You can verify the build by running `./bin/bitnet --help` from within the `build` directory to display the available CLI options for model inference.