디버깅 보조 도구

Qt Creator 는 Python 스크립트를 사용하여 디버거 백엔드(현재 GDB, LLDB 및 CDB 지원)에서 반환된 원시 메모리 내용과 유형 정보 데이터를 ‘로컬(Locals )’ 및 ‘식(Expressions )’ 뷰에서 사용자에게 표시되는 형식으로 변환합니다.

GDB의 프리티 프린터나 LLDB의 데이터 포맷터와 달리, Qt Creator 의 디버깅 헬퍼는 네이티브 디버깅 백엔드와 독립적입니다. 즉, Linux의 GDB, macOS의 LLDB, Windows의 CDB 또는 지원되는 세 가지 백엔드 중 적어도 하나가 사용 가능한 다른 플랫폼에서 동일한 코드를 사용할 수 있습니다.

시스템에 설치되어 있거나 애플리케이션이 사용하는 라이브러리에 링크된 기본 GDB 프리티 프린터를 사용하려면, Preferences > Debugger > GDB > Load system GDB pretty printers 로 이동하십시오. 자세한 내용은 GDB를 참조하십시오.

내장 디버깅 헬퍼 사용자 정의

내장 디버깅 헬퍼가 로드되고 완전히 초기화된 후 명령을 실행하도록 설정할 수 있습니다. 추가 디버깅 헬퍼를 로드하거나 기존 헬퍼를 수정하려면 Preferences > Debugger > Locals & Expressions 로 이동하여 Debugging Helper Customization 필드에 명령을 입력하십시오.

GDB 사용 중 신호 수신과 관련된 오류 메시지가 표시되면, 해당 신호를 처리하기 위한 GDB 명령어를 지정할 수 있습니다. 예를 들어, 다음과 같은 오류 메시지가 표시될 경우 GDB가 SIGSTOP 신호를 무시하도록 설정할 수 있습니다: The debugged process stopped because it received a signal from the operating system. Signal name: SIGSTOP.

GDB가 ‘ SIGSTOP ’ 신호를 처리하지 못하도록 하려면 ‘ Debugging Helper Customization ’ 필드에 다음 명령을 추가하십시오.

handle SIGSTOP nopass
handle SIGSTOP nostop

디버깅 중에 애플리케이션이 신호를 수신하는 즉시 메시지 상자를 표시하려면, ‘ Preferences ’ > ‘ Debugger ’ > ‘ GDB ’ > ‘ Show a message box when receiving a signal ’로 이동하십시오.

사용자 정의 디버깅 헬퍼 추가

사용자 정의 타입에 대한 디버깅 헬퍼를 추가하려면 컴파일할 필요 없이 몇 줄의 Python 코드만 추가하면 됩니다. 이 스크립트는 여러 버전의 Qt 또는 사용자 정의 라이브러리를 동시에 처리할 수 있습니다.

사용자 정의 타입에 대한 디버깅 헬퍼를 추가하려면, 디버거의 시작 파일(예: ~/.gdbinit 또는 ~/.lldbinit)에 디버깅 헬퍼 구현을 추가하거나, Preferences > Debugger > GDB 경로의 Additional Startup Commands 파일에 직접 지정하면 됩니다.

자신만의 데이터 유형에 대한 디버깅 헬퍼를 구현하려면, Qt 설치 디렉터리나 독립형 Qt Creator 설치 디렉터리에 있는 share/qtcreator/debugger/personaltypes.py 파일에 구현 코드를 넣으면 됩니다. macOS의 경우, 이 파일은 Qt Creator 애플리케이션 패키지에 포함되어 있으며, Contents/resources/debugger 폴더에 위치합니다.

personaltypes.py 파일에는 다음과 같은 예제 구현이 하나 포함되어 있습니다:

# def qdump__MapNode(d, value):
#    d.putValue("This is the value column contents")
#    d.putExpandable()
#    if d.isExpanded():
#        with Children(d):
#            # Compact simple case.
#            d.putSubItem("key", value["key"])
#            # Same effect, with more customization possibilities.
#            with SubItem(d, "data")
#                d.putItem("data", value["data"])

디버깅 헬퍼를 추가하려면:

