Overview

This section covers all aspects of building Ember from source, including dependencies, build options, and various build methods.

Quick Start (Ubuntu 20.04+)

For Ubuntu 20.04+ users, the build is streamlined with prebuilt binaries:

# Install dependencies
sudo apt install build-essential cmake git git-lfs pkg-config \
    libgtk-3-dev libxml2-dev libwxsvg-dev libcairo2-dev \
    libpango1.0-dev libfontconfig1-dev libexif-dev libfreetype6-dev
 
# Clone with Git LFS
git lfs install
git clone https://github.com/Dmowmyh/BTV.git
cd BTV
git lfs pull
 
# Build (~2-3 minutes)
mkdir build && cd build
cmake .. && make -j$(nproc)

Note: Git LFS is required to download prebuilt wxWidgets and Doxygen binaries (~80 MB).

Prebuilt Binaries

Ember includes prebuilt binaries for Linux x64 to significantly reduce build times:

Component	Location	Size	Saved Time
wxWidgets 3.3	third_party/wxWidgets-prebuilt/	~80 MB	~12-15 min
Doxygen	third_party/doxygen-binaries/	~15 MB	~3-5 min

How Prebuilts Work

Automatic detection: CMake checks if prebuilts are compatible with your system (glibc version via ldd)
Fallback to source: If incompatible, wxWidgets builds from the submodule automatically
Git LFS: Large .so files are stored with Git LFS, not in the main repository

Disabling Prebuilts

To force building from source:

cmake .. -DUSE_WX_PREBUILT=OFF

Compatibility

System	Prebuilt Support
Ubuntu 20.04+ (glibc 2.31+)	✅ Full support
Ubuntu 18.04 (glibc 2.27)	❌ Falls back to source build
Fedora 32+	✅ Should work (glibc 2.31+)
Arch Linux	✅ Should work (rolling release)

Dependencies

Required Dependencies

Dependency	Version	Purpose
CMake	3.16+	Build system
C++ Compiler	GCC 7+ / Clang 6+	C++14 support required
wxWidgets	3.2+	GUI framework (prebuilt or source)
libxml2	2.9+	XML parsing
GTK3	3.20+	Linux GUI toolkit
Git LFS	2.0+	Prebuilt binary storage

Optional Dependencies

Dependency	Purpose	CMake Option
spdlog	Enhanced logging	Auto-detected
Google Test	Unit testing	BUILD_TESTS
Doxygen	Documentation	BUILD_DOCUMENTATION (prebuilt included)
Graphviz	Doc diagrams	HAVE_DOT

Installing Dependencies

Ubuntu/Debian

# Required (includes Git LFS)
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    git \
    git-lfs \
    libgtk-3-dev \
    libxml2-dev
 
# Optional
sudo apt-get install -y \
    libspdlog-dev \
    graphviz

Fedora

sudo dnf install -y \
    gcc-c++ \
    cmake \
    gtk3-devel \
    libxml2-devel \
    spdlog-devel

Arch Linux

sudo pacman -S \
    base-devel \
    cmake \
    gtk3 \
    libxml2 \
    spdlog

Verifying Dependencies

Use the provided script to check all dependencies:

./verify_dependencies.sh

This script checks for:

Required compilers and tools
Library availability
Correct versions
Missing optional dependencies

CMake Configuration

Basic Configuration

mkdir build && cd build

cmake ..

Configuration Options

Option	Default	Description
CMAKE_BUILD_TYPE	Debug	Build type: Debug, Release, RelWithDebInfo
BUILD_TESTS	ON	Build unit tests
BUILD_DOCUMENTATION	OFF	Build Doxygen documentation
USE_SYSTEM_WXWIDGETS	OFF	Use system wxWidgets instead of building
ENABLE_SANITIZERS	OFF	Enable AddressSanitizer
ENABLE_COVERAGE	OFF	Enable code coverage

Example Configurations

Release Build

cmake .. -DCMAKE_BUILD_TYPE=Release

With Documentation

cmake .. -DBUILD_DOCUMENTATION=ON

With Sanitizers (for debugging)

cmake .. -DENABLE_SANITIZERS=ON -DCMAKE_BUILD_TYPE=Debug

Using System wxWidgets

cmake .. -DUSE_SYSTEM_WXWIDGETS=ON

CMake Modules

Custom CMake modules are in cmake_modules/:

Module	Purpose
EMBERConfig.cmake	Main project configuration
FindLibXML2.cmake	libxml2 detection
FindSpdlog.cmake	spdlog detection
FindwxWidgets.cmake	wxWidgets detection
FindwxSVG.cmake	wxSVG detection (optional)

Build Methods

Method 1: CMake (Recommended)

The fastest approach using prebuilt binaries:

# Ensure Git LFS files are downloaded
git lfs pull
 
# Create build directory
mkdir -p build && cd build
 
# Configure (auto-detects prebuilts)
cmake ..
 
