Skip to content

Update collapse_debuginfo to use the attribute template #1923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Update collapse_debuginfo to use the attribute template #1923

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6efaee6
Unwrap collapse_debuginfo
ehuss Jun 23, 2025
1afc3a3
Move collapse_debuginfo example to the intro and an example block
ehuss Jun 25, 2025
ef4295a
Add a little bit of a description to the example
ehuss Jun 25, 2025
6542139
Add attribute template rules for collapse_debuginfo
ehuss Jun 25, 2025
875bee6
Linkify collapse-macro-debuginfo arg
ehuss Jun 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 37 additions & 15 deletions src/attributes/debugger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,11 +155,41 @@ r[attributes.debugger.collapse_debuginfo]
## The `collapse_debuginfo` attribute

r[attributes.debugger.collapse_debuginfo.intro]
The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site,
when generating debuginfo for code calling this macro.
The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site, when generating debuginfo for code calling this macro.

> [!EXAMPLE]
> ```rust
> #[collapse_debuginfo(yes)]
> macro_rules! example {
> () => {
> println!("hello!");
> };
> }
> ```
>
> When using a debugger, invoking the `example` macro may appear like it is calling a function. That is, when you step to the invocation site, it may show the macro invocation as the next instruction.
>
> Without the `collapse_debuginfo` attribute, the invocation site may behave as-if the macro is expanded in place.

<!-- TODO: I think it would be nice to extend this to explain a little more about why this is useful, and the kinds of scenarios where you would want one vs the other. See https://github.com/rust-lang/rfcs/pull/2117 for some guidance. -->

r[attributes.debugger.collapse_debuginfo.syntax]
The attribute uses the [MetaListIdents] syntax to specify its inputs, and can only be applied to macro definitions.
The syntax for the `collapse_debuginfo` attribute is:

```grammar,attributes
@root CollapseDebuginfoAttribute -> `collapse_debuginfo` `(` CollapseDebuginfoOption `)`

CollapseDebuginfoOption ->
`yes`
| `no`
| `external`
```

r[attributes.debugger.collapse_debuginfo.allowed-positions]
The `collapse_debuginfo` attribute may only be applied to a [`macro_rules` definition].

r[attributes.debugger.collapse_debuginfo.duplicates]
The `collapse_debuginfo` attribute may only be specified once on a macro.

r[attributes.debugger.collapse_debuginfo.options]
Accepted options:
Expand All @@ -168,19 +198,11 @@ Accepted options:
- `#[collapse_debuginfo(external)]` --- code locations in debuginfo are collapsed only if the macro comes from a different crate.

r[attributes.debugger.collapse_debuginfo.default]
The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros.
For built-in macros the default is `yes`.
The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros. For built-in macros the default is `yes`.

> [!NOTE]
> `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes.

```rust
#[collapse_debuginfo(yes)]
macro_rules! example {
() => {
println!("hello!");
};
}
```
> `rustc` has a [`-C collapse-macro-debuginfo`] CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes.

[`-C collapse-macro-debuginfo`]: ../../rustc/codegen-options/index.html#collapse-macro-debuginfo
[`macro_rules` definition]: ../macros-by-example.md
[attribute]: ../attributes.md