Skip to content

BUILD.md

Latest commit

 

History

History
569 lines (385 loc) · 12.5 KB

BUILD.md

File metadata and controls

569 lines (385 loc) · 12.5 KB

Build Cold From Source

This guide prepares a macOS or Linux machine to build Cold from source. Cold is a C++20 Qt 6 Widgets desktop editor with optional terminal support through libvterm, optional tree-sitter support, and runtime integrations for tools such as rg, git, Node, and native compilers.

1. Choose The Build You Want

Start with the core build unless you specifically need every optional feature on the first pass.

Build Use when CMake flags
Core editor You want the fastest setup and can skip the embedded terminal if libvterm is missing -DCMAKE_BUILD_TYPE=Debug
Core + terminal You want the Terminal tab built in -DCOLD_ENABLE_TERMINAL=ON
Core + tree-sitter You are testing the optional legacy lexical highlighting path -DCOLD_ENABLE_TREESITTER=ON
Release You want performance closer to a packaged editor -DCMAKE_BUILD_TYPE=Release

Important defaults:

  • COLD_ENABLE_TERMINAL defaults to ON, but CMake only compiles terminal sources if it finds libvterm through pkg-config.
  • If libvterm is missing, CMake prints a warning and builds without the embedded terminal.
  • COLD_ENABLE_TREESITTER defaults to OFF.
  • LSP semantic-token highlighting is part of the normal build. The optional tree-sitter path is not required for default syntax colors.

2. Install System Dependencies

Cold requires:

Dependency Minimum / purpose
CMake 3.21+
Qt 6.4+ with Core, Widgets, Concurrent, Sql, and Network
Compiler C++20 compiler, usually GCC or Clang
SQLite Used through the Qt Sql module
pkg-config Needed for libvterm detection

Optional but recommended:

Tool Purpose
libvterm Embedded Terminal tab
ripgrep / rg Project search
git Git status, diff, stage, and commit UI
node, npm, tsc, ts-node JavaScript and TypeScript run support
gcc, g++, clang, clang++ C and C++ run support
clang-format Local formatting checks
tree-sitter core library and grammars Optional tree-sitter build

3. macOS Setup

Install the Xcode command line tools if they are not already installed:

xcode-select --install

Install the build dependencies with Homebrew:

brew install qt@6 cmake ninja pkg-config libvterm ripgrep git node llvm coreutils

Apple Silicon Homebrew normally installs under /opt/homebrew. Intel Homebrew normally installs under /usr/local.

For Apple Silicon:

export CMAKE_PREFIX_PATH="/opt/homebrew/opt/qt@6"
export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"

For Intel:

export CMAKE_PREFIX_PATH="/usr/local/opt/qt@6"
export PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH"

The coreutils path matters for scripts/smoke.sh, because the script calls GNU timeout.

If you use Homebrew LLVM for clang-format, add it to PATH before running lint:

export PATH="$(brew --prefix llvm)/bin:$PATH"

Check the required build tools:

cmake --version
c++ --version

Check optional tools when you need those features:

pkg-config --modversion vterm
timeout --version
rg --version
git --version
node --version

If Qt command-line tools such as qmake6 are not on PATH, that is usually fine as long as CMAKE_PREFIX_PATH points to qt@6.

4. Linux Setup

Use the section for your distribution. Package names vary most around Qt and LLVM tooling.

Fedora

sudo dnf install cmake ninja-build gcc gcc-c++ qt6-qtbase-devel pkgconf-pkg-config libvterm-devel ripgrep git nodejs npm

For formatting with the versions expected by the project:

sudo dnf install clang19-tools-extra

Optional tree-sitter core:

sudo dnf install tree-sitter-devel

Debian / Ubuntu

sudo apt update
sudo apt install cmake ninja-build build-essential qt6-base-dev pkg-config libvterm-dev ripgrep git nodejs npm

For formatting with the versions expected by the project:

sudo apt install clang-format-19

Optional tree-sitter core:

sudo apt install libtree-sitter-dev

Arch Linux

sudo pacman -Syu cmake ninja gcc qt6-base pkgconf libvterm ripgrep git nodejs npm

For formatting:

sudo pacman -S clang

Optional tree-sitter core:

sudo pacman -S tree-sitter

openSUSE

sudo zypper install cmake ninja gcc gcc-c++ qt6-base-devel pkgconf-pkg-config libvterm-devel ripgrep git nodejs npm

For formatting:

sudo zypper install clang

Optional tree-sitter core:

sudo zypper install tree-sitter-devel

5. Get The Source

Clone the repository and enter it:

git clone <repo-url> cold
cd cold

If you already have the repository, enter the existing checkout:

cd /path/to/cold

6. Configure The Build

Use an out-of-source build directory. Ninja is recommended when installed, but Unix Makefiles also work.

Debug build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

Release build:

cmake -S . -B build-release -G Ninja -DCMAKE_BUILD_TYPE=Release

Terminal-enabled build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCOLD_ENABLE_TERMINAL=ON

Build without trying terminal support:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCOLD_ENABLE_TERMINAL=OFF

Tree-sitter opt-in build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCOLD_ENABLE_TREESITTER=ON

If CMake cannot find Qt on macOS, pass the prefix explicitly:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)"

If CMake cannot find Qt on Linux, locate the Qt CMake directory:

find /usr -path '*Qt6Config.cmake' 2>/dev/null

Then configure with Qt6_DIR:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DQt6_DIR=/usr/lib/cmake/Qt6