1. share/qtcreator/debugger/personaltypes.py 파일을 열어 편집합니다. 예를 들어, Windows에서는 C:\Qt\Tools\QtCreator\share\qtcreator\debugger 폴더를 확인하십시오. macOS에서는 Qt Creator.app/Contents/resources/debugger를 확인하십시오.
2. personaltypes.py 파일의 맨 끝에 덤퍼 구현을 추가하십시오. 디버깅 헬퍼 구현에 대한 자세한 내용은 다음 섹션을 참조하십시오.
3. Qt Creator 설치를 업데이트할 때(예: Qt 설치 업데이트 시) personaltypes.py 파일이 덮어쓰이지 않도록 하려면, 이 파일을 파일 시스템 내 Qt Creator 설치 경로 외부의 안전한 위치로 복사한 다음, Preferences > Debugger > Locals & Expressions > Extra Debugging Helper 에서 해당 위치를 지정하십시오.

Qt Creator 에서 디버깅 세션을 시작하거나 디버거 로그(Debugger Log ) 뷰의 컨텍스트 메뉴에서 Reload Debugging Helpers 를 선택하면, 사용자 정의 디버깅 헬퍼가 personaltypes.py 에서 자동으로 불러옵니다.

디버깅 헬퍼 개요

디버깅 헬퍼의 구현은 일반적으로 단일 Python 함수로 구성되며, 이 함수의 이름은 qdump__NS__Foo 로 지정해야 합니다. 여기서 NS::Foo 은 검사 대상인 클래스 또는 클래스 템플릿입니다. :: 범위 해결 연산자는 이중 밑줄( __)로 대체된다는 점에 유의하십시오. 중첩된 네임스페이스도 사용할 수 있습니다. 템플릿 인자는 함수 이름 구성에 사용되지 않습니다.

예시:

• namespace Project { template<typename T> struct Foo {... } } 타입에 대한 디버깅 헬퍼를 구현하는 함수의 이름은 qdump__Project__Foo 입니다.
• std::__1::vector<T>::iterator 타입에 대한 디버깅 헬퍼를 구현하는 함수의 이름은 qdump__std____1__vector__iterator 입니다.

Qt Creator의 디버거 플러그인은 이 타입의 객체를 표시하고자 할 때마다 이 함수를 호출합니다. 이 함수에는 다음과 같은 매개변수가 전달됩니다:

• d Dumper 타입의 객체로, 현재 설정을 포함하며 및 뷰의 일부를 나타내는 객체를 구성할 수 있는 기능을 제공합니다. Locals Expressions
• value Value 타입으로, gdb.Value 또는 lldb.SBValue 중 하나를 감싸고 있습니다.

qdump__* 함수는 Locals 및 Expressions 뷰에서 해당 객체와 그 자식 객체들의 표시를 구성하는 데 사용되는 특정 정보를 Dumper 객체에 전달해야 합니다.

예시:

def qdump__QFiniteStack(d, value):
    alloc = value["_alloc"].integer()
    size = value["_size"].integer()
    d.putItemCount(size)
    if d.isExpanded():
        d.putArrayData(value["_array"], size, value.type[0])

디버깅 헬퍼에서 객체의 기본 인스턴스에 접근하려면 value.base() 함수를 사용하거나 다음 예제 코드를 활용하십시오:

def qdump__A(d, value):
   t = value.members(True)[0].type
   dptr, base_v = value.split('p{%s}' % t.name)
   d.putItem(base_v)

디버깅 헬퍼는 유형 이름이 정규 표현식과 일치할 때마다 호출되도록 설정할 수 있습니다. 이를 위해서는 디버깅 헬퍼 함수 이름이 qdump__ (밑줄 두 개)로 시작해야 합니다. 또한, 이 함수에는 regex 라는 세 번째 매개변수가 있어야 하며, 이 매개변수의 기본값은 유형 이름이 일치해야 하는 정규 표현식을 지정해야 합니다.

예를 들어, Nim 0.12 컴파일러는 컴파일하는 모든 제네릭 시퀀스에 TY1 및 TY2 과 같은 인공적인 이름을 할당합니다. Qt Creator 에서 이를 시각화하려면 다음 디버깅 헬퍼를 사용할 수 있습니다:

