# Aids for Debugging

## GDB

This repository contains a `.gdbinit` file that contains helper functions to aid debugging of data structures. GDB will load this file automatically if you have added the directory which contains the .gdbinit file to GDB’s auto-load safe-path, and you start GDB from the directory which holds the .gdbinit file.

You can see the safe-path with `show auto-load safe-path` on a GDB prompt. You can configure it by setting it in `~/.gdbinit` with:

    add-auto-load-safe-path /path/to/mongo-c-driver

If you haven’t added the path to your auto-load safe-path, or start GDB in another directory, load the file with:

    source path/to/mongo-c-driver/.gdbinit

The `.gdbinit` file defines the `printbson` function, which shows the contents of a `bson_t *` variable. If you have a local `bson_t`, then you must prefix the variable with a &.

An example GDB session looks like:

    (gdb) printbson bson
    ALLOC [0x555556cd7310 + 0] (len=475)
    {
        'bool' : true,
        'int32' : NumberInt("42"),
        'int64' : NumberLong("3000000042"),
        'string' : "Stŕìñg",
        'objectId' : ObjectID("5A1442F3122D331C3C6757E1"),
        'utcDateTime' : UTCDateTime(1511277299031),
        'arrayOfInts' : [
            '0' : NumberInt("1"),
            '1' : NumberInt("2")
        ],
        'embeddedDocument' : {
            'arrayOfStrings' : [
                '0' : "one",
                '1' : "two"
            ],
            'double' : 2.718280,
            'notherDoc' : {
                'true' : NumberInt("1"),
                'false' : false
            }
        },
        'binary' : Binary("02", "3031343532333637"),
        'regex' : Regex("@[a-z]+@", "im"),
        'null' : null,
        'js' : JavaScript("print foo"),
        'jsws' : JavaScript("print foo") with scope: {
            'f' : NumberInt("42"),
            'a' : [
                '0' : 3.141593,
                '1' : 2.718282
            ]
        },
        'timestamp' : Timestamp(4294967295, 4294967295),
        'double' : 3.141593
    }

## LLDB

This repository also includes a script that customizes LLDB’s standard `print` command to print a `bson_t` or `bson_t *` as JSON:

    (lldb) print b
    (bson_t) $0 = {"x": 1, "y": 2}

The custom `bson` command provides more options:

    (lldb) bson --verbose b
    len=19
    flags=INLINE|STATIC
    {
      "x": 1,
      "y": 2
    }
    (lldb) bson --raw b
    '\x13\x00\x00\x00\x10x\x00\x01\x00\x00\x00\x10y\x00\x02\x00\x00\x00\x00'

Type `help bson` for a list of options.

The script requires a build of libbson with debug symbols, and an installation of PyMongo. Install PyMongo with:

    python -m pip install pymongo

If you see “No module named pip” then you must install pip, then run the previous command again.

Create a file `~/.lldbinit` containing:

    command script import /path/to/mongo-c-driver/lldb_bson.py

If you see “bson command installed by lldb_bson” at the beginning of your LLDB session, you’ve installed the script correctly.

## Debug assertions

To enable runtime debug assertions, configure with `-DENABLE_DEBUG_ASSERTIONS=ON`.