[llvm] [llvm-objdump] Document selecting symbols containing commas (PR #221619)

Tianyi Chen via llvm-commits llvm-commits at lists.llvm.org
Tue Sep 8 04:47:18 PDT 2026 

https://github.com/chenty2333 updated https://github.com/llvm/llvm-project/pull/221619

>From 72431d5cc762c11e1063e8dfb912d4483870b0b7 Mon Sep 17 00:00:00 2001
From: Tianyi Chen <hi at tychen.cc>
Date: Mon, 7 Sep 2026 08:44:44 +0800
Subject: [PATCH 1/3] [llvm-objdump] Document selecting symbols containing
 commas

Explain that --disassemble-symbols= splits on commas, whereas
--disassemble= accepts a complete symbol name and can be repeated.
Add a demangled C++ example and make this distinction visible in --help.

Cover comma-containing demangled names, repeated --disassemble= options,
and combining them with --disassemble-symbols= in the existing mangling
test. This documents existing behavior from #196594.

Related to #148307.

Assisted-by: OpenAI Codex
---
 llvm/docs/CommandGuide/llvm-objdump.md        | 20 +++++++++++++---
 .../X86/disassemble-functions-mangling.test   | 24 ++++++++++++++++---
 llvm/tools/llvm-objdump/ObjdumpOpts.td        |  6 +++--
 3 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/llvm/docs/CommandGuide/llvm-objdump.md b/llvm/docs/CommandGuide/llvm-objdump.md
index 0e4e5c7181f93..8e0b70ca9e596 100644
--- a/llvm/docs/CommandGuide/llvm-objdump.md
+++ b/llvm/docs/CommandGuide/llvm-objdump.md
@@ -37,12 +37,26 @@ Disassemble all sections found in the input files.
 :::
 
 :::{option} --disassemble-symbols=<symbol1[,symbol2,...]>
-:::
-
-:::{option} --disassemble=symbol1 --disassemble=symbol2 ...
 Disassemble only the specified symbols. Takes demangled symbol names when
 {option}`--demangle` is specified, otherwise takes mangled symbol names.
 Implies {option}`--disassemble`.
+
+Each argument is split on commas. To select a symbol whose name contains commas,
+use `--disassemble=<symbol>` instead.
+:::
+
+:::{option} --disassemble=<symbol>
+Disassemble only the specified symbol. Takes a demangled symbol name when
+{option}`--demangle` is specified, otherwise takes a mangled symbol name.
+Implies {option}`--disassemble`.
+
+The argument is a single symbol name, including any commas. Repeat the option to
+select multiple symbols, for example:
+
+```sh
+llvm-objdump --demangle --disassemble='foo(int, int)' \
+  --disassemble='bar(int, int)' input.o
+```
 :::
 
 :::{option} --dwarf=<value>
diff --git a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
index 8269b4ce322c3..f07c6b36fecb4 100644
--- a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
+++ b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
@@ -1,5 +1,5 @@
-## Show that the --disassemble-symbols switch takes demangled names when
-## --demangle is specified, otherwise the switch takes mangled names.
+## Show that --disassemble-symbols and --disassemble=<symbol> take demangled
+## names when --demangle is specified, otherwise they take mangled names.
 
 # RUN: yaml2obj %s -o %t.o
 
@@ -19,6 +19,15 @@
 # RUN: llvm-objdump -C --disassemble-symbols='std::allocator<wchar_t>::allocator()' %t.o 2>&1 \
 # RUN:   | FileCheck %s --check-prefix=DEMANGLED-MULTI
 
+## --disassemble=<symbol> preserves commas and implies disassembly. It can be
+## repeated or combined with --disassemble-symbols to select multiple symbols.
+# RUN: llvm-objdump -C --disassemble='foo(int, int)' %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=COMMA --implicit-check-not=warning: --implicit-check-not='>:'
+# RUN: llvm-objdump -C --disassemble='foo(int, int)' --disassemble='bar(int, int)' %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefixes=COMMA,SECOND --implicit-check-not=warning: --implicit-check-not='>:'
+# RUN: llvm-objdump -C --disassemble-symbols='foo()' --disassemble='foo(int, int)' %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefixes=DEMANGLED,COMMA --implicit-check-not=warning: --implicit-check-not='>:'
+
 # MANGLED: <_Z3foov>:
 # MANGLED-MISS: warning: '{{.*}}': failed to disassemble missing symbol foo
 
@@ -31,6 +40,9 @@
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 
+# COMMA:  <foo(int, int)>:
+# SECOND: <bar(int, int)>:
+
 --- !ELF
 FileHeader:
   Class:   ELFCLASS64
@@ -42,7 +54,7 @@ Sections:
     Type:  SHT_PROGBITS
     Flags: [SHF_ALLOC, SHF_EXECINSTR]
     Address: 0x1000
-    Content: 9090909090
+    Content: 90909090909090
 Symbols:
   - Name:    _Z3foov
     Value:   0x1000
@@ -59,3 +71,9 @@ Symbols:
   - Name:    _ZNSaIwEC2Ev
     Value:   0x1004
     Section: .text
+  - Name:    _Z3fooii
+    Value:   0x1005
+    Section: .text
+  - Name:    _Z3barii
+    Value:   0x1006
+    Section: .text
diff --git a/llvm/tools/llvm-objdump/ObjdumpOpts.td b/llvm/tools/llvm-objdump/ObjdumpOpts.td
index e22f58236ab9a..c9aadb1c9c7d3 100644
--- a/llvm/tools/llvm-objdump/ObjdumpOpts.td
+++ b/llvm/tools/llvm-objdump/ObjdumpOpts.td
@@ -72,12 +72,14 @@ def traceback_table : Flag<["--"], "traceback-table">,
            "This option is for XCOFF files only">;
 
 def disassemble_symbols_EQ : Joined<["--"], "disassemble-symbols=">,
-  HelpText<"List of symbols to disassemble. "
+  HelpText<"Comma-separated list of symbols to disassemble. "
+           "Use --disassemble=<symbol> for names containing commas. "
            "Accept demangled names when --demangle is "
            "specified, otherwise accept mangled names">;
 
 def disassemble_EQ : Joined<["--"], "disassemble=">,
-  HelpText<"Specify a symbol name to diasassemble. "
+  HelpText<"Disassemble a single symbol, including names containing commas. "
+           "May be repeated. "
            "Accept demangled names when --demangle is "
            "specified, otherwise accept mangled names">;
 

>From 33d331784acc2378afcc408f1f0d4b3142f26b2c Mon Sep 17 00:00:00 2001
From: Tianyi Chen <hi at tychen.cc>
Date: Tue, 8 Sep 2026 12:15:35 +0800
Subject: [PATCH 2/3] [llvm-objdump] Refine symbol-selection documentation and
 tests

Shorten the option descriptions and keep the new tests focused on name matching with and without --demangle.

Assisted-by: OpenAI Codex
---
 llvm/docs/CommandGuide/llvm-objdump.md        | 11 ++----
 .../X86/disassemble-functions-mangling.test   | 34 ++++++++++++-------
 llvm/tools/llvm-objdump/ObjdumpOpts.td        |  5 ++-
 3 files changed, 26 insertions(+), 24 deletions(-)

diff --git a/llvm/docs/CommandGuide/llvm-objdump.md b/llvm/docs/CommandGuide/llvm-objdump.md
index 8e0b70ca9e596..45c0054dd0de9 100644
--- a/llvm/docs/CommandGuide/llvm-objdump.md
+++ b/llvm/docs/CommandGuide/llvm-objdump.md
@@ -42,7 +42,7 @@ Disassemble only the specified symbols. Takes demangled symbol names when
 Implies {option}`--disassemble`.
 
 Each argument is split on commas. To select a symbol whose name contains commas,
-use `--disassemble=<symbol>` instead.
+use {option}`--disassemble` with a symbol argument instead.
 :::
 
 :::{option} --disassemble=<symbol>
@@ -50,13 +50,8 @@ Disassemble only the specified symbol. Takes a demangled symbol name when
 {option}`--demangle` is specified, otherwise takes a mangled symbol name.
 Implies {option}`--disassemble`.
 
-The argument is a single symbol name, including any commas. Repeat the option to
-select multiple symbols, for example:
-
-```sh
-llvm-objdump --demangle --disassemble='foo(int, int)' \
-  --disassemble='bar(int, int)' input.o
-```
+The argument is a single symbol name. To select multiple symbols, specify this
+option multiple times or use {option}`--disassemble-symbols`.
 :::
 
 :::{option} --dwarf=<value>
diff --git a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
index f07c6b36fecb4..331e0ad74cb8b 100644
--- a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
+++ b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
@@ -19,14 +19,22 @@
 # RUN: llvm-objdump -C --disassemble-symbols='std::allocator<wchar_t>::allocator()' %t.o 2>&1 \
 # RUN:   | FileCheck %s --check-prefix=DEMANGLED-MULTI
 
-## --disassemble=<symbol> preserves commas and implies disassembly. It can be
-## repeated or combined with --disassemble-symbols to select multiple symbols.
+## --disassemble=<symbol> without --demangle.
+# RUN: llvm-objdump --disassemble=_Z3fooii %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=MANGLED-COMMA --implicit-check-not=warning: --implicit-check-not='>:'
+# RUN: llvm-objdump --disassemble='foo(int, int)' %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=MANGLED-COMMA-MISS --implicit-check-not=Disassembly
+# RUN: llvm-objdump --disassemble=i %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=PLAIN --implicit-check-not=warning: --implicit-check-not='>:'
+
+## --disassemble=<symbol> with --demangle. Test using a symbol name containing
+## commas, to show that commas are treated as part of the symbol name in this case.
 # RUN: llvm-objdump -C --disassemble='foo(int, int)' %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=COMMA --implicit-check-not=warning: --implicit-check-not='>:'
-# RUN: llvm-objdump -C --disassemble='foo(int, int)' --disassemble='bar(int, int)' %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefixes=COMMA,SECOND --implicit-check-not=warning: --implicit-check-not='>:'
-# RUN: llvm-objdump -C --disassemble-symbols='foo()' --disassemble='foo(int, int)' %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefixes=DEMANGLED,COMMA --implicit-check-not=warning: --implicit-check-not='>:'
+# RUN:   | FileCheck %s --check-prefix=DEMANGLED-COMMA --implicit-check-not=warning: --implicit-check-not='>:'
+# RUN: llvm-objdump -C --disassemble=_Z3fooii %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=DEMANGLED-COMMA-MISS --implicit-check-not=Disassembly
+# RUN: llvm-objdump -C --disassemble=i %t.o 2>&1 \
+# RUN:   | FileCheck %s --check-prefix=PLAIN --implicit-check-not=warning: --implicit-check-not='>:'
 
 # MANGLED: <_Z3foov>:
 # MANGLED-MISS: warning: '{{.*}}': failed to disassemble missing symbol foo
@@ -40,8 +48,11 @@
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 
-# COMMA:  <foo(int, int)>:
-# SECOND: <bar(int, int)>:
+# MANGLED-COMMA: <_Z3fooii>:
+# MANGLED-COMMA-MISS: warning: '{{.*}}': failed to disassemble missing symbol foo(int, int){{$}}
+# DEMANGLED-COMMA: <foo(int, int)>:
+# DEMANGLED-COMMA-MISS: warning: '{{.*}}': failed to disassemble missing symbol _Z3fooii{{$}}
+# PLAIN: <i>:
 
 --- !ELF
 FileHeader:
@@ -54,7 +65,7 @@ Sections:
     Type:  SHT_PROGBITS
     Flags: [SHF_ALLOC, SHF_EXECINSTR]
     Address: 0x1000
-    Content: 90909090909090
+    Content: 909090909090
 Symbols:
   - Name:    _Z3foov
     Value:   0x1000
@@ -74,6 +85,3 @@ Symbols:
   - Name:    _Z3fooii
     Value:   0x1005
     Section: .text
-  - Name:    _Z3barii
-    Value:   0x1006
-    Section: .text
diff --git a/llvm/tools/llvm-objdump/ObjdumpOpts.td b/llvm/tools/llvm-objdump/ObjdumpOpts.td
index c9aadb1c9c7d3..30eb48ef3b42f 100644
--- a/llvm/tools/llvm-objdump/ObjdumpOpts.td
+++ b/llvm/tools/llvm-objdump/ObjdumpOpts.td
@@ -73,13 +73,12 @@ def traceback_table : Flag<["--"], "traceback-table">,
 
 def disassemble_symbols_EQ : Joined<["--"], "disassemble-symbols=">,
   HelpText<"Comma-separated list of symbols to disassemble. "
-           "Use --disassemble=<symbol> for names containing commas. "
            "Accept demangled names when --demangle is "
            "specified, otherwise accept mangled names">;
 
 def disassemble_EQ : Joined<["--"], "disassemble=">,
-  HelpText<"Disassemble a single symbol, including names containing commas. "
-           "May be repeated. "
+  HelpText<"Disassemble a single symbol. "
+           "May be specified multiple times. "
            "Accept demangled names when --demangle is "
            "specified, otherwise accept mangled names">;
 

>From 96723f5a15d1421cea3bd42d1cb971ca20fc53fe Mon Sep 17 00:00:00 2001
From: Tianyi Chen <hi at tychen.cc>
Date: Tue, 8 Sep 2026 19:46:34 +0800
Subject: [PATCH 3/3] [llvm-objdump] Keep symbol-selection update focused on
 documentation

Remove the tests added by this PR, leaving the existing test coverage unchanged.

Assisted-by: OpenAI Codex
---
 .../X86/disassemble-functions-mangling.test   | 32 ++-----------------
 1 file changed, 3 insertions(+), 29 deletions(-)

diff --git a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
index 331e0ad74cb8b..8269b4ce322c3 100644
--- a/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
+++ b/llvm/test/tools/llvm-objdump/X86/disassemble-functions-mangling.test
@@ -1,5 +1,5 @@
-## Show that --disassemble-symbols and --disassemble=<symbol> take demangled
-## names when --demangle is specified, otherwise they take mangled names.
+## Show that the --disassemble-symbols switch takes demangled names when
+## --demangle is specified, otherwise the switch takes mangled names.
 
 # RUN: yaml2obj %s -o %t.o
 
@@ -19,23 +19,6 @@
 # RUN: llvm-objdump -C --disassemble-symbols='std::allocator<wchar_t>::allocator()' %t.o 2>&1 \
 # RUN:   | FileCheck %s --check-prefix=DEMANGLED-MULTI
 
-## --disassemble=<symbol> without --demangle.
-# RUN: llvm-objdump --disassemble=_Z3fooii %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=MANGLED-COMMA --implicit-check-not=warning: --implicit-check-not='>:'
-# RUN: llvm-objdump --disassemble='foo(int, int)' %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=MANGLED-COMMA-MISS --implicit-check-not=Disassembly
-# RUN: llvm-objdump --disassemble=i %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=PLAIN --implicit-check-not=warning: --implicit-check-not='>:'
-
-## --disassemble=<symbol> with --demangle. Test using a symbol name containing
-## commas, to show that commas are treated as part of the symbol name in this case.
-# RUN: llvm-objdump -C --disassemble='foo(int, int)' %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=DEMANGLED-COMMA --implicit-check-not=warning: --implicit-check-not='>:'
-# RUN: llvm-objdump -C --disassemble=_Z3fooii %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=DEMANGLED-COMMA-MISS --implicit-check-not=Disassembly
-# RUN: llvm-objdump -C --disassemble=i %t.o 2>&1 \
-# RUN:   | FileCheck %s --check-prefix=PLAIN --implicit-check-not=warning: --implicit-check-not='>:'
-
 # MANGLED: <_Z3foov>:
 # MANGLED-MISS: warning: '{{.*}}': failed to disassemble missing symbol foo
 
@@ -48,12 +31,6 @@
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 # DEMANGLED-MULTI: <std::allocator<wchar_t>::allocator()>:
 
-# MANGLED-COMMA: <_Z3fooii>:
-# MANGLED-COMMA-MISS: warning: '{{.*}}': failed to disassemble missing symbol foo(int, int){{$}}
-# DEMANGLED-COMMA: <foo(int, int)>:
-# DEMANGLED-COMMA-MISS: warning: '{{.*}}': failed to disassemble missing symbol _Z3fooii{{$}}
-# PLAIN: <i>:
-
 --- !ELF
 FileHeader:
   Class:   ELFCLASS64
@@ -65,7 +42,7 @@ Sections:
     Type:  SHT_PROGBITS
     Flags: [SHF_ALLOC, SHF_EXECINSTR]
     Address: 0x1000
-    Content: 909090909090
+    Content: 9090909090
 Symbols:
   - Name:    _Z3foov
     Value:   0x1000
@@ -82,6 +59,3 @@ Symbols:
   - Name:    _ZNSaIwEC2Ev
     Value:   0x1004
     Section: .text
-  - Name:    _Z3fooii
-    Value:   0x1005
-    Section: .text

More information about the llvm-commits mailing list