gnome-devel-docs master - en to ko translation catalogue (829 entries)

note: (itstool) path: info/desc
en: Other style guides and books about organizing free software projects
ko: 자유 소프트웨어 프로젝트

note: (itstool) path: page/title
en: Additional Materials
ko: 추가 자료

note: (itstool) path: page/p
en: Here we give you links to other materials that you may want to read. These will teach you a lot about how to work on large distributed teams of free software developers, and about good programming style in general.
ko: 여러분이 읽어볼만한 다른 링크를 드리겠습니다. 자유 소프트웨어 개발자로 거대 배포팀에서 일하는 방법, 바람직한 프로그래밍 방법에 대해 일반적인 많은 내용을 담고 있습니다.

note: (itstool) path: item/p
en: <link href="http://producingoss.com/">Producing Open Source Software</link>, by Karl Fogel. This is a truly excellent book of good practices that free software projects should follow. This is about <em>social aspects</em> of the project: how to treat contributors, how to organize and moderate communication, how to deal with non-profit foundations. If you ask yourself at any time, "how should I deal with $human_situation in the project?", this book may provide the answer.
ko: Karl Fogel 저, <link href="http://producingoss.com/">Producing Open Source Software</link>. 자유 소프트웨어를 작성하면서 따라야 할 좋은 습관을 설명하는 정말 뛰어난 책입니다. 프로젝트의 <em>참여자 집단</em> 관점에서, 기여자를 대하는 방법, 어떻게 조직을 구성하고 의사소통을 진행하는지, 비영리 재단과 접촉하는 방법을 다룹니다. 언제든지 자신에게 "프로젝트에서 $human_situation을 어떻게 다루어야 하는가?"를 묻는다면, 이 책에서 답을 줄 수도 있습니다.

note: (itstool) path: item/p
en: <link href="http://www.gnu.org/prep/standards/">GNU Coding Standards</link>. This is an old document, but it still has lots of excellent advice. It talks about C coding style, issues when dealing with plug-in systems, common option names for command-line programs, conventions for Makefiles, and some very GNU-ish details like using Texinfo for documentation.
ko: <link href="http://www.gnu.org/prep/standards/">GNU 코드 작성 표준</link>. 오래된 문서지만, 여전히 최고의 설명이 많이 있습니다. C 코드 작성 방식, 플러그인 시스템 처리 문제, 명령행 프로그램의 일반 옵션 이름, Makefile 작성 형식, 코드 문서 작성시 Texinfo 활용 예시 같은 상당히 GNU스러운 자세한 설명이 있습니다.

note: (itstool) path: item/p
en: <link href="https://www.kernel.org/doc/Documentation/process/coding-style.rst"> Linux Kernel Coding Style</link>. Explains the rationale for "big indentation", brace placement, concise but unambiguous naming, and centralized exit of functions.
ko: <link href="https://www.kernel.org/doc/Documentation/process/coding-style.rst">Linux Kernel Coding Style</link>. "전반적인 들여쓰기"의 근거, 중괄호 위치, 명확하고 분명한 이름 부여 방식, 한 곳에서 함수 실행을 빠져나가는 방식을 설명합니다.

note: (itstool) path: info/desc
en: Backwards compatibility in APIs
ko: API 하위 호환성

note: (itstool) path: page/title
en: API stability
ko: API 안정성

note: (itstool) path: synopsis/title
en: Summary
ko: 요약

note: (itstool) path: item/p
en: Define API stability guarantees for your project. (<link xref="#stability"/>)
ko: 프로젝트의 API 안정성 보증을 정의합니다. (<link xref="#stability"/>)

note: (itstool) path: item/p
en: Ensure version numbers are changed as appropriate when API changes. (<link xref="#versioning"/>)
ko: API를 바꿀 때 적당한 버전 숫자로 바꾸었는지 확인합니다. (<link xref="#versioning"/>)

note: (itstool) path: section/title
en: API and ABI
ko: API와 ABI

note: (itstool) path: section/p
en: At a high level, an API – <em>Application Programming Interface</em> – is the boundary between two components when developing against them. It is closely related to an ABI – <em>Application Binary Interface</em> – which is the boundary at runtime. It defines the possible ways in which other components can interact with a component. More concretely, this normally means the C headers of a library form its API, and compiled library symbols its ABI. The difference between an API and ABI is given by compilation of the code: there are certain things in a C header, such as <code>#define</code>s, which can cause a library’s API to change without changing its ABI. But these differences are mostly academic, and for all practical purposes, API and ABI can be treated interchangeably.
ko: 상위 계층의 API(<em>Application Programming Interface</em>)는 API 및 ABI를 개발할 때 두 요소 간의 경계선상에 있고, 실행 시점에 따른 ABI(<em>Application Binary Interface</em>)와 밀접한 관계가 있습니다. ABI는 서로 동작할 수 있는 구성 요소의 관계를 정합니다. 좀 더 확실하게 말하자면, 라이브러리의 C 헤더가 API를 구성하고, 컴파일한 라이브러리는 ABI를 규정합니다. API와 ABI의 차이점은 코드 컴파일의 차이입니다. <code>#define</code>와 같은 C 헤더의 구성 요소는 ABI를 바꾸지 않고 라이브러리의 API를 바꿀 수 있습니다. 허나, 주로 이론적 차이가 있으며 대부분의 실제 목적에 있어서는 API와 ABI를 서로 바꾸어가며 생각할 수 있습니다.

note: (itstool) path: section/p
en: Examples of API-incompatible changes to a C function would be to add a new parameter, change the function’s return type, or remove a parameter.
ko: API 비호환성에 대해, 새 매개변수를 추가하도록 C 함수를 바꾸거나, 함수의 반환 형식을 바꾼다든지, 매개변수를 제거하는 예를 들 수 있습니다.

note: (itstool) path: section/p
en: However, many other parts of a project can form an API. If a daemon exposes itself on D-Bus, the interfaces exported there form an API. Similarly, if a C API is exposed in higher level languages by use of GIR, the GIR file forms another API — if it changes, any higher level code using it must also change.
ko: 하지만, 대부분의 프로젝트에서는 API를 구성할 수 있습니다. 데몬 자체를 D-Bus에 노출한다면 API를 구성하도록 인터페이스를 내보냅니다. 동일한 관점에서, C API를 GIR로 고 수준 언어에 노출한다면, GIR 파일에서 다른 API를 구성합니다. 이게 바뀌면 API를 사용하는 고 수준 언어 코드도 바꿔야합니다.

note: (itstool) path: section/p
en: Other examples of more unusual APIs are configuration file locations and formats, and GSettings schemas. Any changes to these could require code using your library to change.
ko: 좀 더 드문 API 예를 들자면, 설정 파일 위치, 설정 파일 형식, GSettings 스키마가 있습니다. 이 설정의 값을 바꾸면 라이브러리를 사용하는 코드를 바꿔야 할 수 있습니다.

note: (itstool) path: section/title
en: Stability
ko: 안정성

note: (itstool) path: section/p
en: API stability refers to some level of guarantee from a project that its API will only change in defined ways in the future, or will not change at all. Generally, an API is considered ‘stable’ if it commits to backwards-compatibility (defined below); but APIs could also commit to being unstable or even forwards-compatible. The purpose of API stability guarantees is to allow people to use your project from their own code without worrying about constantly updating their code to keep up with API changes. Typical API stability guarantees mean that code which is compiled against one version of a library will run without problems against all future versions of that library with the same major version number — or similarly that code which runs against a daemon will continue to run against all future versions of that daemon with the same major version number.
ko: API 안정성이란 프로젝트 API를 나중에 지정한 방식으로 바꾸거나 바꾸지 않을 프로젝트 일부 레벨의 보장을 의미합니다. 보통 API가 `안정적`이다 라고 한다면 (아래에 정의한 바와 같이) 하위 호환성을 지키며 커밋했을 경우입니다. 하지만 API에는 불안정하거나 상위 버전 호환성을 지니는 내용이 들어갈 수도 있습니다. API 안정성의 목적은 API가 바뀌어도 코드를 꾸준히 업데이트 하는 일을 걱정하지 않고 있는 코드 자체만으로 사람이 사용할 수 있게 보장하는 것입니다. 보통 API 안정성은 어떤 버전의 라이브러리에 대해 컴파일한 코드가 동일한 주 버전을 지닌 이후 버전의 라이브러리에서도 문제없이 동작함을 의미하거나, 동일한 주 버전의 데몬이 앞으로 나올 버전에서도 계속 동작하는 코드와 비슷한 의미를 지니고 있습니다.

note: (itstool) path: section/p
en: It is possible to apply different levels of API stability to components within a project. For example, the core functions in a library could be stable, and hence their API left unchanged in future; while the newer, less core functions could be left unstable and allowed to change wildly until the right design is found, at which point they could be marked as stable.
ko: 프로젝트에서 구성 요소에 대해 제각기 다른 수준의 API 안정성을 적용할 수 있습니다. 예를 들어 라이브러리의 핵심 함수는 안정적이어야 하며, 나중에도 API를 바꾸지 않은 상태로 두어야 합니다. 반면에 덜 핵심적이며 새로운 함수는 불완전한 상태로 둘 수 있고, 적절한 설계 관점에 도달하여 안정적인 상태로 간주하기 전까지 바꿀 수 있습니다.

note: (itstool) path: section/p
en: Several types of stability commonly considered:
ko: 보통 몇가지 안정성 형식을 고려합니다:

note: (itstool) path: item/title
en: Unstable
ko: 불안정

note: (itstool) path: item/p
en: The API could change or be removed in future.
ko: API를 바꾸거나 나중에 제거할 수 있습니다.

note: (itstool) path: item/title
en: Backwards compatible
ko: 하위 호환성

note: (itstool) path: item/p
en: Only changes which permit code compiled against the unmodified API to continue running against the modified API are allowed (for example, functions cannot be removed).
ko: 수정한 API에서도 수정하지 않은 API에서 컴파일한 코드를 실행할 수 있을 경우(예: 함수는 제거할 수 없음)에만 바꿉니다.

note: (itstool) path: item/title
en: Forwards compatible
ko: 상위 호환성

note: (itstool) path: item/p
en: Only changes which permit code compiled against the modified API to run against the unmodified API are allowed (for example, functions cannot be added).
ko: 수정하지 않은 API에서도 수정한 API에서 컴파일한 코드를 실행할 수 있을 경우(예: 함수를 추가할 수 없음)에만 바꿉니다.

note: (itstool) path: item/title
en: Totally stable
ko: 완전 안정성

note: (itstool) path: item/p
en: No changes are allowed to the API, only to the implementation.
ko: API를 어떤식으로도 바꿀 수 없으며 구현 기능 바꾸기에 한정합니다.

note: (itstool) path: section/p
en: Typically, projects commit to backwards-compatibility when they say an API is ‘stable’. Very few projects commit to total stability because it would prevent almost all further development of the project.
ko: 일반적으로, API가 ‘안정적’이다 라고 한다면, 하위 호환성을 지닌 채로 프로젝트를 커밋합니다. 극히 일부 프로젝트의 경우 전체적인 안정성을 지닌 채로 커밋하는데 대부분의 전반적인 프로젝트를 앞으로 더 개발하지 못하게 하기 때문입니다.

note: (itstool) path: section/title (itstool) path: page/title
en: Versioning
ko: 버전 부여

note: (itstool) path: section/p
en: API stability guarantees are strongly linked to project versioning; both package versioning and libtool versioning. Libtool versioning exists entirely for the purpose of tracking ABI stability, and is explained in detail on the <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> or <link xref="versioning"/>.
ko: API 안정성은 프로젝트 버전 부여와 밀접한 연관성이 있습니다. 여기서 말하는 버전 부여는 패키지 버전 부여와 libtool 버전 부여를 둘 다 지칭합니다. libtool 버전 부여는 ABI 안정성을 추적하려는 목적으로 존재하며, 자세한 내용은 <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> 또는 <link xref="versioning"/>에서 설명합니다.

note: (itstool) path: section/p
en: Package versioning (<em>major.minor.micro</em>) is strongly linked to API stability: typically, the major version number is incremented when backwards-incompatible changes are made (for example, when functions are renamed, parameters are changed, or functions are removed). The minor version number is incremented when forwards-incompatible changes are made (for example, when new public API is added). The micro version number is incremented when code changes are made without modifying API. See <link xref="versioning"/> for more information.
ko: 패키지 버전 부여(<em>major.minor.micro</em>)는 API 안정성과 밀접하게 연결됩니다. 보통 주 버전은 하위 비호환 변경 사항(함수 이름을 바꾸었다거나, 매개변수를 바꾸었다거나, 함수를 제거했을 경우)이 있을 경우 증가합니다. 부 버전은 상위 비호환 변경 사항(새 공개용 API 추가)이 있을 때 증가합니다. 세부 버전은 API를 수정하지 않는 선에서 코드가 바뀌었을 때 증가합니다. 자세한 내용은 <link xref="versioning"/> 링크를 참고하십시오.

note: (itstool) path: section/p
en: API versioning is just as important for D-Bus APIs and GSettings schemas (if they are likely to change) as for C APIs. See the <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">documentation on D-Bus API versioning</link> for details.
ko: API 버전 부여는 D-Bus API와 GSettings 스키마(를 바꿀 것 같다면)에게 C API 만큼 중요합니다. 자세한 내용은 <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API 버전 부여 참고 문서</link>를 참고하십시오.

note: (itstool) path: section/p
en: For GIR APIs, their stability typically follows the C API stability, as they are generated from the C API. One complexity is that their stability additionally depends on the version of gobject-introspection used in generating the GIR, but recent versions have not changed much so this is not a major concern.
ko: GIR API는 C API로 만들기 때문에 GIR API의 안정성은 C API 안정성을 보통 따릅니다. 한가지 복잡한 점이 있다면 GIR API의 안정성은 GIR을 만들 때 사용하는 gobject-introspection의 버전을 따른다는 점인데, 최근 버전은 상당 부분이 바뀌지 않았기에 주된 고려 요소가 아닙니다.

note: (itstool) path: section/title
en: External Links
ko: 외부 링크

note: (itstool) path: section/p
en: The topic of API stability is covered in the following articles:
ko: API 안정성을 주제로 다루는 글은 다음과 같습니다:

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Application_programming_interface">Wikipedia page on APIs</link>
ko: <link href="http://en.wikipedia.org/wiki/Application_programming_interface">위키피디아의 API 페이지</link>

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Application_binary_interface">Wikipedia page on ABIs</link>
ko: <link href="http://en.wikipedia.org/wiki/Application_binary_interface">위키피디아의 ABI 페이지</link>

note: (itstool) path: item/p
en: <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API versioning documentation</link>
ko: <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API 버전 부여 참고 문서</link>

note: (itstool) path: credit/name
en: The GTK+ Team
ko: GTK+ 팀

note: (itstool) path: info/desc
en: Our guidelines for C code in GNOME
ko: 그놈의 C 코드 작성 지침

note: (itstool) path: page/title
en: C Coding Style
ko: C 코드 작성 방식

note: (itstool) path: page/p
en: This document presents the preferred coding style for C programs in GNOME. While coding style is very much a matter of taste, in GNOME we favor a coding style that promotes consistency, readability, and maintainability.
ko: 이 문서는 그놈에서 C 프로그램을 작성하는데 알맞은 코드 작성 방식을 알려줍니다. 코드 작성 방식은 취향의 문제를 상당히 많이 안고 있는데, 그놈에서는 일관성, 가독성, 보존성을 촉진하는 코드 작성 방식을 선호합니다.

note: (itstool) path: page/p
en: We present examples of good coding style as well as examples of bad style that is not acceptable in GNOME. Please try to submit patches that conform to GNOME’s coding style; this indicates that you have done your homework to respect the project’s goal of long-term maintainability. Patches with GNOME’s coding style will also be easier to review!
ko: 바람직한 코드 작성 방식, 그놈에서 용납하지 않은 나쁜 방식의 예제를 보여드리겠습니다. 그놈 코드 작성 방식에 맞는 패치를 제출하십시오. 프로젝트의 장기적인 보존성을 유지하도록 과제를 끝내야 한다는 이야기입니다. 그놈 코드 작성 방식으로 패치를 작성하면 코드 검토를 쉽게 할 수 있습니다!

note: (itstool) path: note/p
en: This document is for C code. For other languages, check the <link xref="index">main page</link> of the GNOME Programming Guidelines.
ko: 이 문서는 C 코드 작성을 다룹니다. 다른 언어에 대해서는 그놈 프로그래밍 지침의 <link xref="index">주 페이지</link>를 참고하십시오.

note: (itstool) path: page/p
en: These guidelines are heavily inspired by GTK’s CODING-STYLE document, the Linux Kernel’s CodingStyle, and the GNU Coding Standards. These are slight variations of each other, with particular modifications for each project’s particular needs and culture, and GNOME’s version is no different.
ko: 이 지침서는 GTK CODING-STYLE 문서, 리눅스 커널 코드 작성 방식, GNU 코드 작성 방식 표준에 상당 부분 영향을 받습니다. 이들 방식에 약간의 차이점이 있지만, 각 프로젝트의 일부를 수정할 때, 요구사항, 문화, 그놈 버전은 차이가 없습니다.

note: (itstool) path: section/title
en: The Single Most Important Rule
ko: 가장 중요한 단일 규칙

note: (itstool) path: section/p
en: The single most important rule when writing code is this: <em>check the surrounding code and try to imitate it</em>.
ko: 코드를 작성할 때 가장 중요한 단일 규칙은 <em>코드를 감싸는 요소를 확인하고 따라해보기</em> 입니다.

note: (itstool) path: section/p
en: As a maintainer it is dismaying to receive a patch that is obviously in a different coding style to the surrounding code. This is disrespectful, like someone tromping into a spotlessly-clean house with muddy shoes.
ko: 메인테이너라면 코드를 전적으로 분명히 다른 방식으로 작성한 패치를 받으면 실망합니다. 이는 얼룩 하나없는 집에 진흙발로 누군가가 들어가는 것처럼 무례한 행위입니다.

note: (itstool) path: section/p
en: So, whatever this document recommends, if there is already written code and you are patching it, keep its current style consistent even if it is not your favorite style.
ko: 그러니까 이 문서에서 뭘 추천하든지, 이미 작성한 코드가 있고 코드를 뜯어고친(patch)다면, 맘에 들지 않더라도 현재 방식을 일관되게 유지하십시오.

note: (itstool) path: section/title
en: Line Width
ko: 행 길이

note: (itstool) path: section/p
en: Try to use lines of code between 80 and 120 characters long. This amount of text is easy to fit in most monitors with a decent font size. Lines longer than that become hard to read, and they mean that you should probably restructure your code. If you have too many levels of indentation, it means that you should fix your code anyway.
ko: 행 길이는 80개 문자 길이와 120개 문자 길이를 활용합니다. 이 정도 길이면 대부분의 모니터에서 적당한 글꼴 크기를 잡았을 때 알맞게 나타납니다. 행 길이가 길어지면 코드를 살펴보기 어려워지며 코드를 다시 배치해야 합니다. 들여쓰기 단계가 너무 많이 들어가면 어쨌든 코드를 고쳐야 합니다.

note: (itstool) path: section/title
en: Indentation
ko: 들여쓰기

note: (itstool) path: section/p
en: In general there are two preferred indentation styles for code in GNOME.
ko: 보통 그놈 코드를 작성할 때 활용하는 들여쓰기 방식은 두가지가 있습니다.

note: (itstool) path: item/p
en: Linux Kernel style. Tabs with a length of 8 characters are used for the indentation, with K&amp;R brace placement:
ko: 리눅스 커널 방식. 들여쓰기 할 때 8칸 탭을 사용하며 K&amp;R 중괄호 배치 방식을 활용합니다:

note: (itstool) path: item/p
en: GNU style. Each new level is indented by 2 spaces, braces go on a line by themselves, and they are indented as well.
ko: GNU 방식. 각 레벨에 2칸 들여쓰기를 하고 중괄호는 한 줄에 하나씩 넣으며, 중괄호도 들여쓰기합니다.

note: (itstool) path: section/p
en: Both styles have their pros and cons. The most important things is to <em>be consistent</em> with the surrounding code. For example, the GTK+ library, which is GNOME’s widget toolkit, is written with the GNU style. Nautilus, GNOME’s file manager, is written in Linux kernel style. Both styles are perfectly readable and consistent when you get used to them.
ko: 각 방식에 장점과 단점이 있습니다. 코드를 감싸는데 있어 <em>일관성</em>을 지니고 있어야 하는게 가장 중요합니다. 예를 들자면, 그놈 위젯 도구 모음 GTK+ 라이브러리는 GNU 코드 방식으로 작성했지만, 그놈 파일 관리자는 리눅스 커널 코드 방식으로 작성했습니다. 두가지 방식 모두 완벽하게 알아보기 쉽고 일관성이 있습니다.

note: (itstool) path: section/p
en: Your first feeling when having to study or work on a piece of code that doesn’t have your preferred indentation style may be, how shall we put it, gut-wrenching. You should resist your inclination to reindent everything, or to use an inconsistent style for your patch. Remember the first rule: <em>be consistent</em> and respectful of that code’s customs, and your patches will have a much higher chance of being accepted without a lot of arguing about the right indentation style.
ko: 아마도 원하지 않는 들여쓰기 방식을 배우거나 코드 일부를 작업할 때 드는 첫 느낌은 속이 메슥거리는 느낌일지도 모르겠습니다. 전체 코드 들여쓰기를 다시하고 싶다든지, 패치에 일관성 없는 코드 작성 방식을 활용하려는 욕구는 참아야합니다. 첫번째 규칙을 되새겨보자면 <em>일관성</em>을 지키고 코드 개별 부분에 있어서도 존중하면, 어떤 들여쓰기 방식이 올바른지 시시비비 따지지 않을 수록 제출한 패치를 반영할 확률이 높습니다.

note: (itstool) path: section/title
en: Tab Characters
ko: 탭 문자

note: (itstool) path: section/p
en: <em>Do not ever change the size of tabs in your editor</em>; leave them as 8 spaces. Changing the size of tabs means that code that you didn’t write yourself will be perpetually misaligned.
ko: <em>편집기에서 탭 길이를 바꾸지 마십시오</em> 8칸으로 두십시오. 탭 길이를 바꾸면, 여러분이 작성하지 않은 코드의 정렬 상태가 완전히 엉망이 됩니다.

note: (itstool) path: section/p
en: Instead, set the <em>indentation size</em> as appropriate for the code you are editing. When writing in something other than Linux kernel style, you may even want to tell your editor to automatically convert all tabs to 8 spaces, so that there is no ambiguity about the intended amount of space.
ko: 대신, 편집 중인 코드에 적당한 <em>들여쓰기 길이</em>를 설정하십시오. 리눅스 커널 작성 방식이 아닌 다른 방식으로 작성한다면, 편집기에서 사용하는 모든 탭 길이를 8칸으로 자동으로 변환하게 하여 공백문자 길이 혼동을 의도대로 없앨 수 있습니다.

note: (itstool) path: section/title
en: Braces
ko: 중괄호

note: (itstool) path: section/p
en: Curly braces should not be used for single statement blocks:
ko: 중괄호는 단일 구문 블록에서는 사용하면 안됩니다:

note: (itstool) path: section/p
en: The “no block for single statements” rule has only four exceptions:
ko: “단일 구문 블록 제외” 규칙은 다음 네가지 예외에 대해서만 해당합니다:

note: (itstool) path: item/p
en: In GNU style, if either side of an if-else statement has braces, both sides should, to match up indentation:
ko: GNU 방식에서는 if-else 구문 각 부분에 중괄호가 있다면, 들여쓰기를 맞추어야 합니다:

note: (itstool) path: item/p
en: If the single statement covers multiple lines, e.g. for functions with many arguments, and it is followed by <code>else</code> or <code>else if</code>:
ko: 함수에 여러 매개변수를 넣는 식으로 단일 구문이 여러 줄을 차지하고, <code>else</code> 또는 <code>else if</code>가 따라온다면:

note: (itstool) path: item/p
en: If the condition is composed of many lines:
ko: 조건문이 여러 줄에 있다면:

note: (itstool) path: item/p
en: Note that such long conditions are usually hard to understand. A good practice is to set the condition to a boolean variable, with a good name for that variable. Another way is to move the long condition to a function.
ko: 이런 긴 조건문은 보통 이해하기 어렵습니다. 적절한 이름을 가진 부울린 변수로 상태 값을 설정하는 것이 바람직한 습관입니다. 긴 조건문을 함수로 옮기는 다른 방식도 있습니다.

note: (itstool) path: item/p
en: Nested <code>if</code>s, in which case the block should be placed on the outermost <code>if</code>:
ko: 중첩 <code>if</code> 문의 경우에는, 블록을 최대한 가장 바깥 <code>if</code> 블록에 넣어야합니다:

note: (itstool) path: section/p
en: In general, new blocks should be placed on a new indentation level, like this:
ko: 보통, 새 블록은 다음과 같이 새 들여쓰기 단계에 넣어야합니다:

note: (itstool) path: section/p
en: While curly braces for function definitions should rest on a new line they should not add an indentation level:
ko: 함수 정의 중괄호를 새 줄에 넣되 들여쓰기 단계를 더 들어가지 않습니다:

note: (itstool) path: section/title
en: Conditions
ko: 조건문

note: (itstool) path: section/p
en: Do not check boolean values for equality. By using implicit comparisons, the resulting code can be read more like conversational English. Another rationale is that a ‘true’ value may not be necessarily equal to whatever the <code>TRUE</code> macro uses. For example:
ko: 부울린 값에 대해서는 동일 여부를 확인하지 마십시오. 비교 구문이 함축되어 있기 때문에 결과 코드는 영문 대화체처럼 보일 수 있습니다. 다른 이유가 있다면 ‘true’ 값을 사용하든 <code>TRUE</code> 매크로를 사용하든 동일하니 필요하지 않습니다. 예를 들면:

note: (itstool) path: section/p
en: The C language uses the value 0 for many purposes. As a numeric value, the end of a string, a null pointer and the <code>FALSE</code> boolean. To make the code clearer, you should write code that highlights the specific way 0 is used. So when reading a comparison, it is possible to know the variable type. For boolean variables, an implicit comparison is appropriate because it’s already a logical expression. Other variable types are not logical expressions by themselves, so an explicit comparison is better:
ko: C언어에서는 0 값을 다양한 용도로 활용합니다. 숫자 값으로, 문자열 마지막 값으로, 널 포인더 값으로, 부울린의 <code>FALSE</code> 값으로 활용합니다. 코드를 더 알아보기 쉽게 하려면, 0을 사용하는 개별 방식을 강조하도록 코드를 작성해야합니다. 따라서 비교 구문을 살펴볼 때 변수 형식을 알려줄 수 있습니다. 부울린 값에 대해서는 이미 자체 표현식이 있기 때문에 함축 비교문을 있는 그대로 두는게 낫습니다. 다른 변수 형식에 대해서는 비논리적인 수식이 될테니, 비교 수식을 분명하게 작성하는 것이 좋습니다:

note: (itstool) path: section/title
en: Functions
ko: 함수

note: (itstool) path: section/p
en: Functions should be declared by placing the returned value on a separate line from the function name:
ko: 함수는 반환 값과 함수 이름 사이에 개행 문자를 넣어 줄을 나누어서 선언해야합니다:

note: (itstool) path: section/p
en: The argument list must be broken into a new line for each argument, with the argument names right aligned, taking into account pointers:
ko: 인자는 한 줄에 하나씩 나누어 넣어야 하며, 포인터를 취하는 매개변수 이름은 오른쪽으로 보내야합니다:

note: (itstool) path: section/p
en: If you use Emacs, you can use <code>M-x align</code> to do this kind of alignment automatically. Just put the point and mark around the function’s prototype, and invoke that command.
ko: 이맥스를 사용한다면 자동 정렬할 때 <code>M-x align</code> 명령을 사용할 수 있습니다. 함수 프로토타입 주변에 커서를 둔 후 명령을 실행하십시오.

note: (itstool) path: section/p
en: The alignment also holds when invoking a function without breaking the line length limit:
ko: 행 길이 제한을 깨지 않는 함수에 대해 실행하는 경우 정렬을 유지합니다:

note: (itstool) path: section/title
en: Whitespace
ko: 공백 문자

note: (itstool) path: section/p
en: Always put a space before an opening parenthesis but never after:
ko: 여는 괄호를 입력하기 전에 공백을 입력하되, 여는 괄호 다음에는 입력하지 마십시오:

note: (itstool) path: section/p
en: When declaring a structure type use newlines to separate logical sections of the structure:
ko: 구조체를 선언할 때 구조체의 논리 섹션을 나누려면 개행 문자를 사용하십시오:

note: (itstool) path: section/p
en: Do not eliminate whitespace and newlines just because something would fit on a single line:
ko: 단일 행에 맞춘다는 이유 하나만으로 공백 문자와 줄 바꿈을 빼먹지 마십시오:

note: (itstool) path: section/p
en: Do eliminate trailing whitespace on any line, preferably as a separate patch or commit. Never use empty lines at the beginning or at the end of a file.
ko: 어떤 행에든 패치 또는 커밋을 따로 만드는 공백 문자를 뒤에 붙이지 마십시오. 파일 시작 부분 또는 끝 부분에 빈 줄을 넣지 마십시오.

note: (itstool) path: section/p
en: This is a little Emacs function that you can use to clean up lines with trailing whitespace:
ko: 다음은 행의 마지막 부분에 있는 공백 문자를 없애는 간단한 이맥스용 함수입니다:

note: (itstool) path: section/title
en: The <code>switch</code> Statement
ko: <code>switch</code> 조건문

note: (itstool) path: section/p
en: A <code>switch</code> should open a block on a new indentation level, and each <code>case</code> should start on the same indentation level as the curly braces, with the case block on a new indentation level:
ko: <code>switch</code> 구문에서는 새 들여쓰기 단계에 블록을 열고, 각 <code>case</code> 구문은 중괄호와 동일한 들여쓰기 단계에서 시작해야 하며, case 블록은 새 들여쓰기 단계에서 시작해야합니다:

note: (itstool) path: section/p
en: It is preferable, though not mandatory, to separate the various cases with a newline:
ko: 꼭 여러 case를 줄바꿈 해야 하는건 아니지만 권장할만합니다:

note: (itstool) path: section/p
en: The <code>break</code> statement for the <code>default</code> case is not mandatory.
ko: <code>default</code> case의 <code>break</code> 구문은 필수가 아닙니다.

note: (itstool) path: section/p
en: If switching over an enumerated type, a <code>case</code> statement must exist for every member of the enumerated type. For members you do not want to handle, alias their <code>case</code> statements to <code>default</code>:
ko: 서수 형식에 따라 switch 구문을 처리한다면, <code>case</code> 구문은 모든 서수 형식의 구성 값에 대해 마감 처리해야합니다. 처리하고 싶지 않은 구성 값은 <code>case</code> 구문의 별칭을 <code>default</code>로 지정하면 됩니다:

note: (itstool) path: section/p
en: If most members of the enumerated type should not be handled, consider using an <code>if</code> statement instead of a <code>switch</code>.
ko: 대부분의 서수 형식 구성 값을 처리하지 않을 경우, <code>switch</code> 대신 <code>if</code> 구문을 사용해보십시오.

note: (itstool) path: section/p
en: If a <code>case</code> block needs to declare new variables, the same rules as the inner blocks apply (see above); the <code>break</code> statement should be placed outside of the inner block:
ko: <code>case</code> 블록에 새 변수를 선언해야 한다면, 내부 블록에도 동일한 규칙을 적용합니다(상단 참고). <code>break</code> 구문은 내부 블록의 바깥에 넣어야합니다:

note: (itstool) path: section/title
en: Header Files
ko: 헤더 파일

note: (itstool) path: section/p
en: The only major rule for headers is that the function definitions should be vertically aligned in three columns:
ko: 헤더 파일의 유일한 주요 규칙은 함수 정의를 세 부분으로 수직 정렬해야 한다는 점 뿐입니다:

note: (itstool) path: section/p
en: The maximum width of each column is given by the longest element in the column:
ko: 각 열의 최대 폭은 가장 긴 내용을 지닌 열의 길이를 따릅니다:

note: (itstool) path: section/p
en: It is also possible to align the columns to the next tab:
ko: 다음 탭의 컬럼에 맞춰 정렬할 수도 있습니다:

note: (itstool) path: section/p
en: As before, you can use <code>M-x align</code> in Emacs to do this automatically.
ko: 이전과 마찬가지로 이맥스에서 <code>M-x align</code> 명령을 실행하여 자동으로 정렬할 수 있습니다.

note: (itstool) path: section/p
en: If you are creating a public library, try to export a single public header file that in turn includes all the smaller header files into it. This is so that public headers are never included directly; rather a single include is used in applications. For example, GTK+ uses the following in its header files that should not be included directly by applications:
ko: 공개용 라이브러리를 만든다면, 작은 헤더 파일을 모두 포함하는 단일 공용 헤더 파일로 내보내보십시오. 프로그램에서 사용하는 단일 포함 요소를 활용하기 보다는 공용 헤더를 직접 포함하지 않습니다. GTK+에서는 프로그램에 직접 넣지 않는 다음 헤더 파일을 활용합니다:

note: (itstool) path: section/p
en: For libraries, all headers should have inclusion guards (for internal usage) and C++ guards. These provide the <code>extern "C"</code> magic that C++ requires to include plain C headers:
ko: 라이브러리에 대해서는, 모든 헤더(내부용) 포함 방지와 C++ 사용 방지를 넣어야합니다. C++에서 일반 C 헤더를 넣어야 할 때` <code>extern "C"</code> 매직 코드로 처리할 수 있습니다:

note: (itstool) path: section/title
en: GObject Classes
ko: GObject 클래스

note: (itstool) path: section/p
en: GObject class definitions and implementations require some additional coding style notices, and should always be <link xref="namespacing#gobject">correctly namespaced</link>.
ko: GObject 클래스 정의 및 구현체에는 추가 코드 작성 방식 언급이 필요하며, 항상 <link xref="namespacing#gobject">올바른 이름 영역에 있</link>어야합니다.

note: (itstool) path: section/p
en: Typedef declarations should be placed at the beginning of the file:
ko: typedef 선언부는 파일의 시작 부분에 있어야합니다:

note: (itstool) path: section/p
en: This includes enumeration types:
ko: 다음 코드에는 서수 형식이 있습니다:

note: (itstool) path: section/p
en: And callback types:
ko: 그리고 콜백 함수 형식은 다음과 같습니다:

note: (itstool) path: section/p
en: Instance structures should be declared using <code>G_DECLARE_FINAL_TYPE</code> or <code>G_DECLARE_DERIVABLE_TYPE</code>:
ko: 인스턴스 구조체는  <code>G_DECLARE_FINAL_TYPE</code> 또는 <code>G_DECLARE_DERIVABLE_TYPE</code>으로 선언해야합니다:

note: (itstool) path: section/p
en: For final types, private data can be stored in the object struct, which should be defined in the C file:
ko: final 형식으로, 비공개 데이터는 C 파일에 정의하는 객체 구조체에 넣을 수 있습니다:

note: (itstool) path: section/p
en: For derivable types, private data must be stored in a private struct in the C file, configured using <code>G_DEFINE_TYPE_WITH_PRIVATE()</code> and accessed using a <code>_get_instance_private()</code> function:
ko: 상속 가능한 형식으로, 비공개 데이터는 <code>G_DEFINE_TYPE_WITH_PRIVATE()</code> 매크로를 활용하여 설정하고 <code>_get_instance_private()</code> 함수로 접근하는 C 파일의 비공개 구조체에 넣어야합니다:

note: (itstool) path: section/p
en: Always use the <code>G_DEFINE_TYPE()</code>, <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>, and <code>G_DEFINE_TYPE_WITH_CODE()</code> macros, or their abstract variants <code>G_DEFINE_ABSTRACT_TYPE()</code>, <code>G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE()</code>, and <code>G_DEFINE_ABSTRACT_TYPE_WITH_CODE()</code>; also, use the similar macros for defining interfaces and boxed types.
ko: 항상 <code>G_DEFINE_TYPE()</code>, <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>, <code>G_DEFINE_TYPE_WITH_CODE()</code> 매크로를 사용하든지, <code>G_DEFINE_ABSTRACT_TYPE()</code>, <code>G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE()</code>, <code>G_DEFINE_ABSTRACT_TYPE_WITH_CODE()</code> 추상 변형 매크로를 활용하십시오. 인터페이스 및 박싱 형식을 정의할 때 동일한 매크로를 활용하십시오.

note: (itstool) path: section/p
en: Interface types should always have the dummy typedef for cast purposes:
ko: 인터페이스 형식은 캐스팅 목적으로 모조 typedef를 두어야합니다:

note: (itstool) path: section/p
en: The interface structure should have ‘Interface’ postfixed to the dummy typedef:
ko: 인터페이스 구조체에는 모조 typedef 뒤에 붙인 ‘Interface’를 넣어야합니다:

note: (itstool) path: section/p
en: Interfaces must have the following macros:
ko: 인터페이스에는 다음 매크로를 넣어야합니다:

note: (itstool) path: td/p
en: Macro
ko: 매크로

note: (itstool) path: td/p
en: Expands to
ko: 확장 대상

note: (itstool) path: section/title
en: Memory Allocation
ko: 메모리 할당

note: (itstool) path: section/p
en: When dynamically allocating data on the heap use <code>g_new()</code>.
ko: 힙에 데이터를 동적으로 할당하려면 <code>g_new()</code> 함수를 활용하십시오.

note: (itstool) path: section/p
en: Public structure types should always be returned after being zero-ed, either explicitly for each member, or by using <code>g_new0()</code>.
ko: 공개 구조체 형식은 0 값으로 처리한 다음에 항상 각 구성 변수 값을 분명하게 반환하거나 <code>g_new0()</code> 함수를 활용하여 반환해야합니다.

note: (itstool) path: section/p
en: See <link xref="memory-management"/> for more details.
ko: 자세한 내용은 <link xref="memory-management"/> 링크를 참고하십시오.

note: (itstool) path: section/title
en: Macros
ko: 매크로

note: (itstool) path: section/p
en: Try to avoid private macros unless strictly necessary. Remember to <code>#undef</code> them at the end of a block or a series of functions needing them.
ko: 반드시 필요한게 아니라면 자체 매크로는 피하십시오. 블록 뒷 부분 또는 필요한 함수 몇 군데에서 <code>#undef</code> 처리를 잊지 마십시오.

note: (itstool) path: section/p
en: Inline functions are usually preferable to private macros.
ko: 인라인 함수는 보통 자체 매크로 용도로 안성맞춤입니다.

note: (itstool) path: section/p
en: Public macros should not be used unless they evaluate to a constant.
ko: 공개 매크로는 상수를 처리하지 않는 한 사용하지 말아야합니다.

note: (itstool) path: section/title
en: Public API
ko: 공용 API

note: (itstool) path: section/p
en: Avoid exporting variables as public API, since this is cumbersome on some platforms. It is always preferable to add getters and setters instead. Also, beware global variables in general.
ko: 일부 플랫폼에서 이상항 동작이 일어날 수 있으므로 공용 API 처럼 변수를 내보내는 일은 피하십시오. 대신 getter 함수와 setter 함수를 만드는게 좋습니다. 또한 일반적인 글로벌 변수 사용에 주의하십시오.

note: (itstool) path: section/title
en: Private API
ko: 비공개 API

note: (itstool) path: section/p
en: Non-exported functions that are needed in more than one source file should be prefixed with an underscore (‘_’), and declared in a private header file. For example, <code>_mylib_internal_foo()</code>.
ko: 하나 이상의 소스 파일에서 필요한 비공개 함수 앞에 밑줄 문자(‘_’)를 붙이시고 자체 헤더 파일에 선언하십시오. 예를 들자면 <code>_mylib_internal_foo()</code> 처럼 작명하십시오.

note: (itstool) path: section/p
en: Underscore-prefixed functions are never exported.
ko: 밑줄 문자를 앞에 붙인 함수는 공개하지 않습니다.

note: (itstool) path: section/p
en: Non-exported functions that are only needed in one source file should be declared static.
ko: 소스 파일에서만 사용할 비공개 변수는 static으로 선언해야합니다.

note: (itstool) path: p/link
en: Creative Commons Attribution-Share Alike 3.0 United States License
ko: 크리에이티브 커먼즈 저작자표시-동일조건변경허락 3.0 미합중국 라이선스

note: (itstool) path: license/p
en: This work is licensed under a <_:link-1/>.
ko: 이 설명서는 <_:link-1/> 라이선스에 따라 활용할 수 있습니다.

note: (itstool) path: license/p
en: As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.
ko: 특별히 예외적으로, 이 문서의 예제 코드는 저작권자에 명시한 대로 어떠한 제한 없이 원하는 대로 복제, 수정, 배포할 수 있습니다.

note: (itstool) path: info/desc
en: Simple persistent object stores
ko: 단순 영속 객체 저장

note: (itstool) path: page/title
en: Databases
ko: 데이터베이스

note: (itstool) path: item/p
en: Use databases for appropriate use cases: not configuration data (use GSettings). (<link xref="#when-to-use-databases"/>)
ko: 적당한 용도에 따라 데이터베이스를 사용하십시오. 설정 데이터(이 경우 GSettings를 사용하십시오)용이 아닙니다(<link xref="#when-to-use-databases"/>).

note: (itstool) path: item/p
en: Choose between GOM and GVDB based on whether indexing is required. (<link xref="#when-to-use-databases"/>)
ko: 색인화 필요성에 따라 GOM과 GVDB 중 하나를 선택하십시오(<link xref="#when-to-use-databases"/>).

note: (itstool) path: item/p
en: Consider your vacuuming policy before committing to using GOM. (<link xref="#when-to-use-databases"/>)
ko: GOM을 활용하여 데이터를 올리기 전 vacuum 정책을 고려하십시오(<link xref="#when-to-use-databases"/>).

note: (itstool) path: item/p
en: Avoid SQL injection vulnerabilities by using prepared statements. (<link xref="#sql-injection"/>)
ko: 미리 준비한 SQL 구문으로 SQL 인젝션 취약성 문제를 피하십시오(<link xref="#sql-injection"/>).

note: (itstool) path: section/title
en: When to Use Databases
ko: 데이터베이스를 사용할 때

note: (itstool) path: section/p
en: Configuration data should be stored in <link href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>. As a rule of thumb, if some data needs to be persistent and affects how an application behaves, it is configuration data. If it could potentially be subject to policies imposed by the system administrator (such as proxy or lockdown settings), it is configuration data. If it contains user created content, it is not configuration data, and should not be stored in GSettings.
ko: 설정 데이터는 <link href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>에 저장해야합니다. 경험에 따르면, 지속적으로 저장해 둬야 하는 데이터가 프로그램의 행동 방식에 영향을 준다면 설정 데이터라 합니다. 잠재적으로 시스템 관리자가 도입한 정책일 수 있다면(이를 테면 프록시 내지는 통제 설정), 역시 설정 데이터라고 합니다. 사용자가 만든 내용인 경우 설정 데이터가 아니며 GSettings에 저장하면 안됩니다.

note: (itstool) path: section/p
en: For such situations where user data is highly structured, storing it in a database is sensible. There are two main databases suggested for use within GNOME: GOM and GVDB. GOM is a wrapper around SQLite, and hence implements indexing of fields and SQL-style queries. GVDB is a much simpler object store, supporting fast serialization of a dictionary of objects to disk.
ko: 잘 구성된 사용자 데이터가 있다면 데이터베이스 저장 방식이 좋습니다. 그놈에서는 GOM과 GVDB 두가지 주요 데이터베이스 활용을 제안합니다. GOM은 SQLite 래퍼이며, 필드 색인화 처리, SQL 방식 구문을 구현했습니다. GVDB는 상당히 단순한 객체 저장소이며, 디스크를 대상으로 삼는 객체 딕셔너리의 고속 직렬화 처리를 지원합니다.

note: (itstool) path: section/p
en: GOM should be used if you need advanced features, especially indexing. GVDB should be used otherwise.
ko: 특히 색인화 처리 같은 고급 기능이 필요하다면 GOM을 사용해야합니다. 이 밖의 경우라면 GVDB를 사용해야합니다.

note: (itstool) path: section/p
en: Before deciding to use GOM (and hence SQLite), you must consider a vacuuming policy for the database, and whether your use case will interact well with SQLite’s vacuuming system. Vacuuming is effectively SQLite’s term for defragmenting the database — if a database is not vacuumed appropriately, performance will degrade and the database size will increase indefinitely. Read <link href="http://blogs.gnome.org/jnelson/2015/01/06/sqlite-vacuum-and-auto_vacuum/">this article</link> on vacuuming for more information; please consider it before choosing to use GOM.
ko: GOM 사용(그러니까 SQLite)을 결정하기 전에, 데이터베이스의 vacuum 정책과, 여러분의 사용 경험이 SQLite의 vacuum 처리 시스템에 익숙한지 여부를 고려해야합니다. vacuum 처리는 데이터베이스 단편화 제거 의미로 사용하는 SQLite의 실질적 용어입니다. 데이터베이스를 제대로 vacuum 처리하지 않으면, 성능이 떨어지며 데이터베이스 크기가 한없이 늘어납니다. 자자세한 vacuum 처리 내용은 <link href="http://blogs.gnome.org/jnelson/2015/01/06/sqlite-vacuum-and-auto_vacuum/">이 글</link>을 살펴보십시오. GOM 사용을 결정하기 전에  이 내용을 고려하십시오.

note: (itstool) path: section/p
en: GNOME has another database library: GNOME Data Access (GDA). This is targeted at abstracting access to various types of relational database, for use in a database utility program or office program, for example. It is not suitable for storing <link href="https://developer.gnome.org/gio/stable/GSettings.html">user settings</link>.
ko: 그놈에는 또 다른 데이터베이스 라이브러리 그놈 데이터 액세스(GDA)가 있습니다. 그놈 데이터 액세스는 데이터베이스 유틸리티 프로그램이나 오피스 프로그램과 같이 다양한 관계 데이터베이스로의 추상적 접근이 목표입니다. <link href="https://developer.gnome.org/gio/stable/GSettings.html">사용자 설정</link>을 저장하는덴 적합하지 않습니다.

note: (itstool) path: section/title
en: Using GOM
ko: GOM 활용

note: (itstool) path: section/p
en: Providing a GOM tutorial is beyond the scope of this document, but a <link href="https://developer.gnome.org/gom/">reference manual is available</link>.
ko: GOM 지침서 제공은 이 문서의 내용 범위를 벗어나지만, <link href="https://developer.gnome.org/gom/">참고 도움말이 있습니다</link>.

note: (itstool) path: section/title
en: SQL Injection
ko: SQL 인젝션

note: (itstool) path: section/p
en: GOM does allow access to the lower level SQLite query APIs. When using them, queries <em style="strong">must</em> be constructed using SQLite’s <link href="https://www.sqlite.org/c3ref/stmt.html">prepared statement</link> and <link href="https://www.sqlite.org/c3ref/bind_blob.html">value binding</link> API, rather than by constructing SQL strings then passing them to SQLite to parse. Constructing strings makes <link href="http://en.wikipedia.org/wiki/SQL_injection">SQL injection</link> vulnerabilities very likely, which can give attackers access to arbitrary user data from the database.
ko: GOM은 저수준 SQLite 요청 API에 접근할 수 있게 합니다. 이 API를 활용할 때 요청문은 SQL 문자열을 만들어서 SQLite에게 해석하라고 던져주는 식으로 전달하기보단, <em style="strong">반드시</em> SQLite의 <link href="https://www.sqlite.org/c3ref/stmt.html">prepared 구문</link> 과 <link href="https://www.sqlite.org/c3ref/bind_blob.html">값 바인딩</link> API로 만들어야합니다. 문자열을 직접 만들면, 공격자가 데이터베이스에 있는 임의의 사용자 데이터에 접근할 수 있게 하는 <link href="http://en.wikipedia.org/wiki/SQL_injection">SQL 인젝션</link> 취약성이 나타날 가능성이 높습니다.

note: (itstool) path: section/title
en: Using GVDB
ko: GVDB 활용

note: (itstool) path: section/p
en: GVDB has a simple API which mirrors a conventional hash table. Presently, GVDB is only available as a copy-and-paste library; fetch the most recent copy of the code from <link href="https://git.gnome.org/browse/gvdb">GVDB git</link> and copy it into your project. It is licenced under LGPLv2.1+.
ko: GVDB는 기존에 활용하던 해시 테이블을 모방한 단순 API입니다. 현재 GVDB는 복사-붙여넣기 라이브러리로만 사용합니다. 최근 코드 사본은 <link href="https://git.gnome.org/browse/gvdb">GVDB git</link>에서 가져오시고 프로젝트에 복사해 넣으십시오. LGPL v2.1 이상의 라이선스를 따릅니다.

note: (itstool) path: section/p
en: A full GVDB tutorial is beyond the scope of this document.
ko: GVDB의 완전한 지침 내용은 이 문서 내용의 범위를 벗어납니다.

note: (itstool) path: info/desc
en: Adding documentation to libraries and APIs
ko: 라이브러리 및 API에 문서 추가

note: (itstool) path: page/title (itstool) path: section/title
en: Documentation
ko: 문서

note: (itstool) path: item/p
en: Use gtk-doc with up-to-date settings for API documentation. (<link xref="#gtk-doc"/>)
ko: API 문서에는 최신의 설정으로 gtk-doc을 활용하십시오(<link xref="#gtk-doc"/>).

note: (itstool) path: item/p
en: Use XML entities for including external symbols into the documentation. (<link xref="#build-system"/>)
ko: 문서에 외부 심볼을 넣으려면 XML 엔티티를 활용하십시오(<link xref="#build-system"/>).

note: (itstool) path: item/p
en: Use a consistent, standard, table of contents for all API documentation to maintain familiarity. (<link xref="#standard-layout"/>)
ko: 모든 API 문서의 익숙함을 유지하려면 일관된 표준 목차를 사용하십시오(<link xref="#standard-layout"/>).

note: (itstool) path: item/p
en: Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to include in the gtk-doc build. (<link xref="#dbus-api"/>)
ko: gtk-doc 빌드에 넣어 D-Bus API 문서를 만들려면 <cmd>gdbus-codegen</cmd>을 활용하십시오(<link xref="#dbus-api"/>).

note: (itstool) path: item/p
en: Add introspection annotations to all API documentation. (<link xref="#introspection-annotations"/>)
ko: 모든 API 문서에 인트로스펙션 주석을 추가하십시오(<link xref="#introspection-annotations"/>).

note: (itstool) path: item/p
en: Add <code>Since</code> lines to all API documentation. (<link xref="#symbol-versioning"/>)
ko: 모든 API 문서에 <code>Since</code>를 추가하십시오(<link xref="#symbol-versioning"/>).

note: (itstool) path: item/p
en: Enable gtk-doc tests. (<link xref="#keeping-up-to-date"/>)
ko: gtk-doc 테스트를 활성화하십시오(<link xref="#keeping-up-to-date"/>).

note: (itstool) path: section/p
en: The preferred documentation system for GNOME libraries is <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, which extracts inline comments from the code to let you build a <link href="http://docbook.org/">DocBook</link> document and collection of HTML pages. These can then be read in <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. A lot of GNOME’s infrastructure is built to handle with documentation written using gtk-doc.
ko: 그놈 라이브러리에 맞는 문서 시스템은 코드의 인라인 주석을 뽑아내어 <link href="http://docbook.org/">닥북</link> 문서와 HTML 페이지 모음을 만드는 <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>입니다. 이 내용은 <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>에서 살펴볼 수 있습니다. 그놈 기반 대부분은 gtk-doc으로 작성한 문서를 처리하여 만들었습니다.

note: (itstool) path: section/title
en: Build System
ko: 빌드 체계

note: (itstool) path: section/p
en: To integrate gtk-doc into a project’s build system, follow the <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en"> instructions in the gtk-doc manual</link>. Note that while the <file>sections.txt</file> file is automatically generated the first time gtk-doc is run, it is not generated subsequently, and should be kept up to date manually. It should also be <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en"> in version control</link>.
ko: gtk-doc을 프로젝트 빌드 시스템에 통합하려면 <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">gtk-doc 설명서 절차</link>에 따르십시오. 참고로 <file>sections.txt</file> 파일은 gtk-doc을 실행할 때 처음에 자동으로 나오고, 그 이후에는 만들지 않으며, 직접 최신으로 유지해야합니다. 또한 <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">버전 관리</link> 상태에 두어야합니다.

note: (itstool) path: section/p
en: gtk-doc’s <code>no-tmpl</code> flavour should be used, and XML mode should be used instead of SGML. (tmpl mode and SGML are both outdated and slower than XML.)
ko: gtk-doc의 <code>no-tmpl</code> 방식을 사용하시고, SGML 대신 XML 모드를 사용해야합니다(tmpl 모드와 SGML 모드는 XML 보다 오래됐으며, 느립니다).

note: (itstool) path: section/p
en: If the package version is needed to be substituted into the documentation, create a file named <file>docs/version.xml.in</file>, containing:
ko: 문서의 패키지 버전을 바꿔야한다면, 다음 내용을 넣은 <file>docs/version.xml.in</file> 파일을 만드십시오:

note: (itstool) path: section/p
en: Add it to <code>AC_CONFIG_FILES</code> in <file>configure.ac</file>, then include it into the main documentation file (<file>*-docs.xml</file>) using: <code>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code> in the <code>DOCTYPE</code> at the top of the document. The package version can then be used inline as <code>&amp;version;</code>.
ko: 위 코드를 <file>configure.ac</file>의 <code>AC_CONFIG_FILES</code>에 추가하시고, 문서 상단의 <code>DOCTYPE</code>에 <code>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code>를 넣은 코드를 주 문서 파일(<file>*-docs.xml</file>)에 넣으십시오. 패키지 버전은 <code>&amp;version;</code> 처럼 인라인 구문 방식으로 사용할 수 있습니다.

note: (itstool) path: section/title
en: Standard Layout
ko: 표준 배치

note: (itstool) path: section/p
en: Using a standard layout for the table of contents, sections, appendices, etc. means the same <file><var>project-name</var>-docs.xml</file> template can be reused with few changes between projects. It also means the documentation layout is similar across all projects, making it more familiar to developers.
ko: 동일한 <file><var>project-name</var>-docs.xml</file> 양식을 사용하는 목차, 섹션, 용어 목록 등에 표준 배치 구성 활용은 프로젝트간에 몇가지 내용이 바뀔 경우 재활용할 수 있습니다. 이는 모든 프로젝트에 걸친 개발자 친화 문서 구성 양식이 유사함을 의미합니다.

note: (itstool) path: section/p
en: The following layout is suggested:
ko: 다음 형식을 제안합니다:

note: (itstool) path: listing/desc
en: A template top-level gtk-doc file for a project
ko: 프로젝트의 최상위 gtk-doc 파일 양식

note: (itstool) path: section/title
en: Licensing
ko: 라이선스 부여

note: (itstool) path: section/p
en: It is important to make the license used for API references clear, especially if they contain code examples which could be copied around.
ko: 다양한 곳에 복사할 수 있는 코드 예제가 있을 경우 분명한 API 참고서 라이선스 지정이 중요합니다.

note: (itstool) path: section/p
en: Typically, projects use the same license for their API reference as for the project’s code itself, to avoid confusion. Some other projects use CC-BY-SA 3.0 for all their reference documentation. The choice is yours.
ko: 보통 혼동을 방지할 목적으로 프로젝트 코드 자체 용도로 API 참고서에 동일한 라이선스를 적용합니다. 일부 기타 프로젝트는 모든 참고서에 CC-BY-SA 3.0를 적용하기도 합니다. 선택은 여러분의 몫입니다.

note: (itstool) path: section/p
en: As shown in the <link xref="#standard-layout">Standard Layout</link> you should include a <file>license.xml</file> in the top-level gtk-doc DocBook file which gives the full text of your documentation license.
ko: <link xref="#standard-layout">표준 배치</link>에서 보여드린 바와 같이, 최상위 gtk-doc 닥북 파일에 문서 라이선스 전문이 들어있는 <file>license.xml</file>을 넣어야합니다.

note: (itstool) path: section/title
en: Public APIs
ko: 공개용 API

note: (itstool) path: section/p
en: All public APIs must have gtk-doc comments. For functions, these should be placed in the source file, directly above the function.
ko: 모든 공용 API에는 gtk-doc 주석이 있어야합니다. 함수 주석은 소스 코드 파일의 함수 바로 위에 있어야합니다.

note: (itstool) path: section/p
en: Documentation comments for macros, function types, class structs, etc. should be placed next to the definitions, typically in header files.
ko: 매크로, 함수 형식, 클래스 구조 등의 문서 주석은, 보통 헤더 파일에서 정의 앞부분에 넣어야합니다.

note: (itstool) path: section/p
en: Section introductions should be placed in the source file they describe, after the license header:
ko: 섹션 도입부는 라이선스 헤더 다음, 설명 대상 소스 파일에 넣어야 합니다:

note: (itstool) path: section/p
en: Keep in mind that in order to include a function, macro, function type, or struct type, it needs to be listed in your documentation’s <file>modulename-sections.txt</file> file.
ko: 함수, 매크로, 함수 형식, 구조체 형식을 문서에 넣으려면 문서의 <file>modulename-sections.txt</file> 파일에 넣어야 함을 잊지 마십시오.

note: (itstool) path: section/p
en: To properly document a new class, it needs to be given its own section in <file>modulename-sections.txt</file>, needs to be included in your toplevel <file>modulename-docs.sgml</file>, and the <code>get_type()</code> function for your class needs to be listed in your <file>modulename.types</file>.
ko: 새 클래스를 문서에 제대로 기록하려면 <file>modulename-sections.txt</file>에 자체 섹션을 적고, 최상위 <file>modulename-docs.sgml</file> 파일에 넣어야 하며, <file>modulename.types</file> 파일에 작성한 클래스가 나타나도록 <code>get_type()</code> 함수를 작성해야합니다.

note: (itstool) path: section/title
en: Introspection Annotations
ko: 인트로스펙션 주석

note: (itstool) path: section/p
en: Each gtk-doc comment should have appropriate <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations"> GObject introspection annotations</link>. These are useful for two reasons:
ko: 각 gtk-doc 주석 부분에는 적절한 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations"> GObject 인트로스펙션 주석</link>을 넣어야합니다. 두가지 이유로 활용 가치가 있습니다:

note: (itstool) path: item/p
en: They add important information about parameter types, nullability and memory management to the C API documentation generated by gtk-doc.
ko: 매개변수 형식, NULL 허용 여부, 메모리 관리 관련 중요 정보를 gtk-doc으로 만든 C API 문서에 추가합니다.

note: (itstool) path: item/p
en: They allow public APIs to be automatically bound in other languages, such as Python or JavaScript.
ko: 공용 API를 파이썬 또는 자바스크립트 등의 기타 언어에 자동으로 바운딩 하도록 해줍니다.

note: (itstool) path: section/p
en: Introspection annotations add information to APIs (functions, function parameters, function return values, structures, GObject properties, GObject signals) which is otherwise not present in the machine readable C API and only exists in the form of human readable documentation or convention. They are very important.
ko: 인트로스펙션 주석은 머신에서 해석 가능한 C API에 나타나지 않는 API(함수, 함수 매개변수, 함수 반환 값, 구조체, GObject 속성, GObject 시그널)에 정보를 추가하며, 사람이 알아볼 수 있는 문서 또는 방식으로만 남습니다. 매우 중요한 부분입니다.

note: (itstool) path: section/p
en: In gtk-doc comments, annotations should be preferred over human-readable equivalents. For example, when documenting a function parameter which may be <code>NULL</code>, use the <code>(nullable)</code> annotation rather than some text:
ko: gtk-doc 주석은 사람이 알아볼 수 있는 동일한 부분의 내용만 주석으로 남겨야 합니다. 예를 들자면 <code>NULL</code> 값을 넣을 수 있는 함수 매개 변수를 문서로 남길 경우, 다른 내용이 아닌 <code>(nullable)</code> 주석을 사용하십시오:

note: (itstool) path: section/p
en: Instead of:
ko: 다음과 같이 적을 필요는 없습니다:

note: (itstool) path: section/p
en: For more information on introspection, see the <link xref="introspection">introspection guidelines</link>.
ko: 인트로스펙션 정보는 <link xref="introspection">인트로스펙션 지침서</link>를 참고하십시오.

note: (itstool) path: section/title
en: Symbol Versioning
ko: 심볼 버전 부여

note: (itstool) path: section/p
en: Whenever a symbol is added to the public API, it should have a documentation comment added. This comment should always contain a <code>Since</code> line with the package version number of the release which will first contain the new API. This should be the number currently in <file>configure.ac</file> if <link xref="versioning#release-process">post-release version incrementing</link> is being used.
ko: 공용 API에 심볼을 추가할 때마다 문서 주석도 추가해야합니다. 이 주석에는 새 API를 처음 넣을 패키지 출시 버전 번호를 넣은 <code>Since</code> 절을 항상 넣어야합니다. <link xref="versioning#release-process">post-release 버전 증가 방식</link>을 활용한다면 <file>configure.ac</file>에 넣은 현재 번호 값이어야합니다.

note: (itstool) path: section/p (itstool) path: example/p
en: For example:
ko: 예제:

note: (itstool) path: section/p
en: gtk-doc uses this information to generate indexes of the APIs added in each release. These should be added to the main <file>*-docs.xml</file> as an appendix:
ko: gtk-doc에서는 각 출시판에 추가한 API의 색인을 만들 때 이 정보를 활용합니다. 이 정보는 <file>*-docs.xml</file> 주 파일에 용어 색인처럼 추가해야합니다:

note: (itstool) path: section/title
en: D-Bus APIs
ko: D-Bus API

note: (itstool) path: section/p
en: D-Bus interface descriptions contain documentation comments, and these can be extracted from the XML using <cmd>gdbus-codegen</cmd>, and turned into DocBook files to be included by gtk-doc.
ko: D-Bus 인터페이스 설명에는 문서 주석이 들어가며, <cmd>gdbus-codegen</cmd> 명령으로 XML에서 빼낼 수 있고, gtk-doc 포함할 DocBook 파일로 전환할 수 있습니다.

note: (itstool) path: section/p
en: The DocBook files can be included in the main <file>*-docs.xml</file> file using:
ko: 다음 코드를 활용하여 DocBook 파일을 메인 <file>*-docs.xml</file> 파일에 넣을 수 있습니다:

note: (itstool) path: section/p
en: The generated XML files must be included in the <code>content_files</code> variable in your gtk-doc <file>Makefile.am</file>, otherwise the build will fail. (This is to fix situations where the <code>builddir</code> does not equal the <code>srcdir</code>.)
ko: 만들어 둔 XML 파일은 gtk-doc <file>Makefile.am</file> 파일의 <code>content_files</code> 변수에 넣어야합니다. 안 넣으면 빌드에 실패합니다(<code>builddir</code> 값과 <code>srcdir</code> 값이 다르면 바꾸십시오).

note: (itstool) path: section/title
en: Keeping Documentation Up to Date
ko: 최신 문서 유지

note: (itstool) path: section/p
en: gtk-doc comes with support for checking the documentation with some basic tests. These check that all version indexes are included in the main <file>*-docs.xml</file> file and that all symbols are documented, among other things.
ko: gtk-doc에는 일부 기본 테스트 과정에서 문서 검사를 지원합니다. 문서 검사 과정에서 <file>*-docs.xml</file> 주 파일에 모든 버전의 색인이 있는지, 모든 심볼을 문서에 남겼는지 등을 검사합니다.

note: (itstool) path: section/p
en: These tests should always be enabled, by adding the following to your gtk-doc <file>Makefile.am</file>:
ko: gtk-doc <file>Makefile.am</file> 파일에 다음 줄을 추가하여, 이 테스트를 항상 진행할 수 있어야합니다:

note: (itstool) path: section/p
en: They will then be run as part of <cmd>make check</cmd>.
ko: 위 줄을 해당 파일에 추가하면 <cmd>make check</cmd> 명령의 일부로 테스트를 실행합니다.

note: (itstool) path: info/desc
en: Accessing the file system
ko: 파일 시스템에 접근하기

note: (itstool) path: page/title
en: File System Access
ko: 파일 시스템 접근

note: (itstool) path: synopsis/p
en: There are a few anti-patterns to consider when accessing the file system. This article assumes knowledge of the standard <link href="https://developer.gnome.org/gio/stable/GFile.html"><code>GFile</code></link>, <link href="https://developer.gnome.org/gio/stable/GInputStream.html"><code>GInputStream</code></link> and <link href="https://developer.gnome.org/gio/stable/GOutputStream.html"><code>GOutputStream</code></link> APIs.
ko: 파일 시스템에 접근해야 할 때 피해야 할 몇가지 방식이 있습니다. 이 내용은 <link href="https://developer.gnome.org/gio/stable/GFile.html"><code>GFile</code></link>, <link href="https://developer.gnome.org/gio/stable/GInputStream.html"><code>GInputStream</code></link>, <link href="https://developer.gnome.org/gio/stable/GOutputStream.html"><code>GOutputStream</code></link> 표준 API를 알고 있음을 가졍합니다.

note: (itstool) path: item/p
en: Use asynchronous I/O for file access. (<link xref="#asynchronous-io"/>)
ko: 파일 접근시 비동기 입출력을 활용하십시오(<link xref="#asynchronous-io"/>).

note: (itstool) path: item/p
en: Always use appropriate functions to construct file names and paths. (<link xref="#file-path-construction"/>)
ko: 파일 이름 및 경로를 만들 때마다 적당한 함수를 활용하십시오(<link xref="#file-path-construction"/>).

note: (itstool) path: item/p
en: Validate file paths are in the expected directories before using them. (<link xref="#path-validation-and-sandboxing"/>)
ko: 파일 경로를 활용하기 전 예상 디렉터리에 있는지 검증하십시오(<link xref="#path-validation-and-sandboxing"/>).

note: (itstool) path: item/p
en: Use mandatory access control profiles to enforce constraints on file access. (<link xref="#path-validation-and-sandboxing"/>)
ko: 파일 접근을 통제하는 필수 접근 통제 프로파일을 사용하십시오(<link xref="#path-validation-and-sandboxing"/>).

note: (itstool) path: section/title
en: Asynchronous I/O
ko: 비동기 입출력

note: (itstool) path: section/p
en: Almost all I/O should be performed asynchronously. That is, without blocking the <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html">GLib main context</link>. This can be achieved by always using the <code>*_async()</code> and <code>*_finish()</code> variants of each I/O function.
ko: 대부분의 모든 입출력 과정은 비동기 방식으로 처리해야합니다. 무슨 이야기냐면 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html">GLib 메인 컨텍스트</link>의 동작을 방해하면 안된다는 의미입니다. 각 입출력 함수의 <code>*_async()</code> 및 <code>*_finish()</code> 변형 함수를 활용하여 언제든 수행 가능합니다.

note: (itstool) path: example/p
en: For example, <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read-async"><code>g_input_stream_read_async()</code></link> rather than <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read"><code>g_input_stream_read()</code></link>.
ko: 예를 들어 <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read"><code>g_input_stream_read()</code></link> 함수 대신 <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read-async"><code>g_input_stream_read_async()</code></link> 함수를 사용하십시오.

note: (itstool) path: section/p
en: Synchronous I/O blocks the main loop, which means that other events, such as user input, incoming networking packets, timeouts and idle callbacks, are not handled until the blocking function returns.
ko: 동기 입출력은 메인 루프의 실행을 가로 막는데, 사용자 입력, 네트워크 패킷 수신, 콜백 시간 초과 및 대기 같은 상황의 경우 프로그램의 동작 흐름을 가로막은 함수에서 반환 값이 나오기 전에는 처리할 수 없다는 의미입니다.

note: (itstool) path: section/p
en: Synchronous I/O is acceptable in certain circumstances where the overheads of scheduling an asynchronous operation exceed the costs of local synchronous I/O on Linux. For example, making a small read from a local file, or from a virtual file system such as <file>/proc</file>. For such reads, the low level functions <code>g_open()</code>, <code>read()</code> and <code>g_close()</code> should be used rather than GIO.
ko: 동기 입출력은 리눅스에서 로컬 동기 입출력 보다 비동기 처리 스케줄의 처리 시간/용량이 비교적 좋지 않은 일부 상황에서 용납 가능합니다. 예를 들어 로컬 파일 또는 <file>/proc</file> 같은 가상 파일 시스템에서 작은 데이터를 읽어들이는 경우가 있습니다. 이 때, GIO 대신 <code>g_open()</code>, <code>read()</code>, <code>g_close()</code> 저수준 함수를 사용해야합니다.

note: (itstool) path: section/p
en: Files in the user’s home directory do <em>not</em> count as local, as they could be on a networked file system.
ko: 로컬에 <em>없다</em>고 간주하는 사용자 개인 디렉터리에 있는 파일은, 네트워크 파일 시스템에 있을 수 있습니다.

note: (itstool) path: section/p
en: Note that the alternative – running synchronous I/O in a separate thread – is highly discouraged; see the <link xref="threading#when-to-use-threading">threading guidelines</link> for more information.
ko: 개별 스레드의 동기 입출력 처리 같은 대안책은 가급적 피하시는게 좋습니다. 자세한 내용은 <link xref="threading#when-to-use-threading">스레드 처리 지침서</link>를 참고하십시오.

note: (itstool) path: section/title
en: File Path Construction
ko: 파일 경로 만들기

note: (itstool) path: section/p
en: File names and paths are not normal strings: on some systems, they can use a character encoding other than UTF-8, while normal strings in GLib are guaranteed to always use UTF-8. For this reason, special functions should be used to build and handle file names and paths. (Modern Linux systems almost universally use UTF-8 for filename encoding, so this is not an issue in practice, but the file path functions should still be used for compatibility with systems such as Windows, which use UTF-16 filenames.)
ko: 파일 이름 및 경로는 일반 문자열이 아닙니다. GLib에서는 일반 문자열에 항상 UTF-8을 사용한다고 간주하지만, 일부 시스템에서는 UTF-8이 아닌 다른 문자 인코딩을 사용할 수 있습니다. 이 이유로, 파일 이름 및 경로를 만들고 처리할 때 특별한 함수를 사용해야합니다(최신 리눅스 시스템에서는 대부분 보편적으로 파일 이름 인코딩에 UTF-8을 사용하여 실제로는 문제되지 않지만, UTF-16 파일 이름을 사용하는 윈도우 같은 시스템의 호환성을 확보하려면 파일 경로 함수를 활용해야합니다).

note: (itstool) path: example/p
en: For example, file paths should be built using <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-build-filename"><code>g_build_filename()</code></link> rather than <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strconcat"><code>g_strconcat()</code></link>.
ko: 예를 들어 파일 경로는 <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strconcat"><code>g_strconcat()</code></link> 함수보다 <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-build-filename"><code>g_build_filename()</code></link> 함수를 사용하여 만들어야합니다.

note: (itstool) path: section/p
en: Doing so makes it clearer what the code is meant to do, and also eliminates duplicate directory separators, so the returned path is canonical (though not necessarily absolute).
ko: 이렇게 하면 코드가 무슨 일을 하는지 의미를 좀 더 분명하게 하며, (필연적으로 절대적이진 않지만)디렉터리 구분 문자 중복을 방지하여 올바른 경로를 반환합니다.

note: (itstool) path: example/p
en: As another example, paths should be disassembled using <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-basename"><code>g_path_get_basename()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname"><code>g_path_get_dirname()</code></link> rather than <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strrstr"><code>g_strrstr()</code></link> and other manual searching functions.
ko: 다른 예를 들어보자면, <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strrstr"><code>g_strrstr()</code></link> 함수 및 다른 직접적인 검색 함수를 활용하기보다는, <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-basename"><code>g_path_get_basename()</code></link> 함수와 <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname"><code>g_path_get_dirname()</code></link> 함수를 활용하여 경로를 분해해야합니다.

note: (itstool) path: section/title
en: Path Validation and Sandboxing
ko: 경로 검증 및 샌드박싱

note: (itstool) path: section/p
en: If a filename or path comes from external input, such as a web page or user input, it should be validated to ensure that putting it into a file path will not produce an arbitrary path. For example if a filename is constructed from the constant string <file>~/</file> plus some user input, if the user inputs <file>../../etc/passwd</file>, they can (potentially) gain access to sensitive account information, depending on which user the program is running as, and what it does with data loaded from the constructed path.
ko: 웹 페이지 또는 사용자 입력 등의 외부 입력으로 파일 이름 또는 경로를 받는다면, 파일 경로로 둔 경로의 임의 경로 여부를 확인하여 검증해야합니다.예를 들어 <file>~/</file> 상수 문자열에 일부 사용자 입력을 받아 파일 이름을 만들고, 여기서 사용자 입력이 <file>../../etc/passwd</file>라면, 사용자가 프로그램을 어떻게 실행하며, 만든 경로에서 어떤 데이터를 불러오냐에 따라 민감한 계정 정보로 접근하는데 접근할 수 있는 권한을(잠재적으로) 얻을 수 있습니다.

note: (itstool) path: section/p
en: This can be avoided by validating constructed paths before using them, using <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-resolve-relative-path"><code>g_file_resolve_relative_path()</code></link> to convert any relative paths to absolute ones, and then validating that the path is beneath a given root sandboxing directory appropriate for the operation. For example, if code downloads a file, it could validate that all paths are beneath <file>~/Downloads</file>, using <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-has-parent"><code>g_file_has_parent()</code></link>.
ko: 이 기능을 사용하기 전, <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-resolve-relative-path"><code>g_file_resolve_relative_path()</code></link> 함수로 상대 경로를 절대 경로로 변환하고 처리에 적당한 루트 샌드박싱 디렉터리에 있는 경로인지 검증하는 방식으로 작성한 경로를 검증하여 (악의적 접근을) 막을 수 있습니다. 이를테면, 코드로 파일을 다운로드할 때, <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-has-parent"><code>g_file_has_parent()</code></link> 함수를 사용하면 모든 경로가 <file>~/Downloads</file> 디렉터리에 있는지 검증할 수 있습니다.

note: (itstool) path: section/p
en: As a second line of defence, all projects which access the file system should consider providing a mandatory access control profile, using a system such as <link href="http://apparmor.net/">AppArmor</link> or <link href="http://selinuxproject.org/">SELinux</link>, which limits the directories and files they can read from and write to.
ko: 방어 차선책으로, 파일 시스템에 접근하는 모든 프로젝트는 디렉터리 및 파일의 읽기/쓰기 동작을 제한하는 <link href="http://apparmor.net/">AppArmor</link> 또는 <link href="http://selinuxproject.org/">SELinux</link> 같은 시스템을 활용하는 필수 접근 제어 프로파일 제공을 고려해야합니다.

note: (itstool) path: info/desc
en: Runtime error handling and reporting
ko: 런타임 오류 처리 및 보고

note: (itstool) path: section/title
en: GError Usage
ko: GError 활용법

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html"><code>GError</code></link> is the standard error reporting mechanism for GLib-using code, and can be thought of as a C implementation of an <link href="http://en.wikipedia.org/wiki/Exception_handling">exception</link>.
ko: <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html"><code>GError</code></link>는 GLib를 사용하는 코드의 표준 오류 보고 기법이며, <link href="http://en.wikipedia.org/wiki/Exception_handling">예외</link>의 C언어 버전 구현체로 생각하실 수 있습니다.

note: (itstool) path: section/p
en: Any kind of runtime failure (anything which is not a <link xref="preconditions">programmer error</link>) must be handled by including a <code>GError**</code> parameter in the function, and setting a useful and relevant GError describing the failure, before returning from the function. Programmer errors must not be handled using GError: use assertions, pre-conditions or post-conditions instead.
ko: 실행 시간에 일어나는 어떤 실패 동작(<link xref="preconditions">프로그래머 잘못</link>이 아님)는 함수에서 반환 처리 전에 함수에 <code>GError**</code> 매개변수를 넣고, 실패를 언급할 때 쓸 만한 해당 GError를 설정하여 처리해야합니다. 프로그래머 오류는 GError로 처리하면 안됩니다. 대신, 단언, 상태-전 또는 상태-후 테스트를 활용하십시오.

note: (itstool) path: section/p
en: GError should be used in preference to a simple return code, as it can convey more information, and is also supported by all GLib tools. For example, <link xref="introspection">introspecting an API</link> will automatically detect all GError parameters so that they can be converted to exceptions in other languages.
ko: GError는 더 많은 정보를 전달해줄 수 있으며 GLib 도구에서 지원하기에 단순 반환 코드를 취향에 따라 사용해야합니다. 예를 들어, <link xref="introspection">API 인트로스펙션</link> 과정에서 모든 GError 매개 변수를 자동으로 찾아서 다른 언어의 예외로 변환할 수 있습니다.

note: (itstool) path: section/p
en: Printing warnings to the console must not be done in library code: use a GError, and the calling code can propagate it further upwards, decide to handle it, or decide to print it to the console. Ideally, the only code which prints to the console will be top-level application code, and not library code.
ko: 라이브러리 코드에서는 콘솔에 경고를 출력하면 안됩니다. GError를 사용하십시오. 그러면 코드를 호출할 때 상위 코드로 오류를 전달할 수 있고, 처리 여부를 결정하거나, 콘솔 출력 여부를 결정할 수 있습니다. 이상적으로, 콘솔에 출력하는 코드는 최상위 프로그램 코드에만 있어야 하며, 라이브러리 코드에 있으면 안됩니다.

note: (itstool) path: section/p
en: Any function call which can take a <code>GError**</code>, <em>should</em> take such a parameter, and the returned GError should be handled appropriately. There are very few situations where ignoring a potential error by passing <code>NULL</code> to a <code>GError**</code> parameter is acceptable.
ko: <code>GError**</code>를 보유할 수 있는 어떤 함수든, 이 형식의 매개변수를 보유하고, 반환한 GError를 적절하게 반처리해야합니다. 가끔은 <code>GError**</code> 매개변수에 <code>NULL</code> 값을 전달하여 잠재 오류를 무시하는 편이 괜찮을 때가 있습니다.

note: (itstool) path: section/p
en: The GLib API documentation contains a <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#glib-Error-Reporting.description">full tutorial for using GError</link>.
ko: GLib API 문서에는 <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#glib-Error-Reporting.description">GError 활용 완벽 지침서</link>가 있습니다.

note: (itstool) path: info/desc
en: Linked lists and container types
ko: 연결 리스트 및 컨테이너 형식

note: (itstool) path: section/title
en: GList Usage
ko: GList 활용법

note: (itstool) path: section/p
en: GLib provides several container types for sets of data: <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html"><code>GList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Singly-Linked-Lists.html"><code>GSList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html"><code>GPtrArray</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Arrays.html"><code>GArray</code></link>.
ko: GLib에는 <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html"><code>GList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Singly-Linked-Lists.html"><code>GSList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html"><code>GPtrArray</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Arrays.html"><code>GArray</code></link> 데이터 집합 컨테이너 형식이 있습니다.

note: (itstool) path: section/p
en: It has been common practice in the past to use GList in all situations where a sequence or set of data needs to be stored. This is inadvisable — in most situations, a GPtrArray should be used instead. It has lower memory overhead (a third to a half of an equivalent list), better cache locality, and the same or lower algorithmic complexity for all common operations. The only typical situation where a GList may be more appropriate is when dealing with ordered data, which requires expensive insertions at arbitrary indexes in the array.
ko: 과거에 이 방식은 저장해야 할 데이터가 있는 모든 경우에 한해 GList를 활용하는 일반 방식이었지만, 이젠 별로 권할 바가 못됩니다. 대부분의 경우 GPtrArray를 대신 사용하는게 좋습니다. 적은 메모리를 차지하고(동일한 리스트 자료구조의 1/3에서 절반수준), 우월한 캐시 지역성을 확보하며, 모든 일반적 상황에서 동일한 또는 적은 알고리즘 복잡도를 보입니다. GList가 더 적절한 전형적인 유일한 경우는, 배열에서는 임의 색인 위치에 데이터를 삽입하려면 많은 노력을 들여야 하는데 반해 정렬 데이터를 취급할 경우일 뿐입니다.

note: (itstool) path: section/p
en: If linked lists are used, be careful to keep the complexity of operations on them low, using standard CS complexity analysis. Any operation which uses <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth"><code>g_list_nth()</code></link> or <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth-data"><code>g_list_nth_data()</code></link> is almost certainly wrong. For example, iteration over a GList should be implemented using the linking pointers, rather than a incrementing index:
ko: 연결 리스트를 사용한다면 표준 CS 복잡도 해석 기법을 활용하여 처리 복잡도를 낮게 유지하도록 만전을 기하십시오. <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth"><code>g_list_nth()</code></link> 함수 또는 <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth-data"><code>g_list_nth_data()</code></link>함수를 사용하는 어떤 동작의 경우는 거의 확실히 제대로 된 게 아닙니다. 예를 들어 GList를 순회한다면, 색인 값을 증가하기 보다, 연결 포인터를 활용하여 구현해야합니다:

note: (itstool) path: section/p
en: Using an incrementing index instead results in a quadratic decrease in performance (<em>O(N^2)</em> rather than <em>O(N)</em>):
ko: 색인 값 증가 방식을 활용하면 성능이 훨씬 더 떨어지는 결과를 초개합니다(<em>O(N)</em>이 아니라 <em>O(N^2)</em>임):

note: (itstool) path: section/p
en: The performance penalty comes from <code>g_list_length()</code> and <code>g_list_nth_data()</code> which both traverse the list (<em>O(N)</em>) to perform their operations.
ko: 리스트를 순차적으로 살펴보는(<em>O(N)</em>) <code>g_list_length()</code> 함수 및 <code>g_list_nth_data()</code> 함수를 실행하면 성능상 불이익을 가져옵니다.

note: (itstool) path: section/p
en: Implementing the above with a GPtrArray has the same complexity as the first (correct) GList implementation, but better cache locality and lower memory consumption, so will perform better for large numbers of elements:
ko: GPtrArray를 구현체의 동작상 복잡도는 처음(올바른) GList 구현제와 동일하지만, 캐시 지역성을 개선하며, 메모리를 덜 소모하여 더 많은 구성 항목을 저장할 때 성능상 우위를 점합니다:

note: (itstool) path: credit/name
en: GNOME Foundation
ko: 그놈 재단

note: (itstool) path: info/desc (itstool) path: page/title
en: GNOME Programming Guidelines
ko: 그놈 프로그래밍 지침서

[ctx: link:trail]
note: (itstool) path: info/title
en: Programming Guidelines
ko: 프로그래밍 지침서

note: (itstool) path: page/p
en: This article contains several guidelines and suggestions for programmers working in and with the GNOME stack. This is intended for programmers to know about the development processes, conventions and philosophies behind GNOME applications and the stack of libraries supporting them. By knowing “the way things are done” in the GNOME ecosystem, it is hoped that programmers will find use of GNOME APIs and development of new applications easier and more natural, and will produce code which is legible and maintainable over a long period of time by a diverse team of programmers.
ko: 이 글에는 그놈 스택에서 작업하는 프로그래머들에게 필요한 다양한 지침과 제안이 들어있습니다. 프로그래머가 개발 과정을 이해하고, 그놈 프로그램의 작성 규칙 및 철학을 배우며, 라이브러리 스택에서 이 과정을 지원함을 일깨우는 목적을 지니고 있습니다. 그놈 생태계에서 “마련한 수단”을 알면, 프로그래머가 그놈 API 사용법을 알고, 새 프로그램 개발을 더 쉽고 자연스럽게 할 수 있으며, 다양한 프로그래머로 구성한 팀에서 장기적으로 관리할 수 있고 알아보기 쉬운 코드를 만들어낼 수 있습니다.

note: (itstool) path: page/p
en: This guide has a two-fold purpose:
ko: 이 안내서의 목적은 두가지입니다:

note: (itstool) path: item/p
en: To give you good suggestions on how to write code for GNOME or using GNOME technologies. This will help you write code that is consistent with best practices, and that will be accepted by the community. This will also lead to code that is a pleasure to work on.
ko: 그놈 코드를 작성하는 방법 또는 그놈 기술 활용법의 바람직한 제언이 담겨있습니다. 최고의 예제를 통해 일관된 코드를 작성할 수 있도록, 그리고 커뮤니티에서 결과를 받아들이도록 도와드립니다. 또한 이 안내서에서는 즐겁게 코드를 작성할 수 있게 이끌어드립니다.

note: (itstool) path: item/p
en: To transmit the knowledge we have gotten over the years on how to keep the GNOME project sustainable, even when people’s contributions increase or decrease.
ko: 지식을 전달하려는 목적으로 여러 사람의 기여 추세가 증감할 때마다 그놈 프로젝트의 보존성을 유지하는 방법을 몇년에 걸쳐 깨달았습니다.

[ctx: link:trail]
note: (itstool) path: info/title
en: General Guidelines
ko: 일반 지침서

note: (itstool) path: section/title
en: General Guidelines
ko: 일반 지침서

[ctx: link:trail]
note: (itstool) path: info/title
en: Maintainer Guidelines
ko: 관리자 지침서

note: (itstool) path: section/title
en: Maintainer Guidelines
ko: 관리자 지침서

[ctx: link:trail]
note: (itstool) path: info/title
en: Specific How-Tos
ko: 개별 설명서

note: (itstool) path: section/title
en: Specific How-Tos
ko: 개별 설명서

[ctx: link:trail]
note: (itstool) path: info/title
en: References
ko: 참고서

note: (itstool) path: section/title
en: References
ko: 참고서

note: (itstool) path: info/desc
en: GObject Introspection support in library code
ko: 라이브러리 코드에 GObject 인트로스펙션 지원

note: (itstool) path: page/title
en: Introspection
ko: 인트로스펙션

note: (itstool) path: synopsis/p
en: <link href="https://wiki.gnome.org/Projects/GObjectIntrospection"> GObject introspection</link> (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 <link href="http://en.wikipedia.org/wiki/Type_introspection">introspect</link> or <link href="http://en.wikipedia.org/wiki/Language_binding">wrap</link> 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.
ko: <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의 추가 정보를 도출합니다.

note: (itstool) path: synopsis/p
en: It should be enabled for all public APIs: so all libraries. It cannot be enabled for programs, since they expose no APIs. However, it is still recommended to <link xref="documentation#introspection-annotations">add introspection annotations to documentation comments</link> in program code, as they clarify the documentation.
ko: 모든 공용 API, 즉 모든 라이브러리에서 쓸 수 있게 해야합니다. 프로그램 자체에서는 API를 노출하지 않으므로  프로그램에선 쓸 수 없습니다. 하지만 프로그램 코드의 <link xref="documentation#introspection-annotations">문서 주석에 인트로스펙션 주석을 추가</link>하여 문서에 명확히 해두는 것이 좋습니다.

note: (itstool) path: item/p
en: Enable introspection for all libraries. (<link xref="#using-introspection"/>)
ko: 모든 라이브러리에 인트로스펙션을 활성화하십시오(<link xref="#using-introspection"/>).

note: (itstool) path: item/p
en: Pay attention to warnings from <cmd>g-ir-scanner</cmd> and <code>introspectable="0"</code> attributes in GIR files. (<link xref="#using-introspection"/>)
ko: <cmd>g-ir-scanner</cmd> 및 GIR 파일의 <code>introspectable="0"</code> 속성 설정 때문에 나타나는 경고에 주의하십시오(<link xref="#using-introspection"/>).

note: (itstool) path: item/p
en: Add introspection annotations to all documentation comments. (<link xref="#using-introspection"/>)
ko: 모든 문서 주석에 인트로스펙션 주석을 추가하십시오(<link xref="#using-introspection"/>).

note: (itstool) path: item/p
en: Design APIs to be introspectable from the start. (<link xref="#api-design"/>)
ko: 시작 단계때부터 인트로스펙션할 수 있게 API를 설계하십시오(<link xref="#api-design"/>).

note: (itstool) path: section/title
en: Using Introspection
ko: 인트로스펙션 활용

note: (itstool) path: section/p
en: The first step for using introspection is to add it to the build system, following the instructions <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/AutotoolsIntegration#Method_1_-_Recommended_-_most_portable">here</link>, following method 1. This should be done early in the life of a project, as introspectability affects <link xref="#api-design">API design</link>.
ko: 인트로스펙션 활용 첫 단계는 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/AutotoolsIntegration#Method_1_-_Recommended_-_most_portable">여기</link> 절차의 1번 방식에 따른 빌드 시스템으로의 추가입니다. 인트로스펙션 기능성이 <link xref="#api-design">API 설계</link>에 영향을 주므로 프로젝트 초기에 미리 끝내야합니다.

note: (itstool) path: section/p
en: This should result in a <file>.gir</file> and <file>.typelib</file> file being generated for the project. The <file>.gir</file> file is human readable, and can be inspected manually to see if the API has been introspected correctly (although the GIR compilation process will print error messages and warnings for any missing annotations or other problems). APIs with <code>introspectable="0"</code> will not be exposed to language bindings as they are missing annotations or are otherwise not representable in the GIR file.
ko: 프로젝트에서 만든 <file>.gir</file> 파일과 <file>.typelib</file> 파일에 결과가 나타나야합니다. <file>.gir</file> 파일은 사람이 알아볼 수 있으며, API를 올바르게 인트로스펙션했을 때(GIR 컴파일 과정에서 일부 빠진 주석과 기타 문제에 대해 오류 메시지와 경고를 출력하긴 하지만) 직접 살펴볼 수 있습니다. <code>introspectable="0"</code> 속성을 설정한 API는 주석이 빠졌거나, 아니면 GIR 파일에 나타나지 않으므로 언어 바인딩에 나타나지 않습니다.

note: (itstool) path: section/p
en: The next step is to <link xref="documentation#introspection-annotations">add annotations to the documentation comments for every piece of public API</link>. If a particular piece of API should not be exposed in the GIR file, use the <code>(skip)</code> annotation. Documentation on the available annotations is <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">here</link>.
ko: 다음 단계는 <link xref="documentation#introspection-annotations">공용 API의 모든 부분의 문서 설명에 주석을 추가하는 일입니다</link>. 만약에 GIR 파일에 API 일부를 노출하면 안될 경우, <code>(skip)</code> 주석을 사용하십시오. 가용 주석을 설명하는 문서는 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">여기</link>에 있습니다.

note: (itstool) path: section/p
en: If annotating the code for a program, a good approach is to split the bulk of the code out into an internal, private convenience library. An internal API reference manual can be built from its documentation comments (see <link xref="documentation"/>). The library is then not installed, but is linked in to the program which is itself installed. This approach for generating internal API documentation is especially useful for large projects where the internal code may be large and hard to navigate.
ko: 프로그램의 코드에 주석을 넣을 때, 바람직한 접근 방식은 상당한 양의 코드를 자체적으로 쪼개어, 내부 전용 편의 라이브러리로 만드는 방법입니다. 자체 API 참조 설명서는 문서 주석으로 만들 수 있습니다(see <link xref="documentation"/>). 이렇게 하면 라이브러리를 설치하지 않지만, 이 라이브러리를 설치한 프로그램과 연결합니다. 이런 자체 API 문서 접근 방식은 자체 코드 규모가 커져 찾아보기 어려워지는 큰 프로젝트에 특히 쓸 만합니다.

note: (itstool) path: section/p
en: Annotations do not have to be added exhaustively: GIR has a set of default annotations which it applies based on various conventions (see <link xref="#api-design"/>). For example, a <code>const gchar*</code> parameter does not need an explicit <code>(transfer none)</code> annotation, because the <code>const</code> modifier implies this already. Learning the defaults for annotations is a matter of practice.
ko: 주석을 꼼꼼하게 달아둘 필요는 없습니다. GIR은 다양한 방식을 기반으로 적용하는 기본 주석 모음입니다(see <link xref="#api-design"/>). 예를 들어, <code>const gchar*</code> 매개 변수는 <code>const</code> 수정자에 이미 <code>(transfer none)</code> 주석의 의미가 있으므로 굳이 적어둘 필요는 없습니다. 주석의 기본 의미는 숙달 대상입니다.

note: (itstool) path: section/title
en: API Design
ko: API 설계

note: (itstool) path: section/p
en: In order to be introspectable without too many annotations, APIs must follow certain conventions, such as the <link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html">standard GObject naming conventions</link>, and the <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/WritingBindingableAPIs">conventions for bindable APIs</link>. This is necessary because of the flexibility of C: code can be written to behave in any way imaginable, but higher level languages don’t allow this kind of freedom. So in order for a C API to be representable in a higher level language, it has to conform to the behaviors supported by that language.
ko: 많은 주석을 달지 않고도 인트로스펙션을 활용할 수 있으려면, 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가, 좀 더 고수준의 언어인 것처럼 보이려면, 해당 언어에서 지원하는 동작에 맞춰야합니다.

note: (itstool) path: section/p
en: For example, GIR expects that if a function can fail, it will have a <code>GError**</code> parameter, which will always be its final parameter. The GIR scanner detects this and automatically converts that parameter to an exception attribute on the method in the GIR file. It cannot do this if the <code>GError*</code> is returned directly, or is not the final function parameter, for example.
ko: 이를테면, GIR에서는 함수 실행이 실패할 수 있음을 예상하여, 항상 마지막에 둘 매개변수로서 <code>GError**</code> 매개변수를 지니고 있습니다. GIR 탐색기에서는 GIR 파일에서 이 매개변수를 찾아 메서드의 예외 속성으로 자동 변환합니다. <code>GError*</code>를 직접 변환하거나, 마지막 함수 매개 변수가 아닐 경우에는 처리할 수 없습니다.

note: (itstool) path: section/p
en: Therefore, APIs must be designed to be introspectable, and the GIR file should be checked as the APIs are being written. If the GIR doesn’t match what you expect for a new API, the API may need extra annotations, or even for its C declaration to be changed (as in the case of <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/WritingBindingableAPIs#va_list"><code>va_list</code></link>).
ko: 따라서, API는 인트로스팩션을 활용할 수 있게 설계해야하며, GIR 파일은 API를 작성한 대로 검사해야 합니다. GIR과 새 API이 일치하지 않으면 API에는 추가 주석이 필요하거나, (<link href="https://wiki.gnome.org/Projects/GObjectIntrospection/WritingBindingableAPIs#va_list"><code>va_list</code></link>의 경우와 마찬가지로)C 선언문을 바꿔야 할 수도 있습니다.

note: (itstool) path: section/p
en: <cmd>g-ir-scanner</cmd> emits warnings when it encounters code it does not understand. By passing <cmd>--warn-error</cmd> as well as <cmd>--warn-all</cmd> in <code>INTROSPECTION_SCANNER_ARGS</code> in <file>Makefile.am</file>, compilation will fail when unintrospectable APIs are encountered. This will ensure all new APIs are introspectable, and is highly recommended.
ko: <cmd>g-ir-scanner</cmd>에서 이해할 수 없는 코드를 찾으면 경고를 출력합니다. <file>Makefile.am</file> 파일에서 <code>INTROSPECTION_SCANNER_ARGS</code>에 <cmd>--warn-error</cmd>, <cmd>--warn-all</cmd>를 전달하면 인트로스펙션을 활용할 수 없는 API임을 확인했을 때 컴파일에 실패합니다. 이 방법으로 새 API에서 인트로스펙션을 활용할 수 있는지 확인하기에 적극 추천합니다.

note: (itstool) path: info/desc
en: Logging debug and information output from libraries and programs
ko: 라이브러리 및 프로그램의 디버깅 및 정보 출력을 기록합니다

note: (itstool) path: page/title
en: Logging
ko: 기록

note: (itstool) path: synopsis/p
en: Logging debug and informational output from libraries and programs is an open problem, and there are various methods for converting multiple streams of log output into the customary stdout and stderr streams. Below are some suggestions for how to implement logging. However, the most important thing is to ensure that logging is consistent, so that log data can be accessed and searched with a minimum of effort, since that’s what it’s used for. Using different logging mechanisms and formats in different projects is not the right approach.
ko: 라이브러리 및 프로그램의 디버깅 출력 내지는 정보 출력 문제는 널리 알려진 문제이며, 개별 표준 입출력 및 표준 오류 스트림을 대상으로, 로그 출력을 다중 스트림으로 변환하는 다양한 방법이 있습니다. 몇가지 로그 처리 구현 방식을 제안해드리겠습니다. 그러나 가장 중요한건 로깅이 일관된 모양새를 지니도록 하여, 최소한의 노력으로 로그 데이터에 접근하고 검색하는게 목적대로 할 수 있어야합니다. 프로젝트별로 다른 로깅 기법 및 형식을 활용하는건 바람직한 접근 방식이 아닙니다.

note: (itstool) path: item/p
en: Use the GLib logging framework instead of logging directly to stderr and stdout. (<link xref="#glib-logging-framework"/>)
ko: 표준 오류 스트림 및 표준 출력 스트림으로 로그를 바로 내보내는 대신, GLib 로깅 프레임워크를 활용하십시오(<link xref="#glib-logging-framework"/>).

note: (itstool) path: item/p
en: If systemd can be a dependency of the project, consider logging directly to the journal. (<link xref="#journald-integration"/>)
ko: systemd를 프로젝트에 붙일 수 있다면 journal로 직접 로깅해보십시오(<link xref="#journald-integration"/>).

note: (itstool) path: item/p
en: Do not implement log rotation and deletion; leave that to system services. (<link xref="#log-rotation"/>)
ko: 로그 순환 및 삭제를 (따로) 구현하지 마시고 시스템 서비스가 알아서 하게 두십시오(<link xref="#log-rotation"/>).

note: (itstool) path: section/title
en: GLib Logging Framework
ko: GLib 기록 프레임워크

note: (itstool) path: section/p
en: GLib provides <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html">a logging framework</link> based around the <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log"><code>g_log()</code></link> function, with convenience wrappers <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"><code>g_debug()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-message"><code>g_message()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-warning"><code>g_warning()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-error"><code>g_error()</code></link>. The GLib logging framework has a few useful features:
ko: GLib에서는 <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log"><code>g_log()</code></link> 함수를 기반으로 <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"><code>g_debug()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-message"><code>g_message()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-warning"><code>g_warning()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-error"><code>g_error()</code></link> 편의 래퍼 함수로 이루어진 <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html">기록 프레임워크</link>를 제공합니다. 기록 프레임워크에는 몇가지 쓸 만한 기능이 있습니다:

note: (itstool) path: item/p
en: Programmatic redirection of log messages using <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log-set-handler"><code>g_log_set_handler()</code></link>.
ko: <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log-set-handler"><code>g_log_set_handler()</code></link> 함수를 활용한 프로그램에서의 기록 메시지 처리 대상 전환.

note: (itstool) path: item/p
en: Multiple logging domains, which can be processed separately.
ko: 따로 처리할 수 있는 다중 기록 도메인.

note: (itstool) path: item/p
en: Multiple log levels, which can be processed separately. For example, this allows debug messages to be turned on and off at runtime.
ko: 따로 처리할 수 있는 다중 기록 단계. 실행 시간 도중에 디버깅 메시지를 켜거나 끌 수 있습니다.

note: (itstool) path: item/p
en: Support for automatically aborting a program on ‘fatal’ messages.
ko: ‘fatal’ 메시지 출력시 자동 중단 지원.

note: (itstool) path: section/p
en: These should be used in preference to functions like <code>printf()</code>, <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-print"><code>g_print()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-printerr"><code>g_printerr()</code></link>, due to their enhanced flexibility. The logging functions allow log processing to be done in code, rather than by external shell scripting, which simplifies everything.
ko: 유연성 개선을 목적으로 <code>printf()</code>,<link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-print"><code>g_print()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-printerr"><code>g_printerr()</code></link>와 같은 함수를 취향에 따라 사용해야합니다. 로깅 처리 함수는 단순화 목적으로 외부 쉘 스크립트에서 보다는, 코드 자체에서 로그를 처리할 수 있습니다.

note: (itstool) path: section/p
en: A key reason to use the logging framework is that it is used in GLib and other related libraries already; by using it, all log messages are then going through the same system and can be processed similarly.
ko: 로깅 프레임워크를 사용하는 주된 이유는 GLib와 기타 관련 라이브러리에서 이미 사용하기 때문입니다. 로깅 프레임워크를 사용하면, 모든 로깅 메시지를 동일한 체계로 넘기며, 비슷하게 처리할 수 있습니다.

note: (itstool) path: section/p
en: To use the GLib logging framework, define <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#G-LOG-DOMAIN:CAPS"><code>G_LOG_DOMAIN</code></link> for the project so it’s unique from all other projects. Call <code>g_debug("Message")</code> to log a debug message.
ko: GLib 로깅 프레임워크를 활용하려면 모든 기타 프로젝트와 분명히 구분할 수 있도록 프로젝트에 <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#G-LOG-DOMAIN:CAPS"><code>G_LOG_DOMAIN</code></link>를 정의하십시오. 디버깅 메시지 기록을 남기려면 <code>g_debug("Message")</code> 함수 코드를 호출하십시오.

note: (itstool) path: section/p
en: If the default GLib log handlers are not sufficient, for example if log messages need to be in a custom format or <link xref="#journald-integration">journald integration</link> is needed, set up a log handler with the following code:
ko: 예를 들어 로그 메시지를 남길 때 자체 형식이 필요하거나 <link xref="#journald-integration">journald 통합</link>이 필요하여 기본 GLib 로그 처리자로 충분히 만족스럽지 않으면, 다음 코드로 로그 처리자를 설정하십시오:

note: (itstool) path: section/title
en: Exceptions
ko: 예외

note: (itstool) path: item/p
en: Do not use <code>g_message()</code> in normal code to print output. Printing output should be done at the top level of an application, using <code>g_print()</code>, and should be quite rare; i.e. only done in command line applications.
ko: 일반 코드에 <code>g_message()</code> 함수를 출력 용도로 사용하지 마십시오. 내용 출력은 명령행 프로그램과 같이 프로그램의 최상단 출력에 한해서만 <code>g_print()</code>로  드물게 처리해야합니다.

note: (itstool) path: item/p
en: Do not use <code>g_warning()</code> in library code. Use <link xref="gerror"><code>GError</code>s</link> instead.
ko: 라이브러리 코드에서 <code>g_warning()</code> 함수를 사용하지 마십시오. <link xref="gerror"><code>GError</code>s</link>를 대신 활용하십시오.

note: (itstool) path: item/p
en: Similarly, do not set up log handlers in library code. Log messages should propagate through library code and be handled in a log handler at the top level of an application.
ko: 이와 비슷하게, 라이브러리 코드에서 로그 처리자를 설정하지 마십시오. 로그 메시지는 라이브러리 코드에서 전달하고 로그 처리자가 프로그램의 최상단으로 전달해야 합니다.

note: (itstool) path: section/title
en: journald Integration
ko: journald 통합

note: (itstool) path: section/p
en: Compared to conventional syslog-style logs, journald supports storage of structured logging data, which can make post-hoc analysis of logs much easier. If it’s possible to add <code>systemd-journal</code> as a dependency to a project, the project’s log handling function could be extended to use <link href="http://0pointer.de/public/systemd-man/sd_journal_send.html"><code>sd_journal_print()</code> and <code>sd_journal_send()</code></link> instead of <code>g_print()</code> and <code>g_printerr()</code>.
ko: 기존의 syslog 방식 로그에 비해, journald에서는 로그의 이후 분석을 쉽게 해주는 구조적 로그 데이터 저장소를 지원합니다. 프로젝트의 의존 로그 처리자로 <code>systemd-journal</code>를 추가할 수 있다면, <code>g_print()</code> 함수와 <code>g_printerr()</code> 함수 대신 <link href="http://0pointer.de/public/systemd-man/sd_journal_send.html"><code>sd_journal_print()</code> 함수와 <code>sd_journal_send()</code></link>  함수로 프로젝트의 로그 처리 함수 활용 범위를 확장할 수 있습니다.

note: (itstool) path: section/p
en: For more information, see this <link href="http://0pointer.de/blog/projects/journal-submit.html">article on logging to the journal</link>.
ko: 자세한 내용은 <link href="http://0pointer.de/blog/projects/journal-submit.html">저널 기록 방법</link> 링크를 참고하십시오.

note: (itstool) path: section/title
en: Log Rotation
ko: 기록 전환

note: (itstool) path: section/p
en: Log file rotation is one feature which is out of scope of the GLib logging system. It should be handled by the normal system logging mechanisms, such as <cmd>logrotate</cmd> or <cmd>systemd-journald</cmd>.
ko: 기록 파일 전환은 GLib 리고 시스템의 범위를 벗어나는 기능 입니다. <cmd>logrotate</cmd> 또는 <cmd>systemd-journald</cmd>와 같은 일반 시스템 기록 매커니즘으로 처리합니다.

note: (itstool) path: info/desc
en: GLib main contexts, invoking functions in other threads, and the event loop
ko: 다른 스레드, 이벤트 반복 루틴에서 함수를 실행하는 GLib 메인 컨텍스트

note: (itstool) path: page/title
en: GLib Main Contexts
ko: GLib 메인 컨텍스트

note: (itstool) path: item/p
en: Use <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link> to invoke functions in other threads, assuming every thread has a thread default main context which runs throughout the lifetime of that thread (<link xref="#g-main-context-invoke-full"/>)
ko: 모든 스레드에는 해당 스레드가 동작하는 동안 실행할 기본 메인 컨텍스트가 있으므로, 다른 스레드에서 함수를 실행하려면 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link> 함수를 활용하십시오(<link xref="#g-main-context-invoke-full"/>)

note: (itstool) path: item/p
en: Use <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> to run a function in the background without caring about the specific thread used (<link xref="#gtask"/>)
ko: 개별 스레드 사용을 전혀 신경쓰지 않고 백그라운드에서 함수를 실행하려면 <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>를 활용하십시오(<link xref="#gtask"/>)

note: (itstool) path: item/p
en: Liberally use assertions to check which context executes each function, and add these assertions when first writing the code (<link xref="#checking-threading"/>)
ko: 각 함수를 실행하는 컨텍스트를 검사할 때 단언 기법을 자유롭게 활용하시고, 코드를 처음 작성할 때 이 단언부를 추가하십시오(<link xref="#checking-threading"/>)

note: (itstool) path: item/p
en: Explicitly document contexts a function is expected to be called in, a callback will be invoked in, or a signal will be emitted in (<link xref="#using-gmaincontext-in-a-library"/>)
ko: 호출 예상 함수, 실행할 콜백, 발생할 시그널의 상황을 분명하게 문서로 남겨주십시오(<link xref="#using-gmaincontext-in-a-library"/>)

note: (itstool) path: item/p
en: Beware of <code>g_idle_add()</code> and similar functions which implicitly use the global-default main context (<link xref="#implicit-use-of-the-global-default-main-context"/>)
ko: 전역 기본 메인 컨텍스트를 은연 중에 활용하는 <code>g_idle_add()</code> 함수 및 유사 함수 활용시 주의하십시오(<link xref="#implicit-use-of-the-global-default-main-context"/>)

note: (itstool) path: section/title
en: What is <code>GMainContext</code>?
ko: <code>GMainContext</code>란 무엇인가?

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainContext"><code>GMainContext</code></link> is a generalized implementation of an <link href="http://en.wikipedia.org/wiki/Event_loop">event loop</link>, useful for implementing polled file I/O or event-based widget systems (such as GTK+). It is at the core of almost every GLib application. To understand <code>GMainContext</code> requires understanding <link href="man:poll(2)">poll()</link> and polled I/O.
ko: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainContext"><code>GMainContext</code></link>는 폴링 방식 파일 입출력 또는 (GTK+ 같은) 이벤트 기반 위젯 시스템에서 쓸 만한 <link href="http://en.wikipedia.org/wiki/Event_loop">이벤트 루프</link>의 정규 구현체입니다. 거의 모든 GLib 프로그램의 핵심입니다. <code>GMainContext</code>를 이해하려면 <link href="man:poll(2)">poll()</link> 함수와 폴링 입출력을 이해해야 합니다.

note: (itstool) path: section/p
en: A <code>GMainContext</code> has a set of <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource"><code>GSource</code></link>s which are ‘attached’ to it, each of which can be thought of as an expected event with an associated callback function which will be invoked when that event is received; or equivalently as a set of file descriptors (FDs) to check. An event could be a timeout or data being received on a socket, for example. One iteration of the event loop will:
ko: <code>GMainContext</code>는 컨텍스트에 ‘붙은’ <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource"><code>GSource</code></link> 모음이며 각각의 GSource는 이벤트를 받았을 때 실행할 콜백 함수와 관련된 이벤트로 생각할 수 있습니다. 또는 검사할 파일 서술자(FD)의 모음과 동일하다고 볼 수 있습니다. 예를 들어, 이벤트는 이벤트는 소켓의 제한 시간 내지는 수신 데이터가 될 수 있습니다. 반복 이벤트 루프는 다음 동작을 수행합니다:

note: (itstool) path: item/p
en: Prepare sources, determining if any of them are ready to dispatch immediately.
ko: 즉시 실행 여부를 결정하는 소스를 준비합니다.

note: (itstool) path: item/p
en: Poll the sources, blocking the current thread until an event is received for one of the sources.
ko: 소스 중 하나에 해당하는 이벤트를 받기 전까지 현재 스레드의 실행을 막는 소스를 폴링합니다.

note: (itstool) path: item/p
en: Check which of the sources received an event (several could have).
ko: 받은 이벤트에 해당하는 소스가 어떤 소스인지 확인합니다(여러 소스가 있을 수 있음).

note: (itstool) path: item/p
en: Dispatch callbacks from those sources.
ko: 해당 소스에서 콜백을 실행합니다.

note: (itstool) path: section/p
en: This is <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#mainloop-states">explained very well</link> in the <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSourceFuncs">GLib documentation</link>.
ko: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSourceFuncs">GLib 문서 </link>에 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#mainloop-states">자세한 설명</link>이 있습니다.

note: (itstool) path: section/p
en: At its core, <code>GMainContext</code> is just a <code>poll()</code> loop, with the preparation, check and dispatch stages of the loop corresponding to the normal preamble and postamble in a typical <code>poll()</code> loop implementation, such as listing 1 from <link href="http://www.linux-mag.com/id/357/">this article</link>. Typically, some complexity is needed in non-trivial <code>poll()</code>-using applications to track the lists of FDs which are being polled. Additionally, <code>GMainContext</code> adds a lot of useful functionality which vanilla <code>poll()</code> doesn’t support. Most importantly, it adds thread safety.
ko: 이 내용의 핵심에서, <code>GMainContext</code>는 <link href="http://www.linux-mag.com/id/357/">이 게시글</link>의 Listing 1과 같이, 전형적인 <code>poll()</code> 루프 구현체에서, 일반적인 전후 처리를 담당하는 루프 실행 단계를 준비하고 검사하고 실행하는 <code>poll()</code> 루프일 뿐입니다. 보통, 어떤 FD를 처리할 지 마련한 <code>poll()</code> 목록을 지켜보는 중요한 <code>poll()</code> 함수 활용 프로그램에서 일부 복잡성이 필요하긴 합니다. 게다가 바닐라 <code>poll()</code> 함수를 지원하지 않는 다양한 쓸 만한 기능을 <code>GMainContext</code>에서 추가합니다. 가장 중요한 점이라면, 스레드 안전성의 추가입니다.

note: (itstool) path: section/p
en: <code>GMainContext</code> is completely thread safe, meaning that a <code>GSource</code> can be created in one thread and attached to a <code>GMainContext</code> running in another thread. (See also: <link xref="threading"/>.) A typical use for this might be to allow worker threads to control which sockets are being listened to by a <code>GMainContext</code> in a central I/O thread. Each <code>GMainContext</code> is ‘acquired’ by a thread for each iteration it’s put through. Other threads cannot iterate a <code>GMainContext</code> without acquiring it, which guarantees that a <code>GSource</code> and its FDs will only be polled by one thread at once (since each <code>GSource</code> is attached to at most one <code>GMainContext</code>). A <code>GMainContext</code> can be swapped between threads across iterations, but this is expensive.
ko: <code>GMainContext</code>는 스레드 실행에 완벽하게 안전하며, 어떤 스레드에 <code>GSource</code>를 만들고 다른 스레드에서 실행하는 <code>GMainContext</code>에 붙일 수 있습니다(추가 참고: <link xref="threading"/>). 일반 활용 방식은 작업 스레드에서 중앙 입출력 스레드의 <code>GMainContext</code>로 감청 소켓을 다룰 수 있게 합니다. 각 <code>GMainContext</code>는 반복 과정에서 <code>GMainContext</code>를 두어 취할 수 있습니다. 다른 스레드에서는 한 번에 하나의 스레드에서 <code>GSource</code>와 FD를 폴링 처리하도록 보장하는 <code>GMainContext</code>를 취하지 않으면 반복 처리할 수 없습니다(각 <code>GSource</code> 는 <code>GMainContext</code> 한 군데에만 붙기 때문). <code>GMainContext</code>는 반복 처리 과정에서 스레드간 상호 전환이 가능하지만, 처리 과정상 노력이 필요합니다.

note: (itstool) path: section/p
en: <code>GMainContext</code> is used instead of <code>poll()</code> mostly for convenience, as it transparently handles dynamically managing the array of FDs to pass to <code>poll()</code>, especially when operating over multiple threads. This is done by encapsulating FDs in <code>GSource</code>s, which decide whether those FDs should be passed to the <code>poll()</code> call on each ‘prepare’ stage of the main context iteration.
ko: <code>GMainContext</code>는, 특히 다중 스레드를 처리할 경우, <code>poll()</code>로의 FD 배열 전달을 동적으로 관리하도록 투명하게 처리하므로 대부분 편의상 <code>poll()</code> 대신 사용합니다. 메인 컨텍스트 반복 처리상 각 ‘준비’ 단계에서 호출하는 <code>poll()</code>에 해당 FD를 전달해야 하는지 여부를 결정하는 <code>GSource</code>에서 FD를 캡슐화하여 처리합니다.

note: (itstool) path: section/title
en: What is <code>GMainLoop</code>?
ko: <code>GMainLoop</code>란 무엇인가?

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainLoop"><code>GMainLoop</code></link> is essentially the following few lines of code, once reference counting and locking have been removed (from <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-loop-run"><code>g_main_loop_run()</code></link>):
ko: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainLoop"><code>GMainLoop</code></link>는 (<link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-loop-run"><code>g_main_loop_run()</code></link>에서) 참조 카운팅과 잠금을 뺀 다음 코드와 같이 몇 줄 안되는 본질입니다:

note: (itstool) path: section/p
en: Plus a fourth line in <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-loop-quit"><code>g_main_loop_quit()</code></link> which sets <code>loop-&gt;is_running = FALSE</code> and which will cause the loop to terminate once the current main context iteration ends.
ko: 그리고 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-loop-quit"><code>g_main_loop_quit()</code></link>의 네번째 줄에서는 <code>loop-&gt;is_running = FALSE</code>를 설정하고 현재 메인 컨텍스트 반복을 끝내 반복 실행을 중단합니다.

note: (itstool) path: section/p
en: Hence, <code>GMainLoop</code> is a convenient, thread-safe way of running a <code>GMainContext</code> to process events until a desired exit condition is met, at which point <code>g_main_loop_quit()</code> should be called. Typically, in a UI program, this will be the user clicking ‘exit’. In a socket handling program, this might be the final socket closing.
ko: 따라서, <code>GMainLoop</code>는 편하고, 나가는 상태를 만나기 전까지 이벤트를 처리하는 스레드에 안전한 <code>GMainContext</code> 실행 코드부이며, 프로그램 실행 상태를 빠져나가려면 <code>g_main_loop_quit()</code> 함수를 호출해야합니다. 이 경우는 보통 UI 프로그램에서 사용자가 ‘나가기’를 눌렀을 경우에 해당합니다. 소켓 처리 프로그램에서는 최종 소켓 처리 과정이 될 수 있습니다.

note: (itstool) path: section/p
en: It is important not to confuse main contexts with main loops. Main contexts do the bulk of the work: preparing source lists, waiting for events, and dispatching callbacks. A main loop simply iterates a context.
ko: 메인 컨텍스트와 메인 루프를 혼동하지 않는게 중요합니다. 메인 컨텍스트는 작업 자체를 실행합니다. 소스 리스트를 준비하고, 이벤트를 기다리며, 콜백을 실행합니다. 메인 루프는 단순히 컨텍스트를 반복 실행할 뿐입니다.

note: (itstool) path: section/title
en: Default Contexts
ko: 기본 컨텍스트

note: (itstool) path: section/p
en: One of the important features of <code>GMainContext</code> is its support for ‘default’ contexts. There are two levels of default context: the thread-default, and the global-default. The global-default (accessed using <code>g_main_context_default()</code>) is run by GTK+ when <code>gtk_main()</code> is called. It’s also used for timeouts (<code>g_timeout_add()</code>) and idle callbacks (<code>g_idle_add()</code>) — these won’t be dispatched unless the default context is running! (See: <link xref="#implicit-use-of-the-global-default-main-context"/>.)
ko: <code>GMainContext</code>의 중요한 기능 중 하나는 ‘기본’ 컨텍스트 지원입니다. 기본 컨텍스트의 실행 레벨은 두가지가 있습니다. 하나는 스레드 기본 레벨, 하나는 전역 기본 레벨입니다. 전역 기본 레벨(<code>g_main_context_default()</code> 함수로 접근함)은 <code>gtk_main()</code>함수를 호출했을 때 GTK+에서 실행합니다. 또한 대기시간 후 실행(<code>g_timeout_add()</code>) 및 대기 콜백(<code>g_idle_add()</code>) 용도로 활용할 수 있습니다. 이 함수는 기본 컨텍스트를 실행하기 전에는 실행하지 않습니다! (<link xref="#implicit-use-of-the-global-default-main-context"/> 참고)

note: (itstool) path: section/p
en: Thread-default contexts are a later addition to GLib (since version 2.22), and are generally used for I/O operations which need to run and dispatch callbacks in a thread. By calling <code>g_main_context_push_thread_default()</code> before starting an I/O operation, the thread-default context is set and the I/O operation can add its sources to that context. The context can then be run in a new main loop in an I/O thread, causing the callbacks to be dispatched on that thread’s stack rather than on the stack of the thread running the global-default main context. This allows I/O operations to be run entirely in a separate thread without explicitly passing a specific <code>GMainContext</code> pointer around everywhere.
ko: 스레드 기본 컨텍스트는 나중에 GLib에 추가(버전 2.22부터)했으며, 스레드에서 실행하고 콜백 함수를 실행해야 하는 입출력 처리에 보통 활용합니다. 입출력 처리를 시작하기 전에 <code>g_main_context_push_thread_default()</code> 함수를 호출하여 스레드 기본 컨텍스트를 설정하고 입출력 처리 과정에 해당 컨텍스트에 소스를 추가할 수 있습니다. 그 다음 컨텍스트를 전역 기본 메인 컨텍스트를 실행하는 스레드의 스택이 아닌 스레드 스택에서 콜백 함수를 실행하도록 하여 입출력 스레드의 새 메인 루프에서 실행할 수 있습니다. 이 과정으로 이곳 저곳에 특정 <code>GMainContext</code> 포인터를 분명하게 전달하지 않고도 각기 다른 스레드에서 입출력 처리를 실행할 수 있습니다.

note: (itstool) path: section/p
en: Conversely, by starting a long-running operation with a specific thread-default context set, the calling code can guarantee that the operation’s callbacks will be emitted in that context, even if the operation itself runs in a worker thread. This is the principle behind <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>: when a new <code>GTask</code> is created, it stores a reference to the current thread-default context, and dispatches its completion callback in that context, even if the task itself is run using <link href="https://developer.gnome.org/gio/stable/GTask.html#g-task-run-in-thread"><code>g_task_run_in_thread()</code></link>.
ko: 반대로 말해, 다수의 개별 스레드 기본 컨텍스트에서 오래 동작하는 처리 과정을 시작하면, 해당 처리 과정을 작업 스레드에서 처리 한다 하더라도, 호출 코드에서 처리 과정상 콜백 함수의 실행을 보장할 수 있습니다. 이는 <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>의 처리 원칙입니다. 새 <code>GTask</code>를 만들면, <link href="https://developer.gnome.org/gio/stable/GTask.html#g-task-run-in-thread"><code>g_task_run_in_thread()</code></link> 함수로 작업 자체를 실행한다 하더라도, 현재 스레드 기본 컨텍스트에 참조를 저장하고 해당 컨텍스트의 마무리 콜백 함수를 실행합니다.

note: (itstool) path: example/p
en: For example, the code below will run a <code>GTask</code> which performs two writes in parallel from a thread. The callbacks for the writes will be dispatched in the worker thread, whereas the callback from the task as a whole will be dispatched in the <code>interesting_context</code>.
ko: 예를 들어, 아래 코드는 스레드에서 동시에 두가지의 기록을 수행하는 <code>GTask</code>를 실행합니다. 전체 작업 과정의 콜백 함수는 <code>interesting_context</code>에서 실행하는데 반해, 기록 과정에 활용할 콜백 함수는 작업 스레드에서 실행합니다.

note: (itstool) path: section/title
en: Implicit Use of the Global-Default Main Context
ko: 전역 기본 메인 컨텍스트의 암시적 활용

note: (itstool) path: section/p
en: Several functions implicitly add sources to the global-default main context. They should <em>not</em> be used in threaded code. Instead, use <code>g_source_attach()</code> with the <code>GSource</code> created by the replacement function from the table below.
ko: 몇가지 함수는 전역 기본 메인 컨텍스트로 암암리에 소스를 추가합니다. 스레드 코드에서는 사용하면 <em>안됩니다</em>. 대신 아래 표의 대용 함수로 만든 <code>GSource</code>와 <code>g_source_attach()</code> 함수를 활용하십시오.

note: (itstool) path: section/p
en: Implicit use of the global-default main context means the callback functions are invoked in the main thread, typically resulting in work being brought back from a worker thread into the main thread.
ko: 전역 기본 메인 컨텍스트를 암묵적으로 사용한다 함은 곧 메인 스레드에서 콜백 함수를 호출한다는 의미이며, 보통, 작업 스레드에서 메인 스레드로 작업이 넘어갑니다.

note: (itstool) path: td/p
en: Do not use
ko: 사용하지 마십시오

note: (itstool) path: td/p
en: Use instead
ko: 대신 다음을 사용하십시오

note: (itstool) path: example/p
en: So to delay some computation in a worker thread, use the following code:
ko: 작업 스레드 처리를 지연하려면 다음 코드를 활용하십시오:

note: (itstool) path: section/title
en: Using <code>GMainContext</code> in a Library
ko: 라이브러리에서 <code>GMainContext</code> 활용

note: (itstool) path: section/p
en: At a high level, library code must not make changes to main contexts which could affect the execution of an application using the library, for example by changing when the application’s <code>GSource</code>s are dispatched. There are various best practices which can be followed to aid this.
ko: 고수준 영역에서, 라이브러리 코드는 라이브러리를 활용하여 프로그램을 실행할 때 영향을 주는 프로그램의 메인 컨텍스트에서 <code>GSource</code>를 실행할 때 변화를 주는 식으로 변화를 주면 안됩니다. 이 문제를 해결할 때 따를 수 있는 다양한 바람직한 사례가 있습니다.

note: (itstool) path: section/p
en: Never iterate a context created outside the library, including the global-default or thread-default contexts. Otherwise, <code>GSource</code>s created in the application may be dispatched when the application is not expecting it, causing <link href="http://en.wikipedia.org/wiki/Reentrancy_%28computing%29">re-entrancy problems</link> for the application code.
ko: 라이브러리, 전역 기본 컨텍스트, 스레드 기본 컨텍스트에서 만든 컨텍스트를 반복 실행하지 마십시오. 프로그램에서 <code>GSource</code> 생성을 기대하지 않을 때 프로그램에서 프로그램 코드에서 <link href="http://en.wikipedia.org/wiki/Reentrancy_%28computing%29">재진입 문제</link>를 유발하는 <code>GSource</code>를 실행합니다.

note: (itstool) path: section/p
en: Always remove <code>GSource</code>s from a main context before dropping the library’s last reference to the context, especially if it may have been exposed to the application (for example, as a thread-default). Otherwise the application may keep a reference to the main context and continue iterating it after the library has returned, potentially causing unexpected source dispatches in the library. This is equivalent to not assuming that dropping the library’s last reference to a main context will finalize that context.
ko: 특히 프로그램에 <code>GSource</code>가 나타난다면(예: 스레드 기본), 라이브러리 최종 참조를 컨텍스트로 두기 전 메인 컨텍스트에서 <code>GSource</code>를 항상 제거하십시오. 그렇지 않으면 프로그램에서 계속 메인 컨텍스트를 참조하고 라이브러리에서 결과값을 반환한 후에도 계속 참조 유지를 반복하여, 라이브러리에서 예기치 못한 소스 실행이 일어납니다. 이는 라이브러리의 최종 참조를 해당 컨텍스트를 끝낼 메인 컨텍스트에 두도록 고려하지 않는 것과 동일합니다.

note: (itstool) path: section/p
en: If the library is designed to be used from multiple threads, or in a context-aware fashion, always document which context each callback will be dispatched in. For example, “callbacks will always be dispatched in the context which is the thread-default at the time of the object’s construction”. Developers using the library’s API need to know this information.
ko: 라이브러리를 다중 스레드에서 사용하도록 설계했거나, 상황별로 사용하는 식이라면 어떤 컨텍스트에서 어떤 콜백을 실행할 지 항상 문서화하십시오. 예를 들자면, “객체 생성시 스레드 기본 컨텍스트에서 콜백을 항상 실행한다”와 같은 식입니다. 라이브러리 API를 활용하는 개발자는 이 내용을 알고 있어야합니다.

note: (itstool) path: section/p
en: Use <code>g_main_context_invoke()</code> to ensure callbacks are dispatched in the right context. It’s much easier than manually using <code>g_idle_source_new()</code> to transfer work between contexts. (See: <link xref="#ensuring-functions-are-called-in-the-right-context"/>.)
ko: <code>g_main_context_invoke()</code> 함수를 활용하여 올바른 컨텍스트에서 콜백을 실행했는지 확인하십시오. 컨텍스트간 작업을 전달할 때 <code>g_idle_source_new()</code> 함수 직접 실행보다 훨씬 쉽습니다(참고: <link xref="#ensuring-functions-are-called-in-the-right-context"/>).

note: (itstool) path: section/p
en: Libraries should never use <code>g_main_context_default()</code> (or, equivalently, pass <code>NULL</code> to a <code>GMainContext</code>-typed parameter). Always store and explicitly use a specific <code>GMainContext</code>, even if it often points to some default context. This makes the code easier to split out into threads in future, if needed, without causing hard-to-debug problems caused by callbacks being invoked in the wrong context.
ko: 라이브러리에서는 <code>g_main_context_default()</code> 함수를 사용하지 말아야합니다(또는, 이와 동일하게 <code>GMainContext</code> 형식 매개변수에 <code>NULL</code>을 전달하면 안됩니다). <code>GMainContext</code>가 일부 기본 컨텍스트를 자주 가리키더라도, 항상 개별 <code>GMainContext</code>를 저장하고 분명하게 활용하십시오. 이렇게 하면, 나중에 필요한 경우 잘못된 컨텍스트에서 콜백을 실행하여 발생하는 디버깅 난제를 유발하지 않고도 코드를 쉽게 스레드로 쪼갤 수 있습니다.

note: (itstool) path: section/p
en: Always write things asynchronously internally (using <link xref="#gtask"><code>GTask</code></link> where appropriate), and keep synchronous wrappers at the very top level of an API, where they can be implemented by calling <code>g_main_context_iteration()</code> on a specific <code>GMainContext</code>. Again, this makes future refactoring easier. This is demonstrated in the above example: the thread uses <code>g_output_stream_write_async()</code> rather than <code>g_output_stream_write()</code>.
ko: 항상 자체적으로 비동기 실행하도록 작성(적당한 곳에 <link xref="#gtask"><code>GTask</code></link> 활용)하고, 개별 <code>GMainContext</code>에서 <code>g_main_context_iteration()</code> 함수를 호출하여 구현할 수 있는 API의 최상단 레벨에서 래퍼의 동기화 실행 상태를 유지하십시오. 다시 말하자면, 앞으로의 일을 대비하면 리팩토링이 쉬워집니다. 위 예제를 통한 시연 예를 들어보겠습니다. 스레드는 <code>g_output_stream_write()</code> 함수 대신 <code>g_output_stream_write_async()</code> 함수를 활용합니다.

note: (itstool) path: section/p
en: Always match pushes and pops of the thread-default main context: <code>g_main_context_push_thread_default()</code> and <code>g_main_context_pop_thread_default()</code>.
ko: 스레드 기본 메인 컨텍스트에서 <code>g_main_context_push_thread_default()</code> 함수 및 <code>g_main_context_pop_thread_default()</code> 함수로 삽입, 제거를 일치시키십시오.

note: (itstool) path: section/title
en: Ensuring Functions are Called in the Right Context
ko: 올바른 컨텍스트에서의 함수 호출 확인

note: (itstool) path: section/p
en: The ‘right context’ is the thread-default main context of the <em>thread the function should be executing in</em>. This assumes the typical case that every thread has a <em>single</em> main context running in a main loop. A main context effectively provides a work or <link href="http://en.wikipedia.org/wiki/Message_queue">message queue</link> for the thread — something which the thread can periodically check to determine if there is work pending from another thread. Putting a message on this queue – invoking a function in another main context – will result in it eventually being dispatched in that thread.
ko: ‘적절한 컨텍스트’란 <em>함수를 실행하는 스레드</em>의 스레드 기본 메인 컨텍스트를 말합니다. 모든 스레드에는 메인 루프에서 실행하는 <em>단일</em> 메인 컨텍스트를 보유하고 있는 전형적인 상황을 가정합니다. 메인 컨텍스트는 스레드에 작업 또는 <link href="http://en.wikipedia.org/wiki/Message_queue">메시지 큐</link>를 분명하게 전달합니다. 어떤 스레드에서는 주기적으로 다른 스레드에서 대기 중인 작업이 있는지 확인합니다. 다른 메인 컨텍스트에서 함수를 실행하는 메시지를 이 큐에 넣으면 어쨌든 꼭 해당 스레드에서 실행합니다.

note: (itstool) path: example/p
en: For example, if an application does a long and CPU-intensive computation it should schedule this in a background thread so that UI updates in the main thread are not blocked. The results of the computation, however, might need to be displayed in the UI, so some UI update function must be called in the main thread once the computation’s complete.
ko: 예를 들어, 어떤 프로그램이 긴 시간동안 CPU를 높은 비율로 점유하는 작업을 수행한다면, 백그라운드 스레드에서 작업하도록 기획하여 메인 스레드에서 UI 업데이트 과정을 멈추지 않게 해야합니다. 그러나 이 처리 과정의 결과는 UI에 나타내어, 처리 과정이 끝났을 때 일부 UI 업데이트 함수를 메인 스레드에서 한 번은 호출해야합니다.

note: (itstool) path: example/p
en: Furthermore, if the computation function can be limited to a single thread, it becomes easy to eliminate the need for locking a lot of the data it accesses. This assumes that other threads are implemented similarly and hence most data is only accessed by a single thread, with threads communicating by <link href="http://en.wikipedia.org/wiki/Message_passing">message passing</link>. This allows each thread to update its data at its leisure, which significantly simplifies locking.
ko: 게다가, 처리 함수 실행을 단일 스레드로 제한할 수 있을 경우 많은 양의 데이터에 접근하는 동작을 제한할 필요성을 쉽게 없앨 수 있습니다. 이 경우는 다른 스레드를 비슷하게 구현하여 대부분의 데이터를 <link href="http://en.wikipedia.org/wiki/Message_passing">메시지 전달 기법</link>으로 스레드간 통신을 수행하여 단일 스레드에서만 접근하는 경우를 가정합니다. 이 상황의 경우 각 스레드에서 다른 스레드로의 데이터 접근을 막는 과정을 확실히 단순화하여 충분한 여유를 두고 데이터를 업데이트할 수 있게 합니다.

note: (itstool) path: section/p
en: For some functions, there might be no reason to care which context they’re executed in, perhaps because they’re asynchronous and hence do not block the context. However, it is still advisable to be explicit about which context is used, since those functions may emit signals or invoke callbacks, and for reasons of thread safety it’s necessary to know which threads those signal handlers or callbacks are going to be invoked in.
ko: 일부 함수에 대해서는, 이 함수를 실행하는 컨텍스트가 어떤 컨텍스트인지 신경쓸 이유가 되지 않을 수도 있습니다. 아마도, 비동기 방식으로 실행하기에 컨텍스트의 실행을 방해하지 않기 때문입니다. 그러나 이 함수가 시그널을 내보내거나 콜백 함수를 실행할 수 있기 때문에 여전히 어떤 컨텍스트를 활용하는지 분명히 해두는게 좋으며, 스레드 실행 안전을 이유로 어떤 스레드에서 시그널 처리자와 콜백 함수를 실행하는지도 알아야 합니다.

note: (itstool) path: example/p
en: For example, the progress callback in <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-copy-async"><code>g_file_copy_async()</code></link> is documented as being called in the thread-default main context at the time of the initial call.
ko: 예를 들면, <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-copy-async"><code>g_file_copy_async()</code></link> 함수의 처리 과정 콜백은 초기 호출시 스레드 기본 메인 컨텍스트에서 호출했을 경우를 문서로 남겨두었습니다.

note: (itstool) path: section/title
en: Principles of Invocation
ko: 실행 원리

note: (itstool) path: section/p
en: The core principle of invoking a function in a specific context is simple, and is walked through below to explain the concepts. In practice the <link xref="#g-main-context-invoke-full">convenience method, <code>g_main_context_invoke_full()</code></link> should be used instead.
ko: 개별 컨텍스트에서 함수를 실행하는 핵심 원칙은 단순하며, 아래에 계속해서 원리를 설명하겠습니다. 실제로는, 대신 <link xref="#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code> 편의 함수</link>를 활용해야합니다.

note: (itstool) path: section/p
en: A <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource"><code>GSource</code></link> has to be added to the target <code>GMainContext</code>, which will invoke the function when it’s dispatched. This <code>GSource</code> should almost always be an idle source created with <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-idle-source-new"><code>g_idle_source_new()</code></link>, but this doesn’t have to be the case. It could be a timeout source so that the function is executed after a delay, for example.
ko: <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource"><code>GSource</code></link>는 함수를 호출하여 실행할 <code>GMainContext</code> 타겟에 추가해야합니다. <code>GSource</code>는 항상 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-idle-source-new"><code>g_idle_source_new()</code></link> 함수로 만든 대기 소스여야 하지만, 꼭 이렇게 할 필요는 없습니다. 대기 시간을 걸어두어 일정 시간이 지나면 함수를 실행하게 할 수 있습니다.

note: (itstool) path: section/p
en: The <code>GSource</code> will be <link xref="#what-is-gmaincontext">dispatched as soon as it’s ready</link>, calling the function on the thread’s stack. In the case of an idle source, this will be as soon as all sources at a higher priority have been dispatched — this can be tweaked using the idle source’s priority parameter with <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-source-set-priority"><code>g_source_set_priority()</code></link>. The source will typically then be destroyed so the function is only executed once (though again, this doesn’t have to be the case).
ko: <code>GSource</code>는 스레드 스택에서 호출할 때 <link xref="#what-is-gmaincontext">준비한 대로 실행합니다</link>. 대기 소스의 경우, 실행한 소스 중 가장 높은 우선 순위에 있는 모든 소스가 됩니다. <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-source-set-priority"><code>g_source_set_priority()</code></link> 함수의 대기 소스 우선 순위 매개변수로 설정할 수 있습니다. 그 다음 소스를 메모리에서 제거하여 함수를 한 번만 실행하게 합니다(다시 말하지만, 꼭 이런건 아닙니다).

note: (itstool) path: section/p
en: Data can be passed between threads as the <code>user_data</code> passed to the <code>GSource</code>’s callback. This is set on the source using <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-source-set-callback"><code>g_source_set_callback()</code></link>, along with the callback function to invoke. Only a single pointer is provided, so if multiple data fields need passing, they must be wrapped in an allocated structure.
ko: <code>GSource</code> 콜백에 <code>user_data</code>를 전달할 때처럼 데이터를 스레드에서 스레드로 전달할 수 있습니다. 실행할 콜백 함수와 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-source-set-callback"><code>g_source_set_callback()</code></link> 함수를 활용하는 소스의 셋입니다. 단일 포인터만 제공하기에 다중 데이터 필드를 전달해야 한다면 할당 구조로 래핑해야합니다.

note: (itstool) path: example/p
en: The example below demonstrates the underlying principles, but there are convenience methods explained below which simplify things.
ko: 하단의 예제에서는 근본 원칙을 보여주지만, 어떤 부분을 단순화할 지 간편한 방식으로 설명합니다.

note: (itstool) path: example/p
en: This invocation is <em style="strong">uni-directional</em>: it calls <code>my_func()</code> in <code>thread1</code>, but there’s no way to return a value to the main thread. To do that, the same principle needs to be used again, invoking a callback function in the main thread. It’s a straightforward extension which isn’t covered here.
ko: 위 코드의 실행은 <em style="strong">단방향성</em>을 지닙니다. <code>thread1</code>에서 <code>my_func()</code> 함수를 호출하지만 메인 스레드로 값을 반환할 방법이 없습니다. 이렇게 하려면 메인 스레드에서 콜백 함수를 실행하는 동일한 원칙을 활용해야합니다. 이 방식은 여기서 다루지 않던 간단한 추가 방식입니다.

note: (itstool) path: example/p
en: To maintain thread safety, data which is potentially accessed by multiple threads must make those accesses mutually exclusive using a <link href="http://en.wikipedia.org/wiki/Mutual_exclusion">mutex</link>. Data potentially accessed by multiple threads: <code>thread1_main_context</code>, passed in the fork call to <code>thread1_main</code>; and <code>some_object</code>, a reference to which is passed in the data closure. Critically, GLib guarantees that <code>GMainContext</code> is thread safe, so sharing <code>thread1_main_context</code> between threads is safe. The example assumes that other code accessing <code>some_object</code> is thread safe.
ko: 스레드 안전성을 유지하려면 다중 스레드에서 잠재적으로 접근할 수 있는 데이터를 <link href="http://en.wikipedia.org/wiki/Mutual_exclusion">뮤텍스</link>를 활용하여 상호배타적으로 접근하게 해야합니다. 데이터는 다중 스레드에서 접근할 수 있습니다. <code>thread1_main_context</code>는 포킹 호출을 <code>thread1_main</code>에 전달하며, <code>some_object</code>는 데이터 클로저에 전달한 참조입니다. 중요한 점은, GLib에서 <code>GMainContext</code>가 스레드 실행에 안전함을 보장하기에, 스레드간 <code>thread1_main_context</code> 공유도 안전합니다. 예제에서는 <code>some_object</code>에 접근하는 다른 코드도 스레드 실행에 안전하다고 간주합니다.

note: (itstool) path: example/p
en: Note that <code>some_string</code> and <code>some_int</code> cannot be accessed from both threads, because <em>copies</em> of them are passed to <code>thread1</code>, rather than the originals. This is a standard technique for making cross-thread calls thread safe without requiring locking. It also avoids the problem of synchronizing freeing <code>some_string</code>.
ko: <code>some_string</code>과 <code>some_int</code>는 이들 사본을 원본 스레드가 아닌 <code>thread1</code>에 전달하므로 각 스레드에서 접근할 수 없음을 참고하십시오. 교차 스레드 호출을 별도의 잠금 매커니즘 없이 스레드에서 안전하게 실행할 수 있게 하는 표준 기술입니다. 이 기술로 하여금 <code>some_string</code> 해제 동기화 문제를 막아줍니다.

note: (itstool) path: example/p
en: Similarly, a reference to <code>some_object</code> is transferred to <code>thread1</code>, which works around the issue of synchronizing destruction of the object (see <link xref="memory-management"/>).
ko: 이와 비슷하게, <code>some_object</code> 참조를, 객체 해제 동기화 문제를 피하는 <code>thread1</code>로 전달합니다(<link xref="memory-management"/> 참고).

note: (itstool) path: example/p
en: <code>g_idle_source_new()</code> is used rather than the simpler <code>g_idle_add()</code> so the <code>GMainContext</code> to attach to can be specified.
ko: 더 간단한 <code>g_idle_add()</code> 함수보다 <code>g_idle_source_new()</code> 함수를 사용하여 <code>GMainContext</code>가 붙을 대상을 지정할 수 있습니다.

note: (itstool) path: section/title
en: Convenience Method: <code>g_main_context_invoke_full()</code>
ko: 간편한 메서드: <code>g_main_context_invoke_full()</code>

note: (itstool) path: section/p
en: This is simplified greatly by the convenience method, <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link>. It invokes a callback so that the specified <code>GMainContext</code> is owned during the invocation. Owning a main context is almost always equivalent to running it, and hence the function is invoked in the thread for which the specified context is the thread-default.
ko: 간편한 메서드 <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link>로 엄청나게 단순화했습니다. 콜백을 실행하여 실행하는 동안 지정 <code>GMainContext</code>을 소유합니다. 소유한 메인 컨텍스트는 실행하는 동안 거의 항상 동일하며, 스레드의 기본으로 지정한 컨텍스트의 스레드에서 함수를 실행합니다.

note: (itstool) path: section/p
en: <code>g_main_context_invoke()</code> can be used instead if the user data does not need to be freed by a <code>GDestroyNotify</code> callback after the invocation returns.
ko: 실행 과정 반환 처리 후 <code>GDestroyNotify</code> 콜백에서 데이터를 해제할 필요가 없다면 <code>g_main_context_invoke()</code> 함수를 대신 사용할 수 있습니다.

note: (itstool) path: example/p
en: Modifying the earlier example, the <code>invoke_my_func()</code> function can be replaced by the following:
ko: 쉬운 예제를 수정하여 다음과 같이 <code>invoke_my_func()</code> 함수 코드를 바꿀 수 있습니다:

note: (itstool) path: example/p
en: Consider what happens if <code>invoke_my_func()</code> were called from <code>thread1</code>, rather than from the main thread. With the original implementation, the idle source would be added to <code>thread1</code>’s context and dispatched on the context’s next iteration (assuming no pending dispatches with higher priorities). With the improved implementation, <code>g_main_context_invoke_full()</code> will notice that the specified context is already owned by the thread (or ownership can be acquired by it), and will call <code>my_func_idle()</code> directly, rather than attaching a source to the context and delaying the invocation to the next context iteration.
ko: <code>invoke_my_func()</code> 함수를 메인 스레드가 아닌 <code>thread1</code>에서 호출했다고 합시다. 초기 구현체에서 대기 소스는 <code>thread1</code> 컨텍스트에 추가하고 컨텍스트의 다음 반복 실행 과정에 실행합니다(더 높은 우선순위로 인해 실행 대기하지 않음을 가정). 개선 구현체에서는 <code>g_main_context_invoke_full()</code> 함수에서 스레드에서 지정 컨텍스트를 취했음을(또는 스레드에서 소유권을 취할 수 있고) 알린 후, 컨텍스트에 소스를 붙이고 다음 컨텍스트 반복 과정까지 실행을 지연하기보단, <code>my_func_idle()</code> 함수를 직접 실행합니다.

note: (itstool) path: example/p
en: This subtle behavior difference doesn’t matter in most cases, but is worth bearing in mind since it can affect blocking behavior (<code>invoke_my_func()</code> would go from taking negligible time, to taking the same amount of time as <code>my_func()</code> before returning).
ko: 대부분 미묘한 동작상 차이는 그다지 문제가 되지 않지만, 동작을 멈추게 할 수 있기 때문에 참고해야합니다(<code>invoke_my_func()</code> 함수는 무시해도 될 정도의 시간동안 실행하지만, 걸리는 시간은 <code>my_func()</code> 함수의 반환 이전 실행 시간과 같습니다).

note: (itstool) path: section/title
en: Checking Threading
ko: 스레드 검사

note: (itstool) path: section/p
en: It is useful to document which thread each function should be called in, in the form of an assertion:
ko: 각 함수를 어떤 스레드에서 실행해야 할 지, 단언 형식으로 문서에 남겨둘 때 쓸 만합니다:

note: (itstool) path: section/p
en: If that’s put at the top of each function, any assertion failure will highlight a case where a function has been called from the wrong thread. It is much easier to write these assertions when initially developing code, rather than debugging race conditions which can easily result from a function being called in the wrong thread.
ko: 각 함수의 최상단에 두었다면, 잘못된 스레드에서 함수를 호출했을 때 강조된 채로 단언 실행에 실패합니다. 잘못된 스레드에서 호출할 함수의 결과를 쉽게 기대하는 식으로 경쟁 상황을 디버깅하기보다는, 초기 코드를 개발할 때 단언부를 작성하는게 훨씬 용이합니다.

note: (itstool) path: section/p
en: This technique can also be applied to signal emissions and callbacks, improving type safety as well as asserting the right context is used. Note that signal emission via <link href="https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-emit"><code>g_signal_emit()</code></link> is synchronous, and doesn’t involve a main context at all.
ko: 이 기법은 올바른 컨텍스트를 활용했는지 검사하는 형 안전성 개선 목적으로 시그널 발생 및 콜백 함수에도 적용할 수 있습니다. 참고로 <link href="https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-emit"><code>g_signal_emit()</code></link> 함수 호출을 통한 시그널 발생은 동기 처리 방식이며, 모든 시그널이 메인 컨텍스트와 동작하진 않습니다.

note: (itstool) path: example/p
en: For example, instead of using the following when emitting a signal:
ko: 예를 들어, 시그널을 보낼 때 다음 코드를 활용하는 대신:

note: (itstool) path: example/p
en: The following can be used:
ko: 다음 코드를 활용할 수 있습니다:

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> provides a slightly different approach to invoking functions in other threads, which is more suited to the case where a function should be executed in <em>some</em> background thread, but not a specific one.
ko: <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>는 별도의 스레드가 아닌 <em>일부</em> 백그라운드 스레드에서 함수를 실행해야 안성맞춤일 경우 다른 스레드에서 함수를 실행하는 약간 다른 접근 방식을 취합니다.

note: (itstool) path: section/p
en: <code>GTask</code> takes a data closure and a function to execute, and provides ways to return the result from this function. It handles everything necessary to run that function in an arbitrary thread belonging to some thread pool internal to GLib.
ko: <code>GTask</code>는 실행할 데이터 클로저와 함수를 취하며, 이 함수에서 결과를 반환하는 반환하는 방편을 제공합니다. <code>GTask</code>는 GLib 자체의 일부 스레드 풀에 있는 임의 스레드에서 해당 함수를 실행할 때 필요한 모든 수단을 통제합니다.

note: (itstool) path: example/p
en: By combining <link xref="#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link> and <code>GTask</code>, it is possible to run a task in a specific context and effortlessly return its result to the current context:
ko: <link xref="#g-main-context-invoke-full"><code>g_main_context_invoke_full()</code></link> 함수와 <code>GTask</code>를 함께 사용하면 특정 컨텍스트의 작업을 실행할 수 있고, 굳이 어떤 노력을 들이지 않고도 현재 컨텍스트로 결과를 반환할 수 있습니다:

note: (itstool) path: info/desc
en: Managing memory allocation and deallocation in C
ko: C언어에서 메모리 할당 및 해제 관리

note: (itstool) path: page/title
en: Memory Management
ko: 메모리 관리

note: (itstool) path: page/p
en: The GNOME stack is predominantly written in C, so dynamically allocated memory has to be managed manually. Through use of GLib convenience APIs, memory management can be trivial, but programmers always need to keep memory in mind when writing code.
ko: 그놈 스택은 근본적으로 C로 작성했으므로 동적 할당 메모리는 직접 관리합니다. GLib 편의 API를 사용하여 메모리 관리를 분명하게 처리할 수 있긴 하지만, 프로그래머는 그래도 코드를 작성할 때는 항상 메모리의 상태를 고려해야합니다.

note: (itstool) path: page/p
en: It is assumed that the reader is familiar with the idea of heap allocation of memory using <code>malloc()</code> and <code>free()</code>, and knows of the paired GLib equivalents, <code>g_malloc()</code> and <code>g_free()</code>.
ko: 독자 여러분이 <code>malloc()</code> 함수 및 <code>free()</code> 함수를 활용하여 메모리 힙 영역 할당에 익숙하고, 이에 동등한 GLib의 <code>g_malloc()</code> 함수와 <code>g_free()</code> 함수의 사용법을 알고 있음을 전제로 합니다.

note: (itstool) path: synopsis/p
en: There are three situations to avoid, in order of descending importance:
ko: 피해야 할 세가지 상황을 중요하지 않은 항목부터 나열해보았습니다:

note: (itstool) path: item/p
en: Using memory after freeing it (use-after-free).
ko: 해제하고 나서 메모리를 활용(해제 후 활용).

note: (itstool) path: item/p
en: Using memory before allocating it.
ko: 할당하기 전에 메모리를 활용.

note: (itstool) path: item/p
en: Not freeing memory after allocating it (leaking).
ko: 할당하고 나서 메모리를 해제하지 않음(누수).

note: (itstool) path: synopsis/p
en: Key principles, in no particular order:
ko: 비순서 핵심 원칙:

note: (itstool) path: item/p
en: Determine and document whether each variable is owned or unowned. They must never change from one to the other at runtime. (<link xref="#principles"/>)
ko: 어떤 변수 참조를 소유하는 지 여부를 결정하고 문서로 남겨두십시오. 실행 시간에 이 결정이 바뀌면 안됩니다(<link xref="#principles"/>).

note: (itstool) path: item/p
en: Determine and document the ownership transfers at function boundaries. (<link xref="#principles"/>)
ko: 함수 영역의 소유 참조 전달 여부를 결정하고 문서로 남겨두십시오(<link xref="#principles"/>).

note: (itstool) path: item/p
en: Ensure that each assignment, function call and function return respects the relevant ownership transfers. (<link xref="#assignments"/>, <link xref="#function-calls"/>, <link xref="#function-returns"/>)
ko: 관련 소유 참조 전달이 일어나는 함수 호출 및 함수 반환시, 각 할당 동작 단계를 확인하십시오(<link xref="#assignments"/>, <link xref="#function-calls"/>, <link xref="#function-returns"/>).

note: (itstool) path: item/p
en: Use reference counting rather than explicit finalization where possible. (<link xref="#reference-counting"/>)
ko: 가능하면 명시적으로 종결처리하기 보다는, 참조 카운팅을 활용하십시오(<link xref="#reference-counting"/>).

note: (itstool) path: item/p
en: Use GLib convenience functions like <link xref="#g-clear-object"><code>g_clear_object()</code></link> where possible. (<link xref="#convenience-functions"/>)
ko: 가능한 부분에 <link xref="#g-clear-object"><code>g_clear_object()</code></link> 함수 같은 GLib 편의 함수를 활용하십시오(<link xref="#convenience-functions"/>).

note: (itstool) path: item/p
en: Do not split memory management across code paths. (<link xref="#principles"/>)
ko: 코드 흐름상 메모리 관리 방식을 별개로 처리하지 마십시오(<link xref="#principles"/>).

note: (itstool) path: item/p
en: Use the single-path cleanup pattern for large or complex functions. (<link xref="#single-path-cleanup"/>)
ko: 거대 복잡 함수에서는 단일 흐름상 처리 방식을 활용하십시오(<link xref="#single-path-cleanup"/>).

note: (itstool) path: item/p
en: Leaks should be checked for using Valgrind or the address sanitizer. (<link xref="#verification"/>)
ko: Valgrind 내지는 주소 정리기로 메모리 누수 상태를 확인해야합니다(<link xref="#verification"/>).

note: (itstool) path: section/title
en: Principles of Memory Management
ko: 메모리 관리 원리

note: (itstool) path: section/p
en: The normal approach to memory management is for the programmer to keep track of which variables point to allocated memory, and to manually free them when they are no longer needed. This is correct, but can be clarified by introducing the concept of <em>ownership</em>, which is the piece of code (such as a function, struct or object) which is responsible for freeing a piece of allocated memory (an <em>allocation</em>). Each allocation has exactly one owner; this owner may change as the program runs, by <em>transferring</em> ownership to another piece of code. Each variable is <em>owned</em> or <em>unowned</em>, according to whether the scope containing it is always its owner. Each function parameter and return type either transfers ownership of the values passed to it, or it doesn’t. If code which owns some memory doesn’t deallocate that memory, that’s a memory leak. If code which doesn’t own some memory frees it, that’s a double-free. Both are bad.
ko: 프로그래머가 보통 접근하는 메모리 관리 개념은 어떤 변수에 메모리를 할당했는지, 더 이상 필요하지 않은 변수를 직접 해제했는지 지켜보는 방식입니다. 이런 접근 방식이 올바른 방식이지만, 어떤 코드 부분에서 할당한 메모리(<em>할당</em> 구역) 일부를 해제 처리하는가(이를 테면, 함수, 구조체, 객체)<em>소유</em> 개념을 도입하여 분명히 할 수 있습니다. 각 할당 부분 별로 분명히 하나의 소유 주체가 있습니다. 이 소유 주체는 프로그램을 실행하는 동안, 다른 코드 부분으로 소유(참조)를 <em>전달</em>하여 바꿀 수 있습니다. 각 변수는 코드 범위에서 항상 참조를 소유하는지 여부에 따라 참조를 <em>소유</em>하거나, <em>비소유</em>합니다. 각 함수 매개 변수와 반환 형식은 값을 전달하든 안 하든, 소유 참조를 전달합니다. 메모리에서 해제하지 않은 일부 메모리 공간을 활용하는 코드가 있다면, 해당 코드에서 메모리 누수가 발생하는 상황이 됩니다. 이미 할당한 메모리를 해제한 상황에서 또 해제하는 코드가 있다면, 중복 해제가 되며, 여기서 설명한 두가지 경우는 메모리 관리에 있어 바람직한 코드가 아닙니다.

note: (itstool) path: section/p
en: By statically calculating which variables are owned, memory management becomes a simple task of unconditionally freeing the owned variables before they leave their scope, and <em>not</em> freeing the unowned variables (see <link xref="#single-path-cleanup"/>). The key question to answer for all memory is: which code has ownership of this memory?
ko: 어떤 변수에서 참조를 소유했는지 통계적으로 헤아려보면, 메모리 관리는 코드 영역을 벗어나기 전에 할당한 메모리 영역을 어떤 상태 확인 없이 해제하는 단순한 과정이 될 수 있으며, 비 소유 할당 메모리 공간을 해제하는 과정이 <em>아닙니다</em>(<link xref="#single-path-cleanup"/> 참고). 이런 메모리 관리에 있어 답이 필요한 핵심 질문은 "이 메모리를 어떤 코드에서 다루는가?" 입니다.

note: (itstool) path: section/p
en: There is an important restriction here: variables must <em style="strong">never</em> change from owned to unowned (or vice-versa) at runtime. This restriction is key to simplifying memory management.
ko: 몇가지 중요한 제한점이 있습니다. 변수 소유 상태는 실행 시간에 절대로 바꾸면 <em>안됩니다</em>. 이 제한 원칙은 메모리 관리 단순화의 핵심입니다.

note: (itstool) path: section/p
en: For example, consider the functions:
ko: 예를 들어 다음 함수를 가정해보겠습니다:

note: (itstool) path: section/p
en: The following code has been annotated to note where the ownership transfers happen:
ko: 다음 코드는 주체 전달이 일어나는 부분을 표시하려 주석을 달아두었습니다:

note: (itstool) path: section/p
en: There are a few points here: Firstly, the ‘owned’ comments by the variable declarations denote that those variables are owned by the local scope, and hence need to be freed before they go out of scope. The alternative is ‘unowned’, which means the local scope does <em>not</em> have ownership, and <em>must not</em> free the variables before going out of scope. Similarly, ownership <em>must not</em> be transferred to them on assignment.
ko: 몇가지 주안점이 있습니다. 우선, 변수 선언의 ‘owned‘ 주석은 해당 변수를 자체 범위에서 소유했음을 나타내며, 코드 실행 후 실행 시점이 외부로 나가는 경우 메모리에서 해제해야합니다. 반대는 ‘unowned‘이며, 해당 코드 범위에서 소유하지 않아, 실행 시점이 외부로 나가더라도 해제하면 <em>안됩니다</em>. 이와 비슷하게, 메모리 할당시에는 소유 상태를 넘기면 <em>안됩니다</em>.

note: (itstool) path: section/p
en: Secondly, the variable type modifiers reflect whether they transfer ownership: because <code>my_str</code> is owned by the local scope, it has type <code>gchar</code>, whereas <code>template</code> is <code>const</code> to denote it is unowned. Similarly, the <code>template</code> parameter of <code>generate_string()</code> and the <code>str</code> parameter of <code>print_string()</code> are <code>const</code> because no ownership is transferred when those functions are called. As ownership <em>is</em> transferred for the string parameter of <code>g_value_take_string()</code>, we can expect its type to be <code>gchar</code>.
ko: 두번째로, 변수형 수정자는 소유 여부를 전달할 지 여부를 반영합니다. <code>my_str</code>는 자체 영역에서 소유하기 때문에 <code>gchar</code>고, 반면에 <code>template</code>는 소유하지 않음을 나타내려 <code>const</code>를 붙입니다. 이와 비슷하게, <code>generate_string()</code> 함수의 매개변수 <code>template</code>와 <code>print_string()</code> 함수의 매개 변수 <code>str</code>은 함수를 호출할 때, 소유 여부를 전달하지 않으므로 <code>const</code>를 붙입니다. <code>g_value_take_string()</code> 함수의 문자열 매개변수에는 소유권을 전달 <em>하므로</em>, 이 매개변수의 형식을 <code>gchar</code>로 넣을 수 있습니다.

note: (itstool) path: section/p
en: (Note that this is not the case for <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html"> <code>GObject</code></link>s and subclasses, which can never be <code>const</code>. It is only the case for strings and simple <code>struct</code>s.)
ko: (참고로 <code>const</code>를 붙이면 안되는 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html"> <code>GObject</code></link>와 하위 클래스에는 해당하지 않습니다. 문자열과 단순 <code>struct</code>에만 해당합니다.)

note: (itstool) path: section/p
en: Finally, a few libraries use a function naming convention to indicate ownership transfer, for example using ‘take’ in a function name to indicate full transfer of parameters, as with <code>g_value_take_string()</code>. Note that different libraries use different conventions, as shown below:
ko: 마지막으로, 일부 라이브러리에서는 소유 이전을 나타내려 함수 작명 원칙을 활용하는데, 함수 이름에 ‘take’가 있으면 <code>g_value_take_string()</code> 함수처럼 매개변수의 소유를 완전히 넘겨 받음을 나타냅니다. 참고로 다른 라이브러리는 아래와 같이 개별 원칙을 따릅니다:

note: (itstool) path: td/p
en: Function name
ko: 함수 이름

note: (itstool) path: td/p
en: Convention 1 (standard)
ko: 형식 1 (표준)

note: (itstool) path: td/p
en: Convention 2 (alternate)
ko: 형식 2 (대안)

note: (itstool) path: td/p
en: Convention 3 (<cmd>gdbus-codegen</cmd>)
ko: 형식 3 (<cmd>gdbus-codegen</cmd>)

note: (itstool) path: td/p
en: No transfer
ko: 전달 안함

note: (itstool) path: td/p
en: Any transfer
ko: 일부 전달

note: (itstool) path: td/p
en: Full transfer
ko: 완전한 전달

note: (itstool) path: td/p
en: Unused
ko: 사용 안함

note: (itstool) path: section/p
en: Ideally, all functions have a <code>(transfer)</code> <link xref="introspection">introspection annotation</link> for all relevant parameters and the return value. Failing that, here is a set of guidelines to use to determine whether ownership of a return value is transferred:
ko: 이상적으로, 모든 함수에는 관련 매개 변수에 <code>(transfer)</code> <link xref="introspection">인트로스펙션 주석</link>이 있으며, 값을 반환합니다. 값 반환에 실패할 경우에 대해 반환 값 주체의 판단에 활용할 지침이 있습니다:

note: (itstool) path: item/p
en: If the type has an introspection <code>(transfer)</code> annotation, look at that.
ko: 형식에 인트로스펙션 <code>(transfer)</code> 주석이 달려있다면, 해당 부분을 살펴보십시오.

note: (itstool) path: item/p
en: Otherwise, if the type is <code>const</code>, there is no transfer.
ko: 형식이 <code>const</code>라면, 전달 값이 없습니다.

note: (itstool) path: item/p
en: Otherwise, if the function documentation explicitly specifies the return value must be freed, there is full or container transfer.
ko: 함수 문서에서 반드시 메모리상 해제를 해야 할 반환 값을 분명하게 정의했다면, 완전한 또는 컨테이너 전달이 이루어집니다.

note: (itstool) path: item/p
en: Otherwise, if the function is named ‘dup’, ‘take’ or ‘steal’, there is full or container transfer.
ko: 함수 이름에 ‘dup’, ‘take’, ‘steal’이 붙어있다면, 완전한 또는 컨테이너 전달이 이루어집니다.

note: (itstool) path: item/p
en: Otherwise, if the function is named ‘peek’, there is no transfer.
ko: 함수 이름에 ‘peek’이 붙어있다면, 전달 값이 없습니다.

note: (itstool) path: item/p
en: Otherwise, you need to look at the function’s code to determine whether it intends ownership to be transferred. Then file a bug against the documentation for that function, and ask for an introspection annotation to be added.
ko: 위의 경우가 아니라면, 소유 주체를 전달하도록 했는지 여부를 확인하는 함수 코드를 살펴보아야 합니다. 그리고 해당 함수의 문서의 버그를 보고하고, 인트로스펙션 주석을 추가해야 한다고 요청하십시오.

note: (itstool) path: section/p
en: Given this ownership and transfer infrastructure, the correct approach to memory allocation can be mechanically determined for each situation. In each case, the <code>copy()</code> function must be appropriate to the data type, for example <code>g_strdup()</code> for strings, or <code>g_object_ref()</code> for GObjects.
ko: 소유 주체와 전달 기반이 주어졌다면, 올바른 메모리 할당 문제 접근 방식으로 각 상황을 기술적으로 밝힐 수 있습니다. 각 경우에, <code>copy()</code> 함수는 데이터 형식에 알맞아야 하는데, 이를테면, <code>g_strdup()</code> 함수는 문자열에, <code>g_object_ref()</code> 함수는 GObject 객체에 알맞아야 합니다.

note: (itstool) path: section/p
en: When thinking about ownership transfer, <code>malloc()</code>/<code>free()</code> and reference counting are equivalent: in the former case, a newly allocated piece of heap memory is transferred; in the latter, a newly incremented reference. See <link xref="#reference-counting"/>.
ko: 소유 주체 전달을 생각할 때, <code>malloc()</code>/<code>free()</code>와 참조 카운팅은 동일하다고 보시면 됩니다. 보통의 경우 새로 할당한 일부 힙 메모리 영역을 전달합니다. 그 다음 새로 증가한 참조를 전달합니다. <link xref="#reference-counting"/>을 참고하십시오.

note: (itstool) path: section/title
en: Assignments
ko: 할당

note: (itstool) path: td/p
en: Assignment from/to
ko: 할당 목적/대상

note: (itstool) path: td/p
en: Owned destination
ko: 소유 대상

note: (itstool) path: td/p
en: Unowned destination
ko: 비소유 대상

note: (itstool) path: td/p
en: Owned source
ko: 소유 원본

note: (itstool) path: td/p
en: Copy or move the source to the destination.
ko: 원본을 대상으로 복제하거나 이동합니다.

note: (itstool) path: td/p
en: Pure assignment, assuming the unowned variable is not used after the owned one is freed.
ko: 소유 대상을 메모리에서 해제하기 전에는 비소유 대상을 활용하지 않음을 전제로 한 일반적인 할당 방식입니다.

note: (itstool) path: td/p
en: Unowned source
ko: 비소유 원본

note: (itstool) path: td/p
en: Copy the source to the destination.
ko: 원본을 대상에 복제합니다.

note: (itstool) path: td/p
en: Pure assignment.
ko: 일반적인 할당 방식입니다.

note: (itstool) path: section/title
en: Function Calls
ko: 함수 호출

note: (itstool) path: td/p
en: Call from/to
ko: 호출 위치/대상

note: (itstool) path: td/p
en: Transfer full parameter
ko: 전체 매개 변수 보내기

note: (itstool) path: td/p
en: Transfer none parameter
ko: 매개변수 보내지 않기

note: (itstool) path: td/p
en: Copy or move the source for the parameter.
ko: 매개변수의 원본을 복제하거나 이동합니다.

note: (itstool) path: td/p
en: Pure parameter passing.
ko: 일반적인 매개변수 전달 방식입니다.

note: (itstool) path: td/p
en: Copy the source for the parameter.
ko: 매개변수의 원본을 복제합니다.

note: (itstool) path: section/title
en: Function Returns
ko: 함수 반환 처리

note: (itstool) path: td/p
en: Return from/to
ko: 반환 위치/대상

note: (itstool) path: td/p
en: Transfer full return
ko: 전체 반환값 보내기

note: (itstool) path: td/p
en: Transfer none return
ko: 반환값 보내지 않기

note: (itstool) path: td/p
en: Pure variable return.
ko: 일반적인 값 반환 방식입니다.

note: (itstool) path: td/p
en: Invalid. The source needs to be freed, so the return value would use freed memory — a use-after-free error.
ko: 잘못됐습니다. 원본을 메모리에서 해제하며, 메모리에서 해제한 반환 값을 사용합니다. 해제 후 사용 오류입니다.

note: (itstool) path: td/p
en: Copy the source for the return.
ko: 반환할 원본 값을 복제합니다.

note: (itstool) path: td/p
en: Pure variable passing.
ko: 일반적인 변수 전달 방식입니다.

note: (itstool) path: section/p
en: Documenting the ownership transfer for each function parameter and return, and the ownership for each variable, is important. While they may be clear when writing the code, they are not clear a few months later; and may never be clear to users of an API. They should always be documented.
ko: 각 함수 매개 변수의 소유 이전 및 값 반환, 각 변수의 소유권 문서화는 중요합니다. 코드를 작성할 때는 분명하겠지만, 몇 달 지나고 나면 무슨 이야기인지 불분명하며 API 사용자는 전혀 알 수 없을지도 모릅니다. 해당 항목도 문서화해야합니다.

note: (itstool) path: section/p
en: The best way to document ownership transfer is to use the <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations#Memory_and_lifecycle_management"> <code>(transfer)</code></link> annotation introduced by <link xref="introspection">gobject-introspection</link>. Include this in the API documentation comment for each function parameter and return type. If a function is not public API, write a documentation comment for it anyway and include the <code>(transfer)</code> annotations. By doing so, the introspection tools can also read the annotations and use them to correctly introspect the API.
ko: 소유 전달을 문서화 하는 최선의 방법은 <link xref="introspection">gobject-introspection</link>에서 도입한 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations#Memory_and_lifecycle_management"> <code>(transfer)</code></link> 주석의 사용입니다. 각 함수 매개변수 및 반환 형식 부분을 다루는 API 문서 주석에 이 주석을 넣으십시오. 만약 함수를 공용 API에 넣지 않더라도, 어쨌든 문서 주석을 작성하고, <code>(transfer)</code> 주석을 넣으십시오. 이렇게 하면 인트로스펙션 도구에서 이 주석을 인식하고 API를 올바르게 인트로스펙션할 때 활용할 수 있습니다.

note: (itstool) path: section/p
en: Ownership for variables can be documented using inline comments. These are non-standard, and not read by any tools, but can form a convention if used consistently.
ko: 변수 소유권은 인라인 문서로 문서 기록 처리할 수 있습니다. 이 방식은 표준이 아니며 어떤 도구에서도 읽지 않지만, 일관되게 적는다면 일정한 형식을 갖출 수 있습니다.

note: (itstool) path: section/p
en: The documentation for <link xref="#container-types"/> is similarly only a convention; it includes the type of the contained elements too:
ko: <link xref="#container-types"/>의 문서는 기존의 내용과 유사합니다. 포함 구성 요소의 형식도 함께 들어갑니다:

note: (itstool) path: section/p
en: Note also that owned variables should always be initialized so that freeing them is more convenient. See <link xref="#convenience-functions"/>.
ko: 또한 소유 변수도 항상 초기화한 후 해제하는게 나중에 더 간편해짐을 참고하십시오. <link xref="#convenience-functions"/> 링크를 참고하십시오.

note: (itstool) path: section/p
en: Also note that some types, for example basic C types like strings, can have the <code>const</code> modifier added if they are unowned, to take advantage of compiler warnings resulting from assigning those variables to owned variables (which must <em>not</em> use the <code>const</code> modifier). If so, the <code>/* unowned */</code> comment may be omitted.
ko: 또한, 문자열과 같은 기본 C 형식 같은 일부 형식에 <code>const</code>를 붙이지 않았을 경우, 키워드를 붙여서 (<code>const</code> 키워드를 굳이 사용할 필요가 <em>없는</em>) 기존의 참조 소유 변수에 다른 변수 값을 할당할 경우 컴파일러 경고를 띄우는 이점을 취하십시오.

note: (itstool) path: section/title
en: Reference Counting
ko: 참조 카운팅

note: (itstool) path: section/p
en: As well as conventional <code>malloc()</code>/<code>free()</code>-style types, GLib has various reference counted types — <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html"> <code>GObject</code></link> being a prime example.
ko: 기존의 <code>malloc()</code>/<code>free()</code> 형식 함수처럼, GLib에 참조 카운팅 방식의 함수가 있습니다. 핵심 예제로 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html"> <code>GObject</code></link>가 있습니다.

note: (itstool) path: section/p
en: The concepts of ownership and transfer apply just as well to reference counted types as they do to allocated types. A scope <em>owns</em> a reference counted type if it holds a strong reference to the instance (for example by calling <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref"> <code>g_object_ref()</code></link>). An instance can be ‘copied’ by calling <code>g_object_ref()</code> again. Ownership can be freed with <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref"> <code>g_object_unref()</code></link> — even though this may not actually finalize the instance, it frees the current scope’s ownership of that instance.
ko: 소유 및 전달 개념은 할당한 형식에 따라 처리하는 참조 카운팅 형식 그대로 반영합니다. 해당 범위는(예를 들자면, <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref"> <code>g_object_ref()</code></link> 함수를 호출하여) 인스턴스에 강 참조를 할당했을 경우 참조 카운팅 형식을 <em>부여</em> 합니다. <code>g_object_ref()</code> 함수를 다시 호출하면 인스턴스를 `복제`할 수 있습니다. <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref"> <code>g_object_unref()</code></link> 함수로 소유 참조를 해제할 수 있습니다. 실제로 인스턴스를 종결짓지 않을 수도 있지만, 현재 코드 범위에서 인스턴스의 소유 관계를 정리(해제)합니다.

note: (itstool) path: section/p
en: See <link xref="#g-clear-object"/> for a convenient way of handling GObject references.
ko: GObject 참조를 다루는 간편한 방법은 <link xref="#g-clear-object"/> 링크를 참고하십시오.

note: (itstool) path: section/p
en: There are other reference counted types in GLib, such as <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html"> <code>GHashTable</code></link> (using <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-ref"> <code>g_hash_table_ref()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-unref"> <code>g_hash_table_unref()</code></link>), or <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html"> <code>GVariant</code></link> (<link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-ref"> <code>g_variant_ref()</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-unref"> <code>g_variant_unref()</code></link>). Some types, like <code>GHashTable</code>, support both reference counting and explicit finalization. Reference counting should always be used in preference, because it allows instances to be easily shared between multiple scopes (each holding their own reference) without having to allocate multiple copies of the instance. This saves memory.
ko: GLib에는 <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html"> <code>GHashTable</code></link> (<link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-ref"> <code>g_hash_table_ref()</code></link> 함수 및 <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-unref"> <code>g_hash_table_unref()</code></link> 함수 활용), <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html"> <code>GVariant</code></link> (<link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-ref"> <code>g_variant_ref()</code></link> 함수, <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-unref"> <code>g_variant_unref()</code></link> 함수) 같은 참조 카운팅 형식이 있습니다. <code>GHashTable</code> 같은 일부 형식에는 참조 카운팅 및 명시적 종결 처리를 지원합니다. 참조 카운팅은 취향에 따라 활용해야 하는데, 인스턴스 다중 복제 객체를 할당하지 않고도, 다양한 범위(각 부분에서 자체 참조를 지님)에서 인스턴스를 공유할 수 있기 때문입니다. 이런 인스턴스 공유 참조 방식으로 메모리를 절약합니다.

note: (itstool) path: section/title
en: Floating References
ko: 플로팅 참조

note: (itstool) path: section/p
en: Classes which are derived from <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GInitiallyUnowned"><code>GInitiallyUnowned</code></link>, as opposed to <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct"><code>GObject</code></link> have an initial reference which is <em>floating</em>, meaning that no code owns the reference. As soon as <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref-sink"><code>g_object_ref_sink()</code></link> is called on the object, the floating reference is converted to a strong reference, and the calling code assumes ownership of the object.
ko: <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct"><code>GObject</code></link>에 반해 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GInitiallyUnowned"><code>GInitiallyUnowned</code></link> 에서 상속받은 클래스는 <em>플로팅</em> 초기 참조를 지니는데, 이는 어떤 코드도 참조를 보유하지 않는다는 의미입니다. 객체에서 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref-sink"><code>g_object_ref_sink()</code></link> 함수를 호출하면, 플로팅 참조에서 강 참조로 바뀌며, 호출 코드에서 객체에 소유권이 있다고 간주합니다.

note: (itstool) path: section/p
en: Floating references are a convenience for use in C in APIs, such as GTK+, where large numbers of objects must be created and organized into a hierarchy. In these cases, calling <code>g_object_unref()</code> to drop all the strong references would result in a lot of code.
ko: GTK+와 같이 여러 개의 객체를 만들고 계층 관계를 형성해야 하는 API에서 C를 사용할 때, 플로팅 참조는 간편한 수단입니다. 이 경우 모든 강 참조를 쳐내는 <code>g_object_unref()</code> 함수를 호출하면 대부분의 코드에서 결과가 나옵니다.

note: (itstool) path: example/p
en: Floating references allow the following code to be simplified:
ko: 플로팅 참조는 다음 코드를 단순화할 수 있습니다:

note: (itstool) path: example/p
en: Instead, the following code can be used, with the <code>GtkContainer</code> assuming ownership of the floating reference:
ko: 대신, 플로팅 참조 소유를 가정하는 <code>GtkContainer</code>로 다음 코드를 사용할 수 있습니다:

note: (itstool) path: section/p
en: Floating references are only used by a few APIs — in particular, <code>GtkWidget</code> and all its subclasses. You must learn which APIs support it, and which APIs consume floating references, and only use them together.
ko: 플로팅 참조는 <code>GtkWidget</code>과 하위 클래스를 수반한 일부 API에서만 사용합니다. 어떤 API에서 지원하는지, 어떤 API에서 플로팅 참조를 활용하고, 상호간 활용하는지 알아야 합니다.

note: (itstool) path: section/p
en: Note that <code>g_object_ref_sink()</code> is equivalent to <code>g_object_ref()</code> when called on a non-floating reference, making <code>gtk_container_add()</code> no different from any other function in such cases.
ko: 참고로 <code>g_object_ref_sink()</code> 함수는 비 플로팅 참조를 호출할 경우 <code>g_object_ref()</code> 함수와 동일하며, 이 경우 다른 함수와 <code>gtk_container_add()</code> 함수간 사용상 차이가 없습니다.

note: (itstool) path: section/p
en: See the <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#floating-ref">GObject manual</link> for more information on floating references.
ko: 자세한 플로팅 참조 정보는 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#floating-ref">GObject 설명서</link>를 참고하십시오.

note: (itstool) path: section/title
en: Convenience Functions
ko: 편의 함수

note: (itstool) path: section/p
en: GLib provides various convenience functions for memory management, especially for GObjects. Three will be covered here, but others exist — check the GLib API documentation for more. They typically follow similar naming schemas to these three (using ‘_full’ suffixes, or the verb ‘clear’ in the function name).
ko: GLib에서는 GObject에 맞춰 메모리 관리를 편리하게 하는 다양한 편의 함수를 제공합니다. 여기선 세가지를 다루지만, 다른 함수도 있습니다. 자세한 내용은 GLib API 문서를 살펴보십시오. 보통 여기 세가지 함수와 유사한 작명 형식을 따릅니다(함수 이름에 ‘_full’ 접미사 또는 ‘clear’ 동사 사용).

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-clear-object"> <code>g_clear_object()</code></link> is a version of <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref"> <code>g_object_unref()</code></link> which unrefs a GObject and then clears the pointer to it to <code>NULL</code>.
ko: <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-clear-object"> <code>g_clear_object()</code></link> 함수는 GObject 참조를 해제하고 포인터를 <code>NULL</code>로 만드는 <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref"> <code>g_object_unref()</code></link> 함수 버전입니다.

note: (itstool) path: section/p
en: This makes it easier to implement code that guarantees a GObject pointer is always either <code>NULL</code>, or has ownership of a GObject (but which never points to a GObject it no longer owns).
ko: 이 함수는 GObject 포인터를 <code>NULL</code> 로 만들거나 GObject의 소유권을 확보(하지만 아무 것도 없는 GObject를 가리키진 않음)하도록 코드를 쉽게 작성할 수 있게 합니다.

note: (itstool) path: section/p
en: By initialising all owned GObject pointers to <code>NULL</code>, freeing them at the end of the scope is as simple as calling <code>g_clear_object()</code> without any checks, as discussed in <link xref="#single-path-cleanup"/>:
ko: <link xref="#single-path-cleanup"/>에 언급한 대로, 보유한 모든 GObject 포인터를 <code>NULL</code>로 초기화하여, 어떠한 검사 과정 없이 코드 범위의 마지막에서 할당을 해제하는건 <code>g_clear_object()</code> 함수를 호출하는 방식으로 쉽게 끝낼 수 있습니다:

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free-full"> <code>g_list_free_full()</code></link> frees all the elements in a linked list, <em>and all their data</em>. It is much more convenient than iterating through the list to free all the elements’ data, then calling <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free"> <code>g_list_free()</code></link> to free the <code>GList</code> elements themselves.
ko: <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free-full"> <code>g_list_free_full()</code></link> 함수는 연결 리스트 자료 구조상 모든 항목과 <em>데이터</em>를 메모리에서 해제합니다. 리스트를 순차적으로 확인하고, <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free"> <code>g_list_free()</code></link> 함수를 호출하여 <code>GList</code> 구성 항목 자체를 메모리에서 해제하여 모든 항목의 데이터를 메모리에서 해제하는 것 보다 훨씬 간단합니다.

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new-full"> <code>g_hash_table_new_full()</code></link> is a newer version of <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new"> <code>g_hash_table_new()</code></link> which allows setting functions to destroy each key and value in the hash table when they are removed. These functions are then automatically called for all keys and values when the hash table is destroyed, or when an entry is removed using <code>g_hash_table_remove()</code>.
ko: <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new-full"> <code>g_hash_table_new_full()</code></link> 함수는 해시 테이블의 각각의 키-값을 없댈 수 있는 설정 함수 <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new"> <code>g_hash_table_new()</code></link>의 새 버전입니다. 이 함수는 해시 테이블을 해제했거나, <code>g_hash_table_remove()</code> 함수로 항목을 제거했을 경우 모든 키-값을 대상으로 자동으로 호출합니다.

note: (itstool) path: section/p
en: Essentially, it simplifies memory management of keys and values to the question of whether they are present in the hash table. See <link xref="#container-types"/> for a discussion on ownership of elements within container types.
ko: 궁극적으로, 해시 테이블에 키 및 값이 있는지 여부에 대한 키 및 값을 저장하는 메모리 관리를 단순화합니다. 컨테이너 형식에 들어있는 구성 요소의 소유 관계를 알아보려면 <link xref="#container-types"/> 링크를 참고하십시오.

note: (itstool) path: section/p
en: A similar function exists for <code>GPtrArray</code>: <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html#g-ptr-array-new-with-free-func"> <code>g_ptr_array_new_with_free_func()</code></link>.
ko: <code>GPtrArray</code>를 다루는 유사한 <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html#g-ptr-array-new-with-free-func"> <code>g_ptr_array_new_with_free_func()</code></link> 함수가 있습니다.

note: (itstool) path: section/title
en: Container Types
ko: 컨테이너 형식

note: (itstool) path: section/p
en: When using container types, such as <code>GPtrArray</code> or <code>GList</code>, an additional level of ownership is introduced: as well as the ownership of the container instance, each element in the container is either owned or unowned too. By nesting containers, multiple levels of ownership must be tracked. Ownership of owned elements belongs to the container; ownership of the container belongs to the scope it’s in (which may be another container).
ko: <code>GPtrArray</code> 또는 <code>GList</code>와 같은 컨테이너 형식을 사용할 때, 소유권의 추가 레벨 개념을 도입합니다. 컨테이너 인스턴스의 소유권과 마찬가지로, 컨테이너의 각 구성 요소는 소유 상태가 되거나 아닐 수 있습니다. 컨테이너를 중첩하면 다중 레벨 소유권을 추적해야합니다. 소유한 구성요소의 소유권은 컨테이너가 가지고 있습니다. 컨테이너의 소유권은 컨테이너가 있는 코드 범위에서 가집니다(아마 다른 컨테이너겠죠).

note: (itstool) path: section/p
en: A key principle for simplifying this is to ensure that all elements in a container have the same ownership: they are either all owned, or all unowned. This happens automatically if the normal <link xref="#convenience-functions"/> are used for types like <code>GPtrArray</code> and <code>GHashTable</code>.
ko: 동일한 컨테이너의 모든 구성 요소 소유권 부여가 단순화의 핵심 원칙입니다. 어떤 주체가 모두 소유하거나 모두 소유하지 않습니다. <code>GPtrArray</code> 및 <code>GHashTable</code> 형식에 대해 일반 <link xref="#convenience-functions"/>를 사용한다면 자동으로 처리합니다.

note: (itstool) path: section/p
en: If elements in a container are <em>owned</em>, adding them to the container is essentially an ownership transfer. For example, for an array of strings, if the elements are owned, the definition of <code>g_ptr_array_add()</code> is effectively:
ko: 컨테이너의 구성 요소가 <em>소유</em> 상태가 되면, 해당 컨테이너로의 구성 요소 추가는 소유권 이전의 본질적 과정입니다. 예를 들어 문자열 배열의 경우 구성 요소를 어떤 주체가 소유하면, 실질적으로 <code>g_ptr_array_add()</code> 함수를 정의합니다:

note: (itstool) path: section/p
en: So, for example, constant (unowned) strings must be added to the array using <code>g_ptr_array_add (array, g_strdup ("constant string"))</code>.
ko: 따라서, 예를 들면, 상수(비소유) 문자열은 <code>g_ptr_array_add (array, g_strdup ("constant string"))</code> 코드로 배열에 추가해야합니다.

note: (itstool) path: section/p
en: Whereas if the elements are unowned, the definition is effectively:
ko: 반면, 구성 요소 소유 주체가 없다면, 정의는 다음과 같습니다:

note: (itstool) path: section/p
en: Here, constant strings can be added without copying them: <code>g_ptr_array_add (array, "constant string")</code>.
ko: <code>g_ptr_array_add (array, "constant string")</code> 코드로 정적 문자열을 복제하지 않고 추가할 수 있습니다.

note: (itstool) path: section/p
en: See <link xref="#documentation"/> for examples of comments to add to variable definitions to annotate them with the element type and ownership.
ko: 구성 요소 형식과 소유 주체를 표기하는 변수 정의 추가 주석 예제를 살펴보려면 <link xref="#documentation"/> 링크를 참고하십시오.

note: (itstool) path: section/title
en: Single-Path Cleanup
ko: 단일 경로 정리

note: (itstool) path: section/p
en: A useful design pattern for more complex functions is to have a single control path which cleans up (frees) allocations and returns to the caller. This vastly simplifies tracking of allocations, as it’s no longer necessary to mentally work out which allocations have been freed on each code path — all code paths end at the same point, so perform all the frees then. The benefits of this approach rapidly become greater for larger functions with more owned local variables; it may not make sense to apply the pattern to smaller functions.
ko: 쓸 만한 더 복잡한 함수 설계 패턴은 호출 주체에 할당 요소를 제거(해제)하고 반환하는 단일 제어 경로의 확보입니다. 할당 추적을 엄청 단순화할 수 있어, 더 이상 코드 경로 상에서 어떤 할당 요소를 해제 했는지 신경써가며 해결할 필요가 없습니다. 모든 코드 경로는 동일한 지점에서 끝나므로, 모든 구성 요소를 해제합니다. 이러한 관점은 자체 변수를 더 많이 지닌 더 큰 함수에 굉장한 장점이 되지만, 작은 함수에 패턴을 적용하기엔 어울리지 않을 수도 있습니다.

note: (itstool) path: section/p
en: This approach has two requirements:
ko: 이 접근 방식에 두가지 요구 사항이 있습니다:

note: (itstool) path: item/p
en: The function returns from a single point, and uses <code>goto</code> to reach that point from other paths.
ko: 함수는 단일 지점에서 반환하며, 다른 경로에서 해당 위치로 접근할 때 <code>goto</code> 문을 활용합니다.

note: (itstool) path: item/p
en: All owned variables are set to <code>NULL</code> when initialized or when ownership is transferred away from them.
ko: 자체 변수를 초기화하거나 소유권을 다른곳으로 보냈을 때는 <code>NULL</code>로 설정합니다.

note: (itstool) path: section/p
en: The example below is for a small function (for brevity), but should illustrate the principles for application of the pattern to larger functions:
ko: 아래 예제는 (간결성 목적) 소규모 함수를 보여주는게 목적이지만, 거대 함수 패턴의 프로그램의 원칙에도 반영해야합니다:

note: (itstool) path: listing/title
en: Single-Path Cleanup Example
ko: 단일 경로 정리 예제

note: (itstool) path: listing/desc
en: Example of implementing single-path cleanup for a simple function
ko: 단일 함수의 단일 경로 정리 구현 예제

note: (itstool) path: section/title
en: Verification
ko: 검증

note: (itstool) path: section/p
en: Memory leaks can be checked for in two ways: static analysis, and runtime leak checking.
ko: 메모리 누수는 정적 분석, 실행 시간 누수 검사 방식으로 검사할 수 있습니다.

note: (itstool) path: section/p
en: Static analysis with tools like <link xref="tooling#coverity">Coverity</link>, the <link xref="tooling#clang-static-analyzer">Clang static analyzer</link> or <link xref="tooling#tartan">Tartan</link> can catch some leaks, but require knowledge of the ownership transfer of every function called in the code. Domain-specific static analyzers like Tartan (which knows about GLib memory allocation and transfer) can perform better here, but Tartan is quite a young project and still misses things (a low true positive rate). It is recommended that code be put through a static analyzer, but the primary tool for detecting leaks should be runtime leak checking.
ko: <link xref="tooling#coverity">Coverity</link> 같은 정적 분석도구, <link xref="tooling#clang-static-analyzer">Clang static analyzer</link> 또는 <link xref="tooling#tartan">Tartan</link>에서 일부 메모리 누수 현상을 잡을 수 있지만, 코드에서 호출하는 모든 함수의 참조 소유 이전 내용을 알고 있어야합니다. Tartan과 같은 영역별 정적 분석기(GLib 메모리 할당 및 참조 이전을 알려줌)에서는 메모리 누수 검사를 더 잘 처리할 수 있지만, Tartan이 조금 더 최근에 나온 프로젝트이며 몇가지 과정이 빠져있습니다(낮은 참 양성 결과 도출율). 정적 분석기에 코드를 확인하는게 좋지만, 메모리 누수를 검사하는 근본 도구는 실행시간 메모리 누수 검사에 활용해야합니다.

note: (itstool) path: section/p
en: Runtime leak checking is done using <link xref="tooling#valgrind">Valgrind</link>, using its <link xref="tooling#memcheck">memcheck</link> tool. Any leak it detects as ‘definitely losing memory’ should be fixed. Many of the leaks which ‘potentially’ lose memory are not real leaks, and should be added to the suppression file.
ko: 실행 시간 메모리 누수 검사는 <link xref="tooling#valgrind">Valgrind</link>와 여기에 있는 <link xref="tooling#memcheck">memcheck</link> 도구로 진행할 수 있습니다. ‘분명한 메모리 사용 영역 분실’로 나타나는 일부 누수 현상은 반드시 수정해야합니다. ‘잠재적’ 메모리 사용영역 분실로 인한 대부분의 메모리 누수 현상은 실제 메모리 누수 현상이 아니며 무시 목록 파일에 추가해야합니다.

note: (itstool) path: section/p
en: If compiling with a recent version of Clang or GCC, the <link xref="tooling#address-sanitizer">address sanitizer</link> can be enabled instead, and it will detect memory leaks and overflow problems at runtime, but without the difficulty of running Valgrind in the right environment. Note, however, that it is still a young tool, so may fail in some cases.
ko: Clang 또는 GCC의 최근 버전으로 컴파일 할 경우 , 대신 <link xref="tooling#address-sanitizer">주소 정리기</link>를 활성화할 수 있으며, 이렇게 하면 실행 시간에 메모리 누수 현상과 오버플로우 문제를 찾습니다. 다만 제대로 된 환경에서 Valgrind 실행의 어려움은 없어집니다. 그러나, 나온 지 얼마 되지 않아 일부 경우에 잘못된 결과가 나타남을 참고하십시오.

note: (itstool) path: section/p
en: See <link xref="tooling#valgrind"/> for more information on using Valgrind.
ko: Valgrind의 자세한 사용법은 <link xref="tooling#valgrind"/> 링크를 참고하십시오.

note: (itstool) path: info/desc
en: Avoiding symbol conflicts between libraries by namespacing all APIs
ko: 모든 API에 공간 이름을 붙여 라이브러리의 심볼 사용 과정상 혼동을 막습니다

note: (itstool) path: page/title
en: Namespacing
ko: 공간 이름 부여

note: (itstool) path: synopsis/p
en: If a library is namespaced correctly, it can define types and methods in its API which have the same names as those in another library, and a program can use both without conflicts. This is achieved by prefixing all types and method names with a namespace unique to the library.
ko: 라이브러리의 공간 이름을 올바르게 부여했다면, API의 형식과 메서드의 이름을 다른 라이브러리에서 보유한 이름과 동일한 이름을 부여할 수 있으며, 프로그램에서는 혼동 없이 활용할 수 있습니다. 모든 형식과 메서드 이름 앞에 공간 이름을 붙여 라이브러리의 유일한 식별체로 만들면 됩니다.

note: (itstool) path: section/title
en: GObject APIs
ko: GObject API

note: (itstool) path: section/p
en: Consistent and complete namespacing of symbols (functions and types) and files is important for two key reasons:
ko: 심볼(함수, 형식) 및 파일의 일관된, 완전한 영역 이름 부여는 다음 두가지 핵심 이유 때문에 중요합니다:

note: (itstool) path: item/p
en: Establishing a convention which means developers have to learn fewer symbol names to use the library — they can guess them reliably instead.
ko: 작명 규칙을 정한다는건 개발자로 하여금 라이브러리를 활용할 때 몇가지 심볼 이름만 익혀두면 됩니다. 심볼 이름을 익히는 대신 분명한 이름을 유추할 수 있습니다.

note: (itstool) path: item/p
en: Ensuring symbols from two projects do not conflict if included in the same file.
ko: 동일한 파일에 심볼이 있는 경우 두 프로젝트를 확인하여 심볼이 중복되지 않게 합니다.

note: (itstool) path: section/p
en: The second point is important — imagine what would happen if every project exported a function called <code>create_object()</code>. The headers defining them could not be included in the same file, and even if that were overcome, the programmer would not know which project each function comes from. Namespacing eliminates these problems by using a unique, consistent prefix for every symbol and filename in a project, grouping symbols into their projects and separating them from others.
ko: 두번째 이유가 중요합니다. 모든 프로젝트에서 <code>create_object()</code> 노출 함수를 호출했을 때 무슨 일이 일어날까요. 이걸 정의하는 헤더는 동일한 파일에 넣을 수 없으며, 이 문제를 해결했다더라도, 프로그래머는 어떤 함수가 어디에서 왔는지 모릅니다. 공간 이름 부여는 프로젝트의 모든 심볼 및 파일 이름에 유일하고 일관된 접두부를 붙이고 프로젝트의 심볼을 하나의 집단으로 묶어 다른 부분과 구별하여 이 문제를 해결합니다.

note: (itstool) path: section/p
en: The conventions below should be used for namespacing all symbols. They are <link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html"> used in all GLib-based projects</link>, so should be familiar to a lot of developers:
ko: 아래 작명 방식은 모든 심볼에 공간 이름을 부여할 때 활용합니다. <link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html">모든 GLib 기반 객체에서 활용</link>하므로 대부분의 개발자에게 익숙해야합니다:

note: (itstool) path: item/p
en: Functions should use <code>lower_case_with_underscores</code>.
ko: 함수 이름은 <code>lower_case_with_underscores</code> 처럼 이름을 붙여야합니다.

note: (itstool) path: item/p
en: Structures, types and objects should use <code>CamelCaseWithoutUnderscores</code>.
ko: 구조체, 형식, 객체는 <code>CamelCaseWithoutUnderscores</code> 처럼 이름을 붙여야합니다.

note: (itstool) path: item/p
en: Macros and constants should use <code>UPPER_CASE_WITH_UNDERSCORES</code>.
ko: 매크로 및 상수는 <code>UPPER_CASE_WITH_UNDERSCORES</code> 처럼 이름을 붙여야합니다.

note: (itstool) path: item/p
en: All symbols should be prefixed with a short (2–4 characters) version of the namespace. This is shortened purely for ease of typing, but should still be unique.
ko: 모든 심볼은 앞에 짧은 공간 이름(2~4문자)을 앞에 붙여야합니다. 근본적으로 입력하기 쉽게 짧게 줄이지만, 다른 부분과 구별할 수 있어야합니다.

note: (itstool) path: item/p
en: All methods of a class should also be prefixed with the class name.
ko: 클래스의 모든 메서드에 클래스 이름을 앞에 붙여야합니다.

note: (itstool) path: section/p
en: Additionally, public headers should be included from a subdirectory, effectively namespacing the header files. For example, instead of <code>#include &lt;abc.h&gt;</code>, a project should allow its users to use <code>#include &lt;namespace/abc.h&gt;</code>.
ko: 게다가, 공용 헤더는 헤더 파일의 이름 공간을 활용하는 것처럼 하위 디렉터리에 두고 소스 파일에 넣어야합니다. 예를 들면 프로젝트에서는 사용자에게 <code>#include &lt;abc.h&gt;</code> 대신, <code>#include &lt;namespace/abc.h&gt;</code>를 사용하도록 해야 합니다.

note: (itstool) path: section/p
en: Some projects namespace their headers within this subdirectory — for example, <code>#include &lt;namespace/ns-abc.h&gt;</code> instead of <code>#include &lt;namespace/abc.h&gt;</code>. This is redundant, but harmless.
ko: 일부 프로젝트는 이 하위 디렉터리에서 헤더 파일에 공간 이름을 부여합니다. <code>#include &lt;namespace/abc.h&gt;</code> 대신 <code>#include &lt;namespace/ns-abc.h&gt;</code> 처럼 씁니다. 중복되지만 문제 없습니다.

note: (itstool) path: section/p
en: For example, for a project called ‘Walbottle’, the short namespace ‘Wbl’ would be chosen. If it has a ‘schema’ class and a ‘writer’ class, it would install headers:
ko: 이를 테면 ‘Walbottle’ 프로젝트에서는 공간 이름 약자로 ‘Wbl’를 쓸 수 있습니다. ‘schema’ 클래스와 ‘writer’ 클래스가 있으면, 다음 헤더를 설치합니다:

note: (itstool) path: section/p
en: (The use of <var>$API_MAJOR</var> above is for <link xref="parallel-installability">parallel installability</link>.)
ko: (상단의 <var>$API_MAJOR</var>는 <link xref="parallel-installability">동시 설치</link>용도입니다.)

note: (itstool) path: section/p
en: For the schema class, the following symbols would be exported (amongst others), following GObject conventions:
ko: 스키마 클래스에는 GObject 이름 작성 규칙에 따라 (여러 심볼 중) 다음 심볼을 내보냅니다:

note: (itstool) path: item/p
en: <code>WblSchema</code> structure
ko: <code>WblSchema</code> 구조

note: (itstool) path: item/p
en: <code>WblSchemaClass</code> structure
ko: <code>WblSchemaClass</code> 구조

note: (itstool) path: item/p
en: <code>WBL_TYPE_SCHEMA</code> macro
ko: <code>WBL_TYPE_SCHEMA</code> 매크로

note: (itstool) path: item/p
en: <code>WBL_IS_SCHEMA</code> macro
ko: <code>WBL_IS_SCHEMA</code> 매크로

note: (itstool) path: item/p
en: <code>wbl_schema_get_type</code> function
ko: <code>wbl_schema_get_type</code> 함수

note: (itstool) path: item/p
en: <code>wbl_schema_new</code> function
ko: <code>wbl_schema_new</code> 함수

note: (itstool) path: item/p
en: <code>wbl_schema_load_from_data</code> function
ko: <code>wbl_schema_load_from_data</code> 함수

note: (itstool) path: info/desc
en: Writing libraries to be future proof through parallel installation
ko: 동시 설치 방식으로 나중에 검증할 라이브러리를 작성합니다

note: (itstool) path: page/title
en: Parallel Installability
ko: 동시 설치 가능성

note: (itstool) path: synopsis/p
en: If two packages can be parallel installed, then they have no filenames in common, and people developing against the package always compile against the version they expected. This applies to daemons, utility programs and configuration files as it does to header files and library binaries.
ko: 두 패키지를 동시에 설치할 수 있다면, 일반적인 파일 이름이 붙어있지 않으며 패키지를 개발한 사람은 원하는 버전에 따라 컴파일합니다. 이 방식은 헤더 파일, 라이브러리 이진 파일에 적용하는 방식대로 데몬, 유틸리티 프로그램, 설정 파일에 적용합니다.

note: (itstool) path: item/p
en: Ensure all versions of a library are parallel installable. (<link xref="#justification"/>)
ko: 모든 라이브러리 버전을 동시에 설치할 수 있는지 확인하십시오(<link xref="#justification"/>).

note: (itstool) path: item/p
en: Version all files installed by a library. (<link xref="#solution"/>)
ko: 라이브러리로 설치한 모든 파일에 버전을 부여하십시오(<link xref="#solution"/>).

note: (itstool) path: item/p
en: Keep package version numbers separate from soname or libtool version numbers. Be clear which part of the package version number changes with the API. (<link xref="#version-numbers"/>)
ko: so 이름 또는 libtool 버전 번호와는 별개로 패키지 버전 번호를 관리하십시오. 어떤 패키지 버전 번호 부분이 API와 바뀌는지 분명히 하십시오(<link xref="#version-numbers"/>).

note: (itstool) path: item/p
en: Install C header files to <file><var>$(includedir)</var>/lib<var>library</var>-<var>version</var>/<var>library</var>/</file>. (<link xref="#header-files"/>)
ko: <file><var>$(includedir)</var>/lib<var>library</var>-<var>version</var>/<var>library</var>/</file>에 C 헤더 파일을 설치하십시오(<link xref="#header-files"/>).

note: (itstool) path: item/p
en: Install library binaries to <file><var>$(libdir)</var>/lib<var>library</var>-<var>version</var>.so.<var>soname</var></file>. (<link xref="#libraries"/>)
ko: <file><var>$(libdir)</var>/lib<var>library</var>-<var>version</var>.so.<var>soname</var></file>에 라이브러리 파일을 설치하십시오(<link xref="#libraries"/>).

note: (itstool) path: item/p
en: Install pkg-config files to <file><var>$(libdir)</var>/pkgconfig/<var>library</var>-<var>version</var>.pc</file>. (<link xref="#pkg-config"/>)
ko: <file><var>$(libdir)</var>/pkgconfig/<var>library</var>-<var>version</var>.pc</file>에 pkg-config 파일을 설치하십시오(<link xref="#pkg-config"/>).

note: (itstool) path: item/p
en: Make configuration files forwards and backwards compatible, or install them to <file><var>$(sysconfdir)</var>/<var>library</var>-<var>version</var>/</file>. (<link xref="#configuration-files"/>)
ko: 설정 파일을 전후 호환성에 맞추든지 <file><var>$(sysconfdir)</var>/<var>library</var>-<var>version</var>/</file>에 설치하십시오(<link xref="#configuration-files"/>).

note: (itstool) path: item/p
en: Set <code>GETTEXT_PACKAGE</code> to <code><var>library</var>-<var>version</var></code>. (<link xref="#gettext"/>)
ko: <code>GETTEXT_PACKAGE</code> 변수 값을 <code><var>library</var>-<var>version</var></code>에 설정하십시오(<link xref="#gettext"/>).

note: (itstool) path: item/p
en: Include a version number in all D-Bus interface names, service names and object paths. For example: <code>org.domain.<var>Library</var><var>Version</var>.<var>Interface</var></code>, <code>org.domain.<var>Library</var><var>Version</var></code> and <code>/org/domain/<var>Library</var><var>Version</var>/</code>. (<link xref="#dbus"/>)
ko: 모든 D-Bus 인터페이스 이름, 서비스 이름, 객체 경로에 버전 번호를 넣으십시오. 이를 테면 <code>org.domain.<var>Library</var><var>Version</var>.<var>Interface</var></code>, <code>org.domain.<var>Library</var><var>Version</var></code>, <code>/org/domain/<var>Library</var><var>Version</var>/</code> 과 같이 넣으십시오(<link xref="#dbus"/>).

note: (itstool) path: item/p
en: Install daemon binaries to <file><var>$(libexecdir)</var>/<var>library</var>-daemon-<var>version</var></file>. (<link xref="#programs"/>)
ko: 데몬 바이너리를 <file><var>$(libexecdir)</var>/<var>library</var>-daemon-<var>version</var></file>에 설치하십시오(<link xref="#programs"/>).

note: (itstool) path: item/p
en: Install utility binaries to <file><var>$(bindir)</var>/<var>library</var>-utility-<var>version</var></file> and install symbolic links to <file><var>$(bindir)</var>/<var>library</var>-utility</file>. (<link xref="#programs"/>)
ko: 유틸리티 바이너리를 <file><var>$(bindir)</var>/<var>library</var>-utility-<var>version</var></file> and install symbolic links to <file><var>$(bindir)</var>/<var>library</var>-utility</file>에 설치하십시오(<link xref="#programs"/>).

note: (itstool) path: section/title
en: Justification
ko: 명분

note: (itstool) path: section/p
en: All public libraries should be designed to be parallel installed to ease API breaks later in the life of the library. If a library is used by multiple projects, and wants to break API, either all of the projects must be ported to the new API in parallel, or some of them will no longer be installable at the same time as the others, due to depending on conflicting versions of this library.
ko: 모든 공개 라이브러리는 라이브러리의 생명 주기 이후 API 구조 변경이 쉽게 함께 설치할 수 있도록 설계해야합니다. 라이브러리를 여러 프로젝트에서 사용하는 상황에서 API 구조를 깨야 한다면, 모든 프로젝트를 동시에 설치한 새 API에 맞춰 이식해야 하며, 이렇게 하지 않으면 일부 프로젝트는 의존 관계상 라이브러리 버전이 맞지 않는 문제로 더이상 라이브러리와 설치할 수 없습니다.

note: (itstool) path: section/p
en: This is unmaintainable, and asking all the projects to port to a new API at the same time is hard to organize and demoralizing, as most API breaks do not bring large new features which would motivate porting.
ko: 이 상태가 바로 관리할 수 없는 상태이며, 대부분의 API가 이식의 동기가 될 눈에 띄는 새 기능을 넣지 않기에, 모든 프로젝트에 새 API에 맞춰 동시에 이식을 요청하기 어렵고, 이식의 의욕을 꺾어버립니다.

note: (itstool) path: section/p
en: The solution is to ensure that all libraries are parallel installable, allowing the old and new versions of the API to be installed and compiled against at the same time, without conflicts. Building in support for this kind of parallel installation is much easier to do at the start of a project than it is to do retroactively.
ko: API의 이전 버전과 새 버전을 동시에 설치하고 컴파일 할 수 있게끔 모든 라이브러리를 동시에 설치할 수 있게 했는지 확인하면 이 문제가 처리됩니다. 동시에 설치할 수 있게 빌드하면, 굳이 근본 부분을 건드리지 않고도 프로젝트의 시작단계를 쉽게 처리할 수 있습니다.

note: (itstool) path: section/p
en: This eliminates the ‘chicken and egg’ problem of porting a collection of applications from one version of a library to the next, and makes breaking API a lot simpler for library maintainers, which can allow for more rapid iteration and development of new features if they desire.
ko: 이 해결 방식은 또한 라이브러리의 어떤 버전과 그 다음 버전을 설치하는 문제에서 여러 프로그램을 이식하는 ‘닭이 먼저냐 달걀이 먼저냐’의 문제를 해결하며, 라이브러리 관리 집단이 원한다면 개발 주기를 더 빠르게 진행할 수 있으며 개발 과정상 새 기능을 넣을 수 있도록 API 구조를 훨씬 쉽게 바꿀 수 있습니다.

note: (itstool) path: section/p
en: The alternative, and equally valid, solution is for the library to never break API — the approach taken by <code>libc</code>.
ko: 이와 동일한 라이브러리 대상 해결책은 API 구조를 그냥 안바꾸는 방법입니다. 이 접근 방식은 <code>libc</code>에서 왔습니다.

note: (itstool) path: section/title
en: Solution
ko: 해결책

note: (itstool) path: section/p
en: The solution to the problem is essentially to rename the library, and in most cases the nicest way to do so is to include the version number in the path of every file it installs. This means multiple versions of the library can be installed at the same time.
ko: 문제 해결책은 근본적으로 라이브러리의 이름을 바꾸는 방식이며, 대부분의 경우 모든 파일을 설치하는 경로의 버전 번호를 넣는 방식입니다. 이는 라이브러리의 여러 버전을 동시에 설치할 수 있다는 의미입니다.

note: (itstool) path: section/p
en: For example, say that library <code>Foo</code> traditionally installs these files:
ko: 예를 들어 <code>Foo</code> 라이브러리에서 기존에 설치한 파일이 다음과 같다고 하겠습니다:

note: (itstool) path: section/p
en: You might modify <code>Foo</code> version 4 to install these files instead:
ko: 이 파일을 설치하려면 위 대신 <code>Foo</code> 버전 4로 수정해야합니다:

note: (itstool) path: section/p
en: It could then be parallel installed with version 5:
ko: 수정하고 나면 버전 5로 동시에 설치할 수 있습니다:

note: (itstool) path: section/p
en: This is easily supported using <link href="http://www.freedesktop.org/wiki/Software/pkg-config/"> <cmd>pkg-config</cmd></link>: <file>foo-4.pc</file> would add <file>/usr/include/foo-4</file> to the include path and <file>libfoo-4.so</file> to the list of libraries to link; <file>foo-5.pc</file> would add <file>/usr/include/foo-5</file> and <file>libfoo-5.so</file>.
ko: <link href="http://www.freedesktop.org/wiki/Software/pkg-config/"> <cmd>pkg-config</cmd></link>에서 쉽게 기능을 빌려 쓸 수 있습니다. <file>foo-4.pc</file> 파일은 include 경로에 <file>/usr/include/foo-4</file> 경로를 추가하고 링크할 라이브러리 목록에 <file>libfoo-4.so</file> 파일을 추가합니다. <file>foo-5.pc</file> 파일은 <file>/usr/include/foo-5</file> 경로와 <file>libfoo-5.so</file> 파일을 추가합니다.

note: (itstool) path: section/title
en: Version Numbers
ko: 버전 번호

note: (itstool) path: section/p
en: The version number that goes in filenames is an <em>ABI/API</em> version. It should not be the full version number of your package — just the part which signifies an API break. If using the standard <code><var>major</var>.<var>minor</var>.<var>micro</var></code> scheme for project versioning, the API version is typically the major version number.
ko: 파일 이름에 붙은 버전 번호는 <em>ABI/API</em> 버전입니다. 패키지의 전체 버전 번호는 아닙니다. API 유지 상태가 깨졌는지 여부를 나타내는 부분일 뿐입니다. 프로젝트 버전 부여시 <code><var>주</var>.<var>부</var>.<var>마이크로</var></code> 표준 버전 부여 형식을 사용한다면 API 버전은 보통 주 버전 번호입니다.

note: (itstool) path: section/p
en: Minor releases (typically where API is added but <em>not</em> changed or removed) and micro releases (typically bug fixes) do not affect <link xref="api-stability">API backwards compatibility</link> so do not require moving all the files.
ko: 부 버전 출시판(보통 API를 추가하지만 바꾸거나 제거하지 <em>않음</em>)과 마이크로 버전 출시판(보통 버그 수정)은 <link xref="api-stability">API 이전 호환성</link>에 영향을 주지 않으므로 모든 파일을 옮길 필요가 없습니다.

note: (itstool) path: section/p
en: The examples in the following sections assume that the API version and soname are exported from <file>configure.ac</file> using the following code:
ko: 다음 부분의 예제는 다음 코드를 활용하여 <file>configure.ac</file> 파일에서 API 버전과 so 이름을 내보낸다고 가정합니다:

note: (itstool) path: listing/title
en: API Versioning in Autoconf
ko: autoconf의 API 버전 부여

note: (itstool) path: listing/desc
en: Code to export the API version and soname from <file>configure.ac</file>
ko: <file>configure.ac</file> 파일에 API 버전 및 so 이름을 내보낼 코드를 작성하십시오

note: (itstool) path: section/title
en: C Header Files
ko: C 헤더 파일

note: (itstool) path: section/p
en: Header files should always be installed in a versioned subdirectory that requires an <cmd>-I</cmd> flag to the C compiler. For example, if my header is <file>foo.h</file>, and applications do this:
ko: 헤더 파일은 C 컴파일러의 <cmd>-I</cmd> 플래그가 요구하는 버전이 붙은 하위 디렉터리에 항상 설치해야합니다. 예를 들어, <file>foo.h</file> 헤더 파일이 있다면 프로그램에서는 다음과 같이 씁니다:

note: (itstool) path: section/p
en: then I should install these files:
ko: 그 다음 이 파일을 설치하겠습니다:

note: (itstool) path: section/p
en: Applications should pass the flag <cmd>-I/usr/include/foo-4</cmd> or <cmd>-I/usr/include/foo-5</cmd> to the C compiler. Again, this is facilitated by using <cmd>pkg-config</cmd>.
ko: 프로그램에서는 <cmd>-I/usr/include/foo-4</cmd> 또는 <cmd>-I/usr/include/foo-5</cmd> 플래그를 C 컴파일러에 보내야합니다. 다시 말하지만, <cmd>pkg-config</cmd>를 활용하면 됩니다.

note: (itstool) path: section/p
en: Note the extra <file>foo/</file> subdirectory. This namespaces the <code mime="text/x-csrc">#include</code> to avoid file naming collisions with other libraries. For example, if two different libraries install headers called <file>utils.h</file>, which one gets included when you use <code mime="text/x-csrc">#include &lt;utils.h&gt;</code>?
ko: <file>foo/</file> 추가 하위 디렉터리를 살펴보십시오. 다른 라이브러리의 파일 이름이 겹치는 일을 피하도록 <code mime="text/x-csrc">#include</code> 절에 이름 영역을 부여합니다. 예를 들자면, 서로 다른 두 라이브러리에서 <file>utils.h</file> 헤더 파일을 설치한다면 <code mime="text/x-csrc">#include &lt;utils.h&gt;</code> 헤더를 사용할 때 무얼 넣을까요?

note: (itstool) path: section/p
en: There’s some temptation to keep one of the header files outside of any subdirectory:
ko: 어떤 하위 디렉터리 외에 있는 헤더 파일 중 하나를 두어야 할 지 망설임이 옵니다:

note: (itstool) path: section/p
en: The problem there is that users are always accidentally getting the wrong header, since <cmd>-I/usr/include</cmd> seems to find its way onto compile command lines with some regularity. If you must do this, at least add a check to the library that detects applications using the wrong header file when the library is initialized.
ko: 문제는 사용자가 언제나 부주의하게 잘못된 헤더를 참조하는데, 컴파일 명령행에 <cmd>-I/usr/include</cmd>를 넣는걸 규칙인 것 처럼 생각하기 때문입니다. 만약 이렇게 해야 한다면, 최소한 라이브러리를 초기화할 때 잘못된 헤더 파일을 사용하여 프로그램을 감지하는 라이브러리가 있는지 검사하는 부분을 추가하십시오.

note: (itstool) path: section/p
en: Versioned header files can be installed from automake using the following code:
ko: 버전을 부여한 헤더 파일은 다음 코드로 automake에서 설치할 수 있습니다:

note: (itstool) path: listing/title
en: Header Files in Automake
ko: automake의 헤더 파일 처리

note: (itstool) path: listing/desc
en: Code to install versioned header files from <file>Makefile.am</file>
ko: <file>Makefile.am</file> 파일에 버전을 부여한 헤더 파일을 설치할 코드를 작성하십시오

note: (itstool) path: section/p
en: As well as correct versioning, all APIs in installed headers should be <link xref="namespacing">namespaced correctly</link>.
ko: 버전을 올바르게 부여하는 것처럼, 설치한 헤더에 있는 모든 API의 <link xref="namespacing">공간 이름을 올바르게 부여</link>해야합니다.

note: (itstool) path: section/title
en: Libraries
ko: 라이브러리

note: (itstool) path: section/p
en: Library object files should have a versioned name. For example:
ko: 라이브러리 객체 파일은 다음과 같이 버전을 붙인 이름을 달고 있어야합니다:

note: (itstool) path: section/p
en: This allows applications to get exactly the one they want at compile time, and ensures that versions 4 and 5 have no files in common.
ko: 이 과정으로 컴파일을 진행하는 동안 원하는 프로그램이 제대로 나오며, 일반적으로 버전 4 및 버전 5에 파일이 없는지 확인합니다.

note: (itstool) path: section/p
en: Versioned libraries can be built and installed from automake using the following code:
ko: 버전을 매긴 라이브러리는 다음 코드로 automake에서 빌드하고 설치할 수 있습니다:

note: (itstool) path: listing/title
en: Libraries in Automake
ko: automake의 라이브러리 처리

note: (itstool) path: listing/desc
en: Code to build and install versioned libraries from <file>Makefile.am</file>
ko: <file>Makefile.am</file>에 버전을 매긴 파일을 빌드하고 설치하는 코드를 작성하십시오

note: (itstool) path: section/title
en: Library sonames
ko: 라이브러리 so 이름

note: (itstool) path: section/p
en: Library sonames (also known as libtool version numbers) only address the problem of runtime linking previously-compiled applications. They don’t address the issue of compiling applications that require a previous version, and they don’t address anything other than libraries.
ko: 라이브러리 so 이름(libtool 버전 번호로도 알려짐)은 앞서 컴파일한 프로그램을 연결하는 실행시 문제만을 해결합니다. 이전 버전에서 필요한 프로그램을 컴파일하는 문제를 바로잡을 수 없으며, 다른 라이브러리의 문제는 바로 잡지 않습니다.

note: (itstool) path: section/p
en: For this reason, sonames should be used, but <em>in addition</em> to versioned names for libraries. The two solutions address different problems.
ko: 이 때문에, so 이름을 활용하지만, <em>추가로</em> 라이브러리의 이름에 버전을 붙입니다. 각각의 문제를 두가지 해결책으로 바로 잡습니다.

note: (itstool) path: section/title
en: pkg-config Files
ko: pkg-config 파일

note: (itstool) path: section/p
en: pkg-config files should have a versioned name. For example:
ko: 다음과 같이 pkg-config 파일에 버전을 매긴 이름을 넣어야합니다:

note: (itstool) path: section/p
en: Since each pkg-config file contains versioned information about the library name and include paths, any project which depends on the library should be able to switch from one version to another simply by changing their pkg-config check from <file>foo-4</file> to <file>foo-5</file> (and doing any necessary API porting).
ko: 각각의 pkg-config 파일에 라이브러리 이름과 수반 경로의 버전 정보가 있기 때문에 라이브러리에 의존하는 어떤 프로젝트든지간에 <file>foo-4</file> 파일에서 <file>foo-5</file> 파일로 pkg-config check를 바꾸(고 API 이식 필요 과정을 진행하)는 방법만으로 버전을 바꿀 수 있어야합니다.

note: (itstool) path: section/p
en: Versioned pkg-config files can be installed from autoconf and automake using the following code:
ko: 버전을 부여한 pkg-config 파일은 다음 코드로 autoconf 및 automake에서 설치할 수 있어야합니다:

note: (itstool) path: listing/title
en: pkg-config Files in Autoconf and Automake
ko: autoconf와 automake의 pkg-config 파일 처리

note: (itstool) path: listing/desc
en: Code to install versioned pkg-config files from <file>configure.ac</file> and <file>Makefile.am</file>
ko: <file>configure.ac</file>파일과 <file>Makefile.am</file> 파일에 버전을 부여한 pkg-config 파일을 설치하는 코드를 작성하십시오

note: (itstool) path: section/title
en: Configuration Files
ko: 설정 파일

note: (itstool) path: section/p
en: From a user standpoint, the best approach to configuration files is to keep the format both <link xref="api-stability">forward and backward compatible</link> (both library versions understand exactly the same configuration file syntax and semantics). Then the same configuration file can be used for all versions of the library, and no versioning is needed on the configuration file itself.
ko: 사용자 관점에서, <link xref="api-stability">전후 호환성</link>(정확히 동일한 설정 파일 및 문맥을 각 라이브러리 버전에서 이해)에 따라 설정 파일 형식을 유지하는게 좋습니다. 그 다음 동일한 설정 파일을 모든 라이브러리 버전에서 활용할 수 있으며, 설정 파일 자체를 버전 관리할 필요가 없습니다.

note: (itstool) path: section/p
en: If you can’t do that, the configuration files should simply be renamed, and users will have to configure each version of the library separately.
ko: 이렇게 할 수 있다면, 간단하게 설정 파일의 이름을 바꿔야 하며, 사용자는 각 라이브러리 버전 별로 따로 설정해야합니다.

note: (itstool) path: section/title
en: Gettext Translations
ko: gettext 번역

note: (itstool) path: section/p
en: If you use gettext for translations in combination with autoconf and automake, normally things are set up to install the translations to <file>/usr/share/locale/<var>lang</var>/LC_MESSAGES/<var>package</var></file>. You’ll need to change <var>package</var>. The convention used in GNOME is to put this in <file>configure.ac</file>:
ko: autoconf와 automake의 번역 기반으로 gettext를 사용한다면 보통 <file>/usr/share/locale/<var>lang</var>/LC_MESSAGES/<var>package</var></file> 경로에 번역 파일을 설치합니다. 여기서 <var>package</var> 변수를 추가해야합니다. 그놈에서는 <file>configure.ac</file>에 이 변수를 넣는 방식을 활용합니다:

note: (itstool) path: section/p
en: Then use <code>GETTEXT_PACKAGE</code> as the package name to pass to <code mime="text/x-csrc">bindtextdomain()</code>, <code mime="text/x-csrc">textdomain()</code>, and <code mime="text/x-csrc">dgettext()</code>.
ko: 그 다음 <code mime="text/x-csrc">bindtextdomain()</code>, <code mime="text/x-csrc">textdomain()</code>, <code mime="text/x-csrc">dgettext()</code>에 패키지 이름을 전달할 목적으로 <code>GETTEXT_PACKAGE</code>를 활용합니다.

note: (itstool) path: section/title
en: D-Bus Interfaces
ko: D-Bus 인터페이스

note: (itstool) path: section/p
en: A D-Bus interface is another form of API, similar to a C API except that resolution of the version is done at runtime rather than compile time. Versioning D-Bus interfaces is otherwise no different to C APIs: version numbers must be included in interface names, service names and object paths.
ko: D-Bus 인터페이스는 컴파일 시간이 아닌 실행 시간에 버전 관리를 처리할 때를 제외하고는 C API와 유사한 API의 한 유형입니다. D-Bus 인터페이스 버전 부여는 다른 C API와 별반 차이가 없습니다. 버전 숫자는 인터페이스 이름, 서비스 이름, 객체 경로에 있어야합니다.

note: (itstool) path: section/p
en: For example, for a service <code>org.example.Foo</code> exposing interfaces <code>A</code> and <code>B</code> on objects <code>Controller</code> and <code>Client</code>, versions 4 and 5 of the D-Bus API would look like this:
ko: 이를테면, 다음과 같이 <code>org.example.Foo</code> 서비스에는 <code>Controller</code>와 <code>Client</code>의 <code>A</code> 와 <code>B</code>, D-Bus API 버전 4와 5가 나타나야합니다:

note: (itstool) path: list/title
en: Service Names
ko: 서비스 이름

note: (itstool) path: list/title
en: Interface Names
ko: 인터페이스 이름

note: (itstool) path: list/title
en: Object Paths
ko: 객체 경로

note: (itstool) path: section/title
en: Programs, Daemons and Utilities
ko: 프로그램, 데몬, 유틸리티

note: (itstool) path: section/p
en: Desktop applications generally do not need to be versioned, as they are not depended on by any other modules. Daemons and utility programs, however, interact with other parts of the system and hence need versioning.
ko: 데스크톱 프로그램은 보통 다른 모듈과 의존 관계가 없기 때문에 버전을 매길 필요가 없습니다. 그러나 데몬과 유틸리티 프로그램은 시스템의 다른 부분과 함께 동작하므로 버전을 매겨야 합니다.

note: (itstool) path: section/p
en: Given a daemon and utility program:
ko: 다음의 데몬 및 유틸리티 프로그램을:

note: (itstool) path: section/p
en: these should be versioned as:
ko: 다음과 같이 버전을 부여합니다:

note: (itstool) path: section/p
en: You may want to install a symbolic link from <file>/usr/bin/foo-lookup-utility</file> to the recommended versioned copy of the utility, to make it more convenient for users to use.
ko: 사용자가 편리하게 쓸 수 있게 <file>/usr/bin/foo-lookup-utility</file>를 유틸리티의 추천 버전 사본으로 심볼릭 링크 사본을 설치하고 싶을 수도 있습니다.

note: (itstool) path: info/desc
en: Contract programming with checks on function input and output
ko: 함수 입출력을 검사하며 사전 계획에 따라 프로그래밍합니다

note: (itstool) path: page/title (itstool) path: section/title
en: Pre- and Post-Conditions
ko: 전 후 상태 테스트

note: (itstool) path: section/p
en: An important part of secure coding is ensuring that incorrect data does not propagate far through code — the further some malicious input can propagate, the more code it sees, and the greater potential there is for an exploit to be possible.
ko: 안전한 코드 작성에 있어 중요한 부분은 잘못된 데이터를 코드로 전달하는지 확인하는 과정입니다. 게다가 일부 악의적인 입력을 전달할 수 있고, 더 많은 코드에서 이 값을 들여다 보며, 권한 탈취 가능성에 더욱 큰 잠재성이 있습니다.

note: (itstool) path: section/p
en: A standard way of preventing the propagation of invalid data is to check all inputs to, and outputs from, all publicly visible functions in a library or module. There are two levels of checking:
ko: 잘못된 데이터의 전달을 막는 표준 방식은 모든 입력과, 모든 출력, 라이브러리 또는 모듈에 공개적으로 나타나는 모든 함수를 검사하는 방식입니다. 검사는 두 단계로 이루어집니다:

note: (itstool) path: item/title
en: Assertions
ko: 단언(assertion)

note: (itstool) path: item/p
en: Check for programmer errors and abort the program on failure.
ko: 프로그래머 오류를 확인하고 처리 실패시 프로그램을 중단하십시오.

note: (itstool) path: item/title
en: Validation
ko: 검증

note: (itstool) path: item/p
en: Check for invalid input and return an error gracefully on failure.
ko: 잘못된 입력을 확인하고 처리 실패시 충분한 오류 메시지를 반환하십시오.

note: (itstool) path: section/p
en: Validation is a complex topic, and is handled using <link xref="gerror">GErrors</link>. The remainder of this section discusses pre- and post-condition assertions, which are purely for catching programmer errors. A programmer error is where a function is called in a way which is documented as disallowed. For example, if <code>NULL</code> is passed to a parameter which is documented as requiring a non-<code>NULL</code> value to be passed; or if a negative value is passed to a function which requires a positive value. Programmer errors can happen on output too — for example, returning <code>NULL</code> when it is not documented to, or not setting a GError output when it fails.
ko: 검증은 복잡한 영역이며 <link xref="gerror">GErrors</link>로 처리합니다. 이 부분의 나머지는, 프로그래머 오류 만을 잡는 전 후 상태의 단언을 다룹니다. 프로그래머 오류는 함수에서 허용하지 않는 문서로 남겨둔 처리 방식입니다. <code>NULL</code> 값을 전달하면 안된다고 문서에 남겨둔 부분에 <code>NULL</code> 값을 전달했을 경우, 또는 양수 값을 전달해야 하는 함수에 음수 값을 전달했을 경우를 예로 들 수 있습니다. 프로그래머 오류는 출력으로도 나타날 수 있습니다. 문서에 <code>NULL</code> 값을 반환한다고 기록하지 않았는데 <code>NULL</code> 값을 반환하거나, 실행에 실패했을 때 GError 출력을 설정하지 않았을 경우가 이에 해당합니다.

note: (itstool) path: section/p
en: Adding pre- and post-condition assertions to code is as much about ensuring the behavior of each function is correctly and completely documented as it is about adding the assertions themselves. All assertions should be documented, preferably by using the relevant <link xref="introspection">introspection annotations</link>, such as <code>(nullable)</code>.
ko: 전 후 상태 단언부를 코드에 추가하면 각 함수의 동작을 좀 더 확실하게 파악할 수 있으며, 코드 자체에 단언부를 추가하는 만큼 그 자체로 완전한 문서화를 이룹니다. 모든 단언부는 <code>(nullable)</code>과 같은 관련 <link xref="introspection">인트로스펙션 주석</link>으로 적절하게 문서에 남겨두어야 합니다.

note: (itstool) path: section/p
en: Pre- and post-condition assertions are implemented using <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-if-fail"><code>g_return_if_fail()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail"><code>g_return_val_if_fail()</code></link>.
ko: <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-if-fail"><code>g_return_if_fail()</code></link> 함수와 <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail"><code>g_return_val_if_fail()</code></link> 함수를 활용하여 전 후 상태 단언부를 구현합니다.

note: (itstool) path: section/p
en: The pre-conditions should check each parameter at the start of the function, before any other code is executed (even retrieving the private data structure from a GObject, for example, since the GObject pointer could be <code>NULL</code>). The post-conditions should check the return value and any output parameters at the end of the function — this requires a single <code>return</code> statement and use of <code>goto</code> to merge other control paths into it. See <link xref="memory-management#single-path-cleanup"/> for an example.
ko: 이전 상태 단계에서는 다른 코드를 실행하기 전 함수의 시작 부분에서 각 매개변수를 검사해야합니다(예를 들면, GObject는 <code>NULL</code>이 될 수 있기에 GObject에서 자체 데이터 구조를 가져옴). 이후 상태 단계에서는 함수 마지막 부분의 출력 매개 변수와 반환 값을 검사해야합니다. 기타 제어 흐름을 한군데로 모아둘 목적으로 단일 <code>return</code> 구문과 <code>goto</code> 문을 사용해야합니다. 예제는 <link xref="memory-management#single-path-cleanup"/> 링크를 참고하십시오.

note: (itstool) path: info/desc
en: Moving computation out of the main thread into worker threads
ko: 메인 스레드 외부의 처리를 작업 스레드로 옮깁니다

note: (itstool) path: page/title
en: Threading
ko: 스레드 처리

note: (itstool) path: item/p
en: Do not use threads if at all possible. (<link xref="#when-to-use-threading"/>)
ko: 가능한 모든 경우에 스레드를 사용하지 마십시오(<link xref="#when-to-use-threading"/>).

note: (itstool) path: item/p
en: If threads have to be used, use <code>GTask</code> or <code>GThreadPool</code> and isolate the threaded code as much as possible. (<link xref="#using-threading"/>)
ko: 스레드를 사용해야하면, <code>GTask</code> 또는 <code>GThreadPool</code>를 사용하고, 가능한 한 스레드 처리한 코드를 격리하십시오(<link xref="#using-threading"/>).

note: (itstool) path: item/p
en: Use <code>g_thread_join()</code> to avoid leaking thread resources if using <code>GThread</code> manually. (<link xref="#using-threading"/>)
ko: <code>GThread</code>를 직접 사용한다면 <code>g_thread_join()</code> 함수를 사용하여 스레드 자원 누수를 막으십시오(<link xref="#using-threading"/>).

note: (itstool) path: item/p
en: Be careful about the <code>GMainContext</code> which code is executed in if using threads. Executing code in the wrong context can cause race conditions, or block the main loop. (<link xref="#using-threading"/>)
ko: 스레드를 사용할 경우 어떤 코드를 실행하든 <code>GMainContext</code>를 주의깊게 다루십시오. 잘못된 컨텍스트에서 코드를 실행하면 레이스 컨티션을 유발하거나 메인 루프가 멈출 수 있습니다(<link xref="#using-threading"/>).

note: (itstool) path: section/title
en: When to Use Threading
ko: 스레드 처리를 활용할 경우

note: (itstool) path: section/p
en: When writing projects using GLib, the default approach should be to <em style="strong">never use threads</em>. Instead, make proper use of the <link xref="main-contexts">GLib main context</link> which, through the use of asynchronous operations, allows most blocking I/O operations to continue in the background while the main context continues to process other events. Analysis, review and debugging of threaded code becomes very hard, very quickly.
ko: GLib로 프로젝트를 작성할 때, 기본 접근에 있어 <em style="strong">스레드를 절대 사용하지 말아야</em>합니다. 대신, 메인 컨텍스트에서 다른 이벤트 처리를 계속 하는 동안 백그라운드에서 대부분이 대부분의 블로킹 입출력 처리가 가능하도록 비동기 처리하는 <link xref="main-contexts">GLib 메인 컨텍스트</link>를 적절하게 활용하는 것이 좋습니다. 스레드 처리한 코드의 분석, 검토, 디버깅은 매우 급격하게 난해해집니다.

note: (itstool) path: section/p
en: Threading should only be necessary when using an external library which has blocking functions which need to be called from GLib code. If the library provides a non-blocking alternative, or one which integrates with a <link href="http://pubs.opengroup.org/onlinepubs/009695399/functions/poll.html"><code>poll()</code></link> loop, that should be used in preference. If the blocking function really must be used, a thin wrapper should be written for it to convert it to the normal <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code> style</link> of GLib asynchronous function, running the blocking operation in a worker thread.
ko: GLib 코드에서 호출해야 하는 함수의 동작을 가로 막는 외부 라이브러리를 활용할 경우라면 스레드를 활용해야합니다. 라이브러리에서 동작을 가로막지 않는 대안책을 마련하거나<link href="http://pubs.opengroup.org/onlinepubs/009695399/functions/poll.html"><code>poll()</code></link> 루프와 잘 동작하는 수단이 있다면 취향에 따라 사용해야합니다. 동작을 가로 막는 함수를 꼭 사용해야 한다면, 작업 스레드에서 동작을 가로 막는 처리를 실행하는 <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code> 방식</link> 일반 GLib 비동기 함수로 변환하도록 씬 래퍼를 작성해야합니다.

note: (itstool) path: example/p
en: Should be wrapped as:
ko: 위 코드를 다음과 같이 래핑해야합니다:

note: (itstool) path: example/p
en: With an implementation something like:
ko: 그리고 다음과 같은 구현체를 넣으십시오:

note: (itstool) path: example/p
en: See the <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code> documentation</link> for more details. A simple way to implement the worker thread is to use <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> and <link href="https://developer.gnome.org/gio/stable/GTask.html#g-task-run-in-thread"><code>g_task_run_in_thread()</code></link>. (See also: <link xref="main-contexts#gtask"/>.)
ko: 자세한 내용은 <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code> 문서</link>를 참고하십시오. 작업 스레드를 구현하는 간단한 방법은 <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> 와 <link href="https://developer.gnome.org/gio/stable/GTask.html#g-task-run-in-thread"><code>g_task_run_in_thread()</code></link> 함수를 활용하는 방법입니다(추가 참고: <link xref="main-contexts#gtask"/>).

note: (itstool) path: section/title
en: Using Threading
ko: 스레드 활용

note: (itstool) path: section/p
en: If <code>GTask</code> is not suitable for writing the worker thread, a more low-level approach must be used. This should be considered very carefully, as it is very easy to get threading code wrong in ways which will unpredictably cause bugs at runtime, cause deadlocks, or consume too many resources and terminate the program.
ko: 작업 스레드를 작성할 때 <code>GTask</code>가 적절한 수단이 아니라면, 좀 더 저수준의 접근 방식을 활용해야합니다. 스레드 코드로 하여금 실행 시간에 예기치 못한 버그가 나타난다거나, 데드락이 갑자기 걸린다거나, 자원을 갑자기 많이 소모한다거나, 프로그램이 끝나는 일은 식은죽 먹기니 매우 신중하게 고려해야 합니다.

note: (itstool) path: section/p
en: A full manual on writing threaded code is beyond the scope of this document, but here are a number of guidelines to follow which should reduce the potential for bugs in threading code. The overriding principle is to reduce the amount of code and data which can be affected by threading — for example, reducing the number of threads, the complexity of worker thread implementation, and the amount of data shared between threads.
ko: 스레드 코드 작성 완벽 설명서는 이 문서의 범위를 벗어나지만, 스레드 코드 작성시 잠재 버그를 줄이려 따를 몇가지 지침서가 있습니다. 무엇보다 우선하는 원칙은 스레드로 영향을 줄 수 있는 코드 및 데이터 양을 줄이는 방식입니다. 예를 들면, 스레드 수를 줄이거나, 작업 스레드 구현의 복잡도를 줄이거나, 스레드간 공유 데이터 양을 줄이는 방법입니다.

note: (itstool) path: item/p
en: Use <link href="https://developer.gnome.org/glib/stable/glib-Thread-Pools.html"><code>GThreadPool</code></link> instead of manually creating <link href="https://developer.gnome.org/glib/stable/glib-Threads.html"><code>GThread</code>s</link> if possible. <code>GThreadPool</code> supports a work queue, limits on the number of spawned threads, and automatically joins finished threads so they are not leaked.
ko: 가능하면 직접 <link href="https://developer.gnome.org/glib/stable/glib-Threads.html"><code>GThread</code></link>를 만들기보다는 <link href="https://developer.gnome.org/glib/stable/glib-Thread-Pools.html"><code>GThreadPool</code></link>을 사용핫비시오. <link href="https://developer.gnome.org/glib/stable/glib-Thread-Pools.html"><code>GThreadPool</code></link>에서는 작업 큐, 가동 스레드 수 제한, 종결 스레드 자동 병합을 지원하여, 스레드가 어디론가 새 나갈 일이 없습니다.

note: (itstool) path: item/p
en: If it is not possible to use a <code>GThreadPool</code> (which is rarely the case):
ko: <code>GThreadPool</code>을 활용할 수 없다면(드문 경우):

note: (itstool) path: item/p
en: Use <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-try-new"><code>g_thread_try_new()</code></link> to spawn threads, instead of <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-new"><code>g_thread_new()</code></link>, so errors due to the system running out of threads can be handled gracefully rather than unconditionally aborting the program.
ko: 스레드를 만들려면 <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-new"><code>g_thread_new()</code></link> 함수 대신 <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-try-new"><code>g_thread_try_new()</code></link> 함수를 활용하여 프로그램의 상태를 알 수 없는 상황에서 갑자기 멈추게 하기 보단 스레드 외적 영역에서의 시스템 동작상 나타나는 오류를 탁월하게 처리할 수 있게 하십시오.

note: (itstool) path: item/p
en: Explicitly join threads using <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-join"><code>g_thread_join()</code></link> to avoid leaking the thread resources.
ko: 스레드 자원의 방치를 막으려면 <link href="https://developer.gnome.org/glib/stable/glib-Threads.html#g-thread-join"><code>g_thread_join()</code></link> 함수를 사용하여 분명하게 스레드를 병합하십시오.

note: (itstool) path: item/p
en: Use message passing to transfer data between threads, rather than manual locking with mutexes. <code>GThreadPool</code> explicitly supports this with <link href="https://developer.gnome.org/glib/stable/glib-Thread-Pools.html#g-thread-pool-push"><code>g_thread_pool_push()</code></link>.
ko: 스레드간 데이터를 전달할 때, 뮤텍스의 동작을 직접 잠그기보다는 메시지 전달 기능을 활용하십시오. <code>GThreadPool</code>에서는 <link href="https://developer.gnome.org/glib/stable/glib-Thread-Pools.html#g-thread-pool-push"><code>g_thread_pool_push()</code></link> 함수로 메시지 전달 기능을 지원합니다.

note: (itstool) path: item/p
en: If mutexes must be used:
ko: 뮤텍스를 활용해야 한다면:

note: (itstool) path: item/p
en: Isolate threading code as much as possible, keeping mutexes private within classes, and tightly bound to very specific class members.
ko: 스레드 코드를 최대한 격리하고, 클래스에서 뮤텍스를 자체 용도로 유지하며, 매우 한정적인 클래스 구성원만 다루십시오.

note: (itstool) path: item/p
en: All mutexes should be clearly commented beside their declaration, indicating which other structures or variables they protect access to. Similarly, those variables should be commented saying that they should <em>only</em> be accessed with that mutex held.
ko: 모든 뮤텍스는 뮤텍스에 보호 접근할 기타 구조체 또는 변수를 나타내는 선언부에 분명하게 설명을 달아두어야합니다. 이와 비슷하게, 해당 뮤텍스의 변수도 뮤텍스에서<em>만</em> 접근해야 한다고 설명을 달아두어야합니다.

note: (itstool) path: item/p
en: Be careful about interactions between main contexts and threads. For example, <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-timeout-add-seconds"><code>g_timeout_add_seconds()</code></link> adds a timeout <em>to be executed in the global default main context</em>, which is being run in the main thread, <em>not necessarily</em> the current thread. Getting this wrong can mean that work intended for a worker thread accidentally ends up being executed in the main thread anyway. (See also: <link xref="main-contexts#default-contexts"/>.)
ko: 메인 컨텍스트와 스레드간 상호 작용을 조심스럽게 취급하십시오. 예를 들면, <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-timeout-add-seconds"><code>g_timeout_add_seconds()</code></link> 함수는, 현재 스레드에서 <em>불필요하며</em>, 메인 스레드에서 실행할 <em>전역 메인 컨텍스트의 실행</em> 제한 시간을 설정합니다. 이 부분을 잘못 설정하면 메인 스레드에서 실행한 작업 스레드가 갑자기 끝날 수 있음을 의미합니다(추가 참조: <link xref="main-contexts#default-contexts"/>).

note: (itstool) path: section/title
en: Debugging
ko: 디버깅

note: (itstool) path: section/p
en: Debugging threading issues is tricky, both because they are hard to reproduce, and because they are hard to reason about. This is one of the big reasons for avoiding using threads in the first place.
ko: 스레드 문제 디버깅은 상당히 까다로운데 재현하기도 어려울 뿐더러 왜 인지도 이유를 밝히기 어렵기 때문입니다. 이게 바로 제일 먼저 스레드를 활용할 때 피해야 할 가장 큰 이유중 하나입니다.

note: (itstool) path: section/p
en: However, if a threading issue does arise, <link xref="tooling#helgrind-and-drd">Valgrind’s drd and helgrind tools are useful</link>.
ko: 그러나, 스레드 문제가 터지면 <link xref="tooling#helgrind-and-drd">Valgrind의 drd 도구와 helgrind 도구가 도움될 수 있습니다</link>.

note: (itstool) path: info/desc
en: Using the right tool for various tasks
ko: 다양한 작업을 처리할 올바른 도구 활용

note: (itstool) path: page/title
en: Tooling
ko: 도구 활용

note: (itstool) path: page/p
en: Development tools are much more than just a text editor and a compiler. Correct use of the right tools can drastically ease debugging and tracking down of complex problems with memory allocation and system calls, amongst other things. Some of the most commonly used tools are described below; other tools exist for more specialized use cases, and should be used when appropriate.
ko: 개발 도구는 텍스트 편집기 및 컴파일러 말고도 굉장히 많습니다. 도구를 올바르게 활용하면 디버깅, 메모리 할당 및 시스템 콜, 기타 복잡한 문제의 추적이 쉬워집니다. 대부분 일반적으로 활용하는 일부 도구를 아래에 설명했습니다만, 특수 목적으로 활용하는 도구가 있으며, 필요하다면 활용해야합니다.

note: (itstool) path: page/p
en: An overarching principle to use when developing is to always have as many debugging options enabled as possible, rather than keeping them disabled until near release time. By constantly testing code with all available debug tooling, bugs can be caught early on, before they become ingrained in code and thus harder to remove.
ko: 대단히 중요한 원칙은 출시 시기가 닥치기 전까지 최대한 많은 디버깅 옵션을 비활성화 하기보단 개발할 때 항상 활성화하는 조치입니다. 가능한 모든 디버그 도구를 활용하여 꾸준히 코드를 테스트하면, 버그가 코드에 깊이 뿌리 박혀 없애기 어려워 지기 전 빨리 잡을 수 있습니다.

note: (itstool) path: page/p
en: Practically, this means having all compiler and other tool warnings enabled and set to fail the build process with an error if they are emitted.
ko: 실제로, 모든 컴파일러 및 기타 도구의 경고를 활성화하고 경고 메시지가 나타났을 경우 빌드 과정의 오류로 간주하여 실패하도록 설정하라는 의미입니다.

note: (itstool) path: item/p
en: Compile frequently with a second compiler. (<link xref="#gcc-and-clang"/>)
ko: 2차 컴파일러로 자주 컴파일하십시오(<link xref="#gcc-and-clang"/>).

note: (itstool) path: item/p
en: Enable a large selection of compiler warnings and make them fatal. (<link xref="#gcc-and-clang"/>)
ko: 다양한 컴파일러 경고 범위를 활성화하고, 경고 항목을 치명적인 항목으로 간주하십시오(<link xref="#gcc-and-clang"/>).

note: (itstool) path: item/p
en: Use GDB to debug and step through code. (<link xref="#gdb"/>)
ko: GDB를 활용하여 코드를 디버깅하고 한 단계씩 실행하십시오(<link xref="#gdb"/>).

note: (itstool) path: item/p
en: Use Valgrind to analyze memory usage, memory errors, cache and CPU performance and threading errors. (<link xref="#valgrind"/>)
ko: Valgrind를 활용하여 메모리 사용 상태, 메모리 오류, 캐시 및 CPU 성능, 스레드 오류를 분석하십시오(<link xref="#valgrind"/>).

note: (itstool) path: item/p
en: Use gcov and lcov to analyze unit test coverage. (<link xref="#gcov-and-lcov"/>)
ko: gcov 및 lcov를 활용하여 단위 테스트 범위를 분석하십시오(<link xref="#gcov-and-lcov"/>).

note: (itstool) path: item/p
en: Use compiler sanitizers to analyze memory, thread and undefined behavior problems. (<link xref="#sanitizers"/>)
ko: 컴파일러 정리기를 활용하여 메모리, 스레드 및 비지정 동작 문제를 분석하십시오(<link xref="#sanitizers"/>).

note: (itstool) path: item/p
en: Submit to Coverity as a cronjob and eliminate static analysis errors as they appear. (<link xref="#coverity"/>)
ko: cronjob을 활용하여 Coverity에 제출하고 정적 분석 오류가 나타나는대로 수정하십시오(<link xref="#coverity"/>).

note: (itstool) path: item/p
en: Use Clang static analyzer and Tartan regularly to eliminate statically analysable errors locally. (<link xref="#clang-static-analyzer"/>)
ko: Clang 정적 분석기 및 Tartan을 주기적으로 활용하여 로컬에서 꾸준히 분석할 수 있는 오류를 하나하나 수정하십시오(<link xref="#clang-static-analyzer"/>).

note: (itstool) path: section/title
en: GCC and Clang
ko: GCC와 Clang

note: (itstool) path: section/p
en: <link href="https://gcc.gnu.org/onlinedocs/gcc/">GCC</link> is the standard C compiler for Linux. An alternative exists in the form of <link href="http://clang.llvm.org/docs/UsersManual.html">Clang</link>, with comparable functionality. Choose one (probably GCC) to use as a main compiler, but occasionally use the other to compile the code, as the two detect slightly different sets of errors and warnings in code. Clang also comes with a static analyzer tool which can be used to detect errors in code without compiling or running it; see <link xref="#clang-static-analyzer"/>.
ko: <link href="https://gcc.gnu.org/onlinedocs/gcc/">GCC</link>는 리눅스용 표준 C 컴파일러입니다. <link href="http://clang.llvm.org/docs/UsersManual.html">Clang</link>이라는 기능 호환 대안도 있습니다. 이 중 하나를 주 컴파일러(아마도 GCC)를 선택하겠지만, 코드에서 나타나는 오류 및 경고 출력이 약간 다르기 때문에, 경우에 따라 코드를 컴파일할 때 다른 컴파일러를 산택합니다. Clang에는 코드를 컴파일하거나 실행하지 않고도 코드의 오류를 찾아낼 수 있는 정적 분석 도구가 있습니다. <link xref="#clang-static-analyzer"/>를 참고하십시오.

note: (itstool) path: section/p
en: Both compilers should be used with as many warning flags enabled as possible. Although compiler warnings do occasionally provide false positives, most warnings legitimately point to problems in the code, and hence should be fixed rather than ignored. A development policy of enabling all warning flags and also specifying the <code>-Werror</code> flag (which makes all warnings fatal to compilation) promotes fixing warnings as soon as they are introduced. This helps code quality. The alternative of ignoring warnings leads to long debugging sessions to track down bugs caused by issues which would have been flagged up by the warnings. Similarly, ignoring warnings until the end of the development cycle, then spending a block of time enabling and fixing them all wastes time.
ko: 두 컴파일러는 가능한 많은 경고 플래그를 설정하여 사용해야 합니다. 컴파일러 경고가 때로는 거짓 양성 결과를 출력할 수도 있지만, 대부분의 경고는 코드의 문제를 정확하게 짚어내며, 이 문제를 무시하기 보단 수정해아합니다. 모든 경고 플래그를 활성화하고 <code>-Werror</code> 플래그(모든 경고를 컴파일 실패로 간주)를 지정하는 개발 정책은 나타나는대로 최대한 경고를 수정하겠다는 의지를 고취하며, 코드 품질 개선에 도움을줍니다. 경고를 무시하면, 경고로 나타난 문제로 인해 발생한 버그를 디버깅 세션 내내 오랫동안 찾게 만듭니다. 개발 기간이 끝날 때까지 경고를 무시하면, 경고를 활성화하고 경고문을 따라 문제를 수정하는데 엄청난 시간을 소비합니다.

note: (itstool) path: section/p
en: Both GCC and Clang support a wide range of compiler flags, only some of which are related to modern, multi-purpose code (for example, others are outdated or architecture-specific). Finding a reasonable set of flags to enable can be tricky, and hence the <link href="http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html"> <code>AX_COMPILER_FLAGS</code></link> macro exists.
ko: GCC와 Clang은 다양한 범위의 컴파일러 플래그를 지원하는데, 일부는 최근 범용 코드에먼 관련이 있습니다(예를 들면, 다른 코드는 오래되었거나 특정 아키텍처에서만 동작합니다). 타당한 활성화 플래그 셋을 결정하는건 까다로울 수 있어 <link href="http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html"> <code>AX_COMPILER_FLAGS</code></link> 매크로가 있습니다.

note: (itstool) path: section/p
en: <code>AX_COMPILER_FLAGS</code> enables a consistent set of compiler warnings, and also tests that the compiler supports each flag before enabling it. This accounts for differences in the set of flags supported by GCC and Clang. To use it, add <code>AX_COMPILER_FLAGS</code> to <file>configure.ac</file>. If you are using in-tree copies of autoconf-archive macros, copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_compiler_flags.m4"> <file>ax_compiler_flags.m4</file></link> to the <file>m4/</file> directory of your project. Note that it depends on the following autoconf-archive macros which are GPL-licenced so potentially cannot be copied in-tree. They may have to remain in autoconf-archive, with that as a build time dependency of the project:
ko: <code>AX_COMPILER_FLAGS</code> 매크로는 언제나 가은 컴파일러 경고 설정을 활성화하며, 경고 설정을 활성화하기 전에 컴파일러의 지원 유무를 테스트합니다. 이 과정에서 GCC 및 Clang에서 지원하는 플래그 모음의 차이를 확인합니다. 이 매크로를 사용하려면 <file>configure.ac</file> 파일에 <code>AX_COMPILER_FLAGS</code> 플래그를 추가하십시오. autoconf-archive 매크로의 트리 내 사본을 활용한다면, 프로젝트의 <file>m4/</file> 디렉터리에 <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_compiler_flags.m4"> <file>ax_compiler_flags.m4</file></link> 파일을 복사하십시오. 참고로, 다음 autoconf-archive 매크로가 어떤 GPL 라이선스를 적용하는지에 따라 다르기 때문에 트리에 복사를 못할 수도 있습니다. 프로젝트에서 빌드할 때만 동작하도록 autoconf-archive에 그냥 두는게 낫습니다:

note: (itstool) path: section/p
en: <code>AX_COMPILER_FLAGS</code> supports disabling <code>-Werror</code> for release builds, so that releases may always be built against newer compilers which have introduced more warnings. Set its third parameter to ‘yes’ for release builds (and only release builds) to enable this functionality. Development and CI builds should always have <code>-Werror</code> enabled.
ko: <code>AX_COMPILER_FLAGS</code>에서는 출시판 빌드 목적으로 <code>-Werror</code> 플래그 비활성화를 지원하므로, 출시판은 항상 더 많은 경고 메시지를 내보낼 수 있는 새 컴파일러로 빌드할 수도 있습니다. 출시판 빌드(그리고 오직 출시 빌드 용도로만) 목적으로 이 기능을 활성화하려면 세번째 매개변수 값을 ‘yes’로 설정하십시오. 개발 및 CI 빌드 과정에서는 항상 <code>-Werror</code> 플래그를 활성화해야합니다.

note: (itstool) path: section/p
en: Release builds can be detected using the <link href="http://www.gnu.org/software/autoconf-archive/ax_is_release.html"><code>AX_IS_RELEASE</code></link> macro, the result of which can be passed directly to <code>AX_COMPILER_FLAGS</code>:
ko: 출시판 빌드는 <code>AX_COMPILER_FLAGS</code>에 결과를 바로 전달할 수 있는 <link href="http://www.gnu.org/software/autoconf-archive/ax_is_release.html"><code>AX_IS_RELEASE</code></link>를 활용하여 찾을 수 있습니다:

note: (itstool) path: section/p
en: The choice of release stability policy (the first argument to <code>AX_IS_RELEASE</code>) should be made per project, taking the project’s <link xref="versioning">versioning stability</link> into account.
ko: 출시 안정 정책의 선택(<code>AX_IS_RELEASE</code>의 첫번째 인자)은 프로젝트의 <link xref="versioning">버전 부여 안정성</link>을 취할 프로젝트 별로 설정해야 합니다.

note: (itstool) path: section/p
en: GDB is the standard debugger for C on Linux. Its most common uses are for debugging crashes, and for stepping through code as it executes. A full tutorial for using GDB is given <link href="https://sourceware.org/gdb/current/onlinedocs/gdb/"> here</link>.
ko: GDB는 리눅스에서 사용하는 C언어용 표준 디버거입니다. 프로그램의 갑작스러운 중단을 디버깅할 때 매우 보편적으로 사용하며, 프로그램의 코드를 실행할 때, 단계별로 살펴보려는 용도로도 활용합니다. GDB 사용 완벽 지침서는 <link href="https://sourceware.org/gdb/current/onlinedocs/gdb/">여기</link>에 있습니다.

note: (itstool) path: section/p
en: To run GDB on a program from within the source tree, use: <cmd>libtool exec gdb --args <var>./program-name</var> <var>--some --arguments --here</var></cmd>
ko: 소스 트리에서 프로그램 실행시 GDB를 실행하려면 <cmd>libtool exec gdb --args <var>./program-name</var> <var>--some --arguments --here</var></cmd> 명령을 사용하십시오

note: (itstool) path: section/p
en: This is necessary due to libtool wrapping each compiled binary in the source tree in a shell script which sets up some libtool variables. It is not necessary for debugging installed executables.
ko: libtool은 몇가지 libtool 변수를 설정하는 쉘 스크립트로 소스 트리상에서 컴파일한 각각의 이진 파일에 둘러싸여있기 때문에 GDB가 필요합니다. 설치한 실행 파일을 디버깅할 때는 필요하지 않습니다.

note: (itstool) path: section/p
en: GDB has many advanced features which can be combined to essentially create small debugging scripts, triggered by different breakpoints in code. Sometimes this is a useful approach (for example, for <link href="https://tecnocode.co.uk/2010/07/12/reference-count-debugging-with-gdb/"> reference count debugging</link>), but sometimes simply using <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"> <code>g_debug()</code></link> to output a debug message is simpler.
ko: GDB는 코드의 각 부분의 중단점에서 실행할 작은 핵심 디버깅 스크립트를 만들 때 근본적으로 합칠 수 있는 여러가지 고급 기능이 있습니다. 때로는 (<link href="https://tecnocode.co.uk/2010/07/12/reference-count-debugging-with-gdb/">참조 카운트 디버깅</link> 같은 경우) 쓸 만한 접근 수단일 수 있지만, 어떤 경우에는 <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"> <code>g_debug()</code></link> 함수로 디버깅 메시지를 출력하는게 더 간단한 방법일 수도 있습니다.

note: (itstool) path: section/p
en: Valgrind is a suite of tools for instrumenting and profiling programs. Its most famous tool is <link xref="#memcheck">memcheck</link>, but it has several other powerful and useful tools too. They are covered separately in the sections below.
ko: Valgrind는 프로그램의 동작을 측정하고 프로파일링하는 도구의 모음입니다. 제일 인기있는 도구는 <link xref="#memcheck">memcheck</link>지만, 몇가지 강력하고 쓸 만한 다른 도구도 있습니다. 다음 부분에서 개별적으로 다루겠습니다.

note: (itstool) path: section/p
en: A useful way of running Valgrind is to run a program’s unit test suite under Valgrind, setting Valgrind to return a status code indicating the number of errors it encountered. When run as part of <cmd>make check</cmd>, this will cause the checks to succeed if Valgrind finds no problems, and fail otherwise. However, running <cmd>make check</cmd> under Valgrind is not trivial to do on the command line. A macro, <link href="http://www.gnu.org/software/autoconf-archive/ax_valgrind_check.html"> <code>AX_VALGRIND_CHECK</code></link> can be used which adds a new <cmd>make check-valgrind</cmd> target to automate this. To use it:
ko: Valgrind를 활용하는 쓸 만한 방법은 Valgrind에서 확인한 수많은 오류를 나타내는 상태 코드를 반환하도록 설정한 Valgrind에서 프로그램의 단위 테스트 모음을 실행하는 방법입니다. <cmd>make check</cmd>의 일부로 실행할 때, Valgrind에서 문제를 찾지 못했다면 성공했다고 표시하고 그렇지 않으면 실패했다고 표시합니다. 그러나, 명령행의 Valgrind에서 <cmd>make check</cmd> 명령을 실행하면 항상 그렇지는 않습니다. <cmd>make check-valgrind</cmd> 타겟을 추가하여 명령행에서 자동으로 Valgrind를 실행하도록 <link href="http://www.gnu.org/software/autoconf-archive/ax_valgrind_check.html"> <code>AX_VALGRIND_CHECK</code></link> 매크로를 활용할 수 있습니다. 언급한 대로 활용하려면:

note: (itstool) path: item/p
en: Copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_valgrind_check.m4"> <file>ax_valgrind_check.m4</file></link> to the <file>m4/</file> directory of your project.
ko: <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_valgrind_check.m4"> <file>ax_valgrind_check.m4</file></link> 파일을 프로젝트의 <file>m4/</file> 디렉터리에 복사하십시오.

note: (itstool) path: item/p
en: Add <code>AX_VALGRIND_CHECK</code> to <file>configure.ac</file>.
ko: <file>configure.ac</file>에 <code>AX_VALGRIND_CHECK</code>를 추가하십시오.

note: (itstool) path: item/p
en: Add <code>@VALGRIND_CHECK_RULES@</code> to the <file>Makefile.am</file> in each directory which contains unit tests.
ko: 단위 테스트를 넣은 각 디렉터리의 <file>Makefile.am</file> 파일에 <code>@VALGRIND_CHECK_RULES@</code> 코드를 추가하십시오.

note: (itstool) path: section/p
en: When <cmd>make check-valgrind</cmd> is run, it will save its results in <file>test-suite-*.log</file>, one log file per tool. Note that you will need to run it from the directory containing the unit tests.
ko: <cmd>make check-valgrind</cmd> 명령을 실행하면, 도구마다 하나씩 만드는 <file>test-suite-*.log</file> 로그 파일에 결과를 저장합니다. 단위 테스트가 있는 디렉터리마다 이 명령을 실행해야 함을 참고하십시오.

note: (itstool) path: section/p
en: Valgrind has a way to suppress false positives, by using <link href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress"> suppression files</link>. These list patterns which may match error stack traces. If a stack trace from an error matches part of a suppression entry, it is not reported. For various reasons, GLib currently causes a number of false positives in <link xref="#memcheck">memcheck</link> and <link xref="#helgrind-and-drd">helgrind and drd</link> which must be suppressed by default for Valgrind to be useful. For this reason, every project should use a standard GLib suppression file as well as a project specific one.
ko: Valgrind에는 <link href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress">파일 숨김 기법(suppression files)</link>으로 거짓 양성 결과를 없애는 방법이 있습니다. 이 목록으로 오류 추적 스택과 비교할 패턴을 나타냅니다. 오류로부터 나온 추적 스택이 숨김 항목의 일부와 일치하면, 보고하지 않습니다. 여러가지 이유로 GLib에서는 <link xref="#memcheck">memcheck</link>와 Valgrind 사용시 기본적으로 숨기는게 좋은 <link xref="#helgrind-and-drd">helgrind 및 drd</link>에서 수많은 거짓 양성 결과를 출력합니다. 이 때문에, 프로젝트에서 지정한대로 표준 GLib 숨김 파일 목록을 사용해야합니다.

note: (itstool) path: section/p
en: Suppression files are supported by the <code>AX_VALGRIND_CHECK</code> macro:
ko: <code>AX_VALGRIND_CHECK</code> 매크로에서 파일을 숨기는 기능도 지원합니다:

note: (itstool) path: section/p
en: memcheck is a memory usage and allocation analyzer. It detects problems with memory accesses and modifications of the heap (allocations and frees). It is a highly robust and mature tool, and its output can be entirely trusted. If it says there is ‘definitely’ a memory leak, there is definitely a memory leak which should be fixed. If it says there is ‘potentially’ a memory leak, there may be a leak to be fixed, or it may be memory allocated at initialization time and used throughout the life of the program without needing to be freed.
ko: memcheck는 메모리 사용 및 할당 분석기입니다. 메모리 접근 및 힙 수정 문제(할당 및 해제)를 찾아냅니다. 상당히 견고하고 잘 다듬어진 도구이며, 출력 결과는 전적으로 신뢰할 수 있습니다. ‘분명하게’ 메모리 누수가 있다고 한다면, 고쳐야 할 메모리 누수가 분명하게 있으며, ‘잠재적’ 메모리 누수가 있다면, 메모리 누수를 수정해야 하거나, 초기화 과정에서 메모리를 할당한 후 힙 메모리 공간을 해제하지 않고 프로그램 동작 내내 사용할 지도 모릅니다.

note: (itstool) path: section/p
en: To run memcheck manually on an installed program, use:
ko: 설치한 프로그램에 대해 memcheck를 실행하려면 다음 명령을 활용하십시오:

note: (itstool) path: section/p
en: Or, if running your program from the source directory, use the following to avoid running leak checking on the libtool helper scripts:
ko: 또는 원본 디렉터리에서 프로그램을 실행한다면, 다음 명령을 사용하여 libtool 보조 스크립트에서 메모리 누수 검사 실행을 막으십시오:

note: (itstool) path: section/p
en: Valgrind lists each memory problem it detects, along with a short backtrace (if you’ve compiled your program with debug symbols), allowing the cause of the memory error to be pinpointed and fixed.
ko: (디버깅 심볼을 둔채로 컴파일 한 경우)Valgrind는 메모리 오류를 정확히 찾아 수정할 수 있도록 짧은 역추적 기록에서 자체적으로 찾아낸 메모리 문제를 나타냅니다.

note: (itstool) path: section/p
en: A full tutorial on using memcheck is <link href="http://valgrind.org/docs/manual/mc-manual.html">here</link>.
ko: memcheck 사용 완벽 지침서는 <link href="http://valgrind.org/docs/manual/mc-manual.html">여기</link>에 있습니다.

note: (itstool) path: section/title
en: cachegrind and KCacheGrind
ko: cachegrind 및 KCacheGrind

note: (itstool) path: section/p
en: cachegrind is a cache performance profiler which can also measure instruction execution, and hence is very useful for profiling general performance of a program. <link href="http://kcachegrind.sourceforge.net/html/Home.html"> KCacheGrind</link> is a useful UI for it which allows visualization and exploration of the profiling data, and the two tools should rarely be used separately.
ko: cachegrind는 인스트럭션 실행도 측정할 수 있는 캐시 성능 프로파일러기 때문에 프로그램의 일반 성능 프로파일링에 매우 쓸 만합니다. <link href="http://kcachegrind.sourceforge.net/html/Home.html">KCacheGrind</link>는 프로파일링 데이터를 시각화하고 탐색할 수 있게 하는 쓸 만한 도구이며, 언급한 두가지 도구를 따로 사용하는 경우는 드뭅니다.

note: (itstool) path: section/p
en: cachegrind works by simulating the processor’s memory hierarchy, so there are situations where it is <link href="http://valgrind.org/docs/manual/cg-manual.html#cg-manual.annopts.accuracy"> not perfectly accurate</link>. However, its results are always representative enough to be very useful in debugging performance hotspots.
ko: cachegrind는 프로세서 메모리 계층을 시뮬레이팅하기에 <link href="http://valgrind.org/docs/manual/cg-manual.html#cg-manual.annopts.accuracy">완전히 정확하지 않은</link> 상황이 있을 수도 있습니다. 그러나, 이 프로그램의 결과는 항상 주요 지점의 성능 디버깅에 충분히 대표적으로 쓸 만합니다.

note: (itstool) path: section/p
en: A full tutorial on using cachegrind is <link href="http://valgrind.org/docs/manual/cg-manual.html">here</link>.
ko: cachegrind 사용 완벽 지침서는 <link href="http://valgrind.org/docs/manual/cg-manual.html">여기</link>에 있습니다.

note: (itstool) path: section/title
en: helgrind and drd
ko: helgrind 및 drd

note: (itstool) path: section/p
en: helgrind and drd are threading error detectors, checking for race conditions in memory accesses, and abuses of the <link href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html"> POSIX pthreads API</link>. They are similar tools, but are implemented using different techniques, so both should be used.
ko: helgrind와 drd는 메모리 접근시 레이스 컨디션과 <link href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html"> POSIX pthreads API</link>의 남용을 검사하는 스레드 오류 감지기입니다. 비슷한 도구지만 다른 기법으로 구현했기에 두가지 도구를 모두 사용해야합니다.

note: (itstool) path: section/p
en: The kinds of errors detected by helgrind and drd are: data accessed from multiple threads without consistent locking, changes in lock acquisition order, freeing a mutex while it is locked, locking a locked mutex, unlocking an unlocked mutex, and several other errors. Each error, when detected, is printed to the console in a little report, with a separate report giving the allocation or spawning details of the mutexes or threads involved so that their definitions can be found.
ko: helgrind와 drd에서 찾는 오류는 일관성있는 잠금 조치 없이 다중 스레드의 데이터 접근, 잠금 승인 순서의 바뀜, 뮤텍스를 잠그는 동안 해제 동작, 잠긴 뮤텍스의 잠금, 잠금 해제한 뮤텍스의 잠금 해제, 및 몇가지 오류입니다. 각 오류를 발견하면, 몇가지 보고서로 콘솔에 출력하며, 이 보고서에는 관련된 뮤텍스 및 스레드의 할당 또는 생성 세부 정보가 들어있어, 관련 스레드와 뮤텍스의 자세한 내용을 찾을 수 있습니다.

note: (itstool) path: section/p
en: helgrind and drd can produce more false positives than memcheck or cachegrind, so their output should be studied a little more carefully. However, threading problems are notoriously elusive even to experienced programmers, so helgrind and drd errors should not be dismissed lightly.
ko: helgrind와 drd는 memcheck또는 cachegrind보다 거짓양성 결과를 더 많이 출력할 수 있어, 좀 더 신중하게 출력 결과를 살펴봐야 합니다. 그러나, 스레드 처리 문제는 경험이 있는 프로그래머에게 마저도 악명이 자자할 정도로 찾기 어렵기에 helgrind와 drd 오류를 가볍게 무시해선 안됩니다.

note: (itstool) path: section/p
en: Full tutorials on using helgrind and drd are <link href="http://valgrind.org/docs/manual/hg-manual.html">here</link> and <link href="http://valgrind.org/docs/manual/drd-manual.html"> here</link>.
ko: helgrind와 drd 사용 완벽 지침서는 <link href="http://valgrind.org/docs/manual/hg-manual.html">이 곳</link>과 <link href="http://valgrind.org/docs/manual/drd-manual.html">이 곳</link>에 있습니다.

note: (itstool) path: section/p
en: sgcheck is an array bounds checker, which detects accesses to arrays which have overstepped the length of the array. However, it is a very young tool, still marked as experimental, and hence may produce more false positives than other tools.
ko: sgcheck는 배열의 길이를 넘겨 짚는 접근을 찾아내는 배열 범위 검사기입니다. 나온 지 얼마 되지 않은 도구이며, 여전히 시험판으로 간주하므로 다른 도구에 비해 (잘못된) 거짓 양성 결과가 나올 수 있습니다.

note: (itstool) path: section/p
en: As it is experimental, sgcheck must be run by passing <cmd>--tool=exp-sgcheck</cmd> to Valgrind, rather than <cmd>--tool=sgcheck</cmd>.
ko: 시험판이므로 Valgrind에 <cmd>--tool=sgcheck</cmd>가 아닌, <cmd>--tool=exp-sgcheck</cmd> 매개 변수를 전달하여 실행해야합니다.

note: (itstool) path: section/p
en: A full tutorial on using sgcheck is <link href="http://valgrind.org/docs/manual/sg-manual.html">here</link>.
ko: 완전한 sgcheck 사용 지침은 <link href="http://valgrind.org/docs/manual/sg-manual.html">여기에 있습니다</link>.

note: (itstool) path: section/title
en: gcov and lcov
ko: gcov 및 lcov

note: (itstool) path: section/p
en: <link href="https://gcc.gnu.org/onlinedocs/gcc/Gcov.html">gcov</link> is a profiling tool built into GCC, which instruments code by adding extra instructions at compile time. When the program is run, this code generates <file>.gcda</file> and <file>.gcno</file> profiling output files. These files can be analyzed by the <cmd>lcov</cmd> tool, which generates visual reports of code coverage at runtime, highlighting lines of code in the project which are run more than others.
ko: <link href="https://gcc.gnu.org/onlinedocs/gcc/Gcov.html">gcov</link>는 GCC로 빌드한 프로파일링 도구이며, 컴파일 시간의 추가 코드를 넣어 코드를 분석합니다. 이 프로그램을 실행할 때, 코드에서 <file>.gcda</file> 와 <file>.gcno</file> 프로파일링 출력 파일이 나옵니다. 이 파일은 코드 실행 영역의 실행 시간 시각 보고서, 다른 곳에서보단 프로젝트에서 더 많이 실행하는 코드의 줄을 강조하는 <cmd>lcov</cmd> 도구로 분석할 수 있습니다.

note: (itstool) path: section/p
en: A critical use for this code coverage data collection is when running the unit tests: if the amount of code covered (for example, which particular lines were run) by the unit tests is known, it can be used to guide further expansion of the unit tests. By regularly checking the code coverage attained by the unit tests, and expanding them towards 100%, you can be sure that the entire project is being tested. Often it is the case that a unit test exercises most of the code, but not a particular control flow path, which then harbours residual bugs.
ko: 코드 범위 데이터 수집의 결정적인 사용은 단위 테스트를 수행할 때입니다. 단위 테스트로 상당히 많은 범위의 코드(어떤 줄을 실행했는지?)를 안다면 단위 테스트 범위 확장을 이끄는데 사용할 수 있습니다. 보통 단위 테스트로 얻어낸 코드 범위를 검사하고, 검사 범위가 100%에 가깝게 도달하면 전체 프로젝트를 테스트했다고 봐도 됩니다. 종종, 단위 테스트는 대분의 코드를 시험해보지만, 일부 제어문을 테스트하지 않으므로 일부 버그가 남아있을 수 있습니다.

note: (itstool) path: section/p
en: lcov supports <link href="http://en.wikipedia.org/wiki/Code_coverage#Basic_coverage_criteria"> branch coverage measurement</link>, so is not suitable for demonstrating coverage of safety critical code. It is perfectly suitable for non-safety critical code.
ko: lcov는 <link href="http://en.wikipedia.org/wiki/Code_coverage#Basic_coverage_criteria">분기분 범위 측정</link>을 지원하여, 안정성이 중요한 코드 범위 시험에는 적절치 않습니다. 불안정 중대 코드에 안성맞춤입니다.

note: (itstool) path: section/p
en: As code coverage has to be enabled at both compile time and run time, a macro is provided to make things simpler. The <link href="http://www.gnu.org/software/autoconf-archive/ax_code_coverage.html"> <code>AX_CODE_COVERAGE</code></link> macro adds a <cmd>make check-code-coverage</cmd> target to the build system, which runs the unit tests with code coverage enabled, and generates a report using <cmd>lcov</cmd>.
ko: 컴파일 시간 및 실행 시간에 코드 범위를 활성화하면, 제공한 메크로로 단순하게 처리할 수 있습니다. <link href="http://www.gnu.org/software/autoconf-archive/ax_code_coverage.html"> <code>AX_CODE_COVERAGE</code></link> 매크로는 빌드 시스템에 <cmd>make check-code-coverage</cmd> 타겟을 추가하여 코드 범위 활성화 후 단위 테스트를 진행하며 <cmd>lcov</cmd> 명령으로 보고서를 만듭니다.

note: (itstool) path: section/p
en: To add <code>AX_CODE_COVERAGE</code> support to a project:
ko: 프로젝트에 <code>AX_CODE_COVERAGE</code> 지원을 추가하려면:

note: (itstool) path: item/p
en: Copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_code_coverage.m4"> <file>ax_code_coverage.m4</file></link> to the <file>m4/</file> directory of your project.
ko: <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_code_coverage.m4"> <file>ax_code_coverage.m4</file></link> 파일을 프로젝트의 <file>m4/</file> 디렉터리에 복사하십시오.

note: (itstool) path: item/p
en: Add <code>AX_CODE_COVERAGE</code> to <file>configure.ac</file>.
ko: <file>configure.ac</file> 파일에 <code>AX_CODE_COVERAGE</code>를 추가하십시오.

note: (itstool) path: item/p
en: Add <code>@CODE_COVERAGE_RULES</code> to the top-level <file>Makefile.am</file>.
ko: 최상위 <file>Makefile.am</file> 파일에  <code>@CODE_COVERAGE_RULES</code>를 추가하십시오.

note: (itstool) path: item/p
en: Add <code>$(CODE_COVERAGE_CFLAGS)</code> to the automake <code><var>*</var>_CFLAGS</code> variable for each target you want coverage for, for example for all libraries but no unit test code. Do the same for <code>$(CODE_COVERAGE_LDFLAGS)</code> and <code><var>*</var>_LDFLAGS</code>.
ko: 예를 들어 모든 라이브러리를 대상으로 하지만 코드 단위 테스트를 수행하지 않는다면, 원하는 각 범위를 대상으로 automake의 <code><var>*</var>_CFLAGS</code> 변수에 <code>$(CODE_COVERAGE_CFLAGS)</code>를 추가하십시오. <code>$(CODE_COVERAGE_LDFLAGS)</code> 와 <code><var>*</var>_LDFLAGS</code>도 똑같이 처리하십시오.

note: (itstool) path: section/p
en: Documentation on using gcov and lcov is <link href="http://ltp.sourceforge.net/coverage/lcov.php">here</link>.
ko: gcov 및 lcov 문서는 <link href="http://ltp.sourceforge.net/coverage/lcov.php">여기에 있습니다</link>.

note: (itstool) path: section/title
en: Address, Thread and Undefined Behavior Sanitizers
ko: 주소, 스레드 및 비정의 동작 정리 프로그램

note: (itstool) path: section/p
en: GCC and Clang both support several sanitizers: sets of extra code and checks which can be optionally compiled in to an application and used to flag various incorrect behaviors at runtime. They are powerful tools, but have to be enabled specially, recompiling your application to enable and disable them. They cannot be enabled at the same time as each other, or used at the same time as <link xref="#valgrind">Valgrind</link>. They are still young, so have little integration with other tooling.
ko: GCC와 Clang에서는 여러가지 정리기가 있습니다. 실행 시간에 추가 코드를 설정하여 프로그램에 추가로 컴파일할 부분을 검사하며, 여러가지 잘못된 동작의 플래그를 설정합니다. 강력하지만, 프로그램을 다시 컴파일할 때 이런 기능을 활성화/비활성화하려면 특히 활성화해야합니다. 여러가지를 동시에 활성화하거나 <link xref="#valgrind">Valgrind</link>와 같은 도구를 동시에 활용할 수 없습니다. 아직 나온 지 얼마 안됐기 때문에 다른 도구와의 집약도가 낮습니다.

note: (itstool) path: section/p
en: All sanitizers are available for both GCC and Clang, accepting the same set of compiler options.
ko: GCC와 Clang에서는 동일한 여러 컴파일러 옵션을 수용하는 모든 정리 프로그램이 있습니다.

note: (itstool) path: section/title
en: Address Sanitizer
ko: 주소 정리기

note: (itstool) path: section/p
en: The <link href="https://code.google.com/p/address-sanitizer/">address sanitizer</link> (‘asan’) detects use-after-free and buffer overflow bugs in C and C++ programs. A full tutorial on using asan is <link href="http://clang.llvm.org/docs/AddressSanitizer.html#usage">available for Clang</link> — the same instructions should work for GCC.
ko: <link href="https://code.google.com/p/address-sanitizer/">address sanitizer</link>(‘asan’)은 C와 C++ 프로그램에서 메모리 할당 해제 후 사용 및 버퍼 오버플로우 버그를 찾습니다. 완전한 asan 사용 지침서는 <link href="http://clang.llvm.org/docs/AddressSanitizer.html#usage">Clang용으로 있습니다</link>만, GCC 용은 아직 작업중입니다.

note: (itstool) path: section/title
en: Thread Sanitizer
ko: 스레드 정리기

note: (itstool) path: section/p
en: The <link href="https://code.google.com/p/thread-sanitizer/">thread sanitizer</link> (‘tsan’) detects data races on memory locations, plus a variety of invalid uses of POSIX threading APIs. A full tutorial on using tsan is <link href="http://clang.llvm.org/docs/ThreadSanitizer.html#usage">available for Clang</link> — the same instructions should work for GCC.
ko: <link href="https://code.google.com/p/thread-sanitizer/">thread sanitizer</link>(‘tsan’)은 메모리 할당시 급하게 데이터를 넣는 코드와, POSIX 스레드 처리 API의 광범위한 오용 사례를 찾습니다. 완전한 tsan 사용 지침서는 <link href="http://clang.llvm.org/docs/ThreadSanitizer.html#usage">Clang용으로 있습니다</link>만, GCC 용은 아직 작업중입니다.

note: (itstool) path: section/title
en: Undefined Behavior Sanitizer
ko: 비정의 동작 정리기

note: (itstool) path: section/p
en: The undefined behavior sanitizer (‘ubsan’) is a collection of smaller instrumentations which detect various potentially undefined behaviors in C programs. A set of instructions for enabling ubsan is <link href="http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation">available for Clang</link> — the same instructions should work for GCC.
ko: undefined behavior sanitizer (‘ubsan’)은 C 프로그램에서 잠재적으로 정의하지 않은 여러가지 동작을 찾아내는 작은 진단 프로그램 모음입니다. ubsan 활성화 방법 모음은 <link href="http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation">Clang용으로 있습니다</link>만, GCC 용은 아직 작업중입니다.

note: (itstool) path: section/p
en: <link href="http://scan.coverity.com/">Coverity</link> is one of the most popular and biggest commercial static analyzer tools available. However, it is available to use free for Open Source projects, and any project is encouraged to <link href="https://scan.coverity.com/users/sign_up">sign up</link>. <link href="https://scan.coverity.com/faq#how-get-project-included-in-scan"> Analysis is performed</link> by running some analysis tools locally, then uploading the source code and results as a tarball to Coverity’s site. The results are then visible online to members of the project, as annotations on the project’s source code (similarly to how lcov presents its results).
ko: <link href="http://scan.coverity.com/">Coverity</link>는 현존하는 상업용 정적 분석 도구 중 가장 유명하고 규모가 큰 도구 중 하나입니다. 그러나 오픈 소스 프로젝트에서 무료로 쓸 수 있으며, 어떤 프로젝트의 경우 <link href="https://scan.coverity.com/users/sign_up">가입</link>하는게 좋습니다. 자체적으로 일부 분석 도구를 실행하여 <link href="https://scan.coverity.com/faq#how-get-project-included-in-scan">분석을 진행</link>하며, Coverity 사이트에 소스 코드를 업로드한 후 타르볼 결과를 가져옵니다. 프로젝트 참여 구성원은 결과를 프로젝트 소스코드의 주석 형식(lcov에서 결과를 보여주는 방식과 비슷)으로 온라인으로 볼 수 있습니다.

note: (itstool) path: section/p
en: As Coverity cannot be run entirely locally, it cannot be integrated properly into the build system. However, scripts do exist to automatically scan a project and upload the tarball to Coverity regularly. The recommended approach is to run these scripts regularly on a server (typically as a cronjob), using a clean checkout of the project’s git repository. Coverity automatically e-mails project members about new static analysis problems it finds, so the same approach as for <link xref="#gcc-and-clang">compiler warnings</link> can be taken: eliminate all the static analysis warnings, then eliminate new ones as they are detected.
ko: Coverity는 로컬에서만 실행할 수는 없으며 빌드 시스템에 제대로 붙일 수 없습니다. 허나, 정기적으로 프로젝트를 자동으로 검사하고 타르볼로 압축하여 Coverity로 업로드하는 스크립트는 있습니다. 추천 방식은 프로젝트 git 저장소를 온전히 체크아웃하는 스크립트를 서버에서 주기적(보통 cronjob 방식)으로 실행하는 방식입니다. Coverity는 새 정적 분석 문제를 프로젝트 구성원에게 전자메일로 알려주어 <link xref="#gcc-and-clang">컴파일러 경고</link> 정보를 얻을 수 있습니다: 모든 정적 분석 경고를 하나하나 없앤 후, 새로 나타나는 경고를 하나하나 처리해나가십시오.

note: (itstool) path: section/p
en: Coverity is good, but it is not perfect, and it does produce a number of false positives. These should be marked as ignored in the online interface.
ko: Coverity는 우수하지만 완벽하진 않으며 거짓 양성 결과가 많이 나옵니다. 이 결과는 온라인 인터페이스에서 무시해야합니다.

note: (itstool) path: section/title
en: Clang Static Analyzer
ko: Clang 정적 분석기

note: (itstool) path: section/p
en: One tool which can be used to perform static analysis locally is the <link href="http://clang-analyzer.llvm.org/">Clang static analyzer</link>, which is a tool co-developed with the <link xref="#gcc-and-clang">Clang compiler</link>. It detects a variety of problems in C code which compilers cannot, and which would otherwise only be detectable at run time (using unit tests).
ko: 자체적으로 정적 분석을 수행할 때 사용할 수 있는 도구는 <link xref="#gcc-and-clang">Clang 컴파일러</link>와 개발한 <link href="http://clang-analyzer.llvm.org/">Clang 정적 분석기</link>입니다. 컴파일러가 찾을 수 없어 실행 시간에만 (단위 테스트로) 찾아낼 수 있는 C 코드의 다양한 문제를 찾아냅니다.

note: (itstool) path: section/p
en: Clang produces some false positives, and there is no easy way to ignore them. The recommended thing to do is to <link href="http://clang-analyzer.llvm.org/faq.html#suppress_issue">file a bug report against the static analyzer</link>, so that the false positive can be fixed in future.
ko: Clang은 일부 거짓 양성 결과를 내며, 이 결과를 무시할 간편한 방법이 없습니다. 거짓 양성 출력을 수정할 수 있게 <link href="http://clang-analyzer.llvm.org/faq.html#suppress_issue">정적 분석기 버그를 보고</link>하는 방안을 추천합니다.

note: (itstool) path: section/p
en: A full tutorial on using Clang is <link href="http://clang-analyzer.llvm.org/scan-build.html">here</link>.
ko: Clang 사용법 완벽 안내서는 <link href="http://clang-analyzer.llvm.org/scan-build.html">여기</link>에 있습니다.

note: (itstool) path: section/p
en: However, for all the power of the Clang static analyzer, it cannot detect problems with specific libraries, such as GLib. This is a problem if a project uses GLib exclusively, and rarely uses POSIX APIs (which Clang does understand). There is a plugin available for the Clang static analyzer, called <link href="http://people.collabora.com/~pwith/tartan/">Tartan</link>, which extends Clang to support checks against some of the common GLib APIs.
ko: 그러나, Clang 정적 분석기의 모든 역량을 위해서라면, GLib 같은 일부 라이브러리의 문제를 찾을 수 없습니다. 프로젝트가 GLib만을 사용하거나 (Clang이 이해하는) POSIX API를 적게 활용한다면 문제가 됩니다. Clang 정적 분석기에 맞춰서 일반 GLib API 일부 사용 검사를 지원하도록 Clang 기능을 확장하는데 쓸 수 있는 <link href="http://people.collabora.com/~pwith/tartan/">Tartan</link> 플러그인이 있습니다.

note: (itstool) path: section/p
en: Tartan is still young software, and will produce false positives and may crash when run on some code. However, it can find legitimate bugs quite quickly, and is worth running over a code base frequently to detect new errors in the use of GLib in the code. Please <link href="http://people.collabora.com/~pwith/tartan/#troubleshooting"> report any problems with Tartan</link>.
ko: Tartan은 나타난 지 얼마 안된 프로그램이며, 거짓 양성 결과를 내기도 하고, 일부 코드에서 실행할 때 갑작스럽게 끝나는 경우가 있습니다. 그러나 적절한 버그를 좀 빨리 찾을 수 있으며, 코드에서 GLib를 사용할 때 새 오류를 찾아내려는 목적으로 코드 기반을 자주 실행할 때 쓸 만합니다. <link href="http://people.collabora.com/~pwith/tartan/#troubleshooting">Tartan 사용 중 나타나는 문제를 알려주십시오</link>.

note: (itstool) path: section/p
en: A full tutorial on enabling Tartan for use with the Clang static analyzer is <link href="http://people.collabora.com/~pwith/tartan/#usage-standalone"> here</link>. If set up correctly, the output from Tartan will be mixed together with the normal static analyzer output.
ko: Clang 정적 분석기와 Tartan을 사용하는 완벽 지침서는 <link href="http://people.collabora.com/~pwith/tartan/#usage-standalone">여기에 있습니다</link>. 올바르게 설치했다면, 일밭 정적 분석기 출력과 Tartan 출력이 섞여서 나옵니다.

note: (itstool) path: info/desc
en: Designing software to be tested and writing unit tests for it
ko: 테스트할 프로그램을 설계하고 프로그램에 맞는 단위 테스트를 작성합니다

note: (itstool) path: page/title
en: Unit Testing
ko: 단위 테스트

note: (itstool) path: synopsis/p
en: Unit testing should be the primary method of testing the bulk of code written, because a unit test can be written once and run many times — manual tests have to be planned once and then manually run each time.
ko: 단위 테스트는 상당한 양의 작성 코드를 테스트하는 근본 방식이어야 하는데, 단위 테스트는 한번 작성하고 여러번 실행하기 때문입니다. 직접 작성한 테스트 코드는 한번 계획하고 직접 여러번 실행해야합니다.

note: (itstool) path: synopsis/p
en: Development of unit tests starts with the architecture and API design of the code to be tested: code should be designed to be easily testable, or will potentially be very difficult to test.
ko: 단위 테스트 개발은 테스트할 코드의 구조와 API 설계로 시작합니다. 코드는 쉽게 테스트 할 수 있도록 설계해야 합니다. 그렇지 않으면 잠재적으로 테스트하기 매우 어려워집니다.

note: (itstool) path: item/p
en: Write unit tests to be as small as possible, but no smaller. (<link xref="#writing-unit-tests"/>)
ko: 단위 테스트는 최대한 작게 작성하지만, 더 작게 작성하지 않습니다(<link xref="#writing-unit-tests"/>).

note: (itstool) path: item/p
en: Use code coverage tools to write tests to get high code coverage. (<link xref="#writing-unit-tests"/>)
ko: 코드 범위를 최대한 할당하는 테스트를 작성하려면 코드 범위 도구를 사용하십시오(<link xref="#writing-unit-tests"/>).

note: (itstool) path: item/p
en: Run all unit tests under Valgrind to check for leaks and other problems. (<link xref="#leak-checking"/>)
ko: 메모리 누수 현상 및 다른 문제를 확인하려면 모든 단위 테스트를 Valgrind에서 실행하십시오(<link xref="#leak-checking"/>).

note: (itstool) path: item/p
en: Use appropriate tools to automatically generate unit tests where possible. (<link xref="#test-generation"/>)
ko: 가능하다면 단위 테스트를 자동으로 만드는 적당한 도구를 사용하십시오(<link xref="#test-generation"/>).

note: (itstool) path: item/p
en: Design code to be testable from the beginning. (<link xref="#writing-testable-code"/>)
ko: 시작할 때부터 테스트할 수 있는 코드로 설계하십시오(<link xref="#writing-testable-code"/>).

note: (itstool) path: section/title
en: Writing Unit Tests
ko: 단위 테스트 코드 작성

note: (itstool) path: section/p
en: Unit tests should be written in conjunction with looking at <link xref="tooling#gcov-and-lcov">code coverage information gained from running the tests</link>. This typically means writing an initial set of unit tests, running them to get coverage data, then reworking and expanding them to increase the code coverage levels. Coverage should be increased first by ensuring all functions are covered (at least in part), and then by ensuring all lines of code are covered. By covering functions first, API problems which will prevent effective testing can be found quickly. These typically manifest as internal functions which cannot easily be called from unit tests. Overall, coverage levels of over 90% should be aimed for; don’t just test cases covered by project requirements, test everything.
ko: <link xref="tooling#gcov-and-lcov">테스트를 실행하면서 코드 영역에서 수집하는 정보</link>를 찾으면서 단위 테스트를 작성해야합니다. 보통 단위 테스트 초기 집합을 작성하고, 실행하여 해당 범위의 데이터를 얻어내며, 코드 영역 수준을 넓혀가며 다시 작업 함을 의미합니다. 영역은 우선적으로 (최소한 일부 영역에서) 모든 함수를 다루는지 확인하고, 코드의 모든 줄을 다루는지 확인하여 영역을 넓혀야합니다. 우선적으로 함수를 다루면, 영향을 주는 테스트를 방해하는 API의 문제를 빨리 찾아낼 수 있습니다. 이 방식으로 단위 테스트에서 쉽게 호출할 수 없는 자체 함수를 나타냅니다. 총체적으로 말하자면, 90% 이상의 범위 수준을 대상으로 해야 합니다. 프로젝트 요구사항에서 다루는 케이스만 테스트하지 마십시오. 모두 테스트하십시오.

note: (itstool) path: section/p
en: Like <link xref="version-control">git commits</link>, each unit test should be ‘as small as possible, but no smaller’, testing a single specific API or behavior. Each test case must be able to be run individually, without depending on state from other test cases. This is important to allow debugging of a single failing test, without having to step through all the other test code as well. It also means that a single test failure can easily be traced back to a specific API, rather than a generic ‘unit tests failed somewhere’ message.
ko: <link xref="version-control">git 커밋</link>과 마찬가지로, 단일 개별 API또는 동작을 테스트할 때, 각각의 단위 테스트는 ‘가능한 한 작게, 그러나 더 작지는 않’아야합니다. 각 테스트 케이스는 기타 테스트 케이스의 상태와는 상관 없이 개별적으로 실행할 수 있어야합니다. 다른 모든 테스트 코드와 마찬가지로 어떤 절차 없이 단일 실패 테스트를 디버깅할 수 있게 하려면 이 점이 중요합니다. 또한, 단일 테스트 실패로 하여금 상투적으로 ‘어딘가에서 단위 테스트에 실패했습니다’ 같은 메시지를 출력하기보단, 개별 API를 역추적할 수 있다는 의미이기도 합니다.

note: (itstool) path: section/p
en: GLib has support for unit testing with its <link href="https://developer.gnome.org/glib/stable/glib-Testing.html">GTest framework</link>, allowing tests to be arranged in groups and hierarchies. This means that groups of related tests can be run together for enhanced debugging too, by running the test binary with the <cmd>-p</cmd> argument: <cmd>./test-suite-name -p /path/to/test/group</cmd>.
ko: GLib은 그룹, 계층별로 테스트를 수행할 수 있는 <link href="https://developer.gnome.org/glib/stable/glib-Testing.html">GTest 프레임워크</link> 단위 테스트를 지원합니다. <cmd>./test-suite-name -p /path/to/test/group</cmd> 명령과 같이 테스트 이진 파일에 <cmd>-p</cmd> 인자를 추가하여 고급 디버깅을 목적으로 관련 그룹 테스트를 함께 실행할 수 있음을 의미합니다.

note: (itstool) path: section/title
en: Installed Tests
ko: 설치한 테스트

note: (itstool) path: section/p
en: All unit tests should be installed system-wide, following the <link href="https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests">installed-tests standard</link>.
ko: 모든 단위 테스트는 <link href="https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests">installed-tests 표준</link>에 따라, 시스템 영역에 걸쳐 설치해야 합니다.

note: (itstool) path: section/p
en: By installing the unit tests, continuous integration (CI) is made easier, since tests for one project can be re-run after changes to other projects in the CI environment, thus testing the interfaces between modules. That is useful for a highly-coupled set of projects like GNOME.
ko: 단위 테스트를 설치하면, 단위 통합(CI)이 쉬워지는데, CI 환경에서 어떤 프로젝트의 테스트는 다른 프로젝트로 바뀌고 나서도 다시 실행할 수 있기에 모듈간 인터페이스를 테스트합니다. 이는 그놈처럼 프로젝트간 강결합을 이룬 상황에 유용합니다.

note: (itstool) path: section/p
en: To add support for installed-tests, add the following to <file>configure.ac</file>:
ko: installed-tests 지원을 추가하려면 <file>configure.ac</file>에 다음 내용을 추가하십시오:

note: (itstool) path: section/p
en: Then in <file>tests/Makefile.am</file>:
ko: 그 다음 <file>tests/Makefile.am</file>에 다음 내용을 추가하십시오:

note: (itstool) path: section/title
en: Leak Checking
ko: 메모리 누수 검사

note: (itstool) path: section/p
en: Once unit tests with high code coverage have been written, they can be run under various dynamic analysis tools, such as <link xref="tooling#valgrind">Valgrind</link> to check for leaks, threading errors, allocation problems, etc. across the entire code base. The higher the code coverage of the unit tests, the more confidence the Valgrind results can be treated with. See <link xref="tooling"/> for more information, including build system integration instructions.
ko: 광범위한 코드 영역을 다루는 단위 테스트를 작성하고 나면, <link xref="tooling#valgrind">Valgrind</link>와 같이 메모리 누수, 스레드 오류, 할당 문제 등 전체 코드 영역을 검사하는 다양한 동적 분석 도구에서 실행할 수 있습니다. 단위 테스트에서 다루는 코드 영역이 더 커지면, Valgrind 결과에 대해 더한 신뢰감이 있을 수 있습니다. 자세히 알아보려면 빌드 시스템 통합 방식 내용이 함께 들어있는 <link xref="tooling"/>을 참고하십시오.

note: (itstool) path: section/p
en: Critically, this means that unit tests should not leak memory or other resources themselves, and similarly should not have any threading problems. Any such problems would effectively be false positives in the analysis of the actual project code. (False positives which need to be fixed by fixing the unit tests.)
ko: 진지하게 말하자면,  단위 테스트에서 메모리나 기타 자원이 정리가 되지 않는 현상이 있어서는 안되며, 이와 비슷하게 스레드 처리 문제가 있어서도 안된다는 의미입니다. 어떤 문제의 경우 실제 프로젝트 코드를 분석할 때 거짓양성이 나타날 수 있습니다(거짓 양성은 굳이 단위 테스트를 수정하여 문제를 고칠 필요가 없습니다).

note: (itstool) path: section/title
en: Test Generation
ko: 테스트 만들기

note: (itstool) path: section/p
en: Certain types of code are quite repetitive, and require a lot of unit tests to gain good coverage; but are appropriate for <link href="http://en.wikipedia.org/wiki/Test_data_generation">test data generation</link>, where a tool is used to automatically generate test vectors for the code. This can drastically reduce the time needed for writing unit tests, for code in these specific domains.
ko: 코드의 제각각의 양상을 보자면 조금 반복적인 부분이 있으며, 바람직한 영역 범위를 다루려면 더 많은 테스트 단위가 필요합니다. 그러나 코드 테스트 벡터를 자동으로 만들 때 활용하는 도구가 있다면, <link href="http://en.wikipedia.org/wiki/Test_data_generation">테스트 데이터 생성</link>에 적합합니다. 특정 영역의 코드에 대해 단위 데스트를 작성할 때 필요한 시간을 획기적으로 줄일 수 있습니다.

note: (itstool) path: section/p
en: One example of a domain amenable to test data generation is parsing, where the data to be parsed is required to follow a strict schema — this is the case for XML and JSON documents. For JSON, a tool such as <link href="http://people.collabora.com/~pwith/walbottle/">Walbottle</link> can be used to generate test vectors for all types of valid and invalid input according to the schema.
ko: 데이터 생성 시험시 도메인을 잘 이해할 수 있는 예제는 규정된 양식(schema)을 따라 데이터를 해석하는 파싱을 들 수 있습니다. XML과 JSON 문서의 경우를 이야기합니다. <link href="http://people.collabora.com/~pwith/walbottle/">Walbottle</link>과 같은 JSON 도구는 양식(schema)에 따라 올바른 또는 올바르지 않은 모든 형식의 테스트 벡터를 만들 때 사용할 수 있습니다.

note: (itstool) path: section/p
en: Every type of JSON document should have a <link href="http://json-schema.org/">JSON Schema</link> defined for it, which can then be passed to Walbottle to generate test vectors:
ko: JSON 문서의 모든 형식은, 테스트 벡터를 만드는 Warbottle에 전달할 수 있는 JSON 문서 형식을 정의하는 <link href="http://json-schema.org/">JSON 양식(schema)</link>이 있습니다:

note: (itstool) path: section/p
en: These test vectors can then be passed to the code under test in its unit tests. The JSON instances generated by <cmd>--valid-only</cmd> should be accepted; those from <cmd>--invalid-only</cmd> should be rejected.
ko: 이 테스트 벡터는 단위 테스트에서 테스트하는 코드에 전달할 수 있습니다. <cmd>--valid-only</cmd>로 만든 JSON 인스턴스는 테스트를 통과해야합니다. 반면에 <cmd>--invalid-only</cmd>로 만든 JSON 인스턴스는 테스트를 통과하지 말아야합니다.

note: (itstool) path: section/title
en: Writing Testable Code
ko: 테스트 가능 코드 작성

note: (itstool) path: section/p
en: Code should be written with testability in mind from the design stage, as it affects API design and architecture in fundamental ways. A few key principles:
ko: 코드는 API 설계 및 아키텍처에 근본적인 방식으로 영향을 주므로 설계 단계 때부터 테스트가 가능하도록 작성해야합니다. 몇가지 핵심 원칙이 있습니다:

note: (itstool) path: item/p
en: Do not use global state. Singleton objects are usually a bad idea as they can’t be instantiated separately or controlled in the unit tests.
ko: 전역 상태를 활용하지 마십시오. 싱글톤 객체는 단위 테스트를 수행할 때 따로 초기화하고 다룰 수 없기에 보통 좋지 않습니다.

note: (itstool) path: item/p
en: Separate out use of external state, such as databases, networking, or the file system. The unit tests can then replace the accesses to external state with mocked objects. A common approach to this is to use dependency injection to pass a file system wrapper object to the code under test. For example, a class should not load a global database (from a fixed location in the file system) because the unit tests would then potentially overwrite the running system’s copy of the database, and could never be executed in parallel. They should be passed an object which provides an interface to the database: in a production system, this would be a thin wrapper around the database API; for testing, it would be a mock object which checks the requests given to it and returns hard-coded responses for various tests.
ko: 데이터베이스, 네트워크, 파일 시스템의 외부 상태를 활용하는 경우 따로 분리하십시오. 이렇게 해야 단위 테스트에서 가정 객체로 외부 상태에 접근하도록 할 수 있습니다. 일반적 접근 방식으로는 테스트를 진행하는 동안 코드에 파일 시스템 래퍼 객체를 전달할 때 독립 인젝션 기법을 활용합니다. 예를 들어 클래스는 전역 데이터베이스(파일 시스템의 고정 지정 위치)를 불러오면 안되는데, 단위 테스트 수행 시 동작중인 시스템의 데이터베이스 사본을 덮어쓸 가능성이 있기 대문이며, 때문에 동시에 실행할 수 없습니다. 객체를 전달하려면 제공 데이터베이스 인터페이스로 해야 하는데, 실 운용 시스템에서는 데이터베이스 API의 씬 래퍼가 되겠습니다. 테스트를 할 때는, 객체 자신을 검사하며, 다양한 테스트에 대해 하드코딩 요청한 결과를 반환하는 모크 객체가 됩니다.

note: (itstool) path: item/p
en: Expose utility functions where they might be generally useful.
ko: 범용적으로 쓸 만한 유틸리티 함수는 노출하십시오.

note: (itstool) path: item/p
en: Split projects up into collections of small, private libraries which are then linked together with a minimal amount of glue code into the overall executable. Each can be tested separately.
ko: 최소한의 연결 코드를 전체 실행 프로그램으로 링크하게 하여 제각각 테스트할 수 있게 작은, 개별 라이브러리 모음으로 프로젝트를 나누십시오.

note: (itstool) path: section/p
en: The topic of software testability is covered in the following articles:
ko: 아래에 프로그램 테스트 가능성 주제를 다룬 글을 모아두었습니다:

note: (itstool) path: info/desc
en: Source code version control with git
ko: git으로 소스 코드 버전 관리하기

note: (itstool) path: page/title
en: Version Control
ko: 버전 관리

note: (itstool) path: synopsis/p
en: git is used for version control for all GNOME projects. This page assumes good working knowledge of git; some introductory material is available <link href="https://www.atlassian.com/git/tutorials/">here</link>, and a <link href="https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf">git cheatsheet is here</link>.
ko: 모든 그놈 프로젝트의 버전 관리에 git을 사용합니다. 이 페이지에서는 독자 여러분이 적절한 git 활용 지식을 갖추고 있다고 간주합니다. 일부 기초 자료는 <link href="https://www.atlassian.com/git/tutorials/">여기</link>에 있고, <link href="https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf">git 간편 길잡이는 이곳에 있습니다</link>.

note: (itstool) path: item/p
en: Make atomic, revertable commits. (<link xref="#guidelines-for-making-commits"/>)
ko: 최소화 한, 복원 가능한 커밋을 만드십시오(<link xref="#guidelines-for-making-commits"/>).

note: (itstool) path: item/p
en: Include full reasoning in commit messages, plus links to relevant bug reports or specifications. (<link xref="#guidelines-for-making-commits"/>)
ko: 커밋 메시지에 완전한 근거와 관련 버그 보고서, 명세 링크를 추가하십시오(<link xref="#guidelines-for-making-commits"/>).

note: (itstool) path: item/p
en: Keep large changes, such as renames, in separate commits. (<link xref="#guidelines-for-making-commits"/>)
ko: 이름 바꾸기 같은 규모가 큰 변경 이력은 커밋을 따로 분리하십시오(<link xref="#guidelines-for-making-commits"/>).

note: (itstool) path: item/p
en: Merge changes from feature branches by rebasing. (<link xref="#use-of-git"/>)
ko: 기능 브랜치에서 리베이스 처리하여 변경 사항을 병합하십시오(<link xref="#use-of-git"/>).

note: (itstool) path: section/title
en: Use of Git
ko: git 사용

note: (itstool) path: section/p
en: Most GNOME repositories follow these rules:
ko: 대부분 그놈 저장소에서는 다음 규칙을 따릅니다:

note: (itstool) path: item/p
en: No forced pushes. Except for branches with the <code>wip/</code> prefix (work-in-progress), the commits’ history must not be modified, as contributors rely on it.
ko: 강제 푸쉬를 하지 않습니다. <code>wip/</code> 접두부(work-in-progress)가 붙어있는 브랜치를 제외하고, 기여자가 의존하는 커밋 이력 정보는 수정하면 안됩니다.

note: (itstool) path: item/p
en: Rebase commits rather than merging, to have a linear history (which is easier to follow).
ko: 커밋을 병합하기 보단 리베이스 처리하여, 선형 내역을 만드십시오(흐름을 살펴보기 쉽습니다).

note: (itstool) path: item/p
en: Work on feature branches on GNOME git in <code>wip/</code> branches, then rebase on master and fast-forward merge the changes. It is a good practice to also add your nickname to the branch name, as <code>wip/nickname/feature</code>.
ko: <code>wip/</code> 브랜치에 있는 그놈 git의 기능 브랜치에서 작업한 다음, 마스터 브랜치에서 리베이스를 수행하고, 변경 사항을 진행 정방향으로 병합하십시오. <code>wip/nickname/feature</code>와 같이 브랜치 이름에 여러분의 별명을 넣는 방식도 좋습니다.

note: (itstool) path: item/p
en: Hide <link href="https://sethrobertson.github.io/GitBestPractices/#sausage">sausage making</link> by squashing commits before merging.
ko: 병합 처리 전 커밋을 합쳐서 <link href="https://sethrobertson.github.io/GitBestPractices/#sausage">줄줄이 형상</link>을 숨기십시오.

note: (itstool) path: section/title
en: Guidelines for Making Commits
ko: 커밋 지침

note: (itstool) path: section/p
en: Commits should be as small as possible, but no smaller. Each commit should address a single issue, containing only changes related to that issue. The message for each commit should describe the issue, explain what causes it, and explain how it has been fixed if it is not obvious. If the commit is associated with a bug report, the full URI for the bug report should be put on a line by itself at the bottom of the commit message. Similarly, the ID for the git commit (from <cmd>git log --oneline</cmd>) should be copied into the bug report once the commit has been pushed, so it is easy to find one from the other.
ko: 커밋은 최대한 작아야 하지만, 그렇다고 더 작아선 안됩니다. 각각의 커밋은 단일 문제를 해결해야 하며, 문제에 대해 바꾼 내용만 들어있어야 합니다. 각각의 커밋의 메시지에는 문제를 설명하고, 어디서 문제가 생겼는지, 수정 사항이 분명하지 않다면 어떻게 수정했는지 설명해야합니다. 커밋이 버그 보고서와 관련있을 경우 버그 보고서의 전체 URI를 커밋 보고서의 가장 윗 부분에 넣어야합니다. 동일하게 git commit의 ID(<cmd>git log --oneline</cmd>)를 커밋을 푸시한 버그 보고서에 복사하여 다른 사람이 쉽게 찾아볼 수 있도록 해야합니다.

note: (itstool) path: section/p
en: The changes in each commit should be easy to read. For example, they should not unnecessarily change whitespace or indentation. Large, mechanical changes, such as renaming a file or function, should be put in separate commits from modifications to code inside that file or function, so that the latter changes do not get buried and lost in the former.
ko: 각 커밋에서 바뀐 내용은 쉽게 알아볼 수 있어야합니다. 예를 들어 불필요한 공백 내지는 들여쓰기 같은 내용이 있어서는 안됩니다. 파일 또는 함수의 이름을 바꾼다거나 하는식으로 기술적으로 바뀐 경우 파일 또는 함수에서 바꾼 내용과는 커밋을 별도로 나누어서 이전에 작업한 내용이 어딘가에 파묻히거나 없어지지 않게 해야합니다.

note: (itstool) path: section/p
en: The following principles give the reasoning for all the advice above:
ko: 다음 몇가지 원칙은 위에서 제시한 권고의 이유입니다:

note: (itstool) path: item/p
en: Each commit should take the repository from one working state to another, otherwise <link href="http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git#Binary-Search">bisection</link> is impossible.
ko: 각 커밋에서 저장소의 어떤 작업 상태를 다른 작업 상태로 전환해야 하며, 그렇지 않으면 <link href="http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git#Binary-Search">바이섹션</link>이 불가능합니다.

note: (itstool) path: item/p
en: Each commit should be individually revertable. If it later turns out that the commit was a bad idea, <cmd>git revert <var>commit ID</var></cmd> should take the repository from a working state to another working state.
ko: 각 커밋은 개별적으로 되돌릴 수 있어야합니다. 커밋이 잘못되었다고 생각이 바뀌면, <cmd>git revert <var>commit ID</var></cmd> 명령으로 어떤 작업 상태로부터 다른 작업 상태로 저장소 상태를 전환해야합니다.

note: (itstool) path: item/p
en: The reasoning for each commit, and its relationship to external resources like specifications and bug reports, should be clear, to the extent that commits written by one developer a year in the past should still be understandable by a second developer without having to trace through the changes and work out what they do.
ko: 각 커밋의 설명, 명세 및 버그 보고서 같은 외부 자료와의 관계는 명확해야 하며, 과거 오래전에 어떤 개발자가 작성한 커밋에 이르기까지, 굳이 어떤 작업을 했는지 바뀐 내용을 찾아보지 않고도 그 다음 개발자가 알아볼 수 있어야합니다.

note: (itstool) path: item/p
en: Each commit should be written once, and designed to be read many times, by many reviewers and future programmers.
ko: 각 커밋은 한 번만 작성하고 여러 검토자와 앞으로의 프로그래머가 여러 번 보도록 설계해야합니다.

note: (itstool) path: section/title
en: Merging Procedure
ko: 병합 절차

note: (itstool) path: section/p
en: To merge a feature branch named <code>my-branch</code> into master, use the following commands:
ko: <code>my-branch</code>라는 특정 브랜치를 마스터 브랜치로 병합하려면, 다음 명령을 활용하십시오:

note: (itstool) path: info/desc
en: Versioning and releasing libraries and applications
ko: 라이브러리 및 프로그램 버전 부여 및 출시

note: (itstool) path: synopsis/p
en: Module versioning differs for libraries and applications: libraries need a libtool version specified in addition to their package version. Applications just have a package version.
ko: 라이브러리와 프로그램의 모듈 버전 부여는 다릅니다. 라이브러리는 libtool 버전과 해당 패키지 버전이 필요합니다.  프로그램은 그냥 패키지 버전만 필요합니다.

note: (itstool) path: item/p
en: Libraries and applications have a package version of the form <em>major.minor.micro</em>. (<link xref="#package-versioning"/>)
ko: 라이브러리와 프로그램은 <em>major.minor.micro</em> 형식의 패키지 버전을 보유합니다(<link xref="#package-versioning"/>).

note: (itstool) path: item/p
en: Libraries additionally have a libtool version of the form <em>current:revision:age</em>. (<link xref="#libtool-versioning"/>)
ko: 라이브러리는 또한 <em>current:revision:age</em> 형식의 libtool 버전을 보유합니다(<link xref="#libtool-versioning"/>).

note: (itstool) path: item/p
en: Version numbers should be updated for each release (using release and post-release increments). (<link xref="#release-process"/>)
ko: 버전 번호는 매 출시 때마다(release 및 post-release 증가) 최신으로 유지해야합니다(<link xref="#release-process"/>).

note: (itstool) path: item/p
en: Package versions should be incremented for feature changes or additions. (<link xref="#package-versioning"/>)
ko: 패키지 버전은 기능의 바꾸거나 추가할 때 늘어나야합니다(<link xref="#package-versioning"/>).

note: (itstool) path: item/p
en: Libtool versions should be updated for API changes or additions. (<link xref="#libtool-versioning"/>)
ko: libtool 버전은 API를 바꾸거나 추가할 때 최신으로 유지해야합니다(<link xref="#libtool-versioning"/>).

note: (itstool) path: item/p
en: Even/odd <em>minor</em> package versions can be used respectively for stable/unstable releases. (<link xref="#stable-unstable-versions"/>)
ko: 짝수/홀수 <em>부</em> 패키지 버전은 각각의 안정/불안정 출시판에 사용할 수 있습니다(<link xref="#stable-unstable-versions"/>).

note: (itstool) path: section/title
en: Package Versioning
ko: 패키지 버전 부여

note: (itstool) path: section/p
en: Both libraries and applications have a package version of the form <em>major.minor.micro</em>.
ko: 라이브러리 및 프로그램에는 <em>주.부.세부</em> 형식의 패키지 버전이 있습니다.

note: (itstool) path: section/p
en: The package version number is that passed to <code>AC_INIT()</code>, and the one which is typically known as the project’s version number. For example, the Debian package for a library will use the library’s package version (though may also include the major version number in the package name to allow for <link xref="parallel-installability">parallel installability</link>). Package versions are updated by the following rules:
ko: <code>AC_INIT()</code>에 전달하는 패키지 버전은 보통 프로젝트 버전으로 알려져 있습니다. 예를 들어 데비안 라이브러리 패키지는 (<link xref="parallel-installability">동시 설치</link>가 가능한 패키지 이름의 주 버전 번호로) 라이브러리의 패키지 버전을 활용합니다. 패키지 버전은 다음 규칙을 따라 업데이트합니다:

note: (itstool) path: item/p
en: If breaking <link xref="api-stability">API compatibility</link> in a library, or making a large change to an application which affects everything (such as a UI redesign), increment major and set minor and micro to 0.
ko: 라이브러리가 <link xref="api-stability">API 호환성</link>을 깬다거나 프로그램에 전반적으로 영향(UI 재설계 등)을 주어 상당 부분이 바뀐다면, 주 버전 번호를 늘리고, 부 버전과 세부 버전을 0으로 설정합니다.

note: (itstool) path: item/p
en: Otherwise, if changing or adding a feature, or adding any API, increment minor and set micro to 0.
ko: 그렇지 않으면, 기능을 바꾸거나 추가할 경우, 또는 API를 추가할 경우 부 버전을 증가하고 마이크로 버전을 0으로 설정합니다.

note: (itstool) path: item/p
en: Otherwise (if making a release containing only bug fixes and translation updates), increment micro.
ko: 그렇지 않으면(버그 수정 및 번역 업데이트가 들어간 출시작을 내보낼 경우), 마이크로 버전을 증가합니다.

note: (itstool) path: section/p
en: Note that the minor version number should be updated if any API is added.
ko: 참고로 부 버전 숫자는 API를 추가했을 경우 새로운 값으로 바꾸어야합니다.

note: (itstool) path: section/title
en: Libtool Versioning
ko: libtool 버전 부여

note: (itstool) path: section/p
en: Libraries have two version numbers: a libtool version which tracks ABI backwards compatibility (see <link xref="api-stability"/>), and a package version which tracks feature changes. These are normally incremented in synchronization, but should be kept separate because ABI backwards compatibility is not necessarily related to feature changes or bug fixes. Furthermore, the two version numbers have different semantics, and cannot be automatically generated from each other.
ko: 라이브러리에는 버전 번호가 두가지가 있습니다. ABI 이전 호환성을 따르는 libtool 버전(<link xref="api-stability"/> 참고), 그리고 기능의 바뀜을 따르는 패키지 버전으로 구성합니다. 보통 동기화 과정에서 증가하지만, ABI 이전 호환성은 기능의 바뀜 또는 버그 수정에 필연적 연관성이 없으므로 별도로 취급해야합니다. 게다가 두 버전 번호는 다른 관점을 가지고 있으며, 두 버전 번호를 활용하여 자동으로 만들 수 없습니다.

note: (itstool) path: section/p
en: A good overview of libtool versioning, and the differences from package versioning, is given in the <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link>; another is in the <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool manual</link>.
ko: 바람직한 libtool 버전 부여, 패키지 버전 부여 설명은 <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link>에 있습니다. 다른 내용은 <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool 설명서</link>에 있습니다.

note: (itstool) path: section/p
en: To update the libtool version, follow the algorithm given in the comments below. This is a typical <file>configure.ac</file> snippet for setting up libtool versioning:
ko: libtool 버전을 최신으로 바꾸려면, 다음 주석에 주어진 알고리즘을 따르십시오. libtool 버전 부여를 설정하는 <file>configure.ac</file> 일반 설정 부분입니다:

note: (itstool) path: section/p
en: The following snippet can be used in a <file>Makefile.am</file> to pass that version info to libtool:
ko: 다음 부분은 <file>Makefile.am</file>에 사용하여 libtool로 버전 정보를 전달할 수 있습니다:

note: (itstool) path: section/title
en: Stable and Unstable Package Versions
ko: 안정 및 불안정 패키지 버전

note: (itstool) path: section/p
en: Most GNOME modules follow a convention for stable and unstable releases. The minor version is even for stable releases and is odd for unstable releases. For example, the 3.20.* versions are stable, but the 3.19.* versions are unstable. The 3.19.* versions can be seen as alpha and beta releases of the 3.20 version.
ko: 대부분의 그놈 모듈은 안정 및 불안정 출시판의 형식을 따릅니다. 짝수 부 버전은 안정 출시판이며 홀수 부 버전은 불안정 출시판입니다. 예를 들어 3.20.* 버전은 안정 버전이지만, 3.19.* 버전은 불안정 버전입니다. 3.19.* 버전은 3.20 버전의 알파 출시판 및 베타 출시판이 될 수 있습니다.

note: (itstool) path: section/p
en: A new micro <em>stable</em> version (e.g. 3.20.0 → 3.20.1) doesn’t add new features, only translation updates and bug fixes. On the other hand, <em>unstable</em> micro releases (e.g. 3.19.1 → 3.19.2) can add API, or change or remove API which was added in a previous micro release in that minor series.
ko: 새 마이크로 <em>안정</em> 버전(예: 3.20.0 → 3.20.1)에는 새 기능이 들어가지 않으며 번역 업데이트 및 버그 수정 사항만 들어갑니다. 반면에 <em>불안정</em> 마이크로 출시판(예: 3.19.1 → 3.19.2)에는 이전 마이너 집합의 마이크로 출시판에 대비하여 API를 추가하거나, 추가한 API를 바꾸고, 제거할 수 있습니다.

note: (itstool) path: section/p
en: The libtool version should be updated only for stable package versions.
ko: libtool 버전은 안정 패키지 버전에 따라서만 최신으로 바뀌어야합니다.

note: (itstool) path: section/title
en: Release Process
ko: 출시 절차

note: (itstool) path: section/p
en: The standard process for making a release of a module increments the libtool version (if the module is a library) at the time of release, then increments the package version number immediately afterwards (this is called a post-release increment).
ko: 모듈의 출시 버전을 만드는 표준 절차는 출시를 진행할 때 libtool 버전(모듈이 라이브러리일 경우) 수를 증가한 후, 패키지 버전 번호를 증가합니다(이를 post-release 버전 증가라고 합니다).

note: (itstool) path: section/p
en: Updating the libtool versions at the time of release means that they are only incremented once for all ABI changes in a release. The use of post-release increment for package versions means the package version number is not outdated (still equal to the previous release) during the development cycle.
ko: 출시 때의 libtool 버전 새로 고침은 출시 과정에서 모든 ABI가 바뀌었을 때만 증가함을 의미합니다. 패키지 버전에 post-release 방식을 사용함은 개발 기간동안 패키지 버전이(이전 출시판과 여전히 동일하게) 시기가 지나지 않음을 의미합니다.

note: (itstool) path: section/p
en: The release process (based on the <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME release process</link>):
ko: 출시 과정(<link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME 출시 과정</link> 기반):

note: (itstool) path: item/p
en: Make sure code is up to date: <cmd>git pull</cmd>
ko: <cmd>git pull</cmd> 명령으로 코드가 최신인지 확인하십시오

note: (itstool) path: item/p
en: Make sure you have no local changes: <cmd>git status</cmd>
ko: <cmd>git status</cmd> 명령으로 로컬에 바뀐 내용이 있는지 확인하십시오

note: (itstool) path: item/p
en: If the release is for a stable package version, increment the libtool version number in <file>configure.ac</file> (if it exists)
ko: 안정 패키지 버전 출시판이라면, <file>configure.ac</file>에서 libtool 버전 값(이 있는 경우)을 늘리십시오

note: (itstool) path: item/p
en: Add an entry to the <file>NEWS</file> file
ko: <file>NEWS</file> 파일에 항목을 추가하십시오

note: (itstool) path: item/p
en: Run <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> and ensure it succeeds
ko: <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> 명령을 실행하고 성공했는지 확인하십시오

note: (itstool) path: item/p
en: Fix any issues which come up, commit those changes, and restart at step 3
ko: 떠있는 문제를 고치고 바뀐 내용을 커밋한 다음 3단계에서 다시 시작하십시오

note: (itstool) path: item/p
en: If <cmd>make distcheck</cmd> finishes with “[archive] is ready for distribution”, run <cmd>git commit -a -m "Release version x.y.z"</cmd> (where ‘x.y.z’ is the package version number)
ko: <cmd>make distcheck</cmd> 명령이 “[archive] is ready for distribution” 메시지로 끝났다면 <cmd>git commit -a -m "Release version x.y.z"</cmd>(‘x.y.z’는 패키지 버전 번호) 명령을 실행하십시오

note: (itstool) path: item/p
en: Run <cmd>git push</cmd>
ko: <cmd>git push</cmd>를 실행하십시오

note: (itstool) path: item/p
en: If that fails due to other commits having been pushed in the meantime, run <cmd>git pull</cmd> to merge your commit on the branch followed by a second <cmd>git push</cmd>. This is an exception to the GNOME guideline to have a linear Git history (<link xref="version-control#use-of-git"/>). If you prefer to have a linear history, you need to restart at step 1.
ko: 위 명령을 실행하는 동안 누군가가 이미 다른 커밋을 푸쉬하여 실패했다면, <cmd>git pull</cmd> 명령을 실행하여 우선 브랜치에 있는 여러분의 커밋과 병합한 후 <cmd>git push</cmd> 명령을 실행하십시오. 선형 Git 기록을 따르는 그놈 지침서의 예외 상황입니다(<link xref="version-control#use-of-git"/>). 선형 기록을 따르는 방식을 선호한다면 1단계부터 다시 시작해야합니다.

note: (itstool) path: item/p
en: Tag the release: <cmd>git tag -s x.y.z</cmd> (where ‘x.y.z’ is the package version number)
ko: <cmd>git tag -s x.y.z</cmd>(‘x.y.z’는 패키지 버전 번호) 명령으로 출시판에 태그를 부여하십시오

note: (itstool) path: item/p
en: Run <cmd>git push origin x.y.z</cmd> (where ‘x.y.z’ is the package version number)
ko: <cmd>git push origin x.y.z</cmd>(‘x.y.z’는 패키지 버전 번호) 명령을 실행하십시오

note: (itstool) path: section/p
en: The release is now complete, and the post-release version increment can be done:
ko: 이제 출시 과정이 끝났으며, 출시 후 버전 증가 작업을 진행할 수 있습니다:

note: (itstool) path: item/p
en: Increment the package version number in <file>configure.ac</file>
ko: <file>configure.ac</file>의 패키지 버전 번호를 늘리십시오

note: (itstool) path: item/p
en: Run <cmd>git commit -a -m "Post-release version increment"</cmd>
ko: <cmd>git commit -a -m "Post-release version increment"</cmd> 명령을 실행하십시오

note: (itstool) path: section/p
en: The package archive generated by <cmd>make distcheck</cmd> can now be uploaded to download.gnome.org or distributed in other ways.
ko: <cmd>make distcheck</cmd> 에서 만든 패키지 아카이브를 download.gnome.org으로 업로드 하든지 다른 수단으로 배포할 수 있습니다.

note: (itstool) path: info/desc
en: Good, readable code keeps the project maintainable
ko: 프로젝트의 보존성을 유지하는 바람직하고, 가독성 높은 코드

note: (itstool) path: page/title
en: The Importance of Writing Good Code
ko: 바람직한 코드 작성의 중요성

note: (itstool) path: page/p
en: GNOME is a very ambitious free software project, and it is composed of many software packages that are more or less independent of each other. A lot of the work in GNOME is done by volunteers: although there are many people working on GNOME full-time or part-time for here, volunteers still make up a large percentage of our contributors. Programmers may come and go at any time and they will be able to dedicate different amounts of time to the GNOME project. People’s “real world” responsibilities may change, and this will be reflected in the amount of time that they can devote to GNOME.
ko: 그놈은 매우 야심적인 자유 소프트웨어 프로젝트이며, 상호간 더 혹은 덜 독립적인 수많은 소프트웨어 패키지로 이루어져있습니다. 그놈에서 작업하는 수많은 결과물은 자발적인 봉사자가 만들어냅니다. 그놈 프로젝트에서 전일 내지는 시간제로 일하는 여러 사람이 있지만, 기여자의 상당수가 봉사자로 이루어져있습니다. 프로그래머는 때때로 오고가며, 그놈 프로젝트를 진행하는 각기 다른 상당한 시간동안 기여할 수 있습니다. “실 세계”에서 여러 사람의 책임감은 변화를 이끌어낼 것이며, 그놈에 상당한 시간을 들일 수 있는 만큼 노력이 반영됩니다.

note: (itstool) path: page/p
en: Software development takes long amounts of time and painstaking effort. This is why most part-time volunteers cannot start big projects by themselves; it is much easier and more rewarding to contribute to existing projects, as this yields results that are immediately visible and usable.
ko: 소프트웨어 개발은 상당한 시간동안 공을 들이 노력으로 이루어집니다. 이게 대부분 여러 시간제 봉사자가 자체적으로 거대한 프로젝트를 시작할 수 없는 이유입니다. 기존의 프로젝트에 기여하면, 결과가 즉시 나타나고 바로 활용할 수 있기 때문에 더 쉬우며, 기여 보상을 더 많이 받을 수 있습니다.

note: (itstool) path: page/p
en: Thus, we conclude that it is very important for existing projects to make it as easy as possible for people to contribute to them. One way of doing this is by making sure that programs are easy to read, understand, modify, and maintain.
ko: 따라서, 사람이 기존 프로젝트에 쉽게 기여할 수 있으려면 이 점이 중요하겠다는 결론을 내렸습니다. 프로그램 코드를 쉽게 읽고, 이해하고, 수정하고, 관리할 수 있는지 여부를 확인하는 길이 한 방법입니다.

note: (itstool) path: page/p
en: Messy code is hard to read, and people may lose interest if they cannot decipher what the code tries to do. Also, it is important that programmers be able to understand the code quickly so that they can start contributing with bug fixes and enhancements in a short amount of time. Source code is a form of <em>communication</em>, and it is more for people than for computers. Just as someone would not like to read a novel with spelling errors, bad grammar, and sloppy punctuation, programmers should strive to write good code that is easy to understand and modify by others.
ko: 지저분한 코드는 알아보기 힘들며, 코드가 어떤 동작을 하는지 알아볼 수 없다면 흥미를 잃어버립니다. 또한 프로그래머가 코드를 빨리 이해하여 버그 수정 및 개선에 적은 시간을 들이는 행동으로 기여를 시작할 수 있게 하는게 중요합니다. 소스 코드는 <em>의사 소통</em>의 한 유형이며, 컴퓨터보단 사람을 위합니다. 누군가가 오탈자, 잘못된 문법, 엉성한 문장 부호가 있는 소설을 읽기 싫어하는 것처럼, 프로그래머도 다른 프로그래머가 쉽게 이해하고 수정할 수 있는 바람직한 코드를 작성하도록 노력해야합니다.

note: (itstool) path: page/p
en: The following are some important qualities of good code:
ko: 바람직한 코드의 품질을 확보하려 지켜야 할 몇가지 중요한 사항이 있습니다:

note: (itstool) path: item/title
en: Cleanliness
ko: 명확성

note: (itstool) path: item/p
en: Clean code is easy to read with minimum effort. This lets people start to understand it easily. This includes the coding style itself (brace placement, indentation, variable names), and the actual control flow of the code.
ko: 깔끔한 코드는 최소한의 노력으로도 읽기 쉽습니다. 사람이 쉽게 이해하기 시작하도록 해줍니다. 코드 작성 방식 그 자체(중괄호 위치, 들여쓰기, 변수 이름) 및, 코드의 실제 제어문 흐름이 깔끔한 코드 구성 개념에 해당합니다.

note: (itstool) path: item/title
en: Consistency
ko: 일관성

note: (itstool) path: item/p
en: Consistent code makes it easy for people to understand how a program works. When reading consistent code, one subconsciously forms a number of assumptions and expectations about how the code works, so it is easier and safer to make modifications to it. Code that <em>looks</em> the same in two places should <em>work</em> the same, too.
ko: 일관된 코드는 프로그램이 어떻게 동작하는지 쉽게 이해할 수 있게 해줍니다. 일관성 있는 코드를 볼 때, 잠재적인 몇 가지 가정을 두고 코드 동작을 기대하기 때문에 코드를 쉽고 안전하게 수정할 수 있습니다. 다른 곳에 있는 동일<em>해보이는</em> 코드는, 마찬가지로 동일하게 <em>동작</em>해야합니다.

note: (itstool) path: item/title
en: Extensibility
ko: 확장성

note: (itstool) path: item/p
en: General-purpose code is easier to reuse and modify than very specific code with lots of hardcoded assumptions. When someone wants to add a new feature to a program, it will obviously be easier to do so if the code was designed to be extensible from the beginning. Code that was not written this way may lead people into having to implement ugly hacks to add features.
ko: 범용 코드는 많은 코드를 하드코딩했을 경우의 특수 목적 코드보다 재활용 및 수정이 쉽습니다. 누군가 프로그램에 새 기능을 추가하려고 하면 코드 규모를 쉽게 확장할 수 있게 설계 했을 경우 분명히 쉽게 처리할 수 있습니다. 이 방식으로 코드를 작성하지 않으면 여러 사람이 기능을 추가할 때 난잡파게 뜯어 고칠수밖에 없게 만듭니다.

note: (itstool) path: item/title
en: Correctness
ko: 정확성

note: (itstool) path: item/p
en: Finally, code that is designed to be correct lets people spend less time worrying about bugs, and more time enhancing the features of a program. Users also appreciate correct code, since nobody likes software that crashes. Code that is written for correctness and safety (i.e. code that explicitly tries to ensure that the program remains in a consistent state) prevents many kinds of silly bugs.
ko: 마지막으로 올바르게 설계한 코드는 버그를 걱정하지 않고 적은 시간을 들일 수 있게 하며, 프로그램 기능 개선에 더 많은 시간을 들일 수 있게 합니다. 사용자는 그 어느 누구도 오류로 갑작스럽게 끝나는 프로그램을 좋아하지 않기에 올바른 코드를 선호합니다. 올바르고 안전하게 작성한 코드(예: 일관된 상태를 유지하는 프로그램인지 분명하게 확인해 본 코드)는 대부분의 어이없는 버그를 막아줍니다.

note: (itstool) path: section/title
en: Book References
ko: 참고 서적

note: (itstool) path: item/p
en: <link href="http://www.cc2e.com">Code Complete</link>, by Steve McConnell.
ko: Steve McConnell 저, <link href="http://www.cc2e.com">Code Complete</link>.

note: (itstool) path: item/p
en: <link href="http://martinfowler.com/books/refactoring.html"> Refactoring: Improving the Design of Existing Code </link>, by Martin Fowler.
ko: Martin Fowler 저, <link href="http://martinfowler.com/books/refactoring.html"> Refactoring: Improving the Design of Existing Code </link>.

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Design_Patterns"> Design Patterns: Elements of Reusable Object-Oriented Software </link>, by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides.
ko: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides 저, <link href="http://en.wikipedia.org/wiki/Design_Patterns"> Design Patterns: Elements of Reusable Object-Oriented Software </link>.

note: (itstool) path: item/p
en: <link href="http://astore.amazon.com/gnomestore-20/detail/020163385X"> Object-Oriented Design Heuristics </link>, by Arthur Riel.
ko: Arthur Riel 저, <link href="http://astore.amazon.com/gnomestore-20/detail/020163385X"> Object-Oriented Design Heuristics </link>.
