[Debugging] Add lldb data formatter for RigidArray by kastiglione · Pull Request #607 · apple/swift-collections

kastiglione · 2026-03-19T01:43:46Z

This introduces a debugging data formatter for RigidArray using a new feature of LLDB: Formatter Bytecode. The scope of this PR is a single initial data type, with the short and long term plan being to support all types vended by Swift Collections.

The bytecode for this implementation is produced using a Python -> Formatter Bytecode compiler, contained in the formatter_bytecode module.

The workflow for authoring and shipping the formatter is:

Update RigidArray.py as needed
Compile RigidArray.py to RigidArray+Formatter.swift (again, formatter_bytecode)
Compile RigidArray+Formatter.swift as part of the BasicContainers module

By including the bytecode in the binary, lldb can load RigidArray's data formatter automatically, without any friction that comes with installation, setup, config, updating, or versioning.

This introduces a debugging data formatter for RigidArray using a new feature of LLDB: [Formatter Bytecode][1]. The scope of this PR is a single initial data type, with the short and long term plan being to support all types vended by Swift Collections. The bytecode for this implementation is produced using a Python -> Formatter Bytecode compiler, contained in the [`formatter_bytecode`][2] module. The workflow for authoring and shipping the formatter is: 1. Update RigidArray.py as needed 2. Compile RigidArray.py to RigidArray+Formatter.swift (again, `formatter_bytecode`) 3. Compile RigidArray+Formatter.swift as part of the BasicContainers module By including the bytecode in the binary, lldb can load RigidArray's data formatter automatically, without any friction that comes with installation, setup, config, updating, or versioning. [1]: https://lldb.llvm.org/resources/formatterbytecode.html [2]: https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/formatter_bytecode.py

kastiglione · 2026-03-19T02:14:15Z

Draft mode until completion of the following:

Add script to invoke compilation of Python formatters to formatter bytecode
Add separate lldb integration test for verifying the formatter works as expected

To manage the scope of this first PR, I'm leaving the following desirable features for future followups:

A SPM plugin that generates the formatter sources on the fly, so that they don't have to be checked into the project
Running the formatter verification tests in CI

adrian-prantl · 2026-03-19T04:33:27Z

Sources/BasicContainers/RigidArray/RigidArray+Formatter.swift

@@ -0,0 +1,38 @@
+#if swift(>=6.3)


What do you think about adding either a comment at the top of this file with instructions for how to regenerate it from the python source?
I guess that could even be a feature of the compiler script...

A comment is now added as part of the new generate_formatters.sh script.

benrimmington · 2026-03-28T18:27:55Z

Sources/BasicContainers/RigidArray/RigidArray+Formatter.swift

+#if os(macOS) || os(iOS) || os(watchOS) || os(tvOS) || os(visionOS)
+@section("__DATA_CONST,__lldbformatters")
+#else
+@section(".lldbformatters")
+#endif


Should this be using:

#if objectFormat(…) from SE-0492 — with section names for MachO, ELF, COFF, and Wasm?

#if os(anyAppleOS) when using a Swift 6.4 compiler?

TIL I learned about these. Thank you. I will update it accordingly.

benrimmington · 2026-03-28T18:31:09Z

Sources/BasicContainers/RigidArray/RigidArray+Formatter.swift