def qdump__NimGenericSequence__(d, value, regex = "^TY.*$"):
    size = value["Sup"]["len"]
    base = value["data"].dereference()
    typeobj = base.dereference().type
    d.putArrayData(base, size, typeobj)

디버깅 헬퍼 구현

디버깅 헬퍼는 표시된 데이터 항목에 대한 설명을 GDB/MI 및 JSON과 유사한 형식으로 생성합니다.

Locals 및 Expressions 뷰의 각 행에 대해, 다음과 같은 문자열을 생성하여 디버거 플러그인으로 전달해야 합니다.

{ iname='some internal name',           # optional
  address='object address in memory',   # optional
  name='contents of the name column',   # optional
  value='contents of the value column',
  type='contents of the type column',
  numchild='number of children',        # zero/nonzero is sufficient
  children=[              # only needed if item is expanded in view
     {iname='internal name of first child',
       },
     {iname='internal name of second child',
       },

  ]}

iname 필드의 값은 객체의 내부 이름으로, 뷰 내 객체 표현의 위치에 해당하는 식별자 목록을 점(.)으로 구분하여 구성됩니다. 이 값이 없는 경우, 상위 객체의 iname 값에 점(.)과 순차 번호를 연결하여 생성됩니다.

name 필드의 값은 뷰의 Name 열에 표시됩니다. 지정되지 않은 경우, 대신 괄호 안에 담긴 단순한 숫자가 사용됩니다.

이 형식이 안정적으로 유지된다고 보장할 수 없으므로, 와이어 형식을 직접 생성하지 말고 Python Dumper 클래스의 추상화 계층, 특히 Dumper 클래스 자체와 Dumper:Value 및 Dumper:Type 추상화를 사용하는 것이 강력히 권장됩니다. 이들은 ` iname ` 및 ` addr ` 필드를 처리하고, 단순 타입의 자식 요소, 참조, 포인터, 열거형, 알려진 및 알려지지 않은 구조체를 다룰 수 있는 완전한 프레임워크를 제공하며, 일반적인 상황을 처리하기 위한 몇 가지 편리한 함수도 포함하고 있습니다.

CDB를 디버거 백엔드로 사용할 때, ‘ Preferences ’ > ‘ Debugger ’ > ‘ CDB ’ > ‘ Use Python dumper ’을 선택하여 Python 덤퍼를 활성화할 수 있습니다.

다음 섹션에서는 qtcreator\share\qtcreator\debugger\dumper.py 에 정의된, 널리 사용되는 덤퍼 클래스와 멤버 중 일부를 설명합니다.

Dumper 클래스

Dumper 클래스에는 일반적인 관리 기능, 저수준 기능 및 편의 함수가 포함되어 있습니다:

• putItem(self, value) - 기본 유형, 참조, 포인터 및 열거형을 직접 처리하고, 복합 유형의 기본 클래스 및 클래스 멤버를 반복 처리하며, 적절한 경우 qdump__* 함수를 호출하는 핵심 함수입니다.
• putIntItem(self, name, value) - 다음 코드와 동일합니다:

  with SubItem(self, name):
      self.putValue(value)
      self.putType("int")

• putBoolItem(self, name, value) - 다음과 동일합니다:

  with SubItem(self, name):
      self.putValue(value)
      self.putType("bool")

• putCallItem(self, name, rettype, value, func, *args) - 디버거 백엔드를 사용하여 ` func ` 함수 호출을 통해 ` rettype `를 반환하고, 이를 ` value `로 지정된 값에 할당하며, 결과 항목을 출력합니다.

  네이티브 호출은 매우 강력하며, 예를 들어 디버깅 대상 프로세스 내의 기존 디버깅 또는 로깅 기능을 활용할 수 있습니다. 그러나 다음과 같은 이유로, 통제된 환경에서만, 그리고 데이터에 접근할 다른 방법이 없을 때에만 사용해야 합니다:

  • 코드를 직접 실행하는 것은 위험합니다. 디버깅 중인 프로세스의 권한으로 네이티브 코드를 실행하므로, 디버깅 중인 프로세스를 손상시킬 뿐만 아니라 디스크나 네트워크에 접근할 가능성도 있습니다.
  • 코어 파일을 검사할 때는 호출을 실행할 수 없습니다.
  • 디버거에서 호출을 설정하고 실행하는 데 많은 비용이 듭니다.
