Skip to content

Getting Started

Jump to bottom
Kevin Henderson edited this page Jul 1, 2026 · 4 revisions

Getting Started

Dependencies

Dependency Version Notes
C++ compiler C++20 GCC 10+, Clang 12+, MSVC 2022
CMake 3.20+
FTXUI v7.0.0 Auto-fetched via FetchContent — no manual install needed
Qt6 6.x Optional; disable with -DBUILD_QT6_UI=OFF

Installing Qt6

Qt6 is only required for the desktop GUI. Skip this if you only want the terminal UI.

# Fedora / RHEL
sudo dnf install qt6-qtbase-devel

# Ubuntu / Debian
sudo apt install qt6-base-dev

# macOS
brew install qt@6

Building

Terminal UI only (no Qt required)

cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug --target number_system_converter
./cmake-build-debug/number_system_converter

Qt6 desktop GUI

cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug --target clearCore-gui
./cmake-build-debug/clearCore-gui

Disable Qt6 explicitly

cmake -S . -B cmake-build-debug -DBUILD_QT6_UI=OFF
cmake --build cmake-build-debug

Build everything

cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug

Running tests

# Build all test targets
cmake --build cmake-build-debug --target \
    decoder_test cpu_test processor_test nsc_tests qt_ui_test

# Run with output on failure
ctest --test-dir cmake-build-debug --output-on-failure

All 95 tests should pass. The test suite covers:

  • decoder_test — R/I/J format decoding, opcode + funct → mnemonic
  • cpu_test — single-cycle CPU against known programs
  • processor_test — polymorphic harness running both SingleCycleCpu and PipelinedCpu through identical programs
  • nsc_tests — number system converter (parseBase, conversions)
  • qt_ui_test — Qt6 smoke tests (skipped when BUILD_QT6_UI=OFF)

Terminal requirements

The FTXUI terminal UI requires a real terminal with ANSI escape code support. It will not render correctly in:

  • Windows cmd.exe without a compatibility layer
  • Some minimal CI/CD environments

Use a standard Linux/macOS terminal, Windows Terminal, or any terminal that supports 256-color ANSI sequences.

First steps

After launching number_system_converter:

  1. Tab 0 — Converter: Type a number in any base; the others update live.
  2. Tab 1 — CPU Dashboard: Load a program from Tab 3, then step through or auto-run.
  3. Tab 2 — CPU Config: Switch between single-cycle and pipelined mode at runtime.
  4. Tab 3 — Program Loader: Enter 32-bit instruction words in hex to load a program.
  5. Tab 4 — Signal Monitor: Watch the oscilloscope animation while the CPU runs.

See Terminal UI for a full description of each tab and its controls.

Clone this wiki locally