ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches

Configure, build, test, package, and document ascii-chat.

Configure, build, test, package, and document ascii-chat.

CMake Build System

Overview

ascii-chat uses CMake with Ninja as its normal generator. The root project configures the native library, executable, dependencies, tests, packaging, and optional web build. Use a separate build directory for each materially different compiler, ABI, SDK, or static/shared dependency configuration.

The source tree is modular: cmake/init/ establishes options and platform detection; cmake/compiler/ owns Clang/LLVM flags and instrumentation; cmake/deps/ finds or builds third-party libraries; cmake/targets/ assembles targets; cmake/install/ owns installation and packaging; and docs/CMakeLists.txt is the independent Doxygen project.

Desktop quick start

Configure once, then build as often as needed:

cmake --preset dev
cmake --build --preset dev
cmake --preset debug
cmake --build --preset debug
cmake --preset release
cmake --build --preset release

A build preset does not replace the initial configure step. Manual configuration is useful for one-off combinations:

cmake -S . -B build-custom -G Ninja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTS=OFF
cmake --build build-custom

Presets

Inspect the repository's current preset names:

cmake --list-presets
cmake --list-presets=build
cmake --list-presets=test
Preset Intended use
default Debug baseline with tests off
debug Debug with the normal diagnostic configuration
debug-fast Debug symbols without sanitizer overhead
dev Fast daily iteration
tests Debug configuration with native tests enabled
relwithdebinfo Optimized build retaining symbols
release Distribution-oriented optimized build
release-musl Explicit Linux musl build
coverage Debug build with coverage instrumentation
windows-debug, windows-release Windows/vcpkg configurations

Toolchains and platforms

Clang/LLVM and Ninja are the supported native toolchain. Windows development normally uses PowerShell with LLVM and the repository presets. Linux and macOS use the platform's Clang or the configured LLVM installation. Keep separate build directories when switching compiler installations or sanitizer runtimes. The native defer tool requires LLVM 19 or newer, its C++ development headers and libraries, and libclang. The dependency installers provision these; ASCIICHAT_LLVM_DEV_ROOT selects an existing compatible development archive. On Windows the installer uses the verified LLVM 23.1.3 archive by default. The optional Python defer backend locates libclang automatically, or accepts ASCIICHAT_LIBCLANG_PATH when it cannot be discovered.

Linux release builds can use USE_MUSL=ON; CMake exposes that option only on Linux. The path needs musl-gcc, GCC as its underlying compiler, and LLD. macOS uses Clang, Apple frameworks, and the configured Homebrew/system dependencies. Windows release builds use the vcpkg configuration and static triplet selected by the preset.

Dependencies and cache

The root configure step may find system packages, use vcpkg on Windows, or build dependencies through the repository's CMake modules. The main cache controls are ASCIICHAT_DEPS_CACHE_ROOT, ASCIICHAT_DEPS_CACHE_DIR, and the derived FETCHCONTENT_BASE_DIR. Keep caches outside disposable build trees. Do not reuse dependency artifacts across incompatible SDKs, architectures, compilers, or musl/glibc configurations.

Git submodules are not required by the documentation-only project. Native configuration may initialize declared submodules when a dependency or feature needs them. If initialization reports that a submodule directory is non-empty, repair that specific partial checkout before retrying.

See Dependencies for the dependency inventory and platform notes.

Important options

Option Effect
BUILD_TESTS=ON Build native test targets
ASCIICHAT_ENABLE_COVERAGE=ON Add coverage instrumentation
ASCIICHAT_ENABLE_ANALYZERS=ON Enable configured Clang-tidy/cppcheck analysis
ASCIICHAT_BUILD_WITH_PANIC=ON Build panic/source instrumentation
ASCIICHAT_USE_PCH=OFF Disable precompiled headers
ASCIICHAT_ENABLE_UNITY_BUILDS=ON Batch sources for faster builds
USE_MUSL=ON Select the Linux musl path
BUILD_WEB=ON Build WASM/browser targets; requires emcc and em++ on PATH
ASCIICHAT_ENFORCE_STATIC_RELEASE=OFF Permit a non-static release configuration
ASCIICHAT_FORMAT_ONLY=ON Configure only formatting-related paths
USE_CPACK=ON Enable package generation

Compiler, ABI, dependency, and target-platform options belong in a fresh build directory rather than being toggled in place.

Tests and CI

cmake --preset tests
cmake --build --preset tests
ctest --preset unit
ctest --preset integration
ctest --preset all

GitHub Actions uses dedicated CI presets and workflows. Diagnose failures from the job log instead of copying every CI cache flag into a local build.

Documentation builds

Documentation is a separate CMake project. It does not configure the native application, compile OpenSSL, initialize the full native dependency graph, or require all submodules. The Doxygen theme submodule is the relevant HTML styling input.

cmake -S docs -B build/docs-standalone \
-DASCII_CHAT_SOURCE_DIR=$PWD
cmake --build build/docs-standalone --target docs

HTML is written to build/docs-standalone/share/doc/html/index.html. The root project can import the same target with cmake --Build System <native-build> --target docs-html; the standalone project is preferred for docs-only work and CI.

iOS prototype and Apple targets

Pull request #626 adds the current iOS simulator/device prototype. It is an in-progress platform target, not a desktop executable. CMake builds a static libasciichat.a-based app and keeps desktop-only executables, tests, TTY setup, and unsupported QUIC paths out of the iOS SDK build.

The prototype includes iOS platform detection, arm64 device and configurable simulator builds, a SwiftUI target named ascii-chat-ios-app, an AVFoundation camera bridge, an AVAudioEngine-backed PortAudio-compatible audio shim, a C render bridge, native mode/lifecycle state, background audio handling, and an XCFramework packaging helper. The Intel simulator has no camera; physical camera and microphone validation remains device work.

Simulator

Run on macOS with Xcode and the iOS simulator SDK:

./scripts/build-ios-simulator.sh build-ios-sim
IOS_SIM_ARCH=arm64 ./scripts/build-ios-simulator.sh build-ios-sim-arm64

The helper validates IOS_SIM_ARCH (x86_64 or arm64), configures BUILD_IOS_SIM=ON, and builds ascii-chat-ios-app.

Device

A device build requires the iPhoneOS SDK and a fresh build directory:

./scripts/build-ios-device.sh build-ios

The helper checks xcrun --sdk iphoneos --show-sdk-path and rejects a directory previously configured for the simulator.

XCFramework

Build both archives and package them with public headers:

./scripts/build-ios-simulator.sh build-ios-sim
./scripts/build-ios-device.sh build-ios
./scripts/package-ios-xcframework.sh \
build-ios/lib/libasciichat.a \
build-ios-sim/lib/libasciichat.a \
build/asciichat.xcframework

The packager refuses to overwrite an existing output, stages public headers plus the required Sokol headers, and invokes xcodebuild -create-xcframework.

Useful targets

Target Purpose
ascii-chat Desktop executable
ascii-chat-static-lib Static native library
ascii-chat-ios-app SwiftUI iOS prototype app
tests Native test aggregation target
docs-html Generate HTML documentation
docs-open Generate docs and print the local index path
format Format configured sources
package Generate available CPack packages

Packaging and installation

cmake --build build/dev
cmake --install build/dev --prefix $HOME/.local
cmake --build build/dev --target package

CPack output depends on host tools available during configuration. Inspect the configure summary instead of assuming every host produces DEB, RPM, PKG, or NSIS.

Troubleshooting

  • Wrong compiler or SDK: start with a fresh build directory and inspect CMakeCache.txt.
  • Submodule failure: repair the reported partial submodule checkout specifically.
  • Unexpected dependency rebuild: check cache root and target ABI/SDK.
  • iOS probes target the host: use the iOS helper so FFmpeg and ICU probes receive the selected SDK.
  • Swift receives Clang flags: keep language-specific options scoped to C/C++ targets.
See also
CMakeLists.txt
CMakePresets.json
docs/CMakeLists.txt
topic_dependencies
topic_testing