This guide provides instructions for building, testing, and benchmarking the Ada URL parser library using CMake.

Quick Reference

# Build library only (no tests, no benchmarks)
cmake -B build && cmake --build build
 
# Build with tests (development checks ENABLED)
cmake -B build -DADA_TESTING=ON && cmake --build build
ctest --output-on-failure --test-dir build
 
# Build with benchmarks (development checks DISABLED for accurate performance)
cmake -B build -DADA_BENCHMARKS=ON -DADA_USE_UNSAFE_STD_REGEX_PROVIDER=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build
./build/benchmarks/benchdata  # Run main benchmark
 
# FASTER BUILDS: Use Ninja instead of Make
cmake -B build -G Ninja -DADA_TESTING=ON && cmake --build build
cmake -B build -G Ninja -DADA_BENCHMARKS=ON -DADA_USE_UNSAFE_STD_REGEX_PROVIDER=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build

Requirements

C++20 compatible compiler (GCC 12+, LLVM 14+, MSVC 2022+)
CMake 3.15+
Git (for fetching test dependencies)
Ninja (optional, for faster builds): sudo apt install ninja-build on Ubuntu

Building the Library

Basic Build (Library Only)

For a minimal build with just the library:

cmake -B build

cmake --build build

This creates the Ada library without tests or benchmarks.

Build with Tests

To build with tests enabled:

cmake -B build -DADA_TESTING=ON

cmake --build build

Important: When ADA_TESTING=ON, development checks are automatically enabled unless you explicitly build in Release mode with NDEBUG defined. Development checks include assertions (ADA_ASSERT_TRUE, ADA_ASSERT_EQUAL) that validate internal state.

Build with Benchmarks

To build benchmarks for performance testing:

cmake -B build -DADA_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release

cmake --build build

Critical: Always build benchmarks in Release mode (-DCMAKE_BUILD_TYPE=Release) to disable development checks. Development assertions significantly impact performance and will give misleading benchmark results.

Using Local Packages

If you have dependencies (like GoogleTest, Google Benchmark) already installed locally:

cmake -B build -DADA_TESTING=ON -DCPM_USE_LOCAL_PACKAGES=ON

cmake --build build

CMake Build Options

Option	Default	Description
ADA_TESTING	OFF	Enable building tests
ADA_BENCHMARKS	OFF	Enable building benchmarks (requires 64-bit)
ADA_TOOLS	OFF	Enable building command-line tools
ADA_BUILD_SINGLE_HEADER_LIB	OFF	Build from single-header amalgamated files
ADA_USE_SIMDUTF	OFF	Enable SIMD-accelerated Unicode via simdutf
CMAKE_BUILD_TYPE	-	Set to Release for optimized builds, Debug for development

Running Tests

After building with -DADA_TESTING=ON:

# Run all tests
ctest --output-on-failure --test-dir build
 
# Run specific test executable
./build/tests/basic_tests
 
# Run tests with verbose output
ctest --verbose --test-dir build

Development Checks in Tests

Tests run with development checks enabled by default (unless built with -DCMAKE_BUILD_TYPE=Release -DNDEBUG). This means:

Assertions are active (ADA_ASSERT_TRUE, ADA_ASSERT_EQUAL)
Internal state validation occurs
Performance is slower but catches bugs early

This is the recommended mode for development.

Running Benchmarks

After building with -DADA_BENCHMARKS=ON:

# Main benchmark comparing against competitors
./build/benchmarks/benchdata
 
# Specific benchmarks
./build/benchmarks/bench          # Basic URL parsing benchmarks
./build/benchmarks/bbc_bench      # BBC URLs benchmark
./build/benchmarks/wpt_bench      # Web Platform Tests benchmark
./build/benchmarks/percent_encode # Percent encoding benchmarks

Development Checks in Benchmarks

Always disable development checks for benchmarks by building in Release mode:

# CORRECT: Benchmarks with development checks disabled
cmake -B build -DADA_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/benchmarks/benchdata
 
# WRONG: Don't benchmark with development checks enabled
cmake -B build -DADA_BENCHMARKS=ON  # Missing Release mode!

Development checks add significant overhead that skews performance measurements. The ADA_DEVELOPMENT_CHECKS macro is automatically disabled when:

Building with -DCMAKE_BUILD_TYPE=Release
NDEBUG is defined
Explicitly set ADA_DEVELOPMENT_CHECKS=0

Complete Development Workflow

1. Initial Setup

# Clone and enter directory
cd /path/to/ada
 
# Create build directory for tests
cmake -B build -DADA_TESTING=ON
cmake --build build

2. Development Cycle (with tests)

# Make code changes...
 
# Rebuild (only rebuilds changed files)
cmake --build build
 
# Run tests to verify correctness
ctest --output-on-failure --test-dir build
 
# Or run specific test
./build/tests/basic_tests

3. Performance Validation (with benchmarks)

# Create separate benchmark build
cmake -B build-release -DADA_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-release
 
# Run benchmarks
./build-release/benchmarks/benchdata
 
# Compare before/after optimizations
# (stash changes, rebuild, run benchmark, restore, rebuild, run again)

4. Clean Rebuild

# Remove build directory and start fresh
rm -rf build
cmake -B build -DADA_TESTING=ON
cmake --build build

Understanding Development Checks

What are Development Checks?

Development checks are compile-time assertions that validate:

Function preconditions and postconditions
Internal invariants (e.g., validate() on URL objects)
Argument validity

When are they Enabled?

Automatically enabled when:

ADA_TESTING=ON (unless overridden with Release mode)
Debug build (CMAKE_BUILD_TYPE=Debug)
NDEBUG is not defined

Automatically disabled when:

CMAKE_BUILD_TYPE=Release
NDEBUG is defined
Production builds

Manual Control

# Force enable development checks (even in Release)
cmake -B build -DADA_DEVELOPMENT_CHECKS=1
 
# Force disable development checks (even in Debug)
cmake -B build -DNDEBUG=1

Running Clang-Tidy

Clang-tidy is used for static analysis. There are two ways to run it:

During Build (Recommended)

Run clang-tidy automatically during compilation:

cmake -B build -DADA_TESTING=ON \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_CXX_CLANG_TIDY=clang-tidy \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

Important: You must use clang++ as the compiler when running clang-tidy during build. Using GCC will cause errors because clang-tidy doesn't understand GCC-specific flags like -mno-avx256-split-unaligned-load.

Standalone with compile_commands.json

First, generate the compilation database:

cmake -B build -DADA_TESTING=ON \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build

Then run clang-tidy on specific files:

clang-tidy -p build src/ada.cpp

clang-tidy -p build src/ada_idna.cpp

The -p build flag tells clang-tidy to use the compile_commands.json from the build directory.

Clang-Tidy Configuration

The .clang-tidy file in the project root configures which checks are enabled. Current configuration enables:

bugprone-* checks (with some exclusions)
clang-analyzer-* checks

All warnings are treated as errors (WarningsAsErrors: '*').

Platform-Specific Notes

Windows

Specify configuration during build:

cmake -B build -DADA_TESTING=ON
cmake --build build --config Release
ctest --output-on-failure --test-dir build --config Release

macOS/Linux

Standard commands work as documented above.

Troubleshooting

Benchmarks are unexpectedly slow

Cause: Development checks are enabled.

Solution: Rebuild with Release mode:

cmake -B build -DADA_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release

cmake --build build

Tests are failing with assertion errors

Expected behavior - development checks are catching bugs. Review the assertion message and fix the underlying issue.

Can't find benchmark executable

Cause: Benchmarks not built (32-bit system or not enabled).

Solution:

cmake -B build -DADA_BENCHMARKS=ON
cmake --build build
ls build/benchmarks/  # Check what was built

Additional Resources

README.md: General project overview and API usage
docs/cli.md: Command-line interface documentation
benchmarks/: Benchmark source code
tests/: Test source code
include/ada/: Library headers

Summary

Task	Command	Development Checks
Library only	cmake -B build && cmake --build build	N/A
Testing	cmake -B build -DADA_TESTING=ON && cmake --build build	✅ Enabled
Benchmarking	cmake -B build -DADA_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build	❌ Disabled
Development	cmake -B build -DADA_TESTING=ON -DCMAKE_BUILD_TYPE=Debug && cmake --build build	✅ Enabled