#conditional-compilation #cfg #alias #conditional #compilation #build

build cfg_aliases

A tiny utility to help save you a lot of effort with long winded #[cfg()] checks

5 releases

0.2.0 Dec 19, 2023
0.1.1 Oct 20, 2020
0.1.0 Apr 8, 2020
0.1.0-alpha.1 Apr 5, 2020

#55 in Rust patterns

Download history 113900/week @ 2023-12-23 163647/week @ 2023-12-30 218288/week @ 2024-01-06 228202/week @ 2024-01-13 252027/week @ 2024-01-20 265921/week @ 2024-01-27 271272/week @ 2024-02-03 254889/week @ 2024-02-10 274775/week @ 2024-02-17 354906/week @ 2024-02-24 414854/week @ 2024-03-02 444173/week @ 2024-03-09 486239/week @ 2024-03-16 467859/week @ 2024-03-23 501116/week @ 2024-03-30 421297/week @ 2024-04-06

1,952,313 downloads per month
Used in 4,164 crates (65 directly)

MIT license

20KB
201 lines

CFG Aliases

CFG Aliases is a tiny utility to help save you a lot of effort with long winded #[cfg()] checks. This crate provides a single cfg_aliases! macro that doesn't have any dependencies and specifically avoids pulling in syn or quote so that the impact on your comile times should be negligible.

You use the the cfg_aliases! macro in your build.rs script to define aliases such as x11 that could then be used in the cfg attribute or macro for conditional compilation: #[cfg(x11)].

Example

Cargo.toml:

[build-dependencies]
cfg_aliases = "0.1.0"

build.rs:

use cfg_aliases::cfg_aliases;

fn main() {
    // Setup cfg aliases
    cfg_aliases! {
        // Platforms
        wasm: { target_arch = "wasm32" },
        android: { target_os = "android" },
        macos: { target_os = "macos" },
        linux: { target_os = "linux" },
        // Backends
        surfman: { all(unix, feature = "surfman", not(wasm)) },
        glutin: { all(feature = "glutin", not(wasm)) },
        wgl: { all(windows, feature = "wgl", not(wasm)) },
        dummy: { not(any(wasm, glutin, wgl, surfman)) },
    }
}

Now that we have our aliases setup we can use them just like you would expect:

#[cfg(wasm)]
println!("This is running in WASM");

#[cfg(surfman)]
{
    // Do stuff related to surfman
}

#[cfg(dummy)]
println!("We're in dummy mode, specify another feature if you want a smarter app!");

This greatly improves what would otherwise look like this without the aliases:

#[cfg(target_arch = "wasm32")]
println!("We're running in WASM");

#[cfg(all(unix, feature = "surfman", not(target_arch = "wasm32")))]
{
    // Do stuff related to surfman
}

#[cfg(not(any(
    target_arch = "wasm32",
    all(unix, feature = "surfman", not(target_arch = "wasm32")),
    all(windows, feature = "wgl", not(target_arch = "wasm32")),
    all(feature = "glutin", not(target_arch = "wasm32")),
)))]
println!("We're in dummy mode, specify another feature if you want a smarter app!");

You can also use the cfg! macro or combine your aliases with other checks using all(), not(), and any(). Your aliases are genuine cfg flags now!

if cfg!(glutin) {
    // use glutin
} else {
    // Do something else
}

#[cfg(all(glutin, surfman))]
compile_error!("You cannot specify both `glutin` and `surfman` features");

Syntax and Error Messages

The aliase names are restricted to the same rules as rust identifiers which, for one, means that they cannot have dashes ( - ) in them. Additionally, if you get certain syntax elements wrong, such as the alias name, the macro will error saying that the recursion limit was reached instead of giving a clear indication of what actually went wrong. This is due to a nuance with the macro parser and it might be fixed in a later release of this crate. It is also possible that aliases with dashes in the name might be supported in a later release. Open an issue if that is something that you would like implemented.

Finally, you can also induce an infinite recursion by having rules that both reference each-other, but this isn't a real limitation because that doesn't make logical sense anyway:

// This causes an error!
cfg_aliases! {
    test1: { not(test2) },
    test2: { not(test1) },
}

Attribution and Thanks

  • Thanks to my God and Father who led me through figuring this out and to whome I owe everything.
  • Thanks to @Yandros on the Rust forum for showing me some crazy macro hacks!
  • Thanks to @sfackler for pointing out the way to make cargo add the cfg flags.
  • Thanks to the authors of the tectonic_cfg_support::target_cfg macro from which most of the cfg attribute parsing logic is taken from. Also thanks to @ratmice for bringing it up on the Rust forum.

No runtime deps