SkipCode

A lightweight Rust macro library for conditionally skipping code at compile time, compatible with both debug and release builds.

Overview

SkipCode provides compile-time conditional compilation macros that work seamlessly across different build configurations. Unlike traditional #[cfg] attributes, these macros evaluate conditions at compile time while maintaining full type checking and syntax validation.

Features

• Zero-cost abstraction: Skipped code is completely removed during compilation
• Type safe: All code is type checked regardless of whether it's skipped
• Flexible syntax: Supports blocks, single statements, and expressions
• Const evaluation: Conditions are evaluated at compile time using const blocks
• Debug/Release compatible: Works consistently across all build configurations

Installation

Add to your Cargo.toml:

[dependencies]
skipcode = "0.1"

Macros

skip!

Completely skips code blocks or statements at compile time.

use skipcode::skip;

let mut x = 0;

// Block form - completely skipped
skip! {
    x = 10;
    println!("This won't execute");
}
assert_eq!(x, 0);

// Single statement form
skip!(x = 20);
assert_eq!(x, 0);

// Empty block
skip! {};

// Invalid: empty input causes compile error
// skip!();

skip_if!

Conditionally skips code based on a compile-time boolean expression.

use skipcode::skip_if;

let mut x = 0;

// Skip when condition is true
skip_if!(true, {
    x = 30;
    println!("Skipped");
});
assert_eq!(x, 0);

// Execute when condition is false
skip_if!(false, x = 40);
assert_eq!(x, 40);

// With configuration flags
skip_if!(cfg!(debug_assertions), {
    println!("Debug-only code");
});

// Complex const expressions
const DEBUG: bool = true;
skip_if!(!DEBUG, x = 50);

// Empty block allowed
skip_if!(true, {});

Use Cases

1. Development-Only Code

skip_if!(cfg!(debug_assertions), {
    // Expensive validation only in debug builds
    validate_invariants();
    log_debug_info();
});

2. Feature Flags

const ENABLE_EXPERIMENTAL: bool = false;

skip_if!(ENABLE_EXPERIMENTAL, {
    use_new_algorithm();
});

3. Platform-Specific Code

#[cfg(target_os = "windows")]
const IS_WINDOWS: bool = true;
#[cfg(not(target_os = "windows"))]
const IS_WINDOWS: bool = false;

skip_if!(IS_WINDOWS, {
    windows_specific_setup();
});

4. Conditional Testing

#[test]
fn test_optional_feature() {
    skip_if!(!ENABLE_FEATURE_X, {
        // Tests that only run when feature is enabled
        assert!(feature_x_works());
    });
}

How It Works

The macros use Rust's const blocks to evaluate conditions at compile time. When a condition is true:

• For skip!: The code is replaced with #[allow(unused)] ()
• For skip_if!: The code branch is replaced with an empty expression

This ensures that:

1. Skipped code is completely removed from the final binary
2. All code is still parsed and type checked
3. No runtime overhead is introduced

Error Messages

The macros provide helpful compile-time errors:

skip_if!(true,);  // Error: skip_if!(): missing code after comma
skip_if!();       // Error: skip_if!(): invalid empty input
skip_if!(true, ()); // Error: skip_if!(): empty statement

Testing

The library includes comprehensive tests:

cargo test

Tests verify that:

• Skipped code doesn't execute
• Non-skipped code executes normally
• Type checking works correctly
• Compile errors are triggered appropriately

Limitations

• Conditions must be compile-time evaluable (const expressions)
• Can't skip entire function definitions (use #[cfg] instead)
• The skipped code must still be syntactically valid Rust

Performance

Zero runtime overhead. All skipping happens during compilation, resulting in the same binary as if the code was never written.

Safety

This crate is #![no_std] compatible and contains no unsafe code.

License

Licensed under either of:

• MIT license: http://opensource.org/licenses/MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate shall be dual-licensed as above, without any additional terms or conditions.

Version Compatibility

• Version 0.1.x: Initial release
• MSRV: Rust 1.56+ (due to const block usage)

Related Crates

• cfg-if: Traditional cfg-based conditional compilation
• const_format: Compile-time string formatting

Examples

See the examples/ directory for complete working examples:

cargo run --example development
cargo run --example features