rust-queries-builder 1.0.7

# Build Optimization Guide

## Crate Structure (v0.5.0+)

The Rust Query Builder is split into three crates for optimal build times and binary sizes:

### Crate Organization

```
rust-queries-builder (umbrella crate, 6KB)
├── rust-queries-core (core functionality, 251KB rlib)
│   ├── Query, LazyQuery, JoinQuery
│   ├── QueryExt extension trait
│   ├── Queryable trait
│   └── Helper macros
└── rust-queries-derive (proc macros)
    ├── #[derive(QueryBuilder)]
    └── #[derive(Queryable)]
```

### Benefits of This Structure

#### 1. **Reduced Binary Size**

The umbrella crate (`rust-queries-builder`) is just **6.1KB** and only re-exports from core.

**Why this matters:**
- If you only need core functionality (no derive macros), depend on `rust-queries-core`
- Saves ~250KB by not including proc-macro infrastructure
- Faster compilation when derive macros aren't needed

#### 2. **Faster Compilation**

Proc macros require extra compiler infrastructure and slow down builds.

**Compilation time comparison:**

| Crate | Clean Build | Incremental |
|-------|-------------|-------------|
| rust-queries-core only | 1.2s | 0.3s |
| rust-queries-builder (all) | 3.5s | 0.6s |

**Savings:** ~65% faster builds without proc macros!

#### 3. **Flexible Dependencies**

Choose what you need:

```toml
# Option 1: Full featured (most convenient)
[dependencies]
rust-queries-builder = "0.5.0"
key-paths-derive = "0.5.0"

# Option 2: Core only (minimal, faster builds)
[dependencies]
rust-queries-core = "0.5.0"
key-paths-derive = "0.5.0"  # Still needed for Keypaths

# Option 3: With derive macros but explicit
[dependencies]
rust-queries-core = "0.5.0"
rust-queries-derive = "0.5.0"
key-paths-derive = "0.5.0"
```

## Usage Examples

### Using the Umbrella Crate (Recommended)

```rust
use rust_queries_builder::{Query, QueryExt, QueryBuilder};
use key_paths_derive::Keypaths;

#[derive(Keypaths, QueryBuilder)]
struct Product {
    name: String,
    price: f64,
}

let products = vec![/* ... */];

// All features available
let query = products.query().where_(...);
let lazy = Product::lazy_query(&products);
```

### Using Core Only (Minimal)

```rust
use rust_queries_core::{Query, LazyQuery, QueryExt};
use key_paths_derive::Keypaths;

#[derive(Keypaths)]  // No QueryBuilder derive
struct Product {
    name: String,
    price: f64,
}

let products = vec![/* ... */];

// Core features work fine
let query = products.query().where_(...);
let lazy = products.lazy_query().where_(...);
```

**When to use core only:**
- Building libraries that don't need derive macros
- Optimizing for minimal dependencies
- Faster CI/CD builds

## Binary Size Comparison

### Example Binary Sizes (release mode)

| Configuration | Binary Size | Reduction |
|---------------|-------------|-----------|
| Full (with derives) | 451KB | baseline |
| Core only | ~380KB | -16% |
| Stripped binary | ~350KB | -22% |

**Note:** Sizes include key-paths-core and standard library. Actual savings depend on your application.

### Optimizing Binary Size

#### 1. Enable LTO (Link Time Optimization)

```toml
[profile.release]
lto = true
codegen-units = 1
strip = true  # Remove debug symbols
```

**Result:** ~30% smaller binaries!

#### 2. Use Core-Only Build

```toml
[dependencies]
rust-queries-core = "0.5.0"  # Not the full builder
```

**Result:** ~15% faster builds, 16% smaller binaries

#### 3. Use `cargo-bloat` to Analyze

```bash
cargo install cargo-bloat
cargo bloat --release --example derive_and_ext
```

This shows exactly what's taking up space in your binary.

## Compilation Performance

### Benchmarks (MacBook Pro M1)

#### Cold Build (after `cargo clean`)

```bash
# Full builder
time cargo build --release
# real    0m3.543s

# Core only
cd rust-queries-core && time cargo build --release
# real    0m1.234s
```

**65% faster without proc macros!**

#### Incremental Build (single file change)

```bash
# Full builder
# real    0m0.612s

# Core only
# real    0m0.298s
```

**51% faster incremental builds!**

### CI/CD Optimization

For faster CI/CD:

```yaml
# .github/workflows/ci.yml
- name: Build core only (fast check)
  run: cargo build --package rust-queries-core --release

- name: Build examples (full check)
  run: cargo build --release --examples
```

**Benefit:** Core builds in ~1.2s, catching most issues quickly!

## Dependency Graph

### Visual Dependency Tree

```
┌─────────────────────────┐
│ rust-queries-builder    │ (umbrella, re-exports)
│      6.1 KB rlib        │
└───────────┬─────────────┘
            │
    ┌───────┴────────┐
    │                │
    ▼                ▼
┌───────────────┐  ┌──────────────────┐
│ rust-queries- │  │ rust-queries-    │
│    core       │  │    derive        │
│  251 KB rlib  │  │  (proc-macro)    │
└───────┬───────┘  └──────────────────┘
        │
        ▼
┌─────────────────┐
│ key-paths-core  │
│  178 KB rlib    │
└─────────────────┘
```

### Dependency Rationale

**Why not merge core with builder?**
- Proc macros force entire crate to be rebuilt on any change
- Separating allows faster incremental builds
- Users can choose minimal dependencies

**Why not merge derive with builder?**
- Proc macros have special build requirements
- Separating follows Rust ecosystem conventions (serde, tokio, etc.)
- Allows independent versioning if needed

## Recommendations

### For Applications

Use the full `rust-queries-builder` for convenience:
```toml
[dependencies]
rust-queries-builder = "0.5.0"
```

**Why:** All features available, negligible size impact for end-user apps

### For Libraries

Consider using core only:
```toml
[dependencies]
rust-queries-core = "0.5.0"
```

**Why:** Fewer dependencies, faster builds, users can add derives if needed

### For CLI Tools

Use core + optimize profile:
```toml
[dependencies]
rust-queries-core = "0.5.0"

[profile.release]
lto = true
strip = true
```

**Why:** Smallest binary size, fastest runtime

## Future Optimizations (v0.6.0+)

Planned improvements:

1. **Feature flags** for optional functionality:
   ```toml
   rust-queries-core = { version = "0.6.0", default-features = false }
   ```

2. **No-std support** for embedded systems:
   ```toml
   rust-queries-core = { version = "0.6.0", features = ["no-std"] }
   ```

3. **Smaller key-paths alternative** for minimal builds

## Summary

The new three-crate structure provides:
- ✅ **6KB** umbrella crate (was 102KB monolithic)
- ✅ **65% faster** builds without proc macros
- ✅ **16% smaller** binaries when using core only
- ✅ Flexible dependency options
- ✅ Better incremental compilation

**Migration:** Zero changes needed! The umbrella crate re-exports everything.

---

**Version:** 0.5.0  
**Last Updated:** October 12, 2025