Debugging with LLDB

A debugger can be used to inspect the state of an application in the event of a crash.

Compile Debug Build

How to make a debug build depends on the build system used:

• For Linux/macOS set: CMAKE_BUILD_TYPE=Debug in CMakeCache.txt
• For Visual Studio, set the Release Configuration to Debug

Run LLDB

Start LLDB by changing the working directory to the location of your new debug build and typing the following:

lldb ./blender

Then to start Blender, type:

run

Now make Blender crash. Blender will freeze, so switch to the LLDB prompt. Get a backtrace by typing:

bt

A more complete backtrace can be printed using:

bt all

For more information, see this guide: LLDB Tutorial.

Pretty Printing

By default, LLDB does not know how to print many Blender core types such as blender::float4 in a good way. The Blender source code contains a bunch of pretty printers that can be registered in LLDB which simplify debugging.

To register those pretty printers add the following line to a ~/.lldbinit file. Everything in this file is run by LLDB when it is started. Make to use the correct file path if the source code is elsewhere.

command source ~/blender-git/blender/tools/debug/lldb/blender_lldb_formater.lldb

As an example, this is how a blender::float2 is printed with and without pretty printers.

# With
print cam.equirect_scale

(blender::float2) float2{0, 0}

# Without
print cam.equirect_scale

(blender::float2) cam.equirect_scale = {
  blender::vec_struct_base<float, 2, true> = {
     = {
      debug_values_ = {
        __elems_ = ([0] = 0, [1] = 0)
      }
       = {
        x = 0
         = {
           = (y = 0)
          yy = {
            values_ = {
              __elems_ = ([0] = 0)
            }
          }
          yyy = {
            values_ = {
              __elems_ = ([0] = 0)
            }
          }
          yyyy = {
            values_ = {
              __elems_ = ([0] = 0)
            }
          }
        }
      }
       = {
        xx = {
          values_ = {
            __elems_ = ([0] = 0)
          }
        }
        xxx = {
          values_ = {
            __elems_ = ([0] = 0)
          }
        }
        xxxx = {
          values_ = {
            __elems_ = ([0] = 0)
          }
        }
        xy = {
          values_ = {
            __elems_ = ([0] = 0, [1] = 0)
          }
        }
        yx = {
          values_ = {
            __elems_ = ([0] = 0, [1] = 0)
          }
        }
        xyxy = {
          values_ = {
            __elems_ = ([0] = 0, [1] = 0)
          }
        }
      }
    }
  }
}