ds2 is a debug server designed to be used with LLDB to perform remote debugging of Linux and android targets. It is still under active development, and one medium-term goal is to support Windows debugging.
ds2 needs cmake and a C++11 compiler.
ds2 uses CMake to generate its build system. After cloning the ds2 repository, run the following commands to build for the current host:
cd ds2
mkdir build
cd build
cmake ..
make
Compiling for Linux-ARM is also possible. On Ubuntu 14.04, install
gcc-4.7-arm-linux-gnueabi
and g++-4.7-arm-linux-gnueabi
and use the
provided toolchain file.
cd ds2
mkdir build
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../Support/CMake/Toolchain-Linux-ARM.cmake ..
make
This will generate a binary that you can copy to your device to start debugging.
For Android native debugging, it is possible to build ds2 with a toolchain from
the Android NDK. A script is provided to generate the toolchain, and a CMake
toolchain file can then be used to generate the build system.
Support/Scripts/prepare-android-toolchain.sh
will download a working version
of the NDK, extract it, and install the toolchain to
/tmp/android-ndk-arm-toolchain
which can then be used for the build.
cd ds2
./Support/Scripts/prepare-android-toolchain.sh arm
mkdir build
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../Support/CMake/Toolchain-Android-ARM.cmake ..
make
Builds of ds2 targetting Android generate a static binary by default. The final build product can be copied over to the remote device and used with minimal dependencies.
ds2 accepts the following options:
usage: ds2 [OPTIONS] [PROGRAM [ARGUMENTS...]]
-a, --attach ARG attach to the name or PID specified
-R, --debug-remote enable debugging of remote protocol
-k, --keep-alive keep the server alive after the client disconnects
-L, --list-processes list processes debuggable by the current user
-o, --log-output ARG output log message to the file specified
-n, --no-colors disable colored output
-P, --platform execute in platform mode
-p, --port ARG listen on the port specified
-S, --slave run in slave mode (used from platform spawner)
After building ds2 for your target, run it with the binary to debug, or attach
to an already running process. Then, start LLDB as usual and attach to the ds2
instance with the gdb-remote
command.
ds2 listens on port 12345 by default; --port
can be used to specify the port
number to use.
Launch ds2 with something like:
$ ./ds2 --port 4242 ./TestSimpleOutput
ds2 is now ready to accept connections on port 4242 from lldb.
$ lldb /path/to/TestSimpleOutput
Current executable set to '/path/to/TestSimpleOutput' (x86_64).
(lldb) gdb-remote sas-ubuntu-vm.local:4242
Process 8336 stopped
* thread #1: tid = 8336, 0x00007ffff7ddb2d0, name = 'TestSimpleOutput', stop reason = signal SIGTRAP
frame #0: 0x00007ffff7ddb2d0
-> 0x7ffff7ddb2d0: movq %rsp, %rdi
0x7ffff7ddb2d3: callq 0x7ffff7ddea70
0x7ffff7ddb2d8: movq %rax, %r12
0x7ffff7ddb2db: movl 0x221b17(%rip), %eax
(lldb) b main
Breakpoint 1: where = TestSimpleOutput`main + 29 at TestSimpleOutput.cpp:6, address = 0x000000000040096d
[... debug debug ...]
(lldb) c
Process 8336 resuming
Process 8336 exited with status = 0 (0x00000000)
(lldb)
See the CONTRIBUTING.md file for how to help out.
ds2 is licensed under the University of Illinois/NCSA Open Source License.
We also provide an additional patent grant which can be found in the PATENTS
file in the root directory of this source tree.
regsgen2, a tool used to generate register definitions is also licensed under
the University of Illinois/NCSA Open Source License and uses a json library
licensed under the Boost Software License. A complete copy of the latter can be
found in Tools/libjson/LICENSE_1_0.txt
.