Skip to content

Getting started with AUI#

IDE#

  • Recommended as "out of the box" crossplatform solution.
  • Has free version for non-commercial development.
  • No additional setup required.
  • Install following extensions:
Extension Description
cpp tools pack Introduces basic C/C++ support and CMake integration.
vscode-clangd C++ language server for extensive code navigation, autocomplete, etc.
  • Add these lines to your settings.json (F1 > Preferences: Open User Settings (JSON)):
settings.json
"clangd.arguments": [
    "--compile-commands-dir=build/"
],

OS prerequirements#

Install Windows updates

You may want to ignore this, but in case of errors, please ensure you have installed Windows updates.

Install MSVC compiler

CLion comes with MinGW by default. It works okayish, but we recommend using de-facto standard compiler for Windows instead.

VS Code does not come with any compiler by default.

You are not forced to use Visual Studio IDE, you can use whatever IDE you want. We just want the compiler part.

Visual Studio Community edition is sufficient.

Install msvc or clang, if you haven't already, and reboot.

Press Win, type Visual Studio Installer and launch.

Choose Individual components tab.

Search and select the following components:

  1. Windows Universal C Runtime
  2. MSVC v142 or newer
  3. Windows 10 SDK or newer
  4. Windows Universal CRT SDK

Click Install.

Don't forget to reboot!

Configure CLion to use MSVC compiler instead of MinGW

While you can use MinGW for your AUI project, it is recommended to use commonly accepted compiler for Windows.

If you use VS Code, it will pick up the correct compiler automatically.

If you use CLion:

  1. Ctrl+Alt+S, navigate to "Build, Execution, Deployment" > "Toolchains".
  2. Press +.
  3. Choose Visual Studio. CLion should pick up it automatically.

  1. Select Visual Studio.
  2. Press "arrow up" button to raise priority. Visual Studio compiler should be by default!
  3. Press OK.

Install Xcode.

Install following dependencies:

sudo apt update
sudo apt install pkg-config libglew-dev zlib1g-dev libssl-dev libcurl4-openssl-dev libgtk-3-dev libdbus-1-dev libfontconfig-dev ninja-build libpulse-dev git cmake g++

Install following dependencies:

sudo dnf install fontconfig-devel gtk3-devel dbus-devel libXi libglvnd-devel libstdc++-static glew-devel pulseaudio-libs-devel git cmake g++

Installation#

AUI does not provide "traditional" installation methods that involve manual downloading and deploying; instead, package managers are used to ensure easily reproducible builds. They compile and link all required dependencies automatically to free you from dependency management and focus you right to development of your application.

You can use our App Template ⚡ to set up a new project quickly with AUI's .clang-format, Github Actions and other features out-of-the-box. The template is based on CMake and aui.boot.

Clone https://github.com/aui-framework/example_app with your IDE or via terminal:

git clone https://github.com/aui-framework/example_app

and open that directory in your IDE.

Recommended: Create a new repo

From App Template ⚡ repository, you can generate a completely separate repo with clean git history:

  1. Open http://github.com/aui-framework/example_app
  2. Click Create a new repository.

  1. Clone your own repo into IDE.

A full-fledged XMake-based app template is available at github.com/aui-framework/xmake_example_app. It comes pre-configured with GitHub Actions CI/CD, .clang-format, .clang-tidy, Valgrind suppression, auto-updating (Windows), and a ready-to-run AUI window — everything you need to start shipping an app.

AUI version support

The XMake app template currently targets AUI v7.1.2. Newer versions of AUI (v8.x and above) are not yet supported. Track progress in the xmake_example_app repository.

Recommended: Create a new repo from the template
  1. Open https://github.com/aui-framework/xmake_example_app

  2. Click Use this template → Create a new repository.

  3. Clone your new repo and open it in your IDE.

The template includes the following GitHub Actions workflows:

  • Build — triggered on push and pull_request. Builds for all supported platforms, runs tests, generates installable packages, and prepares a GitHub Release draft.
  • Code Quality — triggered on pull_request. Runs clang-tidy static analysis and valgrind dynamic analysis on tests.

To create a release, bump the version in CMakeLists.txt and push — the pipeline creates a GitHub Release draft for you automatically.

AUI provides support to several package managers, to choose at your own.

aui.boot is *official* way of using AUI. It is a CMake-based package manager that requires nothing but CMake.

Download AUI.Boot (one-time):

curl https://raw.githubusercontent.com/aui-framework/aui/refs/heads/develop/aui.boot.cmake -o aui.boot.cmake

Create CMakeLists.txt:

CMakeLists.txt
# Standard routine
cmake_minimum_required(VERSION 3.16)
project(project_template)

# Use AUI.Boot
include(aui.boot.cmake)

# import AUI
auib_import(
    aui https://github.com/aui-framework/aui 
    COMPONENTS core views
    VERSION v8.0.0-rc.8
    )


# Create the executable. This function automatically links all sources from the src/ folder, creates CMake target and
# places the resulting executable to bin/ folder.
aui_executable(project_template)

# Link required libs
aui_link(project_template PRIVATE aui::core aui::views)

CMake's missing package manager is a small CMake script for setup-free, cross-platform, reproducible dependency management.

Download CPM to your project directory:

mkdir -p cmake
wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake

Then, create a CMakeLists.txt:

CMakeLists.txt
# Standard routine
cmake_minimum_required(VERSION 3.16)
project(project_template)

# import AUI
include(cmake/CPM.cmake)
CPMAddPackage("gh:aui-framework/aui#v7.1.2")

# Create the executable. This function automatically links all sources from the src/ folder, creates CMake target and
# places the resulting executable to bin/ folder.
aui_executable(project_template)

# Link required libs
aui_link(project_template PRIVATE aui::core aui::views)

XMake is a lightweight, cross-platform build utility with built-in package management. It requires no external package manager — AUI is fetched and compiled automatically from xmake-repo.

AUI version support

XMake package support currently targets AUI v7.1.2. Newer versions (v8.x and above) are not yet available in xmake-repo. If you need the latest AUI, use AUI Boot or CPM instead.

Install XMake

Install via winget (recommended):

winget install xmake

Or download the installer from xmake.io and run it.

Note

After installation, reopen your terminal so that xmake is available on the PATH.

Install via Homebrew:

brew install xmake

curl -fsSL https://xmake.io/shget.text | bash

Or install via apt (may be an older version):

sudo add-apt-repository ppa:xmake-io/xmake
sudo apt update
sudo apt install xmake

curl -fsSL https://xmake.io/shget.text | bash

Verify the installation:

xmake --version

Create xmake.lua

Create the following xmake.lua in your project root:

xmake.lua
-- Specify available build configurations
add_rules("mode.release", "mode.debug")

-- Output compile_commands.json for clangd / VS Code IntelliSense
add_rules("plugin.compile_commands.autoupdate", {outputdir = ".vscode", lsp = "clangd"})

-- AUI requires C++20
set_languages("c++20")

-- Fetch AUI v7.1.2 from xmake-repo (latest version supported via XMake)
add_requires("aui v7.1.2")

-- Define the executable target
target("project_template")
    -- Collect all .cpp files from the src/ directory
    add_files("src/*.cpp")
    add_includedirs("src")
    -- Link AUI with only the components you need
    add_packages("aui", {components = {"core", "image", "views", "xml"}})
    -- Group AUI components into link groups to resolve circular dependencies
    add_linkgroups("aui.views", "aui.xml", "aui.image", "aui.core", {whole = true})

Create src/ directory and entry point

XMake picks up all .cpp files from src/ automatically. Create at minimum:

src/main.cpp
#include <AUI/Platform/Entry.h>
#include <AUI/Platform/AWindow.h>

AUI_ENTRY {
    _new<AWindow>("Hello AUI", 300_dp, 200_dp)->show();
    return 0;
}

Build and run

xmake          # configure dependencies and build
xmake run      # run the resulting executable

On the first run, XMake will download and compile AUI and all its dependencies. This may take a few minutes. Subsequent builds are incremental and fast.

Switching between Debug and Release 
xmake f -m debug    # switch to debug configuration
xmake               # rebuild
xmake f -m release  # switch back to release
xmake
VS Code integration

The plugin.compile_commands.autoupdate rule in xmake.lua automatically generates .vscode/compile_commands.json on every build. This enables full IntelliSense and code navigation in VS Code via the vscode-clangd extension — no additional configuration needed.

See Minimal UI Template XMake for a full ready-to-use example with MainWindow.

aui_executable hooks all CPP files from src/ directory. You need to create src/ directory and a CPP file in it.

src/main.cpp
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/*
 * AUI Framework - Declarative UI toolkit for modern C++20
 * Copyright (C) 2020-2025 Alex2772 and Contributors
 *
 * SPDX-License-Identifier: MPL-2.0
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

/// [AButton_example]
#include <AUI/Platform/Entry.h>
#include <AUI/Platform/AWindow.h>
#include <AUI/Util/UIBuildingHelpers.h>
#include <AUI/View/AButton.h>

using namespace ass;
using namespace declarative;

AUI_ENTRY {
    auto window = _new<AWindow>("Button", 600_dp, 300_dp);
    window->setContents(Centered {
      Button {
        .content = Label { "Click me" },
        .onClick = [] { ALogger::info("Test") << "Hello world!"; },
      },
    });
    window->show();
    return 0;
}
/// [AButton_example]

Why CMake or IDE doesn't recognize a new CPP file?

This indicates that the IDE's build system needs to be initialized or refreshed.

Reload CMake project to hook up a newly added CPP file:

File > Reload CMake Project or right-click on CMakeLists.txt > Load/Reload CMake project.

  1. Please make sure you have followed setup procedure listed in the beginning on this page.
  2. F1 >CMake: Configure. If it asks for a toolchain, choose Unspecified.
cmake -S . -B build

Build and Run Your App#

Run -> Run "project name" or green arrow in top right corner.

  1. F1 >CMake: Configure. If it asks for a toolchain, choose Unspecified.
  2. Choose CMake logo in the left panel (where the extensions tab live).
  3. Right click on project's target > Set Build target and Set Launch/Debug target.
  4. F1 >CMake: Debug.
cmake -S . -B build
cmake --build build

See layout managers for more info about layout managers.

See ASS for more info about styling.

See Examples for examples.