Skip to content

README.md

Latest commit

 

History

History
174 lines (127 loc) · 4.48 KB

README.md

File metadata and controls

174 lines (127 loc) · 4.48 KB
Raw

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()
  1. Install the plugins:
(gdb) Plug update
  1. Manually load a plugin (if not autoloaded):
(gdb) Plug load GEP
  1. 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.