Building the Project

Guide to compiling, testing, and packaging ztick from source.

Prerequisites#

• Zig 0.15.2 ( download)
• libssl-dev (Debian/Ubuntu) or openssl-devel (Fedora/RHEL) — required for TLS support
• git (optional, for cloning the repository)

Zig package dependencies (fetched automatically by zig build):

• zig-o11y/opentelemetry-sdk v0.1.1 — OpenTelemetry instrumentation ( ADR-0004)

Build Variants#

Debug Build (Default)#

zig build

Produces an unoptimized executable with debug symbols. Best for development.

Output: zig-cache/bin/ztick

Use case: Development, debugging, testing

Release Build (Optimized)#

zig build -Doptimize=ReleaseSafe

Produces an optimized executable with safety checks. Recommended for production.

Output: zig-cache/bin/ztick

Performance: 2-3x faster than debug builds

Use case: Production deployment

Release (Unsafe)#

zig build -Doptimize=ReleaseUnsafe

Strips all safety checks for maximum speed. Use only if you’re confident the code is correct.

Output: zig-cache/bin/ztick

Use case: Benchmarking, extreme performance requirements

Testing#

Run All Tests#

zig build test

Compiles and runs all unit tests across all layers (domain, application, infrastructure, interfaces).

Output: Test summary with pass/fail counts

Selective Testing#

Test a specific layer:

zig build test --test-filter domain
zig build test --test-filter application
zig build test --test-filter infrastructure
zig build test --test-filter interfaces

Functional Tests#

Run end-to-end tests:

zig build test-functional

Test Coverage#

ztick aims for high test coverage:

• Domain: 95%+ (pure logic, comprehensive tests)
• Application: 85%+ (scheduler, storage, query handling)
• Infrastructure: 80%+ (adapters, parsers)
• Overall: 80%+

To verify coverage, review test blocks in each source file (co-located tests).

Code Quality#

Format Check#

Verify code follows Zig style guide:

zig fmt --check .

Auto-Format#

Fix formatting issues:

zig fmt .

Build Configuration#

The project uses build.zig for configuration:

cat build.zig  # View build configuration

Compiler Flags#

You can pass additional flags:

zig build -Doptimize=ReleaseSafe -Dstrip=true

Cross-Compilation#

Linux to Windows#

zig build -Dtarget=x86_64-windows-gnu

Linux to macOS#

zig build -Dtarget=aarch64-macos

Linux to ARM#

zig build -Dtarget=aarch64-linux-gnu

Installation#

After building, install to a system path:

zig build --prefix=/usr/local install

This installs the ztick binary to /usr/local/bin/.

Alternative: Copy the binary manually

cp zig-cache/bin/ztick /usr/local/bin/ztick
chmod +x /usr/local/bin/ztick

Troubleshooting#

“zig: not found”#

Zig is not installed or not in PATH. Install from ziglang.org.

Verify installation:

zig version  # Should print 0.15.2

“error: MemoryOutOfBounds”#

The test allocator detected a memory leak. Review your test cleanup:

var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();  // Must have this

Build takes too long#

Zig caches build artifacts. To force a clean rebuild:

rm -rf zig-cache
zig build

Cannot connect to scheduler after build#

Ensure the binary was built successfully:

zig build
ls -la zig-cache/bin/ztick

Development Workflow#

1. Make Changes#

Edit files in src/:

$EDITOR src/domain/job.zig

2. Run Tests#

Test the affected layer:

zig build test --test-filter domain

3. Format Code#

Keep code style consistent:

zig fmt .

4. Build Project#

Full build to catch all issues:

zig build

5. Manual Testing#

Start the scheduler:

./zig-cache/bin/ztick --config config.toml

Test with protocol commands:

echo 'SET test.job 1711612800' | socat - TCP:localhost:5555

Performance Profiling#

Benchmark Database Throughput#

ztick’s database thread is optimized for high throughput at scale. The following benchmarks validate performance targets ( F021):

Single-Worker Latency (baseline):

# Build release version
zig build -Doptimize=ReleaseSafe

# Run with optimized framerate
echo '[database]
framerate = 1024
[database.persistence]
mode = "memory"' > bench.toml

./zig-cache/bin/ztick --config bench.toml &

# In another terminal, run benchmark
./scripts/bench/bench-write.sh WORKERS_TCP=1 DURATION=30

Expected results: p50 latency <1ms

Multi-Worker Throughput (concurrent load):

# Same server setup as above, then:
./scripts/bench/bench-write.sh WORKERS_TCP=8 DURATION=30

Expected results: >3000 msg/s aggregate, p50 <5ms, p99 <15ms

Interpretation:

• Throughput: Messages processed per second (aggregate across all workers)
• p50/p99: Median and 99th percentile request latency (single request, not aggregate)
• Memory mode: Disable persistence (mode = "memory") to isolate database throughput from I/O

Benchmark Scheduler#

To measure scheduler evaluation without network I/O:

# Build release version
zig build -Doptimize=ReleaseSafe

# Run with framerate set high
echo '[database]
framerate = 100' > bench.toml

./zig-cache/bin/ztick --config bench.toml

Monitor CPU usage and latency with system tools:

watch -n 1 'ps aux | grep ztick'

Memory Usage#

Check memory consumption:

valgrind --leak-check=full ./zig-cache/bin/ztick --config config.toml

Or on macOS:

leaks -atExit -- ./zig-cache/bin/ztick --config config.toml

Release Checklist#

Before releasing a new version:

• All tests pass: zig build test
• Code is formatted: zig fmt --check .
• No compiler warnings
• Documentation is up-to-date
• Version number bumped in build.zig.zon
• Changelog updated

See Also#

• Architecture — Design and layer structure
• Contributing — Code style and submission guidelines