• putArrayData(self, address, itemCount, type) - address 에 위치한 배열형 객체의 type 타입으로, itemCount 에 지정된 개수의 자식 객체를 생성합니다.
• putSubItem(self, component, value) - 다음과 동일합니다:

  with SubItem(self, component):
      self.putItem(value)

  중첩된 함수 호출로 인해 발생하는 예외는 모두 처리되며, putItem 에서 생성된 모든 출력은 다음의 출력으로 대체됩니다:

  except RuntimeError:
      d.put('value="<invalid>",type="<unknown>",numchild="0",')

• put(self, value) - 출력 문자열에 직접 내용을 추가하는 저수준 함수입니다. 이는 출력을 추가하는 가장 빠른 방법이기도 합니다.
• putField(self, name, value) - ` name='value' ` 필드를 추가합니다.
• childRange(self) - 현재 Children 범위에서 지정된 자식 범위를 반환합니다.
• putItemCount(self, count) - value='<%d items>' 필드를 출력에 추가합니다.
• putName(self, name) - ` name='' ` 필드를 추가합니다.
• putType(self, type, priority=0) - ` type `가 부모의 기본 자식 유형과 일치하거나, 현재 항목에 대해 ` putType `가 이미 호출되었고 ` priority`의 값이 더 큰 경우를 제외하고, ` type=''` 필드를 추가합니다.
• putBetterType(self, type) - 마지막으로 기록된 type 을 재정의합니다.
• putExpandable(self) - 현재 값에 대한 자식 항목의 존재 여부를 알립니다. 기본값은 자식 항목이 없는 것입니다.
• putNumChild(self, numchild) - 현재 값에 대한 자식 항목의 존재(numchild > 0) 또는 부재를 알립니다.
• putValue(self, value, encoding = None) - 파일 value='' 을 추가하고, 선택적으로 필드 valueencoding='' 을 뒤따르게 합니다. value 는 전적으로 영숫자로만 구성된 문자열로 변환 가능해야 합니다. 실제 값이 영숫자만 허용되는 요건을 충족하기 위해 어떤 방식으로든 인코딩되어야 하는 경우, encoding 매개변수를 사용하여 인코딩 방식을 지정할 수 있습니다. encoding 매개변수는 codec:itemsize:quote 형식의 문자열이며, 여기서 codec 은 latin1, utf8, utf16, ucs4, int 또는 float 중 하나입니다. itemsize 은 codec 에 의해 암시되지 않는 경우 객체의 기본 구성 요소 크기를 제공하며, quote 은 표시 시 값을 따옴표로 묶을지 여부를 지정합니다.

  예시:

  # Safe transport of quirky data. Put quotes around the result.
  d.putValue(d.hexencode("ABC\"DEF"), "utf8:1:1")

• putStringValue(self, value) - QString 를 인코딩하고, 올바른 encoding 설정을 적용하여 putValue 를 호출합니다.
• putByteArrayValue(self, value) - QByteArray 를 인코딩하고, 올바른 encoding 설정을 적용하여 putValue 를 호출합니다.
• isExpanded(self) - 뷰에서 현재 항목이 확장되어 있는지 확인합니다.
• createType(self, pattern, size = None) - Dumper.Type 객체를 생성합니다. 정확한 동작은 pattern 에 따라 다릅니다.
  • pattern 가 잘 알려진 타입의 이름과 일치하면, 해당 타입을 설명하는 Dumper.Type 객체가 반환됩니다.
  • pattern 가 네이티브 백엔드에 알려진 타입의 이름인 경우, 반환된 타입은 해당 네이티브 타입을 설명합니다.
  • 그렇지 않은 경우, pattern 는 구조체의 필드를 설명하는 일련의 항목을 다음과 같이 해석하여 유형 설명을 구성하는 데 사용됩니다. 필드 설명은 다음과 같이 하나 이상의 문자로 구성됩니다:
    • q - 부호 있는 8바이트 정수 값
    • Q - 부호 있는 8바이트 정수 값
    • i - 부호 있는 4바이트 정수 값
    • I - 부호 없는 4바이트 정수 값
    • h - 부호 있는 2바이트 정수
    • H - 부호 없는 2바이트 정수
    • b - 부호 있는 1바이트 정수
    • B - 부호 없는 1바이트 정수
    • d - 8바이트 IEEE 754 부동소수점 값
    • f - 4바이트 IEEE 754 부동소수점 값
    • p - 포인터, 즉 대상 아키텍처에 따라 적절한 크기의 부호 없는 정수 값
    • @ - 적절한 패딩. 크기는 앞뒤 필드와 대상 아키텍처에 따라 결정됩니다
    • <n>s - <n>바이트 크기의 블롭(blob)으로, 암시적 정렬은 1입니다
    • <typename> - 이름이 Dumper.Type 인 함수에 의해 결정된 적절한 크기와 정렬을 가진 블롭 typename

