# How to Build Fincept from Source with CMake Presets on Windows, Linux, and macOS

> Build Fincept from source on Windows, Linux, and macOS using CMake presets. Clone the repo, run CMake configure and build commands for a seamless cross-platform compilation. Get your executable fast.

- Repository: [Fincept Corporation/FinceptTerminal](https://github.com/Fincept-Corporation/FinceptTerminal)
- Tags: how-to-guide
- Published: 2026-04-20

---

**To build Fincept Terminal from source, clone the Fincept-Corporation/FinceptTerminal repository, run `cmake --preset <platform>-release` to configure the build, then `cmake --build --preset <platform>-release` to compile the executable into `build/<platform>-release/`.**

Fincept Terminal is a pure C++20 desktop application that leverages CMake Presets to eliminate manual toolchain configuration across platforms. This guide walks through using the predefined build configurations in [`fincept-qt/CMakePresets.json`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/CMakePresets.json) to compile Fincept from source on Windows, Linux, and macOS with reproducible settings.

## Prerequisites and System Requirements

Before building, verify your environment matches the strict version requirements enforced by [`fincept-qt/CMakeLists.txt`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/CMakeLists.txt):

- **CMake** 3.27 or higher
- **Ninja** 1.11.1
- **Qt** 6.8.3 (exact version pinned; override with `FINCEPT_ALLOW_QT_DRIFT` only for development)
- **Python** 3.11.9 (embedded runtime)
- **Git** (for FetchContent dependency resolution)

Platform-specific compiler minimums:
- **Windows**: MSVC 19.38 (Visual Studio 2022 17.8 or later)
- **Linux**: GCC 12.3 or later
- **macOS**: Apple Clang 15.0 (Xcode 15.2 or later)

## Understanding the CMake Presets Architecture

The repository ships a [`fincept-qt/CMakePresets.json`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/CMakePresets.json) file that defines platform-specific configurations inheriting from a hidden base preset. This base sets the **Ninja** generator, enables `CMAKE_EXPORT_COMPILE_COMMANDS`, and configures Unity builds for infrastructure layers while disabling them for screen files containing static objects.

| Preset | Platform | Compiler | Default Qt Path |
|--------|----------|----------|----------------|
| `win-release` | Windows x64 | MSVC 19.38 | `C:/Qt/6.8.3/msvc2022_64` |
| `linux-release` | Linux x64 | GCC 12.3 | `~/Qt/6.8.3/gcc_64` |
| `macos-release` | macOS 11+ | Apple Clang 15.0 | `$HOME/Qt/6.8.3/macos` |

During configuration, `FetchContent` automatically pulls **md4c**, **QGeoView**, **SingleApplication**, **QtADS**, and optionally **QXlsx** (when Qt private headers are available). All fetches are shallow and cached after the first run.

## Step-by-Step Build Instructions

### 1. Clone the Repository

```bash
git clone https://github.com/Fincept-Corporation/FinceptTerminal.git
cd FinceptTerminal/fincept-qt

```

### 2. Configure with CMake Presets

Select the preset matching your operating system. This command generates build files in `build/<preset>/` and resolves all third-party dependencies.

**Windows** (run from a "Developer Command Prompt for VS 2022"):

```bat
cmake --preset win-release

```

**Linux**:

```bash
cmake --preset linux-release

```

**macOS**:

```bash
cmake --preset macos-release

```

### 3. Compile the Project

Execute the build command using the matching preset. The Ninja generator typically completes compilation in under one minute on modern workstations.

```bash
cmake --build --preset win-release     # Windows

cmake --build --preset linux-release   # Linux

cmake --build --preset macos-release   # macOS

```

### 4. Launch the Application

The build produces `FinceptTerminal` (or `FinceptTerminal.exe` on Windows) in the preset-specific directory.

**Linux and macOS**:

```bash
./build/linux-release/FinceptTerminal

```

**Windows**:

```bat
.\build\win-release\FinceptTerminal.exe

```

## Debug Builds and Advanced Options

For development and debugging, use the `*-debug` preset variants. These set `CMAKE_BUILD_TYPE=Debug`, preserve symbols, and disable whole-program optimization:

```bash
cmake --preset linux-debug && cmake --build --preset linux-debug

```

For local experimentation with non-standard Qt installations, override the path manually:

```bash
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_PREFIX_PATH="/path/to/Qt/6.8.3/gcc_64"
cmake --build build

```

Set `-DFINCEPT_ALLOW_QT_DRIFT=ON` to bypass the strict Qt 6.8.3 version check. **Do not use this flag for CI or release builds.**

## Troubleshooting Common Build Errors

| Error Message | Cause | Resolution |
|--------------|-------|------------|
| `Could not find Qt6 6.8.3` | `CMAKE_PREFIX_PATH` mismatch | Verify Qt 6.8.3 installation path or pass `-DCMAKE_PREFIX_PATH` manually |
| `MSVC version error` | Visual Studio < 17.8 | Upgrade to VS 2022 17.8+ providing MSVC 19.38 |
| `Qt6::GuiPrivate not found` | Missing private headers (Linux) | Install `qt6-base-private-dev` or equivalent distribution package |
| Hang on `FetchContent` | Network/proxy blocking GitHub | Ensure connectivity to `github.com` or pre-populate `~/.cache` with dependency archives |

## Summary

- **Fincept Terminal** provides ready-made CMake Presets in [`fincept-qt/CMakePresets.json`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/CMakePresets.json) for `win-release`, `linux-release`, and `macos-release` configurations.
- The build requires exact toolchain versions: Qt 6.8.3, CMake 3.27, MSVC 19.38/GCC 12.3/Apple Clang 15.0, and Python 3.11.
- Use `cmake --preset <name>` to configure and `cmake --build --preset <name>` to compile; output lands in `build/<preset>/FinceptTerminal`.
- Unity builds accelerate infrastructure compilation, while individual compilation of `fincept-qt/src/screens/` files prevents static object conflicts.
- The application entry point at [`fincept-qt/src/app/main.cpp`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/src/app/main.cpp) initializes the Qt event loop and loads analytics scripts from `fincept-qt/scripts/`.

## Frequently Asked Questions

### What if my Qt installation is in a non-standard location?

Override the preset’s `CMAKE_PREFIX_PATH` by passing `-DCMAKE_PREFIX_PATH="/your/custom/path"` during the CMake configuration step, or use a manual CMake invocation without presets.

### Why does the build enforce specific compiler versions?

The [`fincept-qt/CMakeLists.txt`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/CMakeLists.txt) enforces MSVC 19.38+, GCC 12.3+, or Apple Clang 15.0+ to ensure full C++20 feature support and binary compatibility with the embedded Python 3.11 runtime and Qt 6.8.3 private headers.

### Can I build without using the provided presets?

Yes. Run `cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release` manually, specifying your own `CMAKE_PREFIX_PATH` and `CMAKE_OSX_DEPLOYMENT_TARGET` (macOS). You must still satisfy the compiler and Qt version requirements checked by the root [`CMakeLists.txt`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/CMakeLists.txt).

### Where does the application entry point reside?

The main entry point is [`fincept-qt/src/app/main.cpp`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/src/app/main.cpp), which constructs the `QApplication` and instantiates `MainWindow` from [`fincept-qt/src/app/MainWindow.cpp`](https://github.com/Fincept-Corporation/FinceptTerminal/blob/main/fincept-qt/src/app/MainWindow.cpp). UI screens in `fincept-qt/src/screens/` are compiled individually to avoid Unity build symbol clashes with static initializers.