More in-depth documentation for the new debuginfo options

Author: jdtatz

compiler/rustc_codegen_llvm/src/llvm/ffi.rs

@@ -877,6 +877,16 @@ pub mod debuginfo {
 
     impl DebugEmissionKind {
         pub fn from_generic(kind: rustc_session::config::DebugInfo) -> Self {
+            // We should be setting LLVM's emission kind to `LineTablesOnly` if
+            // we are compiling with "limited" debuginfo. However, some of the
+            // existing tools relied on slightly more debuginfo being generated than
+            // would be the case with `LineTablesOnly`, and we did not want to break
+            // these tools in a "drive-by fix", without a good idea or plan about
+            // what limited debuginfo should exactly look like. So for now we are
+            // instead adding a new debuginfo option "line-tables-only" so as to
+            // not break anything and to allow users to have 'limited' debug info.
+            //
+            // See https://github.com/rust-lang/rust/issues/60020 for details.
             use rustc_session::config::DebugInfo;
             match kind {
                 DebugInfo::None => DebugEmissionKind::NoDebug,

src/doc/rustc/src/codegen-options/index.md

@@ -72,8 +72,8 @@ This flag controls the generation of debug information. It takes one of the
 following values:
 
 * `0` or `none`: no debug info at all (the default).
-* `line-directives-only`: line info directives only.
-* `line-tables-only`: line tables only.
+* `line-directives-only`: line info directives only, (For the nvptx* targets this enables [profiling](https://reviews.llvm.org/D46061), but on other targets the behavior is unspecified).
+* `line-tables-only`: line tables only, (Generates the minimal amount of debug info for backtraces with filename/line number info, but not anything else, i.e. variable or function parameter info).
 * `1` or `limited`: debug info without type information.
 * `2` or `full`: full debug info.
 

src/test/codegen/debug-limited.rs

@@ -1,12 +1,11 @@
 // Verify that the limited debuginfo option emits llvm's FullDebugInfo, but no type info.
 //
-// ignore-windows
 // compile-flags: -C debuginfo=limited
 
 #[repr(C)]
 struct StructType {
     a: i64,
-    b: i32
+    b: i32,
 }
 
 extern "C" {
@@ -16,7 +15,7 @@ extern "C" {
 
 fn main() {
     unsafe {
-        let value: &mut StructType = &mut* creator();
+        let value: &mut StructType = &mut *creator();
         value.a = 7;
         save(value as *const StructType)
     }

src/test/codegen/debug-line-directives-only.rs

@@ -1,12 +1,11 @@
 // Verify that the only debuginfo generated are the line directives.
 //
-// ignore-windows
 // compile-flags: -C debuginfo=line-directives-only
 
 #[repr(C)]
 struct StructType {
     a: i64,
-    b: i32
+    b: i32,
 }
 
 extern "C" {
@@ -16,7 +15,7 @@ extern "C" {
 
 fn main() {
     unsafe {
-        let value: &mut StructType = &mut* creator();
+        let value: &mut StructType = &mut *creator();
         value.a = 7;
         save(value as *const StructType)
     }

src/test/codegen/debug-line-tables-only.rs

@@ -1,12 +1,11 @@
 // Verify that the only debuginfo generated are the line tables.
 //
-// ignore-windows
 // compile-flags: -C debuginfo=line-tables-only
 
 #[repr(C)]
 struct StructType {
     a: i64,
-    b: i32
+    b: i32,
 }
 
 extern "C" {
@@ -16,7 +15,7 @@ extern "C" {
 
 fn main() {
     unsafe {
-        let value: &mut StructType = &mut* creator();
+        let value: &mut StructType = &mut *creator();
         value.a = 7;
         save(value as *const StructType)
     }