Dependencies

⛓️ External projects we rely on

⛓️ External projects we rely on

Dependencies README

This page walks you through installing everything you need to build ascii-chat. Once you're done here, head to Build System to compile.

Step 1: Get Submodules

ascii-chat uses git submodules for vendored dependencies. Get them first:

git submodule init
git submodule update --recursive

This fetches uthash, BearSSL, tomlc17, sokol, and libsodium-bcrypt-pbkdf into deps/.

Step 2: Install Dependencies

Automated Installation (Recommended)

The easiest way to install everything is with the install script:

# Linux/macOS
./scripts/install-deps.sh
 
# Windows (PowerShell)
./scripts/install-deps.ps1

The script detects your platform and installs all required dependencies using your system's package manager (Homebrew, apt, yum, pacman, or vcpkg).

Manual Installation

If you prefer to install manually or the script doesn't work for your system:

Ubuntu/Debian:

# Build tools
sudo apt-get install build-essential clang clang-tidy clang-format cmake ninja-build
 
# Core dependencies
sudo apt-get install libzstd-dev portaudio19-dev libsodium-dev
 
# Testing (optional)
sudo apt-get install libcriterion-dev
 
# Release builds (optional)
sudo apt-get install musl-tools musl-dev libmimalloc-dev

Arch Linux:

sudo pacman -S pkg-config clang llvm cmake ninja make zstd portaudio libsodium criterion musl mimalloc

macOS (Homebrew):

brew install cmake ninja make zstd portaudio libsodium criterion mimalloc llvm

Windows (Scoop + vcpkg):

First, install Visual Studio Build Tools and select the "Desktop development with C++" workload. This provides nmake for building BearSSL.

# Build tools
scoop install cmake ninja llvm
 
# Dependencies via vcpkg
vcpkg install zstd:x64-windows portaudio:x64-windows libsodium:x64-windows mimalloc:x64-windows

Ready to Build

Once dependencies are installed, you're ready to compile. See Build System for build instructions, or just run:

make CMAKE_BUILD_TYPE=RelWithDebInfo

Build Tools

These tools are required to build ascii-chat from source.

Clang/LLVM - C Compiler

Website: https://clang.llvm.org/

Version: 18.0 or later

ascii-chat is a Clang-only project. We use Clang for:

• C23 standard support
• AddressSanitizer and UndefinedBehaviorSanitizer
• clang-format and clang-tidy integration
• Consistent behavior across platforms
• SIMD intrinsics (SSE2, AVX2, NEON)

CMake - Build System Generator

Website: https://cmake.org/

Version: 4.2 or later

CMake configures the build. We use:

• CMake Presets for build configurations
• Modern target-based dependency management
• Cross-compilation support

Ninja - Build System

Website: https://ninja-build.org/

Version: Any

Ninja executes the build. Benefits:

• Automatic parallelization
• 2-3x faster than Make
• Incremental builds with dependency tracking

Core Runtime Dependencies

Required for ascii-chat to function.

PortAudio - Cross-Platform Audio I/O

Purpose: Real-time audio capture and playback

Website: http://www.portaudio.com/

License: MIT License

Version: 19.7.0 or later

Used in lib/audio.c and lib/mixer.c for audio streaming. PortAudio abstracts platform differences (WASAPI on Windows, CoreAudio on macOS, ALSA/PulseAudio on Linux).

libsodium - Modern Cryptography

Purpose: End-to-end encryption and authentication

Website: https://libsodium.org/

License: ISC License

Version: 1.0.18 or later

Powers the cryptographic protocol in lib/crypto/. Provides:

• X25519 key exchange
• XSalsa20-Poly1305 authenticated encryption
• Ed25519 signatures for SSH key authentication

zstd - Fast Compression

Purpose: Real-time video frame compression

Website: https://facebook.github.io/zstd/

License: BSD License

Version: 1.4.0 or later

Used in lib/compression.c to compress ASCII frames before transmission. Level 1 compression gives ~50% size reduction at 400+ MB/s.

Vendored Dependencies (Git Submodules)

Included in deps/ and built from source for version consistency.

uthash - Hash Table for C

Purpose: O(1) hash table lookups for client management

Website: https://troydhanson.github.io/uthash/

License: BSD License

Header-only library for hash tables. Used for client ID lookups, symbol caching, and lock tracking.

