Philip Withnall
philip.withnall@collabora.co.uk 2015

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

특별히 예외적으로, 이 문서의 예제 코드는 저작권자에 명시한 대로 어떠한 제한 없이 원하는 대로 복제, 수정, 배포할 수 있습니다.

라이브러리 코드에 GObject 인트로스펙션 지원
조성호
shcho@gnome.org 2016-2018.

# 인트로스펙션

#

        요약

           GObject
          introspection (abbreviated ‘GIR’) is a system which extracts APIs
          from C code and produces binary type libraries which can be used by non-C
          language bindings, and other tools, to
          introspect
          or wrap
          the original C libraries. It uses a system of annotations in documentation
          comments in the C code to expose extra information about the APIs which is
          not machine readable from the code itself.

        모든 공용 API, 즉 모든 라이브러리에서 쓸 수 있게 해야합니다. 프로그램 자체에서는 API를 노출하지 않으므로  프로그램에선 쓸 수 없습니다. 하지만 프로그램 코드의 문서 주석에 인트로스펙션 주석을 추가하여 문서에 명확히 해두는 것이 좋습니다.

          모든 라이브러리에 인트로스펙션을 활성화하십시오().
          g-ir-scanner 및 GIR 파일의 introspectable="0" 속성 설정 때문에 나타나는 경고에 주의하십시오().
          모든 문서 주석에 인트로스펙션 주석을 추가하십시오().
          시작 단계때부터 인트로스펙션할 수 있게 API를 설계하십시오().

# 인트로스펙션 활용

인트로스펙션 활용 첫 단계는 여기 절차의 1번 방식에 따른 빌드 시스템으로의 추가입니다. 인트로스펙션 기능성이 API 설계에 영향을 주므로 프로젝트 초기에 미리 끝내야합니다.

프로젝트에서 만든 .gir 파일과 .typelib 파일에 결과가 나타나야합니다. .gir 파일은 사람이 알아볼 수 있으며, API를 올바르게 인트로스펙션했을 때(GIR 컴파일 과정에서 일부 빠진 주석과 기타 문제에 대해 오류 메시지와 경고를 출력하긴 하지만) 직접 살펴볼 수 있습니다. `introspectable="0"` 속성을 설정한 API는 주석이 빠졌거나, 아니면 GIR 파일에 나타나지 않으므로 언어 바인딩에 나타나지 않습니다.

다음 단계는 공용 API의 모든 부분의 문서 설명에 주석을 추가하는 일입니다. 만약에 GIR 파일에 API 일부를 노출하면 안될 경우, `(skip)` 주석을 사용하십시오. 가용 주석을 설명하는 문서는 여기에 있습니다.

프로그램의 코드에 주석을 넣을 때, 바람직한 접근 방식은 상당한 양의 코드를 자체적으로 쪼개어, 내부 전용 편의 라이브러리로 만드는 방법입니다. 자체 API 참조 설명서는 문서 주석으로 만들 수 있습니다(see ). 이렇게 하면 라이브러리를 설치하지 않지만, 이 라이브러리를 설치한 프로그램과 연결합니다. 이런 자체 API 문서 접근 방식은 자체 코드 규모가 커져 찾아보기 어려워지는 큰 프로젝트에 특히 쓸 만합니다.

주석을 꼼꼼하게 달아둘 필요는 없습니다. GIR은 다양한 방식을 기반으로 적용하는 기본 주석 모음입니다(see ). 예를 들어, `const gchar*` 매개 변수는 `const` 수정자에 이미 `(transfer none)` 주석의 의미가 있으므로 굳이 적어둘 필요는 없습니다. 주석의 기본 의미는 숙달 대상입니다.

# API 설계

많은 주석을 달지 않고도 인트로스펙션을 활용할 수 있으려면, API에서는 표준 GObject 작명 규칙와 바인딩 처리 가능 API 코드 작성 규칙와 같은 몇가지 규칙을 따라야합니다. C 언어가 유연하기 때문에 이렇게 해야 합니다. 코드는 어떻게든 멋대로 작성할 수 있지만, 고수준 언어일 경우 이런 자율성을 용납하지 않습니다. 따라서 C API가, 좀 더 고수준의 언어인 것처럼 보이려면, 해당 언어에서 지원하는 동작에 맞춰야합니다.

이를테면, GIR에서는 함수 실행이 실패할 수 있음을 예상하여, 항상 마지막에 둘 매개변수로서 `GError**` 매개변수를 지니고 있습니다. GIR 탐색기에서는 GIR 파일에서 이 매개변수를 찾아 메서드의 예외 속성으로 자동 변환합니다. `GError*`를 직접 변환하거나, 마지막 함수 매개 변수가 아닐 경우에는 처리할 수 없습니다.

따라서, API는 인트로스팩션을 활용할 수 있게 설계해야하며, GIR 파일은 API를 작성한 대로 검사해야 합니다. GIR과 새 API이 일치하지 않으면 API에는 추가 주석이 필요하거나, (`va_list`의 경우와 마찬가지로)C 선언문을 바꿔야 할 수도 있습니다.

g-ir-scanner에서 이해할 수 없는 코드를 찾으면 경고를 출력합니다. Makefile.am 파일에서 `INTROSPECTION_SCANNER_ARGS`에 --warn-error, --warn-all를 전달하면 인트로스펙션을 활용할 수 없는 API임을 확인했을 때 컴파일에 실패합니다. 이 방법으로 새 API에서 인트로스펙션을 활용할 수 있는지 확인하기에 적극 추천합니다.