Dumper.Type 클래스

Dumper.Type 클래스는 데이터 조각의 유형을 설명하며, 일반적으로 C++ 클래스나 구조체, 구조체에 대한 포인터, 또는 정수형이나 부동소수점형과 같은 기본 유형을 나타냅니다.

타입 객체, 즉 ` Dumper.Type ` 클래스의 인스턴스는 디버거 백엔드에 의해 생성될 수 있으며, 일반적으로 디버깅 대상 바이너리에 내장되거나 함께 제공되는 디버그 정보를 평가하여 생성되거나, 디버깅 헬퍼에 의해 즉석에서 생성될 수 있습니다.

Qt Creator 대부분의 Qt 클래스에 대해 즉석에서 타입 정보를 제공하므로, 객체 내부 구조를 분석하기 위해 Qt의 디버그 빌드를 사용할 필요가 없습니다.

Dumper.Type 클래스에는 다음과 같이 널리 사용되는 멤버 함수가 있습니다:

• name - 이 유형의 이름을 문자열로 반환하며, 유형이 익명인 경우에는 None 을 반환합니다.
• size(self) - 이 타입의 객체 크기를 바이트 단위로 반환합니다.
• bitsize(self) - 이 유형의 객체 크기를 비트 단위로 반환합니다.
• alignment(self) - 이 타입의 객체에 필요한 정렬 크기를 바이트 단위로 반환합니다.
• deference(self) - 포인터 유형인 경우 해당 포인터가 가리키는 객체의 유형을 반환하고, 그렇지 않은 경우 ` None `를 반환합니다.
• pointer(self) - 이 타입으로 간접 참조할 수 있는 포인터 타입을 반환합니다.
• target(self) - 배열 유형의 경우 항목 유형을, 포인터 및 참조의 경우 해참조된 유형을 반환하는 편의 함수입니다.
• stripTypedefs(self) - 이 유형이 별칭인 경우, 기본 유형을 반환합니다.
• templateArgument(self, position, numeric = False) - 이 유형이 템플릿 유형인 경우, ` position ` 위치에 있는 템플릿 매개변수를 반환합니다. ` numeric `가 ` True`인 경우, 해당 매개변수를 정수 값으로 반환합니다.
• fields(self) - 이 타입의 기본 클래스와 데이터 멤버를 설명하는 Dumper:Fields 목록을 반환합니다.

Dumper.Field 클래스

Dumper.Field 클래스는 타입 객체의 기본 클래스나 데이터 멤버를 설명합니다:

• isBaseClass - 기본 클래스와 데이터 멤버를 구분합니다.
• fieldType(self) - 이 기본 클래스 또는 데이터 멤버의 타입을 반환합니다.
• parentType(self) - 소유 유형을 반환합니다.
• bitsize(self) - 이 필드의 크기를 비트 단위로 반환합니다.
• bitpos(self) - 소유 타입 내에서 이 필드의 오프셋을 비트 단위로 반환합니다.

Dumper.Value 클래스

Dumper.Value 클래스는 C++ 클래스 인스턴스나 기본 데이터 유형과 같은 데이터 조각을 설명합니다. 또한 파일 내용, 비연속 객체, 컬렉션 등 메모리에 직접적으로 표현되지 않는 인공적인 항목을 설명하는 데에도 사용할 수 있습니다.

