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

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 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:

• 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 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

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"):

cmake --preset win-release

Linux:

cmake --preset linux-release

macOS:

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.

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:

./build/linux-release/FinceptTerminal

Windows:

.\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:

cmake --preset linux-debug && cmake --build --preset linux-debug

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

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 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 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 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.

Where does the application entry point reside?

The main entry point is fincept-qt/src/app/main.cpp, which constructs the QApplication and instantiates MainWindow from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}