GDBmongo

Warnings

• gotcha GDB's embedded Python interpreter often uses the system's base Python installation, not necessarily a virtual environment from which GDB was launched. This can lead to `ImportError` if `gdbmongo` is installed only in a virtual environment.
  Fix: Ensure `gdbmongo` is installed in the Python environment GDB is linked against (typically the base system Python), or explicitly manage `sys.path` within your `.gdbinit` to include the virtual environment's site-packages. The provided quickstart snippet includes a conditional install attempt for specific toolchains.
• gotcha By default, `gdbmongo` pretty printer collections other than `gdbmongo-essentials` are disabled to prevent conflicts with pretty printers defined in the official `mongodb/mongo` repository.
  Fix: To enable additional pretty printers (e.g., `mongo_extras`), explicitly pass `True` to `gdbmongo.register_printers()` (e.g., `gdbmongo.register_printers(mongo_extras=True)`), or enable them later within GDB using `(gdb) enable pretty-printer global gdbmongo-mongo-extras`.
• gotcha Directly `import gdb` or attempting to use GDB-specific Python functionality from a standard Python script outside of the GDB process will fail with an `ImportError`. The `gdb` module is part of GDB's embedded Python interpreter.
  Fix: Always execute Python code that interacts with GDB's API (like `gdbmongo`) within GDB, typically by sourcing a Python script (`(gdb) source your_script.py`) or including it in your `.gdbinit` file.
• gotcha As a debugging tool closely tied to the MongoDB Server's internal structures, `gdbmongo`'s functionality can be sensitive to major changes in MongoDB Server versions. Unforeseen behavior or incorrect pretty printing may occur if `gdbmongo` is used with a significantly different MongoDB Server version than it was developed for.
  Fix: Refer to the `gdbmongo` project's documentation or changelog for specific compatibility notes regarding MongoDB Server versions. Regularly update `gdbmongo` to match the version of the MongoDB Server you are debugging to ensure optimal and correct functionality.

Install

• pip install gdbmongo Install via pip

Imports

• gdbmongo

  import gdbmongo

  The 'gdb' module is only available within GDB's embedded Python interpreter. For gdbmongo, you import 'gdbmongo' which then registers its functionality with GDB.
• register_printers

  gdbmongo.register_printers()

  Call this function within GDB's Python context (e.g., from .gdbinit) to enable the pretty printers.

Quickstart

To quickly integrate `gdbmongo` with GDB, add the provided Python snippet to your `~/.gdbinit` file. This script attempts to import `gdbmongo` and, if it fails, can optionally try to install it using `pip` within the GDB's Python environment (especially useful for specific toolchains). After import, it registers the essential pretty printers. You can then launch GDB and use commands like `(gdb) enable pretty-printer global gdbmongo-mongo-extras` to activate other collections.

# In your ~/.gdbinit file:
python
try:
    import gdbmongo
except ImportError:
    import sys
    # Example: Attempt to install gdbmongo if not found (e.g., in a specific toolchain Python)
    if sys.prefix.startswith('/opt/mongodbtoolchain/'): # Adjust path as needed for your environment
        import subprocess
        subprocess.run([sys.prefix + '/bin/python3', '-m', 'pip', 'install', 'gdbmongo'], check=True)
        import gdbmongo
    else:
        import warnings
        warnings.warn("Not attempting to install gdbmongo into non-MongoDB toolchain Python")

# Register printers if gdbmongo was successfully imported
if 'gdbmongo' in dir():
    gdbmongo.register_printers(essentials=True, stdlib=False, abseil=False, boost=False, mongo_extras=False)
end