Adjust the Qt6_DIR path to the path reported on your system.

7. Build

Build the configured tree:

cmake --build build

For Release:

cmake --build build-release

The resulting executable is:

build/cold

or:

build-release/cold

8. Run Cold Locally

Run the Debug binary:

./build/cold

Run the Release binary:

./build-release/cold

On Linux desktop sessions, if Qt reports that no platform plugin can initialize, make sure the Qt platform packages for your desktop are installed. On headless systems, use the smoke test instead of opening the GUI.

9. Verify The Build

Run the offscreen smoke test:

./scripts/smoke.sh ./build/cold

For a Release build:

./scripts/smoke.sh ./build-release/cold

Smoke success is either:

Exit code Meaning
0 The process exited within the smoke window
124 GNU timeout stopped the app after it remained alive in the Qt event loop

On macOS, if timeout is missing, install coreutils and put the Homebrew gnubin directory on PATH as shown in the macOS setup section.

10. Install Locally

Install to a local prefix:

cmake --install build --prefix "$HOME/.local"

Run the installed binary:

"$HOME/.local/bin/cold"

The install rules place:

Installed item Destination
cold bin
src/settings/schema.sql share/cold
resources/lsp/manifest.json share/cold/lsp
LSP artifact directories share/cold/lsp/clangd and share/cold/lsp/typescript

11. Runtime Tool Setup

Cold can build without these tools, but features depend on them at runtime.

Runtime tool Feature
rg Project search
git Git integration
node JavaScript run
npm TypeScript LSP provisioning path
tsc TypeScript compile fallback
ts-node Direct TypeScript run
gcc, g++, clang, clang++ C and C++ run
shell Embedded terminal process

Install TypeScript tools globally if you want TypeScript run support outside project-local tooling:

npm install -g typescript ts-node

If a tool is not on the default PATH, open Cold and set it in:

File -> Preferences -> Tools

LSP server paths are not configured in the Tools tab. Cold resolves language servers separately.

12. LSP Server Setup

Cold supports:

Language group Server id
C / C++ clangd
JavaScript / TypeScript typescript

Resolution order:

  1. Managed cache under the platform data directory.
  2. COLD_LSP_DIR.
  3. Installed share/cold/lsp.
  4. <appDir>/lsp.
  5. Automatic provisioning when general.lsp_auto_download is enabled.
  6. PATH fallback only after provisioning fails and COLD_LSP_ALLOW_PATH=1 or COLD_LSP_PATH_FALLBACK=1.

Default cache locations:

Platform Cache path
Linux ~/.local/share/cold/lsp
macOS ~/Library/Application Support/cold/lsp

For offline development, place server artifacts under a custom directory and point Cold at it:

export COLD_LSP_DIR="/path/to/cold-lsp"

Expected shape:

/path/to/cold-lsp/clangd/
/path/to/cold-lsp/typescript/

To allow fallback to language servers already on PATH after provisioning fails:

export COLD_LSP_ALLOW_PATH=1

13. Lint And Formatting

The project lint script checks C++ formatting for files under src using .clang-format.

Format check (default):

./scripts/lint.sh

Explicit format check:

./scripts/lint.sh --format-only

CI-like mode (stricter version check and --Werror):

./scripts/lint.sh --ci

Apply formatting:

./scripts/lint.sh --fix-format

Expected LLVM tooling:

Tool Expected version
clang-format LLVM 19 or 18

CI uses a Release build-ci tree for the offscreen smoke test. To mirror that layout locally:

cmake -S . -B build-ci -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-ci
./scripts/lint.sh --ci
./scripts/smoke.sh ./build-ci/cold

The CMake integration also exposes lint targets after configure:

cmake --build build --target cold-format-check
cmake --build build --target cold-lint

14. Common Problems

CMake cannot find Qt 6

macOS fix:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)"

Linux fix:

find /usr -path '*Qt6Config.cmake' 2>/dev/null

Then configure with the matching Qt6_DIR.

Terminal tab is missing

Confirm libvterm is visible to pkg-config:

pkg-config --modversion vterm

Reconfigure after installing libvterm:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCOLD_ENABLE_TERMINAL=ON
cmake --build build

Tree-sitter did not build

Tree-sitter is optional and disabled by default. Enable it explicitly:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCOLD_ENABLE_TREESITTER=ON

The build requires the tree-sitter core library and headers. If system grammar libraries are not found, CMake may fetch the C, C++, and JavaScript grammar sources during configure.

Smoke test fails on macOS because timeout is missing

Install GNU coreutils:

brew install coreutils

Add gnubin to PATH:

export PATH="$(brew --prefix coreutils)/libexec/gnubin:$PATH"

LSP does not start

Check whether automatic downloads are enabled in:

File -> Preferences -> General

For offline use, set COLD_LSP_DIR and use the expected server directory shape. For development-only PATH fallback, set:

export COLD_LSP_ALLOW_PATH=1

Search, Git, or Run commands fail inside Cold

Install the missing runtime tool and make sure it is on PATH. If Cold still cannot find it, configure the absolute path in:

File -> Preferences -> Tools

15. Clean Rebuilds

Remove a build directory and configure again:

rm -rf build
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

If you are changing optional dependencies, a clean configure is often clearer than reusing an old CMake cache.

16. Maintainer Checklist

Before sending a build-related change, run the smallest checks that cover it:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./scripts/smoke.sh ./build/cold
./scripts/lint.sh --format-only

For release behavior:

cmake -S . -B build-release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-release
./scripts/smoke.sh ./build-release/cold