Document -Z crate-attr

src/doc/unstable-book/src/compiler-flags/crate-attr.md

@@ -0,0 +1,16 @@
+# `crate-attr`
+
+The tracking issue for this feature is: [#138287](https://github.com./rust-lang/rust/issues/138287).
+
+------------------------
+
+The `-Z crate-attr` flag allows you to inject attributes into the crate root.
+For example, `-Z crate-attr=crate_name="test"` acts as if `#![crate_name="test"]` were present before the first source line of the crate root.
+
+To inject multiple attributes, pass `-Z crate-attr` multiple times.
+
+Formally, the expansion behaves as follows:
+1. The crate is parsed as if `-Z crate-attr` were not present.
+2. The attributes in `-Z crate-attr` are parsed.
+3. The attributes are injected at the top of the crate root.
+4. Macro expansion is performed.

tests/ui/attributes/z-crate-attr/cfg-false.rs

@@ -0,0 +1,7 @@
+// Ensure that `-Z crate-attr=cfg(FALSE)` can comment out the whole crate
+//@ compile-flags: --crate-type=lib -Zcrate-attr=cfg(FALSE)
+//@ check-pass
+
+// NOTE: duplicate items are load-bearing
+fn foo() {}
+fn foo() {}

tests/ui/attributes/z-crate-attr/comments.rs

@@ -0,0 +1,5 @@
+//@ check-pass
+//@ compile-flags: -Zcrate-attr=/*hi-there*/feature(rustc_attrs)
+
+#[rustc_dummy]
+fn main() {}

tests/ui/attributes/z-crate-attr/crate-name.rs

@@ -0,0 +1,6 @@
+// Ensure that `crate_name` and `crate_type` can be set through `-Z crate-attr`.
+//@ check-pass
+//@ compile-flags: -Zcrate-attr=crate_name="override"
+fn main() {
+    assert_eq!(module_path!(), "r#override");
+}

tests/ui/attributes/z-crate-attr/crate-type.rs

@@ -0,0 +1,3 @@
+//@ check-pass
+//@ compile-flags: -Zcrate-attr=crate_type="lib"
+// notice the lack of `main` is load-bearing

tests/ui/attributes/z-crate-attr/garbage.rs

@@ -0,0 +1,4 @@
+// Show diagnostics for invalid tokens
+//@ compile-flags: -Zcrate-attr=`%~@$#
+//@ error-pattern:unknown start of token
+fn main() {}

tests/ui/attributes/z-crate-attr/garbage.stderr

@@ -0,0 +1,20 @@
+error: unknown start of token: `
+  --> <crate attribute>:1:1
+   |
+LL | `%~@$#
+   | ^
+   |
+help: Unicode character '`' (Grave Accent) looks like ''' (Single Quote), but it is not
+   |
+LL - `%~@$#
+LL + '%~@$#
+   |
+
+error: expected identifier, found `%`
+  --> <crate attribute>:1:2
+   |
+LL | `%~@$#
+   |  ^ expected identifier
+
+error: aborting due to 2 previous errors
+

tests/ui/attributes/z-crate-attr/injection.rs

@@ -0,0 +1,3 @@
+//@ compile-flags: '-Zcrate-attr=feature(yeet_expr)]fn main(){}#[inline'
+//@ error-pattern:unexpected closing delimiter
+fn foo() {}

tests/ui/attributes/z-crate-attr/injection.stderr

@@ -0,0 +1,8 @@
+error: unexpected closing delimiter: `]`
+  --> <crate attribute>:1:19
+   |
+LL | feature(yeet_expr)]fn main(){}#[inline
+   |                   ^ unexpected closing delimiter
+
+error: aborting due to 1 previous error
+

tests/ui/attributes/z-crate-attr/inner-attr.rs

@@ -0,0 +1,4 @@
+//@ compile-flags: -Zcrate-attr=#![feature(foo)]
+//@ error-pattern:expected identifier
+
+fn main() {}

tests/ui/attributes/z-crate-attr/inner-attr.stderr

@@ -0,0 +1,8 @@
+error: expected identifier, found `#`
+  --> <crate attribute>:1:1
+   |
+LL | #![feature(foo)]
+   | ^ expected identifier
+
+error: aborting due to 1 previous error
+

tests/ui/attributes/z-crate-attr/multiple.rs

@@ -0,0 +1,3 @@
+//@ compile-flags: -Zcrate-attr=feature(foo),feature(bar)
+//@ error-pattern:invalid crate attr
+fn main() {}

tests/ui/attributes/z-crate-attr/multiple.stderr

@@ -0,0 +1,8 @@
+error: invalid crate attribute
+  --> <crate attribute>:1:1
+   |
+LL | feature(foo),feature(bar)
+   | ^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+

tests/ui/attributes/z-crate-attr/respect-existing-attrs.rs

@@ -0,0 +1,9 @@
+// Make sure that existing root attributes are still respected even when `-Zcrate-attr` is present.
+//@ run-pass
+//@ compile-flags: -Zcrate-attr=feature(rustc_attrs)
+#![crate_name = "override"]
+
+#[rustc_dummy]
+fn main() {
+    assert_eq!(module_path!(), "r#override");
+}

tests/ui/attributes/z-crate-attr/shebang.rs

@@ -0,0 +1,6 @@
+#!/usr/bin/env -S cargo +nightly -Zscript
+// Make sure that shebangs are still allowed even when `-Zcrate-attr` is present.
+//@ check-pass
+//@ compile-flags: -Zcrate-attr=feature(rustc_attrs)
+#[rustc_dummy]
+fn main() {}

tests/ui/attributes/z-crate-attr/unbalanced-paren.rs

@@ -0,0 +1,4 @@
+// Show diagnostics for unbalanced parens.
+//@ compile-flags: -Zcrate-attr=(
+//@ error-pattern:unclosed delimiter
+fn main() {}

tests/ui/attributes/z-crate-attr/unbalanced-paren.stderr

@@ -0,0 +1,10 @@
+error: this file contains an unclosed delimiter
+  --> <crate attribute>:1:2
+   |
+LL | (
+   | -^
+   | |
+   | unclosed delimiter
+
+error: aborting due to 1 previous error
+