🔒 Ad-Blocking Toolkit

← Back to Documentation

Documentation

Rust Workspace Modernization - Summary

Overview

This document summarizes the modernization of Rust projects in the ad-blocking repository. All Rust projects have been unified into a single workspace with modern tooling and configuration.

What Changed

Before

  • 3 separate Rust projects with independent configurations:

    • src/adguard-validation/ (workspace with 2 crates)
    • src/adguard-api-rust/ (workspace with 2 crates)
    • src/rules-compiler-rust/ (single crate)

  • Inconsistent versions:

    • Rust 1.75 (adguard-validation)
    • Edition 2024 (adguard-api-rust, rules-compiler-rust)
    • Edition 2021 (adguard-validation)

  • Duplicate dependencies: Each project declared its own dependency versions

  • No shared configuration: Each project had its own build settings

  • Separate CI jobs: Each project tested independently

After

  • Single unified workspace at repository root

  • 5 workspace members:

    1. adguard-validation-core - Core validation library
    2. adguard-validation-cli - Validation CLI tool
    3. adguard-api-lib - AdGuard DNS API client library
    4. adguard-api-cli - Interactive API CLI
    5. rules-compiler - Filter rules compiler

  • Consistent Rust 1.83 across all projects

  • Shared dependencies managed in root Cargo.toml

  • Unified configuration files for formatting, linting, and builds

  • Single CI job builds and tests all Rust projects

New Files Added

Configuration Files

  1. Cargo.toml (root) - Workspace configuration

    • Defines 5 workspace members
    • Centralizes dependency versions
    • Sets workspace-wide metadata
    • Configures release profile optimizations

  2. rust-toolchain.toml - Toolchain specification

    • Rust 1.83 with rustfmt and clippy components
    • Ensures consistent toolchain across environments

  3. .cargo/config.toml - Build configuration

    • Cargo settings for builds
    • Git CLI integration
    • Profile overrides

  4. .rustfmt.toml - Code formatting

    • 100-character line width
    • Import reordering
    • Unix line endings
    • Stable-only features

  5. clippy.toml - Linting configuration

    • Cognitive complexity threshold: 30
    • Documentation enforcement
    • Test-specific allowances

  6. Cargo.lock - Locked dependencies

    • Ensures reproducible builds
    • Version 4 lockfile format

Documentation Files

  1. RUST_WORKSPACE.md - Comprehensive workspace guide
    • Quick start instructions
    • Development workflows
    • CI/CD integration
    • Best practices

Modified Files

Workspace Configuration Updates

  • src/adguard-validation/Cargo.toml - Simplified to workspace reference
  • src/adguard-api-rust/Cargo.toml - Simplified to workspace reference

Individual Crate Updates (All using workspace dependencies)

  • src/adguard-validation/adguard-validation-core/Cargo.toml
  • src/adguard-validation/adguard-validation-cli/Cargo.toml
  • src/adguard-api-rust/adguard-api-lib/Cargo.toml
  • src/adguard-api-rust/adguard-api-cli/Cargo.toml
  • src/rules-compiler-rust/Cargo.toml

Source Code (Formatting Only)

  • All .rs files formatted with cargo fmt
  • No functional changes
  • Import reordering
  • Consistent style

CI/CD Updates

  • .github/workflows/rust-clippy.yml - Enhanced for workspace
    • Added workspace-level build and test job
    • Added formatting check
    • Added dependency caching
    • Changed from single-project to workspace clippy

Documentation Updates

  • README.md - Added workspace references and updated Rust sections

Benefits

Development Experience

✅ Single command builds: cargo build from root builds everything ✅ Faster builds: Shared build cache reduces compilation time ✅ Consistent tooling: Same Rust version everywhere ✅ Easier dependency updates: Update once, apply to all projects

Code Quality

✅ Unified formatting: cargo fmt --all formats all projects ✅ Consistent linting: Same clippy rules across all projects ✅ Workspace-level lints: Enforce best practices uniformly ✅ Better modularity: Easy to share code between projects

CI/CD

✅ Simpler workflows: One job tests all Rust code ✅ Better caching: Workspace-level dependency caching ✅ Faster CI: Parallel builds and shared cache ✅ Consistent checks: Same standards everywhere

Workspace Structure

ad-blocking/
├── Cargo.toml                                    # Workspace root
├── Cargo.lock                                    # Locked dependencies
├── rust-toolchain.toml                           # Rust 1.83
├── .cargo/
│   └── config.toml                               # Build settings
├── .rustfmt.toml                                 # Formatting
├── clippy.toml                                   # Linting
├── RUST_WORKSPACE.md                             # Documentation
└── src/
    ├── adguard-validation/
    │   ├── adguard-validation-core/              # [Member 1]
    │   │   ├── Cargo.toml
    │   │   └── src/
    │   └── adguard-validation-cli/               # [Member 2]
    │       ├── Cargo.toml
    │       └── src/
    ├── adguard-api-rust/
    │   ├── adguard-api-lib/                      # [Member 3]
    │   │   ├── Cargo.toml
    │   │   └── src/
    │   └── adguard-api-cli/                      # [Member 4]
    │       ├── Cargo.toml
    │       └── src/
    └── rules-compiler-rust/                      # [Member 5]
        ├── Cargo.toml
        └── src/