BearSSL - Minimalist SSL/TLS

Purpose: HTTPS client for fetching public keys from GitHub/GitLab

Website: https://bearssl.org/

License: MIT License

Small (~100KB) SSL library used in lib/crypto/http_client.c. Much smaller and simpler than OpenSSL.

tomlc17 - TOML Parser

Purpose: Configuration file parsing (future feature)

Website: https://github.com/cktan/tomlc17

License: MIT License

Prepared for ~/.ascii-chat/config.toml support.

Sokol - Cross-Platform APIs

Purpose: Future GPU-accelerated rendering

Website: https://github.com/floooh/sokol

License: zlib/libpng License

Header-only library for graphics, audio, and input. Available for future use.

libsodium-bcrypt-pbkdf

Purpose: OpenSSH private key decryption

Website: https://github.com/imaami/libsodium-bcrypt-pbkdf

License: BSD License

Implements bcrypt-pbkdf for decrypting password-protected SSH keys.

Testing Dependencies

Only required for building and running tests.

Criterion - Testing Framework

Purpose: Unit, integration, and performance testing

Website: https://criterion.readthedocs.io/

License: MIT License

Version: 2.4.0 or later

Platform: POSIX only (Linux, macOS). Windows tests run via Docker.

Provides automatic test discovery, fixtures, parameterized tests, and JUnit XML output for CI.

Release Build Dependencies

Optional for development, but required for portable static release builds.

musl - Lightweight C Standard Library

Purpose: Fully static executables with no glibc dependencies

Website: https://musl.libc.org/

License: MIT License

Platform: Linux only

musl enables building fully static executables that run on any Linux distribution without shared library dependencies. Used with -DUSE_MUSL=ON.

mimalloc - High-Performance Allocator

Purpose: Fast memory allocation for production builds

Website: https://github.com/microsoft/mimalloc

License: MIT License

Version: 2.0.0 or later

Up to 2x faster than system malloc. Enabled with -DUSE_MIMALLOC=ON and used by default in release builds.

Platform APIs

ascii-chat uses native platform APIs for webcam access and terminal I/O, eliminating heavy dependencies like OpenCV.

Video Capture:

• Linux: Video4Linux2 (V4L2) - kernel interface, no library
• macOS: AVFoundation - system framework
• Windows: Media Foundation - system library

Terminal I/O:

• POSIX: termios for raw mode and ANSI sequences
• Windows: Console API with virtual terminal sequences

License Compatibility

All dependencies use permissive licenses compatible with ascii-chat:

License	Dependencies
MIT	BearSSL, PortAudio, Criterion, mimalloc, musl, tomlc17
ISC	libsodium
BSD	zstd, uthash, libsodium-bcrypt-pbkdf
zlib	sokol

No copyleft (GPL) dependencies in the core application.

Version Requirements

Dependency	Minimum	Rationale
CMake	4.2	CMake Presets, modern features
Clang	18.0	C23, sanitizers, defer/panic tools
PortAudio	19.7.0	Stable callback API
libsodium	1.0.18	Ed25519 support
zstd	1.4.0	Streaming API
Criterion	2.4.0	Theories and fixtures

Git submodules are pinned to specific commits for reproducibility.

Updating Dependencies

Git Submodules:

# Update all submodules
git submodule update --remote --merge
 
# Update specific submodule
cd deps/uthash && git checkout v2.3.0
cd ../.. && git add deps/uthash && git commit -m "Update uthash"

System Libraries:

# Linux
sudo apt-get update && sudo apt-get upgrade
 
# macOS
brew update && brew upgrade
 
# Windows
vcpkg upgrade

Troubleshooting

PortAudio Not Found

# macOS: Add Homebrew to PKG_CONFIG_PATH
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
 
# Windows: Set vcpkg toolchain
cmake -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ..

Criterion on Windows

Criterion is POSIX-only. Run tests via Docker:

./tests/scripts/run-docker-tests.ps1

BearSSL Build Fails

BearSSL requires a native build tool:

• Linux/macOS: Ensure make is installed (apt install build-essential or brew install make)
• Windows: Requires nmake from Visual Studio Build Tools (install from https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)

Missing Submodules

git submodule init
git submodule update --recursive

See also

Build System - Compile ascii-chat after installing Dependencies

CMakeLists.txt

cmake/dependencies/Dependencies.cmake