What does #[cfg(test)] do when placed at the top of lib.rs?

Question

I'm writing a Rust library (generated from cargo) with unit tests.

I'd like to use the extern crate maplit in my unit tests to be able to use JavaScript-like hashmap literals. I don't want to use maplit in my library code.

maplit provides a macro that apparently must be activated using #[macro_use]. The only way I've been able to get this all working is to place this at the top of lib.rs:

#[cfg(test)] #[macro_use] extern crate maplit;

// my crate-specific stuff

At this point I realized I don't know what exactly #[cfg(test)] does. I'm using it in my tests. These are included with library code, as per the convention, like so:

// some library code

#[cfg(test)]
mod test {
  use super::*;
  // tests here
}

I had thought that the line #[cfg(test)] was marking what follows until the end of the file (or block?) as only applicable to the test configuration.

If so, then putting this directive at the top of lib.rs seems like a problem. Won't my entire library be dropped when I compile a distribution?

I've tried to find documentation on what exactly #[cfg(test)] does, but to no avail.

Answer 1

#[....]

The above is a Rust Attribute which is like an annotation in other languages. For example; in Java we have @Annotation(....) for methods and classes. Unlike annotation the rust attribute can be an expression that follows the attribute syntax.

#[cfg(....)]

The above is a compiler configuration attribute. The cfg() is one of many built-in attributes.

#[cfg(test)]

The above tells the Rust compiler that the following code should only be compiled when the test configuration is active. You can have other configuration attributes like debug, windows or features.

#[cfg(test)] #[macro_use] extern crate maplit;

Is the same as

#[cfg(test)]
#[macro_use]
extern crate maplit;

Which tells the Rust compiler to only compile the next line if the test configuration is active, and the next line tells Rust to only use macros from the following crate.

If so, then putting this directive at the top of lib.rs seems like a problem. Won't my entire library be dropped when I compile a distribution?

The #[cfg(...)] attribute only applies the compiler condition upon the thing it is attached to.

When you place the attribute at the top of the file followed by a space. The attribute is attached to the current module or crate.

As shown here from the documentation example, the crate_type is applied to the entire file:

// General metadata applied to the enclosing module or crate.
#![crate_type = "lib"]

// A function marked as a unit test
#[test]
fn test_foo() {
    /* ... */
}

// A conditionally-compiled module
#[cfg(target_os = "linux")]
mod bar {
    /* ... */
}

// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
type int8_t = i8;

// Inner attribute applies to the entire function.
fn some_unused_variables() {
  #![allow(unused_variables)]

  let x = ();
  let y = ();
  let z = ();
}