From d335d3462072634248712a453a30a7a12255295a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 23 Jun 2025 16:00:55 -0700 Subject: [PATCH 1/6] Unwrap collapse_debuginfo --- src/attributes/debugger.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 10c83a240..97c70e09c 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -155,8 +155,7 @@ 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. r[attributes.debugger.collapse_debuginfo.syntax] The attribute uses the [MetaListIdents] syntax to specify its inputs, and can only be applied to macro definitions. @@ -168,8 +167,7 @@ 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. From c0129863594b1426abd8b94f7dbbb0cf1ffde6a5 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 25 Jun 2025 15:06:05 -0700 Subject: [PATCH 2/6] Move collapse_debuginfo example to the intro and an example block --- src/attributes/debugger.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 97c70e09c..a0df786c4 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -157,6 +157,16 @@ r[attributes.debugger.collapse_debuginfo] 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. +> [!EXAMPLE] +> ```rust +> #[collapse_debuginfo(yes)] +> macro_rules! example { +> () => { +> println!("hello!"); +> }; +> } +> ``` + r[attributes.debugger.collapse_debuginfo.syntax] The attribute uses the [MetaListIdents] syntax to specify its inputs, and can only be applied to macro definitions. @@ -172,13 +182,4 @@ The `external` behavior is the default for macros that don't have this attribute > [!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!"); - }; -} -``` - [attribute]: ../attributes.md From 180ac4e6f6dd3f1b8cb2a6338882ce49dd51436a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 25 Jun 2025 15:31:26 -0700 Subject: [PATCH 3/6] Add a little bit of a description to the example I considered maybe showing actual debugger output to really cement what it is like, but I'm not sure it is worth taking all that space. --- src/attributes/debugger.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index a0df786c4..e15c1f854 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -166,6 +166,12 @@ The *`collapse_debuginfo` [attribute]* controls whether code locations from a ma > }; > } > ``` +> +> 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. + + r[attributes.debugger.collapse_debuginfo.syntax] The attribute uses the [MetaListIdents] syntax to specify its inputs, and can only be applied to macro definitions. From b81139afe8552af2f9f7dda4fab25fe93501b08d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 25 Jun 2025 15:32:20 -0700 Subject: [PATCH 4/6] Add attribute template rules for collapse_debuginfo --- src/attributes/debugger.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index e15c1f854..3cfaaba09 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -174,7 +174,22 @@ The *`collapse_debuginfo` [attribute]* controls whether code locations from a ma 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: @@ -188,4 +203,5 @@ The `external` behavior is the default for macros that don't have this attribute > [!NOTE] > `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. +[`macro_rules` definition]: ../macros-by-example.md [attribute]: ../attributes.md From 73de1912e169d0c3a9908ead7a4e0973491d5b76 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 25 Jun 2025 15:34:56 -0700 Subject: [PATCH 5/6] Linkify collapse-macro-debuginfo arg --- src/attributes/debugger.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 3cfaaba09..6c38af8ea 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -201,7 +201,8 @@ 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`. > [!NOTE] -> `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. +> `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 From 843d11b4c7763c045a82e8138244bffef75abc23 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 20 Aug 2025 06:18:40 +0000 Subject: [PATCH 6/6] Revise `collapse_debuginfo` text --- src/attributes/debugger.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 6c38af8ea..9f4ec5c79 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -151,11 +151,12 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil [Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects [pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html + 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 @@ -167,9 +168,7 @@ The *`collapse_debuginfo` [attribute]* controls whether code locations from a ma > } > ``` > -> 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. +> When using a debugger, invoking the `example` macro may appear as though it is calling a function. That is, when you step to the invocation site, it may show the macro invocation rather than the expanded code. @@ -189,19 +188,20 @@ 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. +The `collapse_debuginfo` attribute may used only once on a macro. r[attributes.debugger.collapse_debuginfo.options] -Accepted options: -- `#[collapse_debuginfo(yes)]` --- code locations in debuginfo are collapsed. -- `#[collapse_debuginfo(no)]` --- code locations in debuginfo are not collapsed. -- `#[collapse_debuginfo(external)]` --- code locations in debuginfo are collapsed only if the macro comes from a different crate. +The `collapse_debuginfo` attribute accepts these options: + +- `#[collapse_debuginfo(yes)]` --- Code locations in debuginfo are collapsed. +- `#[collapse_debuginfo(no)]` --- Code locations in debuginfo are not collapsed. +- `#[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. +> `rustc` has a [`-C collapse-macro-debuginfo`] CLI option to override both the default behavior and the values of any `#[collapse_debuginfo]` attributes. [`-C collapse-macro-debuginfo`]: ../../rustc/codegen-options/index.html#collapse-macro-debuginfo [`macro_rules` definition]: ../macros-by-example.md