Transcript
[ Music ]
>> Hello, my name is Davide and
I am an engineer on the
Debugging Technologies Team at
Apple.
I'm here with my colleague
Jonas.
You might be familiar with po, a
way to print variables in LLDB.
Today, we will talk about it and
how it works.
We will also present other ways
to look at the variables in your
source code together with
powerful mechanisms to format
the output.
LLDB is the debugger that powers
the variable view in Xcode.
You can see the variables you
define and their types there.
While debugging in Xcode, you
can also directly send commands
and interact with LLDB through
the console in the bottom right
of the window.
This includes the ability to
print the values of the
variables to defining your
source code while you're
investigating a bug in your
application.
LLDB offer several ways to
accomplish this task.
Each of which comes with a
different set of trade-offs.
Let's look at them.
As an example, suppose we have a
struct that represents a Trip,
consisting of a name and a list
of destinations.
Let's go on a cruise around the
Mediterranean.
The first command we are going
to explore is po, which you can
think as of standing for print
object description.
When we use this command, what
we get in return is the object
description which is a textual
representation of an instance of
your type.
The system runtime provides a
default one but it's possible to
customize it.
We can do this by adding a
conformance to the
CustomDebugStringConvertible
protocol.
This requires having a single
property called the
debugDescription.
Now, if we print the object
description in the debugger,
we'll see the description we
provided instead of the default
one.
The change only affects the
top-level description.
If you need to modify the
substructure, check the
documentation for the
CustomerReflectable protocol.
This can also be done for
Objective-C objects by
implementing the description
method.
But po does more than just print
variables.
For example, you can take the
name of our cruise and compute
an uppercase version of it or
get an alphabetically sorted
array of the cruise
destinations.
In general, it can evaluate
arbitrary expressions.
So, anything that would compile
at a given prompt in the program
can be passed as an argument to
the comment.
In fact, po is actually an alias
for a command called expression
with an argument for printing
the object description.
LECC and LLDB are a convenient
way to save keystrokes.
If you wanted to implement po
yourself, for example, you could
use command alias.
Specify your own command name as
the first argument, and then
follow with the command you want
to alias.
Once that's defined, you can use
it like any other commands in
LLDB.
Now that we know what po can do,
let's take a deeper look at how
it works.
Let's go through the steps that
po has to perform to deliver a
value.
To provide the full expressivity
of the language you are using
LLDB doesn't parse and evaluate
the expression itself.
Instead, it starts by generating
a piece of source code that can
be compiled from the expression
you gave it, similar to the
snippet shown here.
Then it uses the embedded Swift
and claim compilers to compile
the code which gets executed in
the context of your debugged
program.
Once the execution is complete,
LLDB has to access the resulting
value.
From there you need to get the
object description.
To do this, LLDB wraps the
previous result in another piece
of source code.
This also gets compiled and
executed in the context of your
debug process.
The result of this execution is
a string that LLDB will display
as the result of the po command.
Po is only the first of the
three ways we are presenting to
print variables in LLDB.
Let's look at the others.
The second way to print
variables in an LLDB is the
p-command.
You can think of it as print
without the object description.
Let's look at its output.
The first thing to notice is
that the representation is
slightly different from the one
provided by po, but it is
equivalent in that it contains
the same information.
The second thing to notice is
that the resulting value has
been given a name, $R0.
This is a special convention in
LLDB.
The result of each expression is
given an incrementing name, such
as $R1 and $R2.
And this name can be used in
later expressions in LLDB.
You can refer to $R0 the same
way as any other variable in
your project.
You can, for example, print the
fields of destruction.
Similar to po, p is not a
first-class command in LLDB.
It's just an alias for the
expression command, but without
the -- object description after
it.
As we previously did with po,
let's look at how po works under
the hood.
Since p doesn't have to get the
description, it doesn't have to
do as much work.
You may recall this diagram from
the earlier description of po.
In fact, the first part
compiling and evaluating the
expression is exactly the same
for both commands.
But once it gets the results
LLDB perform a step name dynamic
type resolution on it.
Let's describe it with more
details.
In order to do that, we have to
modify our code example a bit.
Let's see how.
We change our Trip struct to
conform to a protocol name
activity.
In Swift, the static
representation of a type in the
source code and the dynamic type
at the runtime, aren't
necessarily the same.
For example, a variable might be
declared using a protocol of
this type.
In this example, the static type
of cruise's Activity.
But at runtime, the variable
will have an instance of type
Trip which is the dynamic time.
If we print the value of cruise,
we get back an object of type
Trip because LLDB retell results
metadata to display the most
accurate type for a given
variable at a given program
point.
This is what we call dynamic
type resolution.
With the p-command, dynamic type
resolution is only performed on
the result of the expression.
Let's say we want to access one
of the field of cruise.
When LLDB tries to evaluate this
expression through p, it sees
that cruise is an object of type
Activity and doesn't have a
member called name.
The evaluation fails with an
error.
This happens because if you
remember, LLDB compiles code
where running p and the only
type it sees is the one in your
source code, the static one.
It's the same thing as typing
the expression cruise.name in
your source code.
The static compiler will reject
it with an error.
If you want to evaluate the
expression without errors, you
need to first cast the object
explicitly to its dynamic type
and then access the field on the
result.
This is true both for the
debugger and your source code.
P is not yet done with its work.
After it performed dynamic type
resolution on the result, LLDB
passes the resulting object to
the formatter subsystem which is
the part of LLDB responsible for
printing a human readable
description of objects.
Let's dive into it.
To show how formatters work,
we're going to display their
input and output.
Here's what that string looks
like if there was no formatter
for the type.
If you want to try yourself, you
can pass the -- raw option to p.
Standard library types even
simple ones like strings and
integers have complex
representation because they are
highly optimized for speed and
size.
After the formatter operates in
it a string looks exactly as you
expect, a sequence of
characters.
LLDB knows about a bunch of
commonly used types and provides
formatters for them.
You can also write for customize
formatters.
We'll talk about it shortly.
We talk about p and po.
We are now going to describe the
third way to print variables in
LLDB, the v-command.
The output of v is exactly the
same as p as it also relies on
the formatter we just described.
As with the other two commands,
v is just an alias we introduced
in Xcode 10.2 for the frame
variable command.
Unlike the other two mechanisms,
the v-command doesn't compile
and execute code at all which
makes it very fast.
Since v is not compiling code,
it does its own syntax which
will not necessarily be the same
as the language you are
debugging.
For example, it used the dot and
subscript operators to access
fields over time.
But it won't perform overload
the resolution and computed
properties cannot be evaluated
since that would require code to
be executed.
You can use p or po if you need
those.
As you can guess, v works fairly
differently from the other two
mechanisms for printing
variables.
Let's go ahead and clarify some
details.
In our grand tradition of
diagrams here is one for v.
We want to print a variable.
To do so, v first consults the
program state to locate the
variable in memory.
Then it reads the value of the
variable from memory.
Then it performs dynamic type
resolution on it.
If the user asked to access
subfields, it repeats the step
for each of the subfields
performing dynamic type
resolution at each round.
Once it's done, it passes the
result to the data formatter
subsystem.
The fact that v performs dynamic
type resolution potentially
multiple times is an important
detail to remember and the big
difference in the way p and v
operates.
The formatter indeed performs
dynamic type resolution only
once.
Let's look at the scenario where
these matters.
We are back to our example where
p was failing to access the
member of cruise.
By performing dynamic type
resolution at each step of the
interpretation, v is able to
understand that cruise is an
object of type Trip and access
its field in memory.
This is a scenario where v is
strictly more powerful than p
and allows you to look at your
types where p doesn't or without
an explicit cast.
We are done describing the three
different ways for printing
variables in LLDB.
Let's have a recap and the
side-by-side comparison of how
the po, p and v commands differ.
The first point we want to make
is about how objects are
presented.
The po command uses the object
description, whereas the p and v
commands use the data formatters
to display the object.
We also want to remember how our
results are computed.
Both po and p compile
expressions and have access to
the full language.
V instead has its own syntax
interprets the expression and
performs dynamic type resolution
for each step of the
interpretation.
We mentioned earlier that LLDB
formatting can be customized.
To talk more about that, here is
my colleague Jonas.
>> Hi, I'm Jonas, and I'm also
an engineer on the Debugging
Technologies Team.
In LLDB, data formatter is
defined how variables are
displayed in the debugger.
There are building formatters
for common types.
For instance, when using the
v-commands, we can print the
destinations of our cruise and
the array elements are displayed
in a readable format.
Usually, the default formatter
works great for both the user
defined types and for types
coming from the standard
library.
But sometimes you might want to
tweak an existing formatter or
to find one yourself.
And you can, because data
formatters in LLDB are fully
extensible.
Every type can have its own
representation.
To help you customize that
representation, LLDB offers
filters, summaries and synthetic
children.
Filters are used to limit the
output of existing formatters.
Right now, our Trip only has a
few destinations but as the
number increases, the output
could become cluttered.
By adding a filter, we can
specify that we only want to see
the Trips name.
This not only affects the output
of the formatter in the console,
but also the variables here in
Xcode.
Let's remove the filter again
before moving on.
Summaries provide a string
representation of a type.
To give information about that
type at a glance, their data
formatter equivalent of the
description that you would
implement for use with po.
As with filters, they also
affect the variables view in
Xcode.
While the members of our Trip
all have summaries, the Trip
itself does not.
Let's change that.
A good summary would be the
first and last destination.
The summary string can contain
regular text and special
variables that access fields of
the time being printed.
These variables start with a
dollar sign and are wrapped in
curly braces.
They use the same syntax as the
v-commands.
The current type for which the
summary is defined is access as
var.
The summary uses var.name to
access the Trips name and
var.destinations to access its
destinations.
But there's a problem with the
summary.
It only works for Trips that
contain exactly three
destinations.
Because formatters can't access
computed variables like the
count of an array, we have to
hard-code the index of the last
element.
Fortunately, there's another
powerful tool available to us.
We can also define summaries in
Python.
Python formatters can do
arbitrary computations and they
have full access to LLDB's
scripting bridge API which
provides several objects for
accessing the state of the
current debug session.
The target is the program that's
currently being debugged.
The process, thread, and frame
provides access to the
corresponding runtime
information.
Values of variables, registers,
or expressions are represented
by the SB value class.
These are particularly
interesting to the data
formatters because they are used
to navigate types and their
values.
Check out the online
documentation for more details.
Starting with Xcode 11,
scripting uses Python 3.
If you have existing Python 2
scripts, check out the Xcode
release notes for more
information on transitioning to
Python 3.
Let's explore the LLDB API.
Executing the script commands
drops this into an interactive
Python interpreter.
The current frame is accessible
to the lldb.frame variable.
This returns an SBFrame
instance.
We know that the current frame
contains a variable named
cruise.
So, we can go ahead and use find
variable to obtain its SB value.
Since these objects power the
data formatters under the hood,
it is no surprise that printing
them looks identical to the
corresponding data formatter
outputs.
We also know that cruise has
member named destinations.
We can access it by calling
GetChildMemberWithName.
The result is another SB value
that represents the destinations
array.
Let's try to mimic our earlier
formatter using Python, this
time without hard coding the
index of the last element.
We can use GetNumChildren on the
destinations SB value to get the
number of elements.
With GetChildAtIndex, we can
access the first element and the
last element.
Notice that the printed values
are context sensitive.
They contain the index in the
array.
SB value instances maintain the
context of their parent
relation.
Now, we can put everything
together in a single string.
The results, however, it's not
exactly what we want, by
printing, begin and end, we get
descriptions of the SB value
objects.
What we really want here are
their summaries.
We can use GetSummary to
retrieve the formatted value and
use that instead.
Now, the result is place only
the destination strings
themselves.
Let's put everything together.
Formatters can be defined
directly in the debugger console
or you can use a file and load
it into LLDB.
In this case, we'll create a
file called Trip.py.
When defining a provider in a
file instead of using the
current frame to access the
variable we want to display the
SB value is passed as an input
parameter to a function.
The rest of the implementation
is pretty much identical to what
we did before.
Another advantage of using
Python to define the formatter
is that we have control flow.
If the trip has no destinations,
we can just sprint that it's an
empty trip.
We get the summary for the first
and last destination and return
to summary string.
Now, we need to load our new
summary provider into LLDB.
This is done using the command
script import command.
Next, we need to specify that
our new formatter is the one to
use for the Trip type.
Using type summary add and
providing the type to be
formatted, and the provider
function to use.
It's important to use the fully
qualified type here.
With everything hooked up v now
uses the Python summary provider
to print a cruise object.
Not only does the summary show
up in the console, it is also
displayed in Xcode's Variable
View.
We've talked about filters and
summaries.
The final way to customize the
display of your type is with
synthetic children.
These make it possible to
customize what kind of children
your type exposes, such as when
you expend to type in the
variables view in Xcode.
In Python, each child has an SB
value, and each can have its own
summary.
Defining your own synthetic
child provider is similar to
defining a summary provider.
But instead of a function you
define a class that implements
certain methods.
In addition to init, you provide
a method to get the total number
of children, the synthetic
children themselves, and an
index for a given name.
A full example of this is
available in the resources link
from this session.
Just like before, use command
script import to load the Python
source code into LLDB.
In this case, we already loaded
this file earlier and running
the command again will reload
the file.
To specify the formatter, to use
for synthetic children use type
synthetic add and provide the
type to be formatted and the
class to use.
After going through the effort
of defining our own custom
providers, we don't want to lose
them at the end of our debug
session.
Any command you type in the
console can be persisted in the
.lldbinit file in your home
directory.
This file gets automatically
loaded at the beginning of your
debug session.
LLDB has a variety of features
to help you see the state of
your program while debugging.
Use v, p, or po to print
variables, depending on whether
you just need to display its
value, execute code or get the
object description.
Customize or define your own
data formatters, using filters,
string summaries, and synthetic
children.
Finally, if you have scripts
written in Python 2, update them
to be compatible with Python 3.
The version used by LLDB
starting in Xcode 11.
For more information, check out
the page for this session on
developer.apple.com.