2. Help & Apropos

Written by Derek Selander

Just like any respectable developer tool, LLDB ships with a healthy amount of documentation. Knowing how to navigate through this documentation — including some of the more obscure command flags — is essential to mastering LLDB.

The “help” command

Open a Terminal window and type lldb. The LLDB prompt will appear. From there, simply type the help command:

(lldb) help 

This will dump out all available commands, including the custom commands loaded from your ~/.lldbinit — but more on that later.

There’s quite a few commands one can use with LLDB.

However, many commands have numerous subcommands, which in turn can have subcommands, which also have their own associated documentation. I told you it was a healthy amount of documentation!

Take the breakpoint command for instance. Run the documentation for breakpoint by typing the following:

(lldb) help breakpoint

You’ll see the following output:

 Commands for operating on breakpoints (see 'help b' for shorthand.)

Syntax: breakpoint

The following subcommands are supported:

      clear   -- Delete or disable breakpoints matching the specified source file and line.
      command -- Commands for adding, removing and listing LLDB commands executed when a breakpoint is hit.
      delete  -- Delete the specified breakpoint(s).  If no breakpoints are specified, delete them all.
      disable -- Disable the specified breakpoint(s) without deleting them.  If none are specified, disable all breakpoints.
      enable  -- Enable the specified disabled breakpoint(s). If no breakpoints are specified, enable all of them.
      list    -- List some or all breakpoints at configurable levels of detail.
      modify  -- Modify the options on a breakpoint or set of breakpoints in the executable.  If no breakpoint is specified,
                 acts on the last created breakpoint.  With the exception of -e, -d and -i, passing an empty argument clears
                 the modification.
      name    -- Commands to manage name tags for breakpoints
      read    -- Read and set the breakpoints previously saved to a file with "breakpoint write".  
      set     -- Sets a breakpoint or set of breakpoints in the executable.
      write   -- Write the breakpoints listed to a file that can be read in with "breakpoint read".  If given no arguments,
                 writes all breakpoints.

For more help on any particular subcommand, type 'help <command> <subcommand>'.

From there, you can see several supported subcommands. Look up the documentation for breakpoint name by typing the following:

(lldb) help breakpoint name

You’ll see the following output:

   Commands to manage name tags for breakpoints

Syntax: breakpoint name

The following subcommands are supported:

      add       -- Add a name to the breakpoints provided.
      configure -- Configure the options for the breakpoint name provided.  If you provide a breakpoint ID, the options will be
                   copied from the breakpoint, otherwise only the options specified will be set on the name.
      delete    -- Delete a name from the breakpoints provided.
      list      -- List either the names for a breakpoint or info about a given name.  With no arguments, lists all names

For more help on any particular subcommand, type 'help <command> <subcommand>'.

If you don’t understand breakpoint name at the moment, don’t worry — you’ll become familiar with breakpoints and all of the subsequent commands soon. For now, the help command is the most important command you can remember.

The “apropos” command

Sometimes you don’t know the name of the command you’re searching for, but you know a certain word or phrase that might point you in the right direction. The apropos command can do this for you; it’s a bit like using a search engine to find something on the web.

apropos will do a case-insensitive search for any word or string against the LLDB documentation and return any matching results. For example, try searching for anything pertaining to Swift:

(lldb) apropos swift

You’ll see the following output:

The following commands may relate to 'swift':
  swift    -- A set of commands for operating on the Swift Language Runtime.
  demangle -- Demangle a Swift mangled name
  refcount -- Inspect the reference count data for a Swift object

The following settings variables may relate to 'swift':


  target.swift-framework-search-paths -- List of directories to be searched when locating frameworks for Swift.
  target.swift-module-search-paths -- List of directories to be searched when locating modules for Swift.
  target.use-all-compiler-flags -- Try to use compiler flags for all modules when setting up the Swift expression parser, not just the main executable.
  target.experimental.swift-create-module-contexts-in-parallel -- Create the per-module Swift AST contexts in parallel.

This dumped everything that might pertain to the word Swift: first the commands, and then the LLDB settings which can be used to control how LLDB operates.

You can also use apropos to search for a particular sentence. For example, if you were searching for something that can help with reference counting, you might try the following:

(lldb) apropos "reference count"
The following commands may relate to 'reference count':
  refcount -- Inspect the reference count data for a Swift object

Notice the quotes surrounding the words "reference count". apropos will only accept one argument to search for, so the quotes are necessary to treat the input as a single argument.

Isn’t that neat? apropos is a handy tool for querying. It’s not quite as sophisticated as modern internet search engines; however, with some playing around, you can usually find what you’re looking for.

Note: A new bug that popped up in the latest Xcode 10 version of LLDB (lldb-1000.11.37.1) will not give the full command tree when using apropos. For example, the refcount command displayed above can only actually be used via language swift refcount. The apropos command displayed this correctly in previous version, (and will likely again in the future) but for now you’ll need to do a little digging to get the exact command using apropos

Where to go from here?

It’s easy to forget the onslaught of LLDB commands that will soon come, but try to commit these two commands, help and apropos, to heart. They’re the foundation for querying information on commands and you’ll be using them all the time as you master debugging.