Build Outputs

Debug Build (cargo build)

  • Target: target/debug/
  • Compilation time: ~35-40 seconds
  • Binary size: Unoptimized

Release Build (cargo build --release)

  • Target: target/release/
  • Compilation time: ~85-90 seconds
  • Binary size: Optimized with LTO

Binaries Produced

  1. adguard-validate (4.5 MB) - Validation CLI
  2. adguard-api-cli (3.7 MB) - API CLI
  3. rules-compiler (1.4 MB) - Rules compiler
  4. libadguard_validation.so (14 KB) - Validation library (FFI)
  5. libadguard_validation.a (56 MB) - Static library
  6. libadguard_api_lib.rlib (4.8 MB) - API library
  7. librules_compiler.rlib (722 KB) - Compiler library

Testing Results

Unit Tests

$ cargo test --workspace
running 25 tests
test result: ok. 25 passed; 0 failed; 0 ignored; 0 measured

Integration Tests

running 1 test
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Doc Tests

running 4 tests  
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured

Total: 30 tests passed

Linting Results

Clippy

$ cargo clippy --workspace --all-features
warning: unused import warnings (5 in adguard-validation-core)
warning: auto-generated code warnings (89 in adguard-api-lib)
Finished successfully

Formatting

$ cargo fmt --all -- --check
No formatting issues found

Migration Guide

For Developers

Before (old way still works):

cd src/rules-compiler-rust
cargo build
cargo test

After (recommended):

# From repository root
cargo build --workspace
cargo test --workspace
cargo build -p rules-compiler

For CI/CD

Before:

- name: Build rules-compiler
  working-directory: ./src/rules-compiler-rust
  run: cargo build

After:

- name: Build all Rust projects
  run: cargo build --workspace

Common Commands

Building

# All projects
cargo build --workspace

# Release mode
cargo build --workspace --release

# Specific project
cargo build -p rules-compiler
cargo build -p adguard-api-cli

Testing

# All tests
cargo test --workspace

# Specific project
cargo test -p rules-compiler

# With output
cargo test --workspace -- --nocapture

Linting

# Check all projects
cargo clippy --workspace --all-features

# Fix issues
cargo clippy --workspace --fix --allow-dirty

Formatting

# Format all
cargo fmt --all

# Check formatting
cargo fmt --all -- --check

Running Binaries

# From root
cargo run -p rules-compiler -- --help
cargo run -p adguard-api-cli -- --version
cargo run -p adguard-validation-cli -- --help

# Release mode
cargo run --release -p rules-compiler -- -c config.yaml

Backward Compatibility

✅ All existing functionality preserved ✅ Individual projects can still be built independently ✅ No changes to binary behavior ✅ Same CLI interfaces ✅ Compatible with existing scripts and workflows

Future Improvements

Potential Enhancements

  • Create shared utilities crate for common code
  • Add workspace-level benchmarks
  • Implement workspace-level examples
  • Add more comprehensive integration tests
  • Create workspace-level documentation generation

Dependency Updates

The workspace makes it easier to:

  • Update dependencies across all projects
  • Identify and remove unused dependencies
  • Track security vulnerabilities
  • Maintain consistent versions

Security

Workspace-Level Security Features

  • unsafe_code = "forbid" - No unsafe code allowed
  • Security scanning in CI/CD (CodeQL, clippy)
  • Dependency auditing capability
  • Locked dependencies for reproducibility

Performance

Build Performance

  • First build: ~90 seconds (release mode)
  • Incremental builds: ~5-10 seconds (unchanged dependencies)
  • Parallel compilation: Enabled by default
  • Shared cache: Reduces redundant compilations

Binary Size

All binaries are optimized with:

  • LTO (Link-Time Optimization)
  • Strip debug symbols
  • Single codegen unit
  • Panic = abort

Conclusion

The Rust workspace modernization provides:

  • ✅ Better developer experience with unified tooling
  • ✅ Improved code quality with consistent standards
  • ✅ Faster CI/CD with better caching
  • ✅ Easier maintenance with centralized configuration
  • ✅ Full backward compatibility with existing workflows

All changes are non-breaking and enhance the project's modularity and maintainability.

Date: December 27, 2025 Rust Version: 1.83.0 Cargo Version: 1.83.0 Total Workspace Members: 5 Total Tests: 30 (all passing)