Skip to content

Installation

Jump to bottom
snare edited this page Aug 18, 2016 · 7 revisions

The Voltron package and its dependencies must be installed somewhere the Python interpreter embedded in the debugger can find them. This can be one of the following locations:

  1. That Python installation's global site-packages directory
  2. The user's local site-packages directory for that version of Python
  3. A Python virtual environment linked to that version of Python

In the majority of cases, Voltron can simply be installed with pip either system-wide (option 1 above):

$ [ sudo ] pip install voltron

Or in the user's home directory (option 2 above):

$ pip install voltron --user

On systems where there are multiple installations of Python, it may be slightly more complicated. See below for platform-specific instructions.

macOS

On macOS, LLDB (installed by Xcode) and GDB (installed by Homebrew) are both linked against the system's default version of Python, so Voltron must be installed using this version of Python. On systems without any other Python installation, you can just go ahead and install with pip as above.

On systems with other versions of Python installed (via Homebrew, MacPorts or other methods), you may need to explicitly specify the system version of Python:

$ /usr/bin/python -m pip install voltron [ --user ]

Other installations of LLDB or GDB (manually compiled or installed with MacPorts) may be linked with other Python installations, so you'll need to install Voltron with whichever the debugger is linked against.

You can find out which version of Python your debugger is linked against with otool:

$ otool -L /usr/local/bin/gdb|grep -i python
    /System/Library/Frameworks/Python.framework/Versions/2.7/Python (compatibility version 2.7.0, current version 2.7.5)

This version of GDB above is installed with Homebrew, so it's linked against the system Python. You'll have to figure out which installation of Python your debugger is linked with and where the python binary is on your own, but when you do you can install Voltron with:

$ /path/to/python -m pip install voltron [ --user ]

Linux

Ubuntu

Ubuntu (at least 14.04) comes with Python versions 2 and 3. GDB is linked with Python 3, but /usr/bin/python is Python 2. In order to get Voltron to work you'll need to install Voltron into the Python 3 site-packages.

First, install some dependencies:

$ sudo apt-get install libreadline6-dev python3-dev python3-setuptools python3-yaml

Then install Voltron:

$ pip3 install voltron

Other distros

You're mostly on your own here. You can figure out which version of Python the debugger is linked with using readelf:

$ readelf -d `which gdb`|grep python
0x0000000000000001 (NEEDED)             Shared library: [libpython3.4m.so.1.0]

Then you'll need to install Voltron using that version of Python, wherever it lives:

$ /path/to/python -m pip install voltron [ --user ]

Windows

WinDbg

Voltron support for WinDbg is implemented by way of the PyKD module.

  1. Install WinDbg via Windows SDK

  2. Download the zip of the latest release of PyKD

  3. Install the PyKD module. If you know how to do this properly (install it to the WinDbg extensions dir, which I gave up on because it didn't want to work on my system), then do it. I just load it in WinDbg by absolute path.

  4. Install the PyKD Python wheel with pip:

     $ pip install /path/to/pykd-0.3.0.38-py2-none-win_amd64.whl

  5. Start WinDbg or CDB

  6. Load PyKD:

     > .load C:\path\to\pykd.pyd

  7. Initialise Voltron:

     > !py --global C:\path\to\voltron\entry.py

  8. Or launch CDB, load PyKD and init Voltron in one command:

     > cdb -c '.load C:\pykd.pyd ; !py --global C:\Users\admin\voltron\voltron\entry.py' calc

Troubleshooting

  1. Make sure you have the same bitness versions of Python and PyKD (possibly WinDbg but I don't think there's an option).

  2. Make sure you've installed the PyKD Python wheel.

  3. You will need curses for Windows

VDB

TBC

Virtual environments

Voltron can be installed into a Python virtual environment if you'd rather not install it (and all its dependencies) into your Python site-packages directory. You'll need to make sure you're using the correct installation of Python per the installation instructions above.

Create a virtual environment:

$ virtualenv voltron_venv

Or, if you're using a Python installation that the virtualenv executable in your path does not belong to:

$ /path/to/python -m virtualenv voltron_venv

Install Voltron into the virtual environment:

$ voltron_venv/bin/pip install voltron

Now when you launch the debugger, you'll need to set your PYTHONPATH environment variable:

$ PYTHONPATH=voltron_venv/lib/python2.7/site-packages lldb

Note the Python version in the path there - that will need to reflect whatever the actual path to the site-packages dir inside the virtual environment is. You could also set and export this variable in your shell init.

When you launch the views, you'll need to call the voltron executable inside the virtual environment:

$ voltron_venv/bin/voltron view reg

You could also add the venv to your PATH environment variable.

Clone this wiki locally