+@used
+let __BasicContainers___RigidArray______formatter: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8) = (


Could this use a raw identifier from SE-0451, instead of the replacement underscores?

I was also going to ask about using an InlineArray literal, but then I found your previous discussion.

I will look into whether it would be feasible to allow InlineArray to be used in the future as a constant.

A raw identifier is another good suggestion. The name of this is irrelevant to lldb.

@benrimmington

Following feedback from @benrimmington in apple/swift-collections#607, this changes the following: 1. Uses `objectFormat()` compiler conditional instead of `os()` (see "Cross-platform object file format support" in [SE-0492](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0492-section-control.md#cross-platform-object-file-format-support)) 2. Uses a raw identifier for the generated Swift symbol name, instead of an escaped name (see [SE-0451](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0451-escaped-identifiers.md))

@benrimmington

…(#189425) Following feedback from @benrimmington in apple/swift-collections#607, this changes the following: 1. Uses `objectFormat()` compiler conditional instead of `os()` (see "Cross-platform object file format support" in [SE-0492](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0492-section-control.md#cross-platform-object-file-format-support)) 2. Uses a raw identifier for the generated Swift symbol name, instead of an escaped name (see [SE-0451](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0451-escaped-identifiers.md))

lorentey · 2026-03-31T17:58:31Z

Utils/Debugger/HEADER.swift

+//
+// This source file is part of the Swift Collections open source project
+//
+// Copyright (c) 2024 - 2026 Apple Inc. and the Swift project authors


Suggested change

// Copyright (c) 2024 - 2026 Apple Inc. and the Swift project authors

// Copyright (c) 2026 Apple Inc. and the Swift project authors

lorentey · 2026-03-31T18:06:11Z

Sources/BasicContainers/RigidArray/RigidArray+Formatter.swift

+@section(".lldbformatters")
+#endif
+@used
+let `^BasicContainers[.]RigidArray<.+>$ formatter`: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8) = (


This will fail to work in single-module mode (COLLECTIONS_SINGLE_MODULE), where the sources are combined into a single module. (The Xcode project inside Xcode is a good way to exercise that. The module name in that configuration is Collections in this repo, but we edit that when we build for adopters inside Apple OSes.)

We could surround the template with #if !COLLECTIONS_SINGLE_MODULE, but that would make debugging code less pleasant for OS engineers, so the right move is probably to duplicate this:

#if COLLECTIONS_SINGLE_MODULE ... let `^BasicContainers[.]RigidArray<.+>$ formatter`: ... = ... #else ... let `^Collections[.]RigidArray<.+>$ formatter`: ... = ... #endif

That's yucky, but it works. (I don't think we can do #if conditions just around the symbol name... 😞

We could put the set of known module names into the regex:

^(BasicContainers|Collections)[.]RigidArray<.+>$

We've discussed having the module name be implicit, but I don't yet know if that's doable in practice.

That's a much better solution! 👍

lorentey · 2026-03-31T18:11:27Z

Utils/Debugger/Formatters/RigidArray.py

+##
+## This source file is part of the Swift Collections open source project
+##
+## Copyright (c) YEARS Apple Inc. and the Swift project authors


Suggested change

## Copyright (c) YEARS Apple Inc. and the Swift project authors

## Copyright (c) 2026 Apple Inc. and the Swift project authors

lorentey · 2026-03-31T18:19:47Z

Utils/Debugger/generate_formatters.sh

+curl -fsSL \
+  "https://raw.githubusercontent.com/llvm/llvm-project/$COMPILER_VERSION/lldb/examples/python/formatter_bytecode.py" \
+  -o "$compiler"


I have reservations about downloading scripts sight unseen for execution on engineers' machines. Can we just copy the formatter directly into this repo, like we used to do with gyb?

When `COLLECTIONS_SINGLE_MODULE` is set, a single `Collections` module is built. Type names need to match accordingly.

@benrimmington

Following feedback from @benrimmington in apple/swift-collections#607, this changes the following: 1. Uses `objectFormat()` compiler conditional instead of `os()` (see "Cross-platform object file format support" in [SE-0492](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0492-section-control.md#cross-platform-object-file-format-support)) 2. Uses a raw identifier for the generated Swift symbol name, instead of an escaped name (see [SE-0451](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0451-escaped-identifiers.md)) (cherry picked from commit b66d98a)

kastiglione requested a review from lorentey as a code owner March 19, 2026 01:43

kastiglione requested a review from adrian-prantl March 19, 2026 01:44

kastiglione added 4 commits March 18, 2026 18:47

manually remove trailing comma

e6bfc56

Support compilers prior to 6.3

43c367c

Support only Swift 6.3+

4e38902

Make conditional cover whole file

a4bbcdd

kastiglione marked this pull request as draft March 19, 2026 02:10

adrian-prantl reviewed Mar 19, 2026

View reviewed changes

benrimmington reviewed Mar 28, 2026

View reviewed changes

kastiglione mentioned this pull request Mar 30, 2026

[lldb][bytecode] Improvements to compiler generated Swift llvm/llvm-project#189425

Merged

Update RigidArray+Formatter.swift

a6cefb8

kastiglione added 3 commits March 31, 2026 09:55

Add license header

7d721cb

Add generate_formatters.sh script

86d184d

Add license headers to introduced scripts

3d4a9de

lorentey reviewed Mar 31, 2026

View reviewed changes

kastiglione added 3 commits March 31, 2026 12:53

Fix copyright dates

f93d09e

Support single-module mode

a2c6704

When `COLLECTIONS_SINGLE_MODULE` is set, a single `Collections` module is built. Type names need to match accordingly.

Vendor formatter_bytecode.py

c8734cb

kastiglione requested a review from adrian-prantl March 31, 2026 20:07

Ignore licence check on vendored formatter_bytecode.py

6ac9e45

		@used
		let __BasicContainers___RigidArray______formatter: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8) = (

	// Copyright (c) 2024 - 2026 Apple Inc. and the Swift project authors
	// Copyright (c) 2026 Apple Inc. and the Swift project authors

	## Copyright (c) YEARS Apple Inc. and the Swift project authors
	## Copyright (c) 2026 Apple Inc. and the Swift project authors

Conversation

kastiglione commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kastiglione commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kastiglione Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kastiglione commented Mar 19, 2026 •

edited

Loading

kastiglione commented Mar 19, 2026 •

edited

Loading

kastiglione Mar 31, 2026 •

edited

Loading