# SAOC Plan for LLDB integration

## Milestone 1

Implement a demangler into the LLVM codebase using one of the three
implementation proposals, ordered by preference:

1. Port GCC/GDC libiberty D demangler to C++ LLVM core codebase.
2. Create a `libllvmd` wrapper around the D runtime interface to export a C API
   to provide LLVM with the ability to demangle D functions using
   core.demangle.
3. Create a fresh implementation of D demangler in C++ to the LLVM core
   codebase.

This needs further discussion to see which implementation proposal fits the
best into the LLVM codebase and which one is willing for more acceptance.
Currently, the priority is to do the **first** one but dual licensing is a
challenge and it is being discussed with the creator of GDC (Iain) to grant it.

The **second** option would benefit from `dlopen` to provide support for D
demangling to avoid a D compiler dependency on the LLDB tree.

The **third** option is the least feasible and would probably require a bit
more time to implement, as it is time-consuming implementing a whole new
demangler in C++. Although, if none of the two is practical, this could be an
option.

After having a concise decision I will start implementing/porting it into the
LLVM codebase and strive for acceptance into the upstream repositories. In the
meantime, proper testing will be also performed to ensure sane code coverage.

The demangling will take part of writing the backtrace correctly:

```
* thread #1, name = 'app', stop reason = signal SIGSEGV: invalid address (fault address: 0xdeadbeef)
   frame #0: 0x000055555555744e app.foobar(int*, int[], int[int], real, app.Foo, app.Bar) (p=0xdeadbeef, a=..., b=..., c=123.122999999999999998, f=..., bar=...) at app.d:32:2
 * frame #1: 0x00005555555576ff D main () at app.d:63:2
```

Currently the backtrace is looking something like this:

```
* thread #1, name = 'app', stop reason = signal SIGSEGV: invalid address (fault address: 0xdeadbeef)
   frame #0: 0x000055555555744e app`_D3app6foobarFPiAiHiieSQv3FooSQBc3BarZi(p=0xdeadbeef, a=..., b=..., c=123.122999999999999998, f=..., bar=...) at app.d:32:2
 * frame #1: 0x00005555555576ff app`_Dmain at app.d:63:2
```

## Milestone 2

After implementing the demangler, some custom data structures that are not well
recognized by the debugger should be taken to consideration. The first thing to
handle correctly is the primitive types, more specifically formatting
arrays.

For example for the GDB debugger, normal arrays (e.g. int[]) are formatted like
the following:

```
a = {[0] = 1, [1] = 2, [2] = 3}
```

Currently, on LLDB this is shown as a raw structure of `length` and `ptr`:

```
(int[]) a = {
 length = 3
 ptr = 0x00007ffff75ad010
}
```

There are two steps to implement this properly and one of them should be
addressed by this milestone.

1. Currently the compiler generates DWARF code to represent arrays as structs.
   This is an incorrect approach, according to DWARF 4 and 5 specifications.
   Instead, the compiler should generate a `DW_TAG_array_type` for the
   debuggers to properly understand it.
2. To provide backward compatibility and support for DMD, reading
   `DW_TAG_structure_type` as arrays should be addressed by reading both
   `length` and `ptr` properties. This is needed, at least for DMD, because the
   compiler backend is stuck on an outdated DWARF version.

Additionally, as a bonus, for special cases like strings, it is also desired to
just print the `string` itself, as GDB does:

```
s = "artur"
```

DWARF also has a tag for strings named `DW_TAG_string_type` that could be
implemented in the compiler too.

## Milestone 3

Finally, implementation for custom expressions. Expression evaluation only
supports basic expressions such as dereferencing pointers `*ptr` or nested type
access `abc.xyz.a`, similar to C/C++ syntax.

Even though GDB doesn't currently support expressions, like array access or
slices, this would be a good addition to have.

Some expression examples are:

- `arr[0]`
- `arr[0..3]`
- `arr[0..4][0]`

For this milestone, it should be desired to at least read one D expression such
as array indexes. Other expressions might be implemented as a bonus.