Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 3d042d4

Browse files
jieyouxuehuss
andauthored
Update //@ proc-macro aux build directive docs (#2149)
Co-authored-by: Eric Huss <eric@huss.org>
1 parent 220aaee commit 3d042d4

File tree

2 files changed

+46
-25
lines changed

2 files changed

+46
-25
lines changed

‎src/tests/compiletest.md‎

Lines changed: 42 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -572,6 +572,7 @@ There are multiple [directives](directives.md) to assist with that:
572572
- `aux-crate`
573573
- `aux-bin`
574574
- `aux-codegen-backend`
575+
- `proc-macro`
575576

576577
`aux-build` will build a separate crate from the named source file. The source
577578
file should be in a directory called `auxiliary` beside the test file.
@@ -604,44 +605,60 @@ for tests in `tests/ui-fulldeps`, since it requires the use of compiler crates.
604605

605606
### Auxiliary proc-macro
606607

607-
If you want a proc-macro dependency, then there currently is some ceremony
608-
needed.
608+
If you want a proc-macro dependency, then you can use the `proc-macro`
609+
directive. This directive behaves just like `aux-build`, i.e. that you should
610+
place the proc-macro test auxiliary file under a `auxiliary` folder under the
611+
same parent folder as the main test file. However, it also has four additional
612+
preset behavior compared to `aux-build` for the proc-macro test auxiliary:
613+
614+
1. The aux test file is built with `--crate-type=proc-macro`.
615+
2. The aux test file is built without `-C prefer-dynamic`, i.e. it will not try
616+
to produce a dylib for the aux crate.
617+
3. The aux crate is made available to the test file via extern prelude with
618+
`--extern <aux_crate_name>`. Note that since UI tests default to edition
619+
2015, you still need to specify `extern <aux_crate_name>` unless the main
620+
test file is using an edition that is 2018 or newer if you want to use the
621+
aux crate name in a `use` import.
622+
4. The `proc_macro` crate is made available as an extern prelude module. Same
623+
edition 2015 vs newer edition distinction for `extern proc_macro;` applies.
624+
625+
For example, you might have a test `tests/ui/cat/meow.rs` and proc-macro
626+
auxiliary `tests/ui/cat/auxiliary/whiskers.rs`:
609627

610-
Place the proc-macro itself in a file like `auxiliary/my-proc-macro.rs` with the
611-
following structure:
628+
```text
629+
tests/ui/cat/
630+
meow.rs # main test file
631+
auxiliary/whiskers.rs # auxiliary
632+
```
612633

613-
```rust,ignore
614-
//@ force-host
615-
//@ no-prefer-dynamic
634+
```rs
635+
// tests/ui/cat/meow.rs
616636

617-
#![crate_type = "proc-macro"]
637+
//@ proc-macro: whiskers.rs
618638

619-
extern crate proc_macro;
620-
use proc_macro::TokenStream;
639+
extern crate whiskers; // needed as ui test defaults to edition 2015
621640

622-
#[proc_macro]
623-
pub fn foo(input: TokenStream) -> TokenStream {
624-
"".parse().unwrap()
641+
fn main() {
642+
whiskers::identity!();
625643
}
626644
```
627645

628-
The `force-host` is needed because proc-macros are loaded in the host compiler,
629-
and `no-prefer-dynamic` is needed to tell compiletest to not use
630-
`prefer-dynamic` which is not compatible with proc-macros. The `#![crate_type]`
631-
attribute is needed to specify the correct crate-type.
646+
```rs
647+
// tests/ui/cat/auxiliary/whiskers.rs
632648

633-
Then in your test, you can build with `aux-build`:
634-
635-
```rust,ignore
636-
//@ aux-build: my-proc-macro.rs
637-
638-
extern crate my_proc_macro;
649+
extern crate proc_macro;
650+
use proc_macro::*;
639651

640-
fn main() {
641-
my_proc_macro::foo!();
652+
#[proc_macro]
653+
pub fn identity(ts: TokenStream) -> TokenStream {
654+
ts
642655
}
643656
```
644657

658+
> **Note**: The `proc-macro` header currently does not work with the
659+
> `build-aux-doc` header for rustdoc tests. In that case, you will need to use
660+
> the `aux-build` header, and use `#![crate_type="proc_macro"]`, and `//@
661+
> force-host` and `//@ no-prefer-dynamic` headers in the proc-macro.
645662
646663
## Revisions
647664

‎src/tests/directives.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,12 @@ not be exhaustive. Directives can generally be found by browsing the
5858
| `aux-build` | Build a separate crate from the named source file | All except `run-make` | Path to auxiliary `.rs` file |
5959
| `aux-crate` | Like `aux-build` but makes available as extern prelude | All except `run-make` | `<extern_prelude_name>=<path/to/aux/file.rs>` |
6060
| `aux-codegen-backend` | Similar to `aux-build` but pass the compiled dylib to `-Zcodegen-backend` when building the main file | `ui-fulldeps` | Path to codegen backend file |
61+
| `proc-macro` | Similar to `aux-build`, but for aux forces host and don't use `-Cprefer-dynamic`[^pm]. | All except `run-make` | Path to auxiliary proc-macro `.rs` file |
6162
| `build_aux_docs` | Build docs for auxiliaries as well | All except `run-make` | N/A |
6263

64+
[^pm]: please see the Auxiliary proc-macro section in the
65+
[compiletest](./compiletest.md) chapter for specifics.
66+
6367
### Controlling outcome expectations
6468

6569
See [Controlling pass/fail

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /