From 0bf5d4e44c5f55092dfabb0f7b7f1a03352a4fe8 Mon Sep 17 00:00:00 2001 From: Vadim Petrochenkov Date: Tue, 13 Feb 2024 16:26:42 +0300 Subject: [PATCH 1/7] Add docs for `#[collapse_debuginfo]` attribute --- src/attributes/debugger.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 6ea80221e..468a1b2cf 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -139,3 +139,26 @@ 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 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax + +## The `collapse_debuginfo` attribute + +This attribute controls whether code locations from this macro definition are collapsed into a +single location associated with the macro's call site, when generating debuginfo for code calling +this macro. + +The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to +macro definitions. + +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 `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`. + +Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from +command line using the `-C collapse-macro-debuginfo` option. + +[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From bb166095d19e4f7906d30a07e552917da6c047d1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:16:23 -0800 Subject: [PATCH 2/7] Use standard template introducing an attribute. --- 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 468a1b2cf..6b2eef6e5 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -142,7 +142,7 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil ## The `collapse_debuginfo` attribute -This attribute controls whether code locations from this macro definition are collapsed into a +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. @@ -161,4 +161,5 @@ built-in macros. For built-in macros the default is `yes`. Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from command line using the `-C collapse-macro-debuginfo` option. +[attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From 224b6c5306b6141e2bd0020de155bb272cfd1e5b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:16:40 -0800 Subject: [PATCH 3/7] Use em-dash separator --- src/attributes/debugger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 6b2eef6e5..f92db1e1d 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -150,9 +150,9 @@ The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can macro definitions. 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 +- `#[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 `external` behavior is the default for macros that don't have this attribute, unless they are From 4e9c91f0ec870e69242505e1692875e993f1a96c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:17:29 -0800 Subject: [PATCH 4/7] Place `rustc` behavior in a side note. Generally the reference tries to stay focused on the language, and only provide implementation notes as side-information. --- src/attributes/debugger.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index f92db1e1d..b1dec97ef 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -158,8 +158,7 @@ Accepted options: 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`. -Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from -command line using the `-C collapse-macro-debuginfo` option. +> **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. [attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From 860fe4acc154f788189910a01b0b3db108e1dbe7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:18:40 -0800 Subject: [PATCH 5/7] Use semantic line wrapping. --- src/attributes/debugger.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index b1dec97ef..60dc16b6a 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -142,21 +142,18 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil ## The `collapse_debuginfo` attribute -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. -The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to -macro definitions. +The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to macro definitions. 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. +- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro comes from a different crate. -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 c495b9660f6d8c1d6753cf2271dbfd54cc5acd9c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:21:12 -0800 Subject: [PATCH 6/7] Link `collapse_debuginfo` in the index of built-in attributes. --- src/attributes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/attributes.md b/src/attributes.md index a1ad5c60c..b3879d46f 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -273,6 +273,7 @@ The following is an index of all built-in attributes. added in future. - Debugger - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type. + - [`collapse_debuginfo`] — Controls how macro invocations are encoded in debuginfo. [Doc comments]: comments.md#doc-comments [ECMA-334]: https://www.ecma-international.org/publications-and-standards/standards/ecma-334/ @@ -291,6 +292,7 @@ The following is an index of all built-in attributes. [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute [`cfg`]: conditional-compilation.md#the-cfg-attribute [`cold`]: attributes/codegen.md#the-cold-attribute +[`collapse_debuginfo`]: attributes/debugger.md#the-collapse_debuginfo-attribute [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute [`crate_type`]: linkage.md [`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute From 2d51a2aec405dd54a617f5ee1b27cef326f30ced Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 27 Apr 2024 10:53:08 -0700 Subject: [PATCH 7/7] Add an example of collapse_debuginfo --- src/attributes/debugger.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 60dc16b6a..6d184e87e 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -157,5 +157,14 @@ 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!"); + }; +} +``` + [attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax