Installation

Mach supports Windows 10 and later and Ubuntu 24.04 and later.

This guide will walk you through preparing your development environment, installing Mach, and verifying that everything is ready to use.

Requirements

Mach requires:

C++20
CMake 3.20 or later

Supported compilers:

Windows: MSVC 19.44 or later
Linux: GCC 13.4+ or Clang 17.0.6+

Windows

Prerequisites

The recommended way to install the required C++ toolchain on Windows is through the Visual Studio Installer.

Install either Visual Studio or the standalone Build Tools for Visual Studio and select the Desktop development with C++ workload.

Make sure the installation includes:

MSVC C++ build tools
Windows SDK
CMake tools for Windows

For more information about setting up C++ development with Visual Studio, see Microsoft’s Install C++ support in Visual Studio guide.

Already have a C++ development environment? You can skip this step if your installed MSVC and CMake versions meet Mach’s requirements.

You can verify that CMake is available by opening a new terminal and running:

cmake --version

If you need to install or update CMake separately, download it from the official CMake download page.

Install with the Mach Installer (Recommended)

Download the latest Mach .msi installer from the releases page.

Run the installer and follow the installation steps.

The installer sets up:

The Mach framework
The Mach CLI
Mach’s required framework dependencies
The required environment configuration

The Mach installer does not install your C++ compiler or development tools. Make sure the prerequisites above are installed first.

Once installation is complete, open a new terminal and verify that Mach is available:

mach --version

If the command prints the installed Mach version, the installation was successful.

Install with vcpkg

If you already use vcpkg to manage your C++ dependencies, you can install Mach directly through vcpkg:

vcpkg install mach:x64-windows-static

On Windows, Mach currently supports the x64-windows-static triplet. The default x64-windows dynamic triplet is not supported.

Configure your CMake project using the vcpkg toolchain and the x64-windows-static triplet:

cmake -B build -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static

Install with WinGet

WinGet support is coming soon.

Once available, Mach will also be installable directly from the terminal:

winget install MachFramework.Mach

After installation, open a new terminal and verify the installation:

mach --version

Linux

Prerequisites

Mach supports Ubuntu 24.04 and later.

Install CMake and a C++ compiler using APT.

To use GCC:

sudo apt update
sudo apt install cmake gcc g++

Or, to use Clang:

sudo apt update
sudo apt install cmake clang

Once installed, verify your CMake version:

cmake --version

For GCC:

g++ --version

Or for Clang:

clang++ --version

Make sure the installed versions meet Mach’s requirements: CMake 3.20+ and either GCC 13.4+ or Clang 17.0.6+.

Depending on your Ubuntu version, the default APT repositories may provide an older compiler. If the installed version does not meet Mach’s requirements, install a newer toolchain before continuing.

Install with the Mach Package (Recommended)

Download the latest Mach .deb package from the releases page.

Open the downloaded package and click Install to install Mach using Ubuntu’s software installer.

Alternatively, install the package from the terminal:

sudo apt install ./mach_1.0.0_amd64.deb

The package installs the Mach framework, the Mach CLI, and Mach’s required framework dependencies.

Once installation is complete, verify that Mach is available:

mach --version

If the command prints the installed Mach version, the installation was successful.

Install with vcpkg

If you already use vcpkg to manage your C++ dependencies, make sure the required build tools are installed:

sudo apt install build-essential pkg-config

Then install Mach through vcpkg:

vcpkg install mach

Configure your CMake project using the vcpkg toolchain:

cmake -B build -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake"

Mach is installed and your development environment is ready. Next, create your first Mach project.