specify how `#![cfg(...)]` works differently in the crate root versus anywhere else

Open
#103 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
rust
Domain
documentation

Research direction

Start by reading the linked Rust issues and the current Conditional Compilation documentation, including the older first-edition page mentioned in the issue. Confirm how an inner cfg attribute behaves at the crate root versus inside a module or other item. Done means the Reference clearly documents this distinction and explains the crate-root and non-root outcomes.

Written by the indexing model from the issue text.

Description

A-attributes E-Easy New Content

This is a port of https://github.com/rust-lang/rust/issues/34968.

Spawned off of https://github.com/rust-lang/rust/issues/34932#issuecomment-234397781

If you put the inner attribute #![cfg(..)] at a crate root, this (apparently) causes an empty crate to be generated. I.e., it is as if the crate itself still exists, but all of its contents have disappeared.

This is slightly different than the behavior of #![cfg(..)] elsewhere (e.g. in a mod item), where such an inner attribute will cause the whole item to be omitted from the AST, rather than just causing the contents of the item to be omitted.

I don't see any mention of this corner case in the Rust documentation for Conditional Compilation, here: https://doc.rust-lang.org/book/first-edition/conditional-compilation.html

Since the second edition of the book doesn't have a dedicated section to conditional compilation, it would be worth elaborating on it here. Whether or not that includes porting some of that discussion out is another matter. This issue was more about how an inner cfg attribute creates an empty crate when used in the crate root, but removes the item entirely if used anywhere else. (This is what winapi does to only build on windows, for example.)

Dominant language
Rust
Stars
1.6k
Forks
607
Avg merge
1d 1h
Merged PRs (30d)
12

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rust-lang/reference

All issues in rust-lang/reference

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.