<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="introspection" xml:lang="ko">

  <info>
    <link type="guide" xref="index#specific-how-tos"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>라이브러리 코드에 GObject 인트로스펙션 지원</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>조성호</mal:name>
      <mal:email>shcho@gnome.org</mal:email>
      <mal:years>2016, 2017.</mal:years>
    </mal:credit>
  </info>

  <title>인트로스펙션</title>

  <synopsis>
    <title>요약</title>

    <p><link href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject 인트로스펙션</link>(‘GIR’로 약칭)은 C 코드에서 API를 뽑아내며 C 언어가 아닌 다른 언어의 바인딩, 기타 도구에서 원본 C 라이브러리 <link href="http://en.wikipedia.org/wiki/Type_introspection">인트로스펙션</link> 또는 <link href="http://en.wikipedia.org/wiki/Language_binding">래핑</link>하여 활용할 수 있게 바이너리 형식 라이브러리를 만들어내는 체계입니다. C 코드에 주석으로 남겨둔 문서의 주석 체계를 활용하여 코드 자체로부터 머신이 해독할 수 없는 API의 추가 정보를 도출합니다.</p>

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

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

  <section id="using-introspection">
    <title>인트로스펙션 활용</title>

    <p>인트로스펙션 활용 첫 단계는 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/AutotoolsIntegration#Method_1_-_Recommended_-_most_portable">여기</link> 절차의 1번 방식에 따른 빌드 시스템으로의 추가입니다. 인트로스펙션 기능성이 <link xref="#api-design">API 설계</link>에 영향을 주므로 프로젝트 초기에 미리 끝내야합니다.</p>

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

    <p>다음 단계는 <link xref="documentation#introspection-annotations">공용 API의 모든 부분의 문서 설명에 주석을 추가하는 일입니다</link>. 만약에 GIR 파일에 API 일부를 노출하면 안될 경우, <code>(skip)</code> 주석을 사용하십시오. 가용 주석을 설명하는 문서는 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">여기</link>에 있습니다.</p>

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

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

  <section id="api-design">
    <title>API 설계</title>

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

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

    <p>따라서, API는 인트로스팩션을 활용할 수 있게 설계해야하며, GIR 파일은 API를 작성한 대로 검사해야 합니다. GIR과 새 API이 일치하지 않으면 API에는 추가 주석이 필요하거나, (<link href="https://wiki.gnome.org/Projects/GObjectIntrospection/WritingBindingableAPIs#va_list"><code>va_list</code></link>의 경우와 마찬가지로)C 선언문을 바꿔야 할 수도 있습니다.</p>

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