*lldb.txt* A plugin that enables debugging from your favourite editor

                        _                 ____    ____
                 _   __(_)___ ___        / / /___/ / /_
                | | / / / __ `__ \______/ / / __  / __ \
                | |/ / / / / / / /_____/ / / /_/ / /_/ /
                |___/_/_/ /_/ /_/     /_/_/\__,_/_.___/

                   LLDB Debugger Ingegration For VIM

==============================================================================

CONTENTS                                                       *lldb-contents*

    1. Introduction .................... |lldb-intro|
    2. Getting Started ................. |lldb-start|
    3. Commands ........................ |lldb-commands|
    4. Mappings ........................ |lldb-mappings|
    4. License ......................... |lldb-license|
    5. Bugs ............................ |lldb-bugs|
    6. Contributing .................... |lldb-contributing|


Original Author:    Daniel Malea <daniel.malea@intel.com>
Forked by:          Tobias Pflug <tobias.pflug@gmail.com>
Maintainer:         John C F <john.ch.fr@gmail.com>
License:            Same terms as Vim itself (see |license|)

INTRODUCTION                                    *lldb-intro*

The plugin provides an interface to the lldb debugger allowing for
convenient debugging sessions inside your favorite editor including
features such as breakpoints, stepping, watchpoints etc.

The original plugin can be found here:

http://llvm.org/svn/llvm-project/lldb/trunk/utils/vim-lldb/

Credit for pretty much all current functionality goes to the original
authors. Currently, work has been done to migrate the existing features
to use Neovim's new API so that the user interface is much more responsive.
Also, the focus has been to simplify the code wherever possible, so that
it will be easier to debug and extend.


GETTING STARTED                                 *lldb-start*

To quickly get started compile (with debugging symbols) the source and
open a source file belonging to the program in Neovim, and execute >

    :LLtarget create /path/to/executable

Notice that all built-in commands have tab-completion enabled.
With cursor on some line in the source file, press <M-b> to set a breakpoint
at that line. Alternatively, you can execute: >

    :LLbreakpoint set --name function_name

Now, press <S-F5> or call LLUpdateLayout(), and execute one of >

    :LLprocess launch
    :LLprocess launch args
    :LLprocess launch -i stdin_redir_file -o stdout_redir_file args

Once the program reaches the specified breakpoint you will be able to
inspect state and step through the program using the commands described below.

Don't forget that, since the debugger is asynchronous, you can interrupt an
unresponsive process using: >

    :LLprocess interrupt

Once it's interrupted, you can select your frame of interest using one of >

    :LLup [num]
    :LLdown [num]
    :LLframe select <frame-index>

Alternatively, you can kill it using: >

    :LLprocess kill

CUSTOMIZING                                     *lldb-customizing*

There are a 2 global options you can edit to change the layout. Default
values are specified:

*g:lldb_layout_windows* = [ 'backtrace', 'breakpoints', 'disassembly',
                        \ 'locals', 'registers', 'threads' ]
                        This is the order in which windows showing the
                        corresponding buffers will be created.

*g:lldb_layout_cmds* = '.TRBBRkRkR'
                        This specifies how the windows will be created.
                        T = tab sp
                        R = rightbelow vsp
                        B = belowright sp
                        A = aboveleft sp
                        L = leftabove vsp
                        . = Next command should show the code buffer.

COMMANDS                                        *lldb-commands*

The LLDB command interpreter is exposed to Vim's command mode using the
':LL' prefix. Tab-completion is available and will cycle through commands.
Some commands have modified behaviour.

                                                *lldb-:LLattach*
:LLattach <proc-name>   Attach to a process by name.

                                                *lldb-:LLdetach*
:LLdetach               Detach from the current process.

                                                *lldb-:LLframe*
:LLframe {args}         Passed through to LLDB's command interpreter.

                                                *lldb-:LLthread*
:LLthread <args>        Passes through to LLDB's command interpreter.

                                                *lldb-:LLprocess*
:LLprocess {args}       Passed through to LLDB's command interpreter.

                                                *lldb-:LLtarget*
:LLtarget {args}        Passed through to LLDB's command interpreter.

                                                *lldb-:LLbreakpoint*
:LLbreakpoint {args}    Alias to the lldb breakpoint command.

                                                *lldb-:LLwatchpoint*
:LLwatchpoint {args}    Alias to the lldb watchpoint command.

                                                *lldb-:LLstart*
:LLstart                Create a process by executing the current target
                        and wait for LLDB to attach.

                                                *lldb-:LLrun*
:LLrun                  Create a process by executing the current target
                        without waiting for LLDB to attach.

                                                *lldb-:LLcontinue*
:LLcontinue             Continue execution of the process until the next
                        breakpoint is hit or the process exits.

                                                *lldb-:LLrefresh*
:LLrefresh              Checks whether there are any pending debugger events
                        to be processed, and updates the debugger info buffers.

                                                *lldb-:LLstep*
:LLstep                 Step into the current function call.

                                                *lldb-:LLstepin*
:LLstepin               Step into the current function call.

                                                *lldb-:LLstepinst*
:LLstepinst             Step one instruction.

                                                *lldb-:LLstepinstover*
:LLstepinstover         Step one instruction, but skip over jump or call
                        instructions.

                                                *lldb-:LLnext*
:LLnext                 Step to the next line.

                                                *lldb-:LLfinish*
:LLfinish               Step out of the current function.

                                                *lldb-:LLprint*
                                                *lldb-:LLpo*
:LLprint <expr>         Aliases to the lldb print and po commands.
:LLpo <expr>

                                                *lldb-:LLup*
                                                *lldb-:LLdown*
:LLup [num]             Aliases to the lldb up and down commands.
:LLdown [num]

This list is incomplete. Most of the lldb commands are available and are
passed through to the command interpreter.

MAPPINGS                                        *lldb-mappings*

The following are the default key mappings:

                                                *<M-b>*
<M-b>                   Insert breakpoint at cursor location.

                                                *<F5>*
<F5>                    Executes |:LLrefresh|

                                                *<S-F5>*
<S-F5>                  Resets the window layout.

                                                *<F8>*
<F8>                    Executes |:LLcontinue|

                                                *<F9>* *<S-F9>*
                                                *v_<F9>* *v_<S-F9>*
<F9>                    Invokes |:LLprint| <cword> in normal mode.
<S-F9>                  Invokes |:LLprint| <cword> in normal mode.
                        In visual mode, the selected text will be passed to
                        the respective command.


LICENSE                                         *lldb-license*

Same as Vim itself. See |license|.

BUGS                                            *lldb-bugs*

If you run into a bug use the github issue tracker to report it:
https://github.com/critiqjo/lldb.nvim/issues

CONTRIBUTING                                    *lldb-contributing*

If you want to help out you are more then welcome to do so. In fact
I am sure there are plenty of people out there that will do a better
job with this plugin than me. My C skills are more than rusty. I mostly
wanted to make this nice plugin more public and host it in a way in which
it is easy to install with your favorite plugin manager.

Long story short: Bring on your forks and pull requests.

 vim:tw=78:sw=4:ft=help:norl:
