GDBPlug

A minimalist plugin manager for GDB, inspired by vim-plug.

Features

• Simple plugin declaration syntax
• Automatic installation and updating of plugins from GitHub
• Support for both Python (.py) and GDB script (.gdb) plugins
• Autoload functionality

Installation

1. Copy the code into your ~/.gdbinit file

2. Alternatively, you can source it directly:

echo "source /path/to/gdb_plug.py" >> ~/.gdbinit

Usage

Basic Configuration

Add plugin declarations to your .gdbinit:

python
import os
import subprocess
import sys

# Auto install at first run
def load_gdbplug():
    # Path configurations
    plugin_dir = os.path.expanduser("~/.config/gdb")
    plugin_path = os.path.join(plugin_dir, "gdbplug.py")
    raw_plugin_url = "https://raw.githubusercontent.com/PEMessage/gdbplug/main/gdbplug.py"
    if not os.path.exists(plugin_path):
        print("Installing gdbplug...")
        try:
            os.makedirs(plugin_dir, exist_ok=True)
            subprocess.run([
                "curl", "-fLo", plugin_path,
                "--create-dirs", raw_plugin_url
                ], check=True)
        except Exception as e:
            print(f"Installation failed: {e}")
            sys.exit(1)
    import gdb as G
    G.execute("source {}".format(plugin_path))
load_gdbplug()

# Initialize plugin manager
Plug.begin(autoload=True) # global configuration

# Register plugins
if True:
    Plug.plug("hugsy/gef")  # Autoload by default
    Plug.plug("cyrus-and/gdb-dashboard", autoload=False)  # per-plug configuration

# Load all autoload plugins
Plug.end()
end

Commands

• Plug update [name...] - Update all or specified plugins
• Plug list - List registered plugins
• Plug load <name> - Load a specific plugin

Plugin Configuration Options

When registering a plugin with Plug.plug():

• repo: GitHub repository (required, format: "user/repo")
• name: Plugin name (defaults to repository name)
• directory: Installation directory (defaults to ~/.config/gdb/plug/<name>)
• autoload: Whether to load automatically (default: True)
• path: Directory (or list of directories), relative to the plugin root, prepended to sys.path before loading. Useful for python package plugins.
• source: File (or list of files), relative to the plugin root, to source. When set, it replaces the default initialization-file discovery.
• setup: Python code string or callable run after path/source. A callable receives the plugin directory. In a code string, {dir} is replaced by the plugin directory. Use this for plugins that need to import and register something instead of being sourced.

Environment Variables

• GDB_PLUG_HOME: Custom plugin installation directory (default: ~/.config/gdb/plug)
• GDB_PLUG_AUTOLOAD: Overwirte global autoload configuration

Example Workflow

1. Register plugins in your .gdbinit:

Plug.begin()
Plug.plug("hugsy/gef")
Plug.plug("cyrus-and/gdb-dashboard", autoload=False)
Plug.end()

2. Install the plugins:

(gdb) Plug update

3. Manually load a plugin (if not autoloaded):

(gdb) Plug load GEP

4. List installed plugins:

(gdb) Plug list

Supported Initialization Files

When loading a plugin, the manager looks for these files in order:

1. <plugin-name>.py
2. <plugin-name>.gdb
3. main.py
4. main.gdb
5. .gdbinit
6. gdbinit-<plugin-name>.py (e.g., gdbinit-gep.py)

Plugins Without a Standard Entry File

Some repositories do not provide a sourceable entry file at their root. A common example is koutheir/libcxx-pretty-printers, whose printers live in src/libcxx/v1/printers.py and must be registered with a function call. Use path + setup for these:

Plug.plug(
    "koutheir/libcxx-pretty-printers",
    path="src",
    setup="from libcxx.v1.printers import register_libcxx_printers\n"
          "register_libcxx_printers(None)",
)

The equivalent callable form:

def register_libcxx(plugin_dir):
    import sys
    from libcxx.v1.printers import register_libcxx_printers
    register_libcxx_printers(None)

Plug.plug("koutheir/libcxx-pretty-printers", path="src", setup=register_libcxx)

License

GPL

Inspiration

This project was inspired by vim-plug's simplicity and effectiveness for managing Vim plugins.

Contributing

Contributions are welcome! Please open issues or pull requests for any improvements, especially to the PlugCommand.complete function as noted in the source.