Dumper.Value 에는 항상 연관된 Dumper.Type 가 있습니다. 값의 실제 데이터를 나타내는 두 가지 주요 표현은 다음과 같습니다:

• Python 버퍼 프로토콜을 따르는 Python 객체(예: Python memoryview) 또는 bytes 객체. size() 는 이 값의 타입 크기와 일치해야 합니다.
• 현재 주소 공간 내 객체의 시작 지점을 가리키는 포인터를 나타내는 정수형 값. 객체의 크기는 해당 타입의 size() 에 의해 결정됩니다.

Dumper.Value 에 대한 디버거 헬퍼를 생성할 때는 일반적으로 이 객체의 내부 표현에 대한 지식이 필요하지 않습니다.

Dumper.Value 클래스의 멤버 함수와 속성은 다음과 같습니다:

• integer(self) - 이 값을 적절한 크기의 부호 있는 정수 값으로 해석한 결과를 반환합니다.
• pointer(self) - 이 값을 현재 주소 공간 내의 포인터로 해석한 결과를 반환합니다.
• members(self, includeBases) - 이 값의 기본 객체와 데이터 멤버를 나타내는 ` Dumper.Value ` 객체 목록을 반환합니다.
• dereference(self) - 포인터를 나타내는 값의 경우, 참조 해제된 값을 반환하고, 그 외의 경우에는 ` None ` 객체를 반환합니다.
• cast(self, type) - 이 값과 동일한 데이터를 가지되, 유형이 ` type`인 값을 반환합니다.
• address(self) - 이 값이 현재 주소 공간 내의 연속된 영역으로 구성되어 있는 경우 해당 주소의 주소를 반환하고, 그렇지 않은 경우에는 ` None `를 반환합니다.
• data(self) - 이 값의 데이터를 Python bytes 객체로 반환합니다.
• split(self, pattern) - 이 값의 데이터로부터 pattern 에 따라 생성된 값들의 리스트를 반환합니다. 허용되는 패턴은 Dumper.createType 와 동일합니다.
• dynamicTypeName(self) - 이 값이 기본 클래스 객체인 경우, 이 값의 동적 유형 이름을 가져오려고 시도합니다. 불가능할 경우 ` None `를 반환합니다.

자식 및 SubItem 클래스

데이터가 초기화되지 않았거나 손상된 경우 자식 항목을 생성하려는 시도로 인해 오류가 발생할 수 있습니다. 이러한 상황에서 원활하게 복구하려면 Children 및 SubItem 컨텍스트 관리자를 사용하여 중첩된 항목을 생성하십시오.

Children 생성자 __init__(self, dumper, numChild = 1, childType = None, childNumChild = None, maxNumChild = None, addrBase = None, addrStep = None) 는 하나의 필수 인자와 여러 개의 선택적 인자를 사용합니다. 필수 인자는 현재 Dumper 객체를 가리킵니다. 선택적 인자를 사용하여 자식 항목의 수 numChild 와 각 자식 항목의 유형 childType_ 및 childNumChild_ 를 지정할 수 있습니다. maxNumChild 가 지정되면 해당 수만큼의 자식 항목만 표시됩니다. 이는 그렇지 않을 경우 지나치게 오랜 시간이 소요될 수 있는 컨테이너 내용을 덤프할 때 사용해야 합니다. addrBase 및 addrStep 매개변수를 사용하면 자식 덤퍼가 생성하는 데이터의 양을 줄일 수 있습니다. n번째자식 항목의 주소가 addrBase + n * addrStep과 일치하는 경우, 해당 항목의 주소 출력이 생략됩니다.

예시:

if d.isExpanded():
    with Children(d):
        with SubItem(d):
            d.putName("key")
            d.putItem(key)
        with SubItem(d):
            d.putName("value")
            d.putItem(value)

다음과 같이 더 편리하게 작성할 수 있다는 점에 유의하십시오:

d.putNumChild(2)
if d.isExpanded():
    with Children(d):
        d.putSubItem("key", key)
        d.putSubItem("value", value)