Skip to content

Commit 7dcaf5c

Browse files
[docs] Mention useful debugging tools with short blurbs about usage.
Based on Dave Lee's suggestion in: swiftlang#35639 (review)
1 parent bd93de8 commit 7dcaf5c

File tree

1 file changed

+65
-5
lines changed

1 file changed

+65
-5
lines changed

docs/DebuggingTheCompiler.md

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -634,16 +634,76 @@ and `-I /path/to/includedir` to include necessary swift modules and interfaces.
634634

635635
### Working with multi-architecture binaries
636636

637-
In certain cases, one might be looking at multi-architecture binaries,
638-
such as [universal binaries](https://en.wikipedia.org/wiki/Universal_binary).
639-
By default `nm` will show symbols from all architectures, so a universal
640-
binary might look funny due to two copies of everything. Use `nm -arch`
641-
to look at a specific architecture:
637+
On macOS, one might be interested in debugging multi-architecture binaries
638+
such as [universal binaries][]. By default `nm` will show symbols from all
639+
architectures, so a universal binary might look funny due to two copies of
640+
everything. Use `nm -arch` to look at a specific architecture:
642641

643642
```
644643
nm -n -m -arch x86_64 path/to/libcake.dylib | swift demangle
645644
```
646645

646+
[universal binaries]: https://en.wikipedia.org/wiki/Universal_binary
647+
648+
### Other helpful tools
649+
650+
TODO: This section should mention information about non-macOS platforms:
651+
maybe we can have a table with rows for use cases and columns for
652+
platforms (macOS, Linux, Windows), and the cells would be tool names.
653+
We could also mention platforms next to the tool names.
654+
655+
In the previous sub-sections, we've seen how using different tools can
656+
make working with assembly and object code much nicer. Here is a short
657+
listing of commonly used tools on macOS, along with some example use cases:
658+
659+
- Miscellaneous:
660+
- `strings`: Find printable strings in a binary file.
661+
- Potential use cases: If you're building a binary in multiple configurations,
662+
and forgot which binary corresponds to which configuration, you can look
663+
through the output of `strings` to identify differences.
664+
- `c++filt`: The C++ equivalent of `swift-demangle`.
665+
- Potential use cases: Looking at the generated code for the
666+
Swift runtime, investigating C++ interop issues.
667+
668+
- Linking:
669+
- `libtool`: A tool to create static and dynamic libraries. Generally, it's
670+
easier to instead ask `swiftc` to link files, but potentially handy as
671+
a higher-level alternative to `ld`, `ar` and `lipo`.
672+
673+
- Debug info:
674+
- `dwarfdump`: Extract debug info in human-readable form.
675+
- Potential use cases: If you want to quickly check if two binaries
676+
are identical, you can compare their UUIDs. For on-disk binaries,
677+
you can obtain the UUID using `dwarfdump --uuid` For binaries
678+
loaded by a running application, you can obtain the UUID using
679+
`image list` in LLDB.
680+
- `objdump`: Dump object files.
681+
Some examples of using `objdump` are documented in the previous subsection.
682+
If you have a Swift compiler build, you can use `llvm-objdump` from
683+
`$LLVM_BUILD_DIR/bin` instead of using the system `objdump`.
684+
685+
Compared to other tools on this list, `objdump` packs a LOT of
686+
functionality; it can show information about sections, relocations
687+
and more. It also supports many flags to format and filter the output.
688+
689+
- Linker information (symbol table, sections, binding):
690+
- `nm`: Display symbol tables.
691+
Some examples of using `nm` are documented in the previous subsection.
692+
- `size`: Get high-level information about sections in a binary,
693+
such as the sizes of sections and where they are located.
694+
- `dyldinfo`: Display information used by dyld, such as which dylibs
695+
an image depends on.
696+
- `install_name_tool`: Change the name for a dynamic shared library,
697+
and query or modify the runpath search paths (aka 'rpaths') it uses.
698+
699+
- Multi-architecture binaries:
700+
- `lipo`: A tool that can be used to create, inspect and dissect
701+
[universal binaries][universal binaries].
702+
- Potential use cases: If you have a universal binary on an
703+
Apple Silicon Mac, but want to quickly test if the issue would reproduce
704+
on `x86_64`, you can extract the `x86_64` slice by using `lipo`.
705+
The `x86_64` binary will automatically run under Rosetta 2.
706+
647707
## Bisecting Compiler Errors
648708

649709
### Bisecting on SIL optimizer pass counts to identify optimizer bugs

0 commit comments

Comments
 (0)