# How to Build ArmorPaint from Source on Linux: A Complete Guide

> Build ArmorPaint from source on Linux with our guide. Learn to install dependencies, clone the repo, and compile the latest version for your projects.

- Repository: [Armory 3D/armorpaint](https://github.com/armory3d/armorpaint)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To build ArmorPaint from source on Linux, install the Vulkan and GTK development libraries, clone the armory3d/armorpaint repository, execute `../base/make --run` from the `paint` directory to invoke the custom `amake` build system, and launch the resulting binary at `build/ArmorPaint`.**

ArmorPaint is a native 3D PBR texture-painting application developed by armory3d. Compiling it from source on Linux requires Clang, the Vulkan SDK, and GTK3 libraries, orchestrated through a custom JavaScript-driven build tool called `amake`. This guide explains the exact steps to configure your environment and generate a working binary using the official source tree.

## Prerequisites: Install Linux Dependencies

Before compiling, install the system libraries listed in [`base/docs/linux_deps.md`](https://github.com/armory3d/armorpaint/blob/main/base/docs/linux_deps.md). The build requires **Vulkan** graphics drivers, **GTK-3** for the interface, and **Clang** as the compiler.

On Debian or Ubuntu systems, run:

```bash
sudo apt update && sudo apt install -y make clang libvulkan-dev libgtk-3-dev \
    libssl-dev libxi-dev libxrandr-dev libxcursor-dev libasound2-dev

```

Arch Linux users should install the equivalent packages from their repositories. These dependencies link against the engine's WebGPU Vulkan backend and the UI layer's native windowing system.

## Clone the Repository

Clone the source tree and navigate to the UI layer directory:

```bash
git clone https://github.com/armory3d/armorpaint
cd armorpaint/paint

```

The repository splits into two main sections: `base/` contains the core engine and build system, while `paint/` houses the application UI, material logic, and plugin system. The build commands are always executed from within the `paint` directory.

## Understanding the Build System

ArmorPaint uses a custom build system called **amake** located in `base/tools/amake/`. This lightweight JavaScript-driven tool abstracts platform differences and generates native project files.

The entry point is the `base/make` wrapper script. When invoked, it forwards arguments to the platform-specific `amake` binary at `tools/bin/linux/amake`. This generates a `build/` directory containing Ninja-generated Makefiles configured to link against the Vulkan SDK and GTK libraries.

Key architectural components include:

- **Engine (`base/sources/`)**: Written in C/C++ with a WebGPU wrapper ([`webgpu_gpu.c`](https://github.com/armory3d/armorpaint/blob/main/webgpu_gpu.c)) for Vulkan rendering
- **UI Layer (`paint/sources/`)**: Implements [`viewport.c`](https://github.com/armory3d/armorpaint/blob/main/viewport.c), [`util_ui.c`](https://github.com/armory3d/armorpaint/blob/main/util_ui.c), and [`util_brush.c`](https://github.com/armory3d/armorpaint/blob/main/util_brush.c), interacting with the engine via [`iron_draw.c`](https://github.com/armory3d/armorpaint/blob/main/iron_draw.c)
- **Plugin System**: Shared libraries loaded at runtime from `paint/plugins/`

## Compile ArmorPaint

### Run the Build Wrapper

From the `paint` directory, execute the build command:

```bash
../base/make --run

```

This invokes `amake` to generate build files and compiles the project. The process links the engine core against Vulkan and GTK, producing the final executable. On successful completion, you will find `ArmorPaint` inside the newly created `build/` directory.

### Optional Build Targets

The `amake` system supports specific build targets for development:

**Engine only**: To compile only the core engine library without the full UI:

```bash
../base/make --target engine

```

**Embed mode**: To enable resource embedding using Clang 19+ `#embed` directives:

```bash
../base/make --embed

```

For advanced configuration, invoke `amake` directly with custom targets as documented in [`base/tools/amake/readme.md`](https://github.com/armory3d/armorpaint/blob/main/base/tools/amake/readme.md).

## Launch the Application

Run the compiled binary:

```bash
./build/ArmorPaint

```

If the build succeeded, the application initializes using [`base/sources/engine.c`](https://github.com/armory3d/armorpaint/blob/main/base/sources/engine.c) for the main loop and [`paint/sources/viewport.c`](https://github.com/armory3d/armorpaint/blob/main/paint/sources/viewport.c) for UI rendering. Ensure your system has a Vulkan-compatible GPU and drivers loaded.

## Summary

- **Install dependencies** from [`base/docs/linux_deps.md`](https://github.com/armory3d/armorpaint/blob/main/base/docs/linux_deps.md) including `libvulkan-dev`, `libgtk-3-dev`, and `clang`
- **Clone** the armory3d/armorpaint repository and enter the `paint/` directory
- **Build** using `../base/make --run`, which calls the custom `amake` tool to generate Ninja Makefiles
- **Locate** the output binary at `build/ArmorPaint` and execute it directly
- **Customize** the build with `--target engine` for core-only compilation or `--embed` for modern Clang features

## Frequently Asked Questions

### What Linux dependencies are required to build ArmorPaint?

You need development headers for Vulkan, GTK-3, OpenSSL, X11, and ALSA. The specific packages for Debian/Ubuntu are `make clang libvulkan-dev libgtk-3-dev libssl-dev libxi-dev libxrandr-dev libxcursor-dev libasound2-dev`, as listed in [`base/docs/linux_deps.md`](https://github.com/armory3d/armorpaint/blob/main/base/docs/linux_deps.md).

### How does the `amake` build system differ from CMake or Make?

`amake` is a custom JavaScript-driven tool in `base/tools/amake/` that generates native project files for multiple platforms. The `base/make` wrapper script calls the Linux-specific `tools/bin/linux/amake` binary, which creates a `build/` directory with Ninja-generated Makefiles tailored for the Vulkan and GTK toolchain.

### Can I compile only the ArmorPaint engine without the UI?

Yes. Pass the `--target engine` flag to the build wrapper: `../base/make --target engine`. This compiles only the core engine library from `base/sources/` without linking the UI layer modules like [`viewport.c`](https://github.com/armory3d/armorpaint/blob/main/viewport.c) or [`util_ui.c`](https://github.com/armory3d/armorpaint/blob/main/util_ui.c).

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

The executable is placed at `build/ArmorPaint` relative to the `paint/` directory where you ran the build command. This binary links dynamically against the Vulkan SDK and GTK-3 libraries installed on your system.