# Build (uses all CPU cores)
make -j$(nproc)
 
# Run
./bin/emberforge

Build time: ~2-3 minutes on Ubuntu 20.04+ with prebuilts.

Method 2: Build Script

The build.sh script handles everything automatically:

# Basic build
./build.sh
 
# With automatic dependency installation
./build.sh --auto-install
 
# Release build
./build.sh --release
 
# Clean build
./build.sh --clean
 
# Build with tests
./build.sh --tests
 
# Build documentation
./build.sh --docs

Build Script Options

Option	Description
--auto-install	Automatically install missing dependencies
--release	Build in Release mode
--debug	Build in Debug mode (default)
--clean	Clean build directory first
--tests	Build and run tests
--docs	Build documentation
--jobs N	Use N parallel jobs
--verbose	Verbose output
--help	Show help message

Method 3: Docker Build

For reproducible builds in an isolated environment:

cd docker
 
# Build Docker image
docker build -t ember-build .
 
# Run build
./test_build.sh

The Docker environment includes all dependencies pre-installed.

Build Outputs

After a successful build:

build/
├── bin/
│   ├── emberforge          # Main application
│   └── tests/
│       └── embercore_tests # Unit tests
├── lib/
│   └── libembercore.a      # Core library
└── docs/
    └── html/               # Generated documentation
        └── index.html

Documentation Generation

Using the Script

./docs/generate_docs.sh

This script:

Configures CMake with BUILD_DOCUMENTATION=ON
Runs make docs
Copies output to docs/html/

Manual Generation

cd build
cmake .. -DBUILD_DOCUMENTATION=ON
make docs

Viewing Documentation

# Open in browser
xdg-open build/docs/html/index.html
 
# Or after running generate_docs.sh
xdg-open docs/html/index.html

Git Hooks

Ember uses Git hooks to maintain code quality.

Installing Hooks

./scripts/hooks/setup-hooks.sh

This installs:

pre-commit: Format checking, linting
pre-push: Build verification, tests, static analysis

Pre-commit Hooks

Configured in .pre-commit-config.yaml:

Hook	Purpose
trailing-whitespace	Remove trailing whitespace
end-of-file-fixer	Ensure files end with newline
check-yaml	Validate YAML files
check-json	Validate JSON files
clang-format	Code formatting
cppcheck	Static analysis

Running Pre-commit Manually

# Run on all files
pre-commit run --all-files
 
# Run specific hook
pre-commit run clang-format --all-files

Pre-push Hooks

The pre-push hook (scripts/hooks/pre-push) runs:

Full build - Ensures code compiles
Unit tests - Runs all tests
clang-tidy - Static analysis (parallel)
cppcheck - Additional static analysis

Running Pre-push Manually

./scripts/hooks/pre-push

Bypassing Hooks (Not Recommended)

# Skip pre-commit
git commit --no-verify
 
# Skip pre-push
git push --no-verify

Continuous Integration

GitHub Actions

Workflows in .github/workflows/:

Workflow	Trigger	Purpose
build-test.yml	Push/PR	Build verification
unit-tests.yml	Push/PR	Run unit tests

CI Environment

CI builds use Docker for consistency:

Ubuntu-based image
All dependencies pre-installed
Same environment as docker/Dockerfile

Troubleshooting

Common Build Issues

Git LFS Files Not Downloaded

CMake Error: Bundled wxWidgets prebuilt incompatible with this system

If you see this on Ubuntu 20.04+ where prebuilts should work:

Solution: The .so files weren't downloaded by Git LFS:

git lfs install

git lfs pull

Verify the files exist:

ls -la third_party/wxWidgets-prebuilt/linux-x64/lib/*.so

# Should show ~80MB of .so files, not small pointer files

Prebuilt Incompatible (Older glibc)

Bundled wxWidgets prebuilt incompatible with this system (missing deps or wrong glibc)

Falling back to building from source

This is expected on systems with glibc < 2.31 (e.g., Ubuntu 18.04). The build will automatically fall back to compiling wxWidgets from source (~15 min longer).

wxWidgets Not Found

CMake Error: Could not find wxWidgets

Solution: Ensure the wxWidgets submodule is initialized:

git submodule update --init --recursive

Or install system wxWidgets:

sudo apt-get install libwxgtk3.0-gtk3-dev

libxml2 Not Found

CMake Error: Could not find LibXML2

Solution:

sudo apt-get install libxml2-dev

Compiler Too Old

error: 'auto' changes meaning in C++11

Solution: Use a newer compiler:

sudo apt-get install g++-9
export CXX=g++-9
cmake ..

Out of Memory During Build

Solution: Reduce parallel jobs:

make -j2 # Instead of -j$(nproc)

Getting Help

Check ./verify_dependencies.sh output
Review CMake configuration output
Ensure git lfs pull was run after cloning
Check GitHub Issues for similar problems