msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2018-03-12 16:01+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
msgid "translator-credits"
msgstr ""

#. (itstool) path: credit/name
#: C/additional-materials.page:10
#: C/c-coding-style.page:10
#: C/documentation.page:11
#: C/index.page:8
#: C/writing-good-code.page:10
msgid "Federico Mena-Quintero"
msgstr ""

#. (itstool) path: credit/years
#: C/additional-materials.page:12
#: C/c-coding-style.page:12
#: C/documentation.page:13
#: C/index.page:10
#: C/writing-good-code.page:12
msgid "2013"
msgstr ""

#. (itstool) path: info/desc
#: C/additional-materials.page:17
msgid "Other style guides and books about organizing free software projects"
msgstr ""

#. (itstool) path: page/title
#: C/additional-materials.page:21
msgid "Additional Materials"
msgstr ""

#. (itstool) path: page/p
#: C/additional-materials.page:23
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/additional-materials.page:32
msgid "<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."
msgstr ""

#. (itstool) path: item/p
#: C/additional-materials.page:46
msgid "<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."
msgstr ""

#. (itstool) path: item/p
#: C/additional-materials.page:57
msgid "<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."
msgstr ""

#. (itstool) path: credit/name
#: C/api-stability.page:10
#: C/databases.page:11
#: C/documentation.page:16
#: C/file-system.page:11
#: C/gerror.page:11
#: C/glist.page:11
#: C/index.page:21
#: C/introspection.page:10
#: C/logging.page:11
#: C/main-contexts.page:11
#: C/memory-management.page:10
#: C/namespacing.page:10
#: C/parallel-installability.page:18
#: C/preconditions.page:11
#: C/threading.page:11
#: C/tooling.page:10
#: C/unit-testing.page:10
#: C/version-control.page:10
#: C/versioning.page:10
msgid "Philip Withnall"
msgstr ""

#. (itstool) path: credit/years
#: C/api-stability.page:12
#: C/databases.page:13
#: C/documentation.page:18
#: C/file-system.page:13
#: C/gerror.page:13
#: C/glist.page:13
#: C/index.page:23
#: C/introspection.page:12
#: C/logging.page:13
#: C/memory-management.page:12
#: C/parallel-installability.page:20
#: C/preconditions.page:13
#: C/threading.page:13
#: C/tooling.page:12
#: C/unit-testing.page:12
#: C/version-control.page:12
#: C/versioning.page:12
msgid "2015"
msgstr ""

#. (itstool) path: info/desc
#: C/api-stability.page:17
msgid "Backwards compatibility in APIs"
msgstr ""

#. (itstool) path: page/title
#: C/api-stability.page:20
msgid "API stability"
msgstr ""

#. (itstool) path: synopsis/title
#: C/api-stability.page:23
#: C/databases.page:24
#: C/documentation.page:32
#: C/file-system.page:24
#: C/introspection.page:23
#: C/logging.page:26
#: C/main-contexts.page:27
#: C/memory-management.page:65
#: C/namespacing.page:25
#: C/parallel-installability.page:33
#: C/threading.page:24
#: C/tooling.page:45
#: C/unit-testing.page:23
#: C/version-control.page:23
#: C/versioning.page:23
msgid "Summary"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:26
msgid "Define API stability guarantees for your project. (<link xref=\"#stability\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:30
msgid "Ensure version numbers are changed as appropriate when API changes. (<link xref=\"#versioning\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/api-stability.page:38
msgid "API and ABI"
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:40
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:54
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:59
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:67
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/api-stability.page:75
msgid "Stability"
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:77
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:93
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:102
msgid "Several types of stability commonly considered:"
msgstr ""

#. (itstool) path: item/title
#: C/api-stability.page:107
msgid "Unstable"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:108
msgid "The API could change or be removed in future."
msgstr ""

#. (itstool) path: item/title
#: C/api-stability.page:111
msgid "Backwards compatible"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:112
msgid "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)."
msgstr ""

#. (itstool) path: item/title
#: C/api-stability.page:119
msgid "Forwards compatible"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:120
msgid "Only changes which permit code compiled against the modified API to run against the unmodified API are allowed (for example, functions cannot be added)."
msgstr ""

#. (itstool) path: item/title
#: C/api-stability.page:127
msgid "Totally stable"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:128
msgid "No changes are allowed to the API, only to the implementation."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:132
msgid "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."
msgstr ""

#. (itstool) path: section/title
#. (itstool) path: page/title
#: C/api-stability.page:140
#: C/versioning.page:20
msgid "Versioning"
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:142
msgid "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\"/>."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:151
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:162
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:169
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/api-stability.page:179
#: C/unit-testing.page:272
#: C/version-control.page:161
msgid "External Links"
msgstr ""

#. (itstool) path: section/p
#: C/api-stability.page:181
msgid "The topic of API stability is covered in the following articles:"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:185
msgid "<link href=\"http://en.wikipedia.org/wiki/Application_programming_interface\">Wikipedia page on APIs</link>"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:189
msgid "<link href=\"http://en.wikipedia.org/wiki/Application_binary_interface\">Wikipedia page on ABIs</link>"
msgstr ""

#. (itstool) path: item/p
#: C/api-stability.page:193
msgid "<link href=\"http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning\">D-Bus API versioning documentation</link>"
msgstr ""

#. (itstool) path: credit/name
#: C/c-coding-style.page:15
#: C/documentation.page:21
msgid "The GTK+ Team"
msgstr ""

#. (itstool) path: info/desc
#: C/c-coding-style.page:20
msgid "Our guidelines for C code in GNOME"
msgstr ""

#. (itstool) path: page/title
#: C/c-coding-style.page:23
msgid "C Coding Style"
msgstr ""

#. (itstool) path: page/p
#: C/c-coding-style.page:25
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/c-coding-style.page:32
msgid "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!"
msgstr ""

#. (itstool) path: note/p
#: C/c-coding-style.page:42
msgid "This document is for C code. For other languages, check the <link xref=\"index\">main page</link> of the GNOME Programming Guidelines."
msgstr ""

#. (itstool) path: page/p
#: C/c-coding-style.page:49
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:58
msgid "The Single Most Important Rule"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:60
msgid "The single most important rule when writing code is this: <em>check the surrounding code and try to imitate it</em>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:65
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:72
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:80
msgid "Line Width"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:82
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:93
msgid "Indentation"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:95
msgid "In general there are two preferred indentation styles for code in GNOME."
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:102
msgid "Linux Kernel style. Tabs with a length of 8 characters are used for the indentation, with K&amp;R brace placement:"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:107
#, no-wrap
msgid ""
"\n"
"for (i = 0; i &lt; num_elements; i++) {\n"
"\tfoo[i] = foo[i] + 42;\n"
"\n"
"\tif (foo[i] &lt; 35) {\n"
"\t\tprintf (\"Foo!\");\n"
"\t\tfoo[i]--;\n"
"\t} else {\n"
"\t\tprintf (\"Bar!\");\n"
"\t\tfoo[i]++;\n"
"\t}\n"
"}"
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:122
msgid "GNU style. Each new level is indented by 2 spaces, braces go on a line by themselves, and they are indented as well."
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:128
#, no-wrap
msgid ""
"\n"
"for (i = 0; i &lt; num_elements; i++)\n"
"  {\n"
"    foo[i] = foo[i] + 42;\n"
"\n"
"    if (foo[i] &lt; 35)\n"
"      {\n"
"        printf (\"Foo!\");\n"
"        foo[i]--;\n"
"      }\n"
"    else\n"
"      {\n"
"        printf (\"Bar!\");\n"
"        foo[i]++;\n"
"      }\n"
"  }"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:148
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:157
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:170
msgid "Tab Characters"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:172
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:178
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:188
msgid "Braces"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:190
msgid "Curly braces should not be used for single statement blocks:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:194
#, no-wrap
msgid ""
"\n"
"/* valid */\n"
"if (condition)\n"
"\tsingle_statement ();\n"
"else\n"
"\tanother_single_statement (arg1);"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:201
msgid "The “no block for single statements” rule has only four exceptions:"
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:208
msgid "In GNU style, if either side of an if-else statement has braces, both sides should, to match up indentation:"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:213
#, no-wrap
msgid ""
"\n"
"/* valid GNU style */\n"
"if (condition)\n"
"  {\n"
"    foo ();\n"
"    bar ();\n"
"  }\n"
"else\n"
"  {\n"
"    baz ();\n"
"  }"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:225
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if (condition)\n"
"  {\n"
"    foo ();\n"
"    bar ();\n"
"  }\n"
"else\n"
"  baz ();"
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:237
msgid "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>:"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:243
#, no-wrap
msgid ""
"\n"
"/* valid Linux kernel style */\n"
"if (condition) {\n"
"\ta_single_statement_with_many_arguments (some_lengthy_argument,\n"
"\t\t\t\t\t\tanother_lengthy_argument,\n"
"\t\t\t\t\t\tand_another_one,\n"
"\t\t\t\t\t\tplus_one);\n"
"} else\n"
"\tanother_single_statement (arg1, arg2);\n"
"\n"
"/* valid GNU style */\n"
"if (condition)\n"
"  {\n"
"    a_single_statement_with_many_arguments (some_lengthy_argument,\n"
"                                            another_lengthy_argument,\n"
"                                            and_another_one,\n"
"                                            plus_one);\n"
"  }\n"
"else\n"
"  {\n"
"    another_single_statement (arg1, arg2);\n"
"  }"
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:268
msgid "If the condition is composed of many lines:"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:272
#, no-wrap
msgid ""
"\n"
"/* valid Linux kernel style */\n"
"if (condition1 ||\n"
"    (condition2 &amp;&amp; condition3) ||\n"
"    condition4 ||\n"
"    (condition5 &amp;&amp; (condition6 || condition7))) {\n"
"\ta_single_statement ();\n"
"}\n"
"\n"
"/* valid GNU style */\n"
"if (condition1 ||\n"
"    (condition2 &amp;&amp; condition3) ||\n"
"    condition4 ||\n"
"    (condition5 &amp;&amp; (condition6 || condition7)))\n"
"  {\n"
"    a_single_statement ();\n"
"  }"
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:290
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/c-coding-style.page:299
msgid "Nested <code>if</code>s, in which case the block should be placed on the outermost <code>if</code>:"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:304
#, no-wrap
msgid ""
"\n"
"/* valid Linux kernel style */\n"
"if (condition) {\n"
"\tif (another_condition)\n"
"\t\tsingle_statement ();\n"
"\telse\n"
"\t\tanother_single_statement ();\n"
"}\n"
"\n"
"/* valid GNU style */\n"
"if (condition)\n"
"  {\n"
"    if (another_condition)\n"
"      single_statement ();\n"
"    else\n"
"      another_single_statement ();\n"
"  }"
msgstr ""

#. (itstool) path: item/code
#: C/c-coding-style.page:322
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if (condition)\n"
"\tif (another_condition)\n"
"\t\tsingle_statement ();\n"
"\telse if (yet_another_condition)\n"
"\t\tanother_single_statement ();"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:332
msgid "In general, new blocks should be placed on a new indentation level, like this:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:337
#, no-wrap
msgid ""
"\n"
"int retval = 0;\n"
"\n"
"statement_1 ();\n"
"statement_2 ();\n"
"\n"
"{\n"
"\tint var1 = 42;\n"
"\tgboolean res = FALSE;\n"
"\n"
"\tres = statement_3 (var1);\n"
"\n"
"\tretval = res ? -1 : 1;\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:352
msgid "While curly braces for function definitions should rest on a new line they should not add an indentation level:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:357
#, no-wrap
msgid ""
"\n"
"/* valid Linux kernel style*/\n"
"static void\n"
"my_function (int argument)\n"
"{\n"
"\tdo_my_things ();\n"
"}\n"
"\n"
"/* valid GNU style*/\n"
"static void\n"
"my_function (int argument)\n"
"{\n"
"  do_my_things ();\n"
"}"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:372
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"static void\n"
"my_function (int argument) {\n"
"\tdo_my_things ();\n"
"}\n"
"\n"
"/* invalid */\n"
"static void\n"
"my_function (int argument)\n"
"  {\n"
"    do_my_things ();\n"
"  }"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:388
msgid "Conditions"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:390
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:397
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if (found == TRUE)\n"
"\tdo_foo ();\n"
"\n"
"/* invalid */\n"
"if (found == FALSE)\n"
"\tdo_bar ();"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:406
#, no-wrap
msgid ""
"\n"
"/* valid */\n"
"if (found)\n"
"\tdo_foo ();\n"
"\n"
"/* valid */\n"
"if (!found)\n"
"\tdo_bar ();"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:415
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:426
#, no-wrap
msgid ""
"\n"
"/* valid */\n"
"if (some_pointer == NULL)\n"
"\tdo_blah ();\n"
"\n"
"/* valid */\n"
"if (number == 0)\n"
"\tdo_foo ();\n"
"\n"
"/* valid */\n"
"if (str != NULL &amp;&amp; *str != '\\0')\n"
"\tdo_bar ();"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:439
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if (!some_pointer)\n"
"\tdo_blah ();\n"
"\n"
"/* invalid */\n"
"if (!number)\n"
"\tdo_foo ();\n"
"\n"
"/* invalid */\n"
"if (str &amp;&amp; *str)\n"
"\tdo_bar ();"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:454
msgid "Functions"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:456
msgid "Functions should be declared by placing the returned value on a separate line from the function name:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:461
#, no-wrap
msgid ""
"\n"
"void\n"
"my_function (void)\n"
"{\n"
"  …\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:468
msgid "The argument list must be broken into a new line for each argument, with the argument names right aligned, taking into account pointers:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:474
#, no-wrap
msgid ""
"\n"
"void\n"
"my_function (some_type_t      type,\n"
"             another_type_t  *a_pointer,\n"
"             double_ptr_t   **double_pointer,\n"
"             final_type_t     another_type)\n"
"{\n"
"  …\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:484
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:490
msgid "The alignment also holds when invoking a function without breaking the line length limit:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:495
#, no-wrap
msgid ""
"\n"
"align_function_arguments (first_argument,\n"
"                          second_argument,\n"
"                          third_argument);"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:502
msgid "Whitespace"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:504
msgid "Always put a space before an opening parenthesis but never after:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:508
#, no-wrap
msgid ""
"\n"
"/* valid */\n"
"if (condition)\n"
"\tdo_my_things ();\n"
"\n"
"/* valid */\n"
"switch (condition) {\n"
"}"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:517
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if(condition)\n"
"\tdo_my_things();\n"
"\n"
"/* invalid */\n"
"if ( condition )\n"
"\tdo_my_things ( );"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:526
msgid "When declaring a structure type use newlines to separate logical sections of the structure:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:531
#, no-wrap
msgid ""
"\n"
"struct _GtkWrapBoxPrivate\n"
"{\n"
"\tGtkOrientation        orientation;\n"
"\tGtkWrapAllocationMode mode;\n"
"\n"
"\tGtkWrapBoxSpreading   horizontal_spreading;\n"
"\tGtkWrapBoxSpreading   vertical_spreading;\n"
"\n"
"\tguint16               vertical_spacing;\n"
"\tguint16               horizontal_spacing;\n"
"\n"
"\tguint16               minimum_line_children;\n"
"\tguint16               natural_line_children;\n"
"\n"
"\tGList                *children;\n"
"};"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:549
msgid "Do not eliminate whitespace and newlines just because something would fit on a single line:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:554
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"if (condition) foo (); else bar ();"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:558
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:564
msgid "This is a little Emacs function that you can use to clean up lines with trailing whitespace:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:569
#, no-wrap
msgid ""
"\n"
"(defun clean-line-ends ()\n"
"  (interactive)\n"
"  (if (not buffer-read-only)\n"
"      (save-excursion\n"
"\t(goto-char (point-min))\n"
"\t(let ((count 0))\n"
"\t  (while (re-search-forward \"[ \t]+$\" nil t)\n"
"\t    (setq count (+ count 1))\n"
"\t    (replace-match \"\" t t))\n"
"\t  (message \"Cleaned %d lines\" count)))))"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:583
msgid "The <code>switch</code> Statement"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:585
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:592
#, no-wrap
msgid ""
"\n"
"/* valid Linux kernel style */\n"
"switch (condition) {\n"
"case FOO:\n"
"\tdo_foo ();\n"
"\tbreak;\n"
"\n"
"case BAR:\n"
"\tdo_bar ();\n"
"\tbreak;\n"
"}\n"
"\n"
"/* valid GNU style */\n"
"switch (condition)\n"
"  {\n"
"  case FOO:\n"
"    do_foo ();\n"
"    break;\n"
"\n"
"  case BAR:\n"
"    do_bar ();\n"
"    break;\n"
"  }"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:616
#, no-wrap
msgid ""
"\n"
"/* invalid */\n"
"switch (condition) {\n"
"  case FOO: do_foo (); break;\n"
"  case BAR: do_bar (); break;\n"
"}\n"
"\n"
"/* invalid */\n"
"switch (condition)\n"
"  {\n"
"  case FOO: do_foo ();\n"
"    break;\n"
"  case BAR: do_bar ();\n"
"    break;\n"
"  }\n"
"\n"
"/* invalid */\n"
"switch (condition)\n"
"  {\n"
"    case FOO:\n"
"    do_foo ();\n"
"    break;\n"
"    case BAR:\n"
"    do_bar ();\n"
"    break;\n"
"  }"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:643
msgid "It is preferable, though not mandatory, to separate the various cases with a newline:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:648
#, no-wrap
msgid ""
"\n"
"switch (condition) {\n"
"case FOO:\n"
"\tdo_foo ();\n"
"\tbreak;\n"
"\n"
"case BAR:\n"
"\tdo_bar ();\n"
"\tbreak;\n"
"\n"
"default:\n"
"\tdo_default ();\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:662
msgid "The <code>break</code> statement for the <code>default</code> case is not mandatory."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:667
msgid "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>:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:674
#, no-wrap
msgid ""
"\n"
"switch (enumerated_condition) {\n"
"case HANDLED_1:\n"
"\tdo_foo ();\n"
"\tbreak;\n"
"\n"
"case HANDLED_2:\n"
"\tdo_bar ();\n"
"\tbreak;\n"
"\n"
"case IGNORED_1:\n"
"case IGNORED_2:\n"
"default:\n"
"\tdo_default ();\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:690
msgid "If most members of the enumerated type should not be handled, consider using an <code>if</code> statement instead of a <code>switch</code>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:695
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:701
#, no-wrap
msgid ""
"\n"
"/* valid GNU style */\n"
"switch (condition)\n"
"  {\n"
"  case FOO:\n"
"    {\n"
"      int foo;\n"
"\n"
"      foo = do_foo ();\n"
"    }\n"
"    break;\n"
"\n"
"  …\n"
"  }"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:718
msgid "Header Files"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:720
msgid "The only major rule for headers is that the function definitions should be vertically aligned in three columns:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:725
#, no-wrap
msgid ""
"\n"
"return_type          function_name           (type   argument,\n"
"                                              type   argument,\n"
"                                              type   argument);"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:730
msgid "The maximum width of each column is given by the longest element in the column:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:735
#, no-wrap
msgid ""
"\n"
"void         gtk_type_set_property (GtkType      *type,\n"
"                                    const gchar  *value,\n"
"                                    GError      **error);\n"
"const gchar *gtk_type_get_property (GtkType      *type);"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:741
msgid "It is also possible to align the columns to the next tab:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:745
#, no-wrap
msgid ""
"\n"
"void          gtk_type_set_prop           (GtkType *type,\n"
"                                           gfloat   value);\n"
"gfloat        gtk_type_get_prop           (GtkType *type);\n"
"gint          gtk_type_update_foobar      (GtkType *type);"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:751
msgid "As before, you can use <code>M-x align</code> in Emacs to do this automatically."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:756
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:766
#, no-wrap
msgid ""
"\n"
"#if !defined (__GTK_H_INSIDE__) &amp;&amp; !defined (GTK_COMPILATION)\n"
"#error \"Only &lt;gtk/gtk.h&gt; can be included directly.\"\n"
"#endif"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:771
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:777
#, no-wrap
msgid ""
"\n"
"#ifndef MYLIB_FOO_H_\n"
"#define MYLIB_FOO_H_\n"
"\n"
"#include &lt;gtk/gtk.h&gt;\n"
"\n"
"G_BEGIN_DECLS\n"
"\n"
"…\n"
"\n"
"G_END_DECLS\n"
"\n"
"#endif /* MYLIB_FOO_H_ */"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:793
msgid "GObject Classes"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:795
msgid "GObject class definitions and implementations require some additional coding style notices, and should always be <link xref=\"namespacing#gobject\">correctly namespaced</link>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:801
msgid "Typedef declarations should be placed at the beginning of the file:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:805
#, no-wrap
msgid ""
"\n"
"typedef struct _GtkBoxedStruct       GtkBoxedStruct;\n"
"typedef struct _GtkMoreBoxedStruct   GtkMoreBoxedStruct;"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:809
msgid "This includes enumeration types:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:813
#, no-wrap
msgid ""
"\n"
"typedef enum\n"
"{\n"
"  GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,\n"
"  GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH\n"
"} GtkSizeRequestMode;"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:820
msgid "And callback types:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:824
#, no-wrap
msgid ""
"\n"
"typedef void (* GtkCallback) (GtkWidget *widget,\n"
"                              gpointer   user_data);"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:828
msgid "Instance structures should be declared using <code>G_DECLARE_FINAL_TYPE</code> or <code>G_DECLARE_DERIVABLE_TYPE</code>:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:834
#, no-wrap
msgid ""
"\n"
"#define GTK_TYPE_FOO (gtk_foo_get_type ())\n"
"G_DECLARE_FINAL_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:838
msgid "For final types, private data can be stored in the object struct, which should be defined in the C file:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:843
#, no-wrap
msgid ""
"\n"
"struct _GtkFoo\n"
"{\n"
"  GObject   parent_instance;\n"
"\n"
"  guint     private_data;\n"
"  gpointer  more_private_data;\n"
"};"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:852
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:858
#, no-wrap
msgid ""
"\n"
"#define GTK_TYPE_FOO gtk_foo_get_type ()\n"
"G_DECLARE_DERIVABLE_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)\n"
"\n"
"struct _GtkFooClass\n"
"{\n"
"  GtkWidgetClass parent_class;\n"
"\n"
"  void (* handle_frob)  (GtkFrobber *frobber,\n"
"                         guint       n_frobs);\n"
"\n"
"  gpointer padding[12];\n"
"};"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:872
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:882
msgid "Interface types should always have the dummy typedef for cast purposes:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:887
#, no-wrap
msgid ""
"\n"
"typedef struct _GtkFooable          GtkFooable;"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:890
msgid "The interface structure should have ‘Interface’ postfixed to the dummy typedef:"
msgstr ""

#. (itstool) path: section/code
#: C/c-coding-style.page:895
#, no-wrap
msgid ""
"\n"
"typedef struct _GtkFooableInterface     GtkFooableInterface;"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:898
msgid "Interfaces must have the following macros:"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:905
msgid "Macro"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:906
msgid "Expands to"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:911
msgid "<code>GTK_TYPE_<var>iface_name</var></code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:912
msgid "<code><var>iface_name</var>_get_type</code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:915
msgid "<code>GTK_<var>iface_name</var></code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:916
msgid "<code>G_TYPE_CHECK_INSTANCE_CAST</code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:919
msgid "<code>GTK_IS_<var>iface_name</var></code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:920
msgid "<code>G_TYPE_CHECK_INSTANCE_TYPE</code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:923
msgid "<code>GTK_<var>iface_name</var>_GET_IFACE</code>"
msgstr ""

#. (itstool) path: td/p
#: C/c-coding-style.page:924
msgid "<code>G_TYPE_INSTANCE_GET_INTERFACE</code>"
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:932
msgid "Memory Allocation"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:934
msgid "When dynamically allocating data on the heap use <code>g_new()</code>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:938
msgid "Public structure types should always be returned after being zero-ed, either explicitly for each member, or by using <code>g_new0()</code>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:944
msgid "See <link xref=\"memory-management\"/> for more details."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:950
msgid "Macros"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:952
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:958
msgid "Inline functions are usually preferable to private macros."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:962
msgid "Public macros should not be used unless they evaluate to a constant."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:969
msgid "Public API"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:971
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/c-coding-style.page:980
msgid "Private API"
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:982
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:988
msgid "Underscore-prefixed functions are never exported."
msgstr ""

#. (itstool) path: section/p
#: C/c-coding-style.page:992
msgid "Non-exported functions that are only needed in one source file should be declared static."
msgstr ""

#. (itstool) path: p/link
#: C/cc-by-sa-3-0.xml:4
msgid "Creative Commons Attribution-Share Alike 3.0 United States License"
msgstr ""

#. (itstool) path: license/p
#: C/cc-by-sa-3-0.xml:3
msgid "This work is licensed under a <_:link-1/>."
msgstr ""

#. (itstool) path: license/p
#: C/cc-by-sa-3-0.xml:6
msgid "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."
msgstr ""

#. (itstool) path: info/desc
#: C/databases.page:18
msgid "Simple persistent object stores"
msgstr ""

#. (itstool) path: page/title
#: C/databases.page:21
msgid "Databases"
msgstr ""

#. (itstool) path: item/p
#: C/databases.page:27
msgid "Use databases for appropriate use cases: not configuration data (use GSettings). (<link xref=\"#when-to-use-databases\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/databases.page:31
msgid "Choose between GOM and GVDB based on whether indexing is required. (<link xref=\"#when-to-use-databases\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/databases.page:35
msgid "Consider your vacuuming policy before committing to using GOM. (<link xref=\"#when-to-use-databases\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/databases.page:39
msgid "Avoid SQL injection vulnerabilities by using prepared statements. (<link xref=\"#sql-injection\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/databases.page:47
msgid "When to Use Databases"
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:49
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:60
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:69
msgid "GOM should be used if you need advanced features, especially indexing. GVDB should be used otherwise."
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:74
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:86
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/databases.page:97
msgid "Using GOM"
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:99
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/databases.page:113
msgid "SQL Injection"
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:115
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/databases.page:131
msgid "Using GVDB"
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:133
msgid "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+."
msgstr ""

#. (itstool) path: section/p
#: C/databases.page:141
msgid "A full GVDB tutorial is beyond the scope of this document."
msgstr ""

#. (itstool) path: info/desc
#: C/documentation.page:26
msgid "Adding documentation to libraries and APIs"
msgstr ""

#. (itstool) path: page/title
#. (itstool) path: section/title
#: C/documentation.page:29
#: C/memory-management.page:473
msgid "Documentation"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:35
msgid "Use gtk-doc with up-to-date settings for API documentation. (<link xref=\"#gtk-doc\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:39
msgid "Use XML entities for including external symbols into the documentation. (<link xref=\"#build-system\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:43
msgid "Use a consistent, standard, table of contents for all API documentation to maintain familiarity. (<link xref=\"#standard-layout\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:47
msgid "Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to include in the gtk-doc build. (<link xref=\"#dbus-api\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:51
msgid "Add introspection annotations to all API documentation. (<link xref=\"#introspection-annotations\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:55
msgid "Add <code>Since</code> lines to all API documentation. (<link xref=\"#symbol-versioning\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:59
msgid "Enable gtk-doc tests. (<link xref=\"#keeping-up-to-date\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:66
msgid "gtk-doc"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:68
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:81
msgid "Build System"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:83
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:94
msgid "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.)"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:106
msgid "If the package version is needed to be substituted into the documentation, create a file named <file>docs/version.xml.in</file>, containing:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:110
#, no-wrap
msgid ""
"@PACKAGE_VERSION@"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:111
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:121
msgid "Standard Layout"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:123
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:131
msgid "The following layout is suggested:"
msgstr ""

#. (itstool) path: listing/title
#: C/documentation.page:135
msgid "<file><var>project-name</var>-docs.xml</file>"
msgstr ""

#. (itstool) path: listing/desc
#: C/documentation.page:136
msgid "A template top-level gtk-doc file for a project"
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:142
msgid "Licensing"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:150
msgid "It is important to make the license used for API references clear, especially if they contain code examples which could be copied around."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:155
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:161
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:169
msgid "Public APIs"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:171
msgid "All public APIs must have gtk-doc comments. For functions, these should be placed in the source file, directly above the function."
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:176
#, no-wrap
msgid ""
"/**\n"
" * gtk_get_flow:\n"
" * @widget: a #GtkWidget\n"
" *\n"
" * Gets the flow of a widget.\n"
" *\n"
" * Note that flows may be laminar or turbulent...\n"
" *\n"
" * Returns: (transfer none): the flow of @widget\n"
" */\n"
"GtkFlow *\n"
"gtk_get_flow (GtkWidget *widget)\n"
"{\n"
"\n"
"  ...\n"
"\n"
"}"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:194
msgid "Documentation comments for macros, function types, class structs, etc. should be placed next to the definitions, typically in header files."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:200
msgid "Section introductions should be placed in the source file they describe, after the license header:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:205
#, no-wrap
msgid ""
"/**\n"
" * SECTION:gtksizerequest\n"
" * @Short_Description: Height-for-width geometry management\n"
" * @Title: GtkSizeRequest\n"
" *\n"
" * The GtkSizeRequest interface is GTK+'s height-for-width (and\n"
" * width-for-height) geometry management system.\n"
" * ...\n"
" */"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:215
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:221
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:231
msgid "Introspection Annotations"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:233
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:240
msgid "They add important information about parameter types, nullability and memory management to the C API documentation generated by gtk-doc."
msgstr ""

#. (itstool) path: item/p
#: C/documentation.page:244
msgid "They allow public APIs to be automatically bound in other languages, such as Python or JavaScript."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:250
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:258
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:264
#, no-wrap
msgid ""
"/**\n"
" * my_function:\n"
" * @parameter: (nullable): some parameter which affects something\n"
" *\n"
" * Body of the function documentation.\n"
" */"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:271
msgid "Instead of:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:274
#, no-wrap
msgid ""
"/**\n"
" * my_bad_function:\n"
" * @parameter: some parameter which affects something, or %NULL to ignore\n"
" *\n"
" * Bad body of the function documentation.\n"
" */"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:281
msgid "For more information on introspection, see the <link xref=\"introspection\">introspection guidelines</link>."
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:288
msgid "Symbol Versioning"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:290
msgid "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."
msgstr ""

#. (itstool) path: section/p
#. (itstool) path: example/p
#: C/documentation.page:300
#: C/memory-management.page:494
#: C/threading.page:79
msgid "For example:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:303
#, no-wrap
msgid ""
"/**\n"
" * my_function:\n"
" * @param: some parameter\n"
" *\n"
" * Body of the function documentation.\n"
" *\n"
" * Since: 0.5.0\n"
" */"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:312
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:317
#, no-wrap
msgid ""
"&lt;part&gt;\n"
"\t&lt;title&gt;Appendices&lt;/title&gt;\n"
"\t&lt;index id=\"api-index-full\"&gt;\n"
"\t\t&lt;title&gt;API Index&lt;/title&gt;\n"
"\t\t&lt;xi:include href=\"xml/api-index-full.xml\"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;\n"
"\t&lt;/index&gt;\n"
"\t&lt;index id=\"api-index-deprecated\"&gt;\n"
"\t\t&lt;title&gt;Index of deprecated symbols&lt;/title&gt;\n"
"\t\t&lt;xi:include href=\"xml/api-index-deprecated.xml\"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;\n"
"\t&lt;/index&gt;\n"
"\t&lt;index role=\"0.1.0\"&gt;\n"
"\t\t&lt;title&gt;Index of new symbols in 0.1.0&lt;/title&gt;\n"
"\t\t&lt;xi:include href=\"xml/api-index-0.1.0.xml\"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;\n"
"\t&lt;/index&gt;\n"
"\t&lt;!-- More versions here. --&gt;\n"
"\t&lt;xi:include href=\"xml/annotation-glossary.xml\"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;\n"
"&lt;/part&gt;"
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:337
msgid "D-Bus APIs"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:339
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:352
msgid "The DocBook files can be included in the main <file>*-docs.xml</file> file using:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:356
#, no-wrap
msgid ""
"&lt;chapter&gt;\n"
"  &lt;title&gt;C Interfaces&lt;/title&gt;\n"
"  &lt;partintro&gt;\n"
"    &lt;para&gt;C wrappers for the D-Bus interfaces.&lt;/para&gt;\n"
"  &lt;/partintro&gt;\n"
"\n"
"  &lt;xi:include href=\"xml/SomeDBusService.xml\"/&gt;\n"
"  &lt;xi:include href=\"xml/SomeOtherService.xml\"/&gt;\n"
"&lt;/chapter&gt;"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:366
msgid "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>.)"
msgstr ""

#. (itstool) path: section/title
#: C/documentation.page:375
msgid "Keeping Documentation Up to Date"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:377
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:384
msgid "These tests should always be enabled, by adding the following to your gtk-doc <file>Makefile.am</file>:"
msgstr ""

#. (itstool) path: section/code
#: C/documentation.page:388
#, no-wrap
msgid ""
"TESTS = $(GTKDOC_CHECK)"
msgstr ""

#. (itstool) path: section/p
#: C/documentation.page:390
msgid "They will then be run as part of <cmd>make check</cmd>."
msgstr ""

#. (itstool) path: info/desc
#: C/file-system.page:18
msgid "Accessing the file system"
msgstr ""

#. (itstool) path: page/title
#: C/file-system.page:21
msgid "File System Access"
msgstr ""

#. (itstool) path: synopsis/p
#: C/file-system.page:26
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/file-system.page:37
msgid "Use asynchronous I/O for file access. (<link xref=\"#asynchronous-io\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/file-system.page:41
msgid "Always use appropriate functions to construct file names and paths. (<link xref=\"#file-path-construction\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/file-system.page:45
msgid "Validate file paths are in the expected directories before using them. (<link xref=\"#path-validation-and-sandboxing\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/file-system.page:49
msgid "Use mandatory access control profiles to enforce constraints on file access. (<link xref=\"#path-validation-and-sandboxing\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/file-system.page:58
msgid "Asynchronous I/O"
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:60
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/file-system.page:70
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:78
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:84
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:93
msgid "Files in the user’s home directory do <em>not</em> count as local, as they could be on a networked file system."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:98
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/file-system.page:107
msgid "File Path Construction"
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:109
msgid "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.)"
msgstr ""

#. (itstool) path: example/p
#: C/file-system.page:120
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:128
msgid "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)."
msgstr ""

#. (itstool) path: example/p
#: C/file-system.page:135
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/file-system.page:148
msgid "Path Validation and Sandboxing"
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:150
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:161
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/file-system.page:172
msgid "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."
msgstr ""

#. (itstool) path: info/desc
#: C/gerror.page:18
msgid "Runtime error handling and reporting"
msgstr ""

#. (itstool) path: page/title
#: C/gerror.page:21
msgid "GError"
msgstr ""

#. (itstool) path: section/title
#: C/gerror.page:24
msgid "GError Usage"
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:26
msgid "<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>."
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:33
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:42
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:50
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:58
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/gerror.page:66
msgid "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>."
msgstr ""

#. (itstool) path: info/desc
#: C/glist.page:18
msgid "Linked lists and container types"
msgstr ""

#. (itstool) path: page/title
#: C/glist.page:21
msgid "GList"
msgstr ""

#. (itstool) path: section/title
#: C/glist.page:24
msgid "GList Usage"
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:26
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:34
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:45
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/glist.page:54
#, no-wrap
msgid ""
"GList *some_list, *l;\n"
"\n"
"for (l = some_list; l != NULL; l = l-&gt;next)\n"
"  {\n"
"    gpointer element_data = l-&gt;data;\n"
"\n"
"    /* Do something with @element_data. */\n"
"  }"
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:63
msgid "Using an incrementing index instead results in a quadratic decrease in performance (<em>O(N^2)</em> rather than <em>O(N)</em>):"
msgstr ""

#. (itstool) path: section/code
#: C/glist.page:67
#, no-wrap
msgid ""
"GList *some_list;\n"
"guint i;\n"
"\n"
"/* This code is inefficient and should not be used in production. */\n"
"for (i = 0; i &lt; g_list_length (some_list); i++)\n"
"  {\n"
"    gpointer element_data = g_list_nth_data (some_list, i);\n"
"\n"
"    /* Do something with @element_data. */\n"
"  }"
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:78
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/glist.page:84
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/glist.page:89
#, no-wrap
msgid ""
"GPtrArray *some_array;\n"
"guint i;\n"
"\n"
"for (i = 0; i &lt; some_array-&gt;len; i++)\n"
"  {\n"
"    gpointer element_data = some_array-&gt;pdata[i];\n"
"\n"
"    /* Do something with @element_data. */\n"
"  }"
msgstr ""

#. (itstool) path: credit/name
#: C/index.page:13
#: C/writing-good-code.page:15
msgid "Miguel de Icaza"
msgstr ""

#. (itstool) path: credit/name
#: C/index.page:17
#: C/writing-good-code.page:19
msgid "Morten Welinder"
msgstr ""

#. (itstool) path: credit/name
#: C/index.page:26
msgid "GNOME Foundation"
msgstr ""

#. (itstool) path: credit/page
#: C/index.page:27
msgid "http://foundation.gnome.org/"
msgstr ""

#. (itstool) path: info/desc
#. (itstool) path: page/title
#: C/index.page:32
#: C/index.page:37
msgid "GNOME Programming Guidelines"
msgstr ""

#. (itstool) path: info/title
#: C/index.page:34
msgctxt "link:trail"
msgid "Programming Guidelines"
msgstr ""

#. (itstool) path: page/p
#: C/index.page:39
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/index.page:50
msgid "This guide has a two-fold purpose:"
msgstr ""

#. (itstool) path: item/p
#: C/index.page:56
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/index.page:65
msgid "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."
msgstr ""

#. (itstool) path: info/title
#: C/index.page:75
msgctxt "link:trail"
msgid "General Guidelines"
msgstr ""

#. (itstool) path: section/title
#: C/index.page:77
msgid "General Guidelines"
msgstr ""

#. (itstool) path: info/title
#: C/index.page:83
msgctxt "link:trail"
msgid "Maintainer Guidelines"
msgstr ""

#. (itstool) path: section/title
#: C/index.page:85
msgid "Maintainer Guidelines"
msgstr ""

#. (itstool) path: info/title
#: C/index.page:91
msgctxt "link:trail"
msgid "Specific How-Tos"
msgstr ""

#. (itstool) path: section/title
#: C/index.page:93
msgid "Specific How-Tos"
msgstr ""

#. (itstool) path: info/title
#: C/index.page:99
msgctxt "link:trail"
msgid "References"
msgstr ""

#. (itstool) path: section/title
#: C/index.page:101
msgid "References"
msgstr ""

#. (itstool) path: info/desc
#: C/introspection.page:17
msgid "GObject Introspection support in library code"
msgstr ""

#. (itstool) path: page/title
#: C/introspection.page:20
msgid "Introspection"
msgstr ""

#. (itstool) path: synopsis/p
#: C/introspection.page:25
msgid "<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."
msgstr ""

#. (itstool) path: synopsis/p
#: C/introspection.page:37
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/introspection.page:46
msgid "Enable introspection for all libraries. (<link xref=\"#using-introspection\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/introspection.page:50
msgid "Pay attention to warnings from <cmd>g-ir-scanner</cmd> and <code>introspectable=\"0\"</code> attributes in GIR files. (<link xref=\"#using-introspection\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/introspection.page:55
msgid "Add introspection annotations to all documentation comments. (<link xref=\"#using-introspection\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/introspection.page:59
msgid "Design APIs to be introspectable from the start. (<link xref=\"#api-design\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/introspection.page:67
msgid "Using Introspection"
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:69
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:77
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:88
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:98
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:108
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/introspection.page:119
msgid "API Design"
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:121
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:134
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:143
msgid "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>)."
msgstr ""

#. (itstool) path: section/p
#: C/introspection.page:151
msgid "<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."
msgstr ""

#. (itstool) path: info/desc
#: C/logging.page:18
msgid "Logging debug and information output from libraries and programs"
msgstr ""

#. (itstool) path: page/title
#: C/logging.page:23
msgid "Logging"
msgstr ""

#. (itstool) path: synopsis/p
#: C/logging.page:28
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:40
msgid "Use the GLib logging framework instead of logging directly to stderr and stdout. (<link xref=\"#glib-logging-framework\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:44
msgid "If systemd can be a dependency of the project, consider logging directly to the journal. (<link xref=\"#journald-integration\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:48
msgid "Do not implement log rotation and deletion; leave that to system services. (<link xref=\"#log-rotation\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/logging.page:56
msgid "GLib Logging Framework"
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:58
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:72
msgid "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>."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:76
msgid "Multiple logging domains, which can be processed separately."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:79
msgid "Multiple log levels, which can be processed separately. For example, this allows debug messages to be turned on and off at runtime."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:83
msgid "Support for automatically aborting a program on ‘fatal’ messages."
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:88
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:99
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:105
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:112
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/logging.page:118
#, no-wrap
msgid ""
"\n"
"static const gchar *\n"
"log_level_to_string (GLogLevelFlags level)\n"
"{\n"
"  switch (level)\n"
"    {\n"
"      case G_LOG_LEVEL_ERROR: return \"ERROR\";\n"
"      case G_LOG_LEVEL_CRITICAL: return \"CRITICAL\";\n"
"      case G_LOG_LEVEL_WARNING: return \"WARNING\";\n"
"      case G_LOG_LEVEL_MESSAGE: return \"MESSAGE\";\n"
"      case G_LOG_LEVEL_INFO: return \"INFO\";\n"
"      case G_LOG_LEVEL_DEBUG: return \"DEBUG\";\n"
"      default: return \"UNKNOWN\";\n"
"    }\n"
"}\n"
"\n"
"static void\n"
"log_handler_cb (const gchar    *log_domain,\n"
"                GLogLevelFlags  log_level,\n"
"                const gchar    *message,\n"
"                gpointer        user_data)\n"
"{\n"
"  const gchar *log_level_str;\n"
"\n"
"  /* Ignore debug messages if disabled. */\n"
"  if (!debug_enabled &amp;&amp; (log_level &amp; G_LOG_LEVEL_DEBUG))\n"
"    {\n"
"      return;\n"
"    }\n"
"\n"
"  log_level_str = log_level_to_string (log_level &amp; G_LOG_LEVEL_MASK);\n"
"\n"
"  /* Use g_printerr() for warnings and g_print() otherwise. */\n"
"  if (flags &lt;= G_LOG_LEVEL_WARNING)\n"
"    {\n"
"      g_printerr (\"%s: %s: %s\\n\", log_domain, log_level_str, message);\n"
"    }\n"
"  else\n"
"    {\n"
"      g_print (\"%s: %s: %s\\n\", log_domain, log_level_str, message);\n"
"    }\n"
"}\n"
"\n"
"g_log_set_handler (\"log-domain\",\n"
"                   G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION,\n"
"                   log_handler_cb, NULL);"
msgstr ""

#. (itstool) path: section/title
#: C/logging.page:166
msgid "Exceptions"
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:169
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:175
msgid "Do not use <code>g_warning()</code> in library code. Use <link xref=\"gerror\"><code>GError</code>s</link> instead."
msgstr ""

#. (itstool) path: item/p
#: C/logging.page:179
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/logging.page:189
msgid "journald Integration"
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:191
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:202
msgid "For more information, see this <link href=\"http://0pointer.de/blog/projects/journal-submit.html\">article on logging to the journal</link>."
msgstr ""

#. (itstool) path: section/title
#: C/logging.page:210
msgid "Log Rotation"
msgstr ""

#. (itstool) path: section/p
#: C/logging.page:212
msgid "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>."
msgstr ""

#. (itstool) path: credit/years
#: C/main-contexts.page:13
msgid "2014–2015"
msgstr ""

#. (itstool) path: info/desc
#: C/main-contexts.page:18
msgid "GLib main contexts, invoking functions in other threads, and the event loop"
msgstr ""

#. (itstool) path: page/title
#: C/main-contexts.page:24
msgid "GLib Main Contexts"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:30
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:37
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:43
msgid "Liberally use assertions to check which context executes each function, and add these assertions when first writing the code (<link xref=\"#checking-threading\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:48
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:53
msgid "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\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:62
msgid "What is <code>GMainContext</code>?"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:64
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:74
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:84
msgid "Prepare sources, determining if any of them are ready to dispatch immediately."
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:88
msgid "Poll the sources, blocking the current thread until an event is received for one of the sources."
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:92
msgid "Check which of the sources received an event (several could have)."
msgstr ""

#. (itstool) path: item/p
#: C/main-contexts.page:95
msgid "Dispatch callbacks from those sources."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:100
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:108
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:121
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:137
msgid "<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."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:149
msgid "What is <code>GMainLoop</code>?"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:151
msgid "<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>):"
msgstr ""

#. (itstool) path: section/code
#: C/main-contexts.page:157
#, no-wrap
msgid ""
"loop-&gt;is_running = TRUE;\n"
"while (loop-&gt;is_running)\n"
"  {\n"
"    g_main_context_iteration (context, TRUE);\n"
"  }"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:163
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:170
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:178
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:186
msgid "Default Contexts"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:188
msgid "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\"/>.)"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:200
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:214
msgid "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>."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:227
msgid "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>."
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:234
#, no-wrap
msgid ""
"\n"
"typedef struct {\n"
"  GMainLoop *main_loop;\n"
"  guint n_remaining;\n"
"} WriteData;\n"
"\n"
"/* This is always called in the same thread as thread_cb() because\n"
" * it’s always dispatched in the @worker_context. */\n"
"static void\n"
"write_cb (GObject      *source_object,\n"
"          GAsyncResult *result,\n"
"          gpointer      user_data)\n"
"{\n"
"  WriteData *data = user_data;\n"
"  GOutputStream *stream = G_OUTPUT_STREAM (source_object);\n"
"  GError *error = NULL;\n"
"  gssize len;\n"
"\n"
"  /* Finish the write. */\n"
"  len = g_output_stream_write_finish (stream, result, &amp;error);\n"
"  if (error != NULL)\n"
"    {\n"
"      g_error (\"Error: %s\", error-&gt;message);\n"
"      g_error_free (error);\n"
"    }\n"
"\n"
"  /* Check whether all parallel operations have finished. */\n"
"  write_data-&gt;n_remaining--;\n"
"\n"
"  if (write_data-&gt;n_remaining == 0)\n"
"    {\n"
"      g_main_loop_quit (write_data-&gt;main_loop);\n"
"    }\n"
"}\n"
"\n"
"/* This is called in a new thread. */\n"
"static void\n"
"thread_cb (GTask        *task,\n"
"           gpointer      source_object,\n"
"           gpointer      task_data,\n"
"           GCancellable *cancellable)\n"
"{\n"
"  /* These streams come from somewhere else in the program: */\n"
"  GOutputStream *output_stream1, *output_stream;\n"
"  GMainContext *worker_context;\n"
"  GBytes *data;\n"
"  const guint8 *buf;\n"
"  gsize len;\n"
"\n"
"  /* Set up a worker context for the writes’ callbacks. */\n"
"  worker_context = g_main_context_new ();\n"
"  g_main_context_push_thread_default (worker_context);\n"
"\n"
"  /* Set up the writes. */\n"
"  write_data.n_remaining = 2;\n"
"  write_data.main_loop = g_main_loop_new (worker_context, FALSE);\n"
"\n"
"  data = g_task_get_task_data (task);\n"
"  buf = g_bytes_get_data (data, &amp;len);\n"
"\n"
"  g_output_stream_write_async (output_stream1, buf, len,\n"
"                               G_PRIORITY_DEFAULT, NULL, write_cb,\n"
"                               &amp;write_data);\n"
"  g_output_stream_write_async (output_stream2, buf, len,\n"
"                               G_PRIORITY_DEFAULT, NULL, write_cb,\n"
"                               &amp;write_data);\n"
"\n"
"  /* Run the main loop until both writes have finished. */\n"
"  g_main_loop_run (write_data.main_loop);\n"
"  g_task_return_boolean (task, TRUE);  /* ignore errors */\n"
"\n"
"  g_main_loop_unref (write_data.main_loop);\n"
"\n"
"  g_main_context_pop_thread_default (worker_context);\n"
"  g_main_context_unref (worker_context);\n"
"}\n"
"\n"
"/* This can be called from any thread. Its @callback will always be\n"
" * dispatched in the thread which currently owns\n"
" * @interesting_context. */\n"
"void\n"
"parallel_writes_async (GBytes              *data,\n"
"                       GMainContext        *interesting_context,\n"
"                       GCancellable        *cancellable,\n"
"                       GAsyncReadyCallback  callback,\n"
"                       gpointer             user_data)\n"
"{\n"
"  GTask *task;\n"
"\n"
"  g_main_context_push_thread_default (interesting_context);\n"
"\n"
"  task = g_task_new (NULL, cancellable, callback, user_data);\n"
"  g_task_set_task_data (task, data,\n"
"                        (GDestroyNotify) g_bytes_unref);\n"
"  g_task_run_in_thread (task, thread_cb);\n"
"  g_object_unref (task);\n"
"\n"
"  g_main_context_pop_thread_default (interesting_context);\n"
"}"
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:336
msgid "Implicit Use of the Global-Default Main Context"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:338
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:345
msgid "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."
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:356
msgid "Do not use"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:357
msgid "Use instead"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:362
msgid "<code>g_timeout_add()</code>"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:363
msgid "<code>g_timeout_source_new()</code>"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:366
msgid "<code>g_idle_add()</code>"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:367
msgid "<code>g_idle_source_new()</code>"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:370
msgid "<code>g_child_watch_add()</code>"
msgstr ""

#. (itstool) path: td/p
#: C/main-contexts.page:371
msgid "<code>g_child_watch_source_new()</code>"
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:377
msgid "So to delay some computation in a worker thread, use the following code:"
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:381
#, no-wrap
msgid ""
"\n"
"static guint\n"
"schedule_computation (guint delay_seconds)\n"
"{\n"
"  GSource *source = NULL;\n"
"  GMainContext *context;\n"
"  guint id;\n"
"\n"
"  /* Get the calling context. */\n"
"  context = g_main_context_get_thread_default ();\n"
"\n"
"  source = g_timeout_source_new_seconds (delay_seconds);\n"
"  g_source_set_callback (source, do_computation, NULL, NULL);\n"
"  id = g_source_attach (source, context);\n"
"  g_source_unref (source);\n"
"\n"
"  /* The ID can be used with the same @context to\n"
"   * cancel the scheduled computation if needed. */\n"
"  return id;\n"
"}\n"
"\n"
"static void\n"
"do_computation (gpointer user_data)\n"
"{\n"
"  /* … */\n"
"}"
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:412
msgid "Using <code>GMainContext</code> in a Library"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:414
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:422
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:431
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:442
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:451
msgid "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\"/>.)"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:458
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:468
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:479
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:487
msgid "Ensuring Functions are Called in the Right Context"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:489
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:503
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:511
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:523
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:533
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:542
msgid "Principles of Invocation"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:544
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:551
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:562
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:574
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:584
msgid "The example below demonstrates the underlying principles, but there are convenience methods explained below which simplify things."
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:589
#, no-wrap
msgid ""
"\n"
"/* Main function for the background thread, thread1. */\n"
"static gpointer\n"
"thread1_main (gpointer user_data)\n"
"{\n"
"  GMainContext *thread1_main_context = user_data;\n"
"  GMainLoop *main_loop;\n"
"\n"
"  /* Set up the thread’s context and run it forever. */\n"
"  g_main_context_push_thread_default (thread1_main_context);\n"
"\n"
"  main_loop = g_main_loop_new (thread1_main_context, FALSE);\n"
"  g_main_loop_run (main_loop);\n"
"  g_main_loop_unref (main_loop);\n"
"\n"
"  g_main_context_pop_thread_default (thread1_main_context);\n"
"  g_main_context_unref (thread1_main_context);\n"
"\n"
"  return NULL;\n"
"}\n"
"\n"
"/* A data closure structure to carry multiple variables between\n"
" * threads. */\n"
"typedef struct {\n"
"  gchar   *some_string;  /* owned */\n"
"  guint    some_int;\n"
"  GObject *some_object;  /* owned */\n"
"} MyFuncData;\n"
"\n"
"static void\n"
"my_func_data_free (MyFuncData *data)\n"
"{\n"
"  g_free (data-&gt;some_string);\n"
"  g_clear_object (&amp;data-&gt;some_object);\n"
"  g_free (data);\n"
"}\n"
"\n"
"static void\n"
"my_func (const gchar *some_string,\n"
"         guint        some_int,\n"
"         GObject     *some_object)\n"
"{\n"
"  /* Do something long and CPU intensive! */\n"
"}\n"
"\n"
"/* Convert an idle callback into a call to my_func(). */\n"
"static gboolean\n"
"my_func_idle (gpointer user_data)\n"
"{\n"
"  MyFuncData *data = user_data;\n"
"\n"
"  my_func (data-&gt;some_string, data-&gt;some_int, data-&gt;some_object);\n"
"\n"
"  return G_SOURCE_REMOVE;\n"
"}\n"
"\n"
"/* Function to be called in the main thread to schedule a call to\n"
" * my_func() in thread1, passing the given parameters along. */\n"
"static void\n"
"invoke_my_func (GMainContext *thread1_main_context,\n"
"                const gchar  *some_string,\n"
"                guint         some_int,\n"
"                GObject      *some_object)\n"
"{\n"
"  GSource *idle_source;\n"
"  MyFuncData *data;\n"
"\n"
"  /* Create a data closure to pass all the desired variables\n"
"   * between threads. */\n"
"  data = g_new0 (MyFuncData, 1);\n"
"  data-&gt;some_string = g_strdup (some_string);\n"
"  data-&gt;some_int = some_int;\n"
"  data-&gt;some_object = g_object_ref (some_object);\n"
"\n"
"  /* Create a new idle source, set my_func() as the callback with\n"
"   * some data to be passed between threads, bump up the priority\n"
"   * and schedule it by attaching it to thread1’s context. */\n"
"  idle_source = g_idle_source_new ();\n"
"  g_source_set_callback (idle_source, my_func_idle, data,\n"
"                         (GDestroyNotify) my_func_data_free);\n"
"  g_source_set_priority (idle_source, G_PRIORITY_DEFAULT);\n"
"  g_source_attach (idle_source, thread1_main_context);\n"
"  g_source_unref (idle_source);\n"
"}\n"
"\n"
"/* Main function for the main thread. */\n"
"static void\n"
"main (void)\n"
"{\n"
"  GThread *thread1;\n"
"  GMainContext *thread1_main_context;\n"
"\n"
"  /* Spawn a background thread and pass it a reference to its\n"
"   * GMainContext. Retain a reference for use in this thread\n"
"   * too. */\n"
"  thread1_main_context = g_main_context_new ();\n"
"  g_thread_new (\"thread1\", thread1_main,\n"
"                g_main_context_ref (thread1_main_context));\n"
"\n"
"  /* Maybe set up your UI here, for example. */\n"
"\n"
"  /* Invoke my_func() in the other thread. */\n"
"  invoke_my_func (thread1_main_context,\n"
"                  \"some data which needs passing between threads\",\n"
"                  123456, some_object);\n"
"\n"
"  /* Continue doing other work. */\n"
"}"
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:698
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:706
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:720
msgid "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>."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:729
msgid "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\"/>)."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:735
msgid "<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."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:744
msgid "Convenience Method: <code>g_main_context_invoke_full()</code>"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:748
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:757
msgid "<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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:764
msgid "Modifying the earlier example, the <code>invoke_my_func()</code> function can be replaced by the following:"
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:769
#, no-wrap
msgid ""
"\n"
"static void\n"
"invoke_my_func (GMainContext *thread1_main_context,\n"
"                const gchar  *some_string,\n"
"                guint         some_int,\n"
"                GObject      *some_object)\n"
"{\n"
"  MyFuncData *data;\n"
"\n"
"  /* Create a data closure to pass all the desired variables\n"
"   * between threads. */\n"
"  data = g_new0 (MyFuncData, 1);\n"
"  data-&gt;some_string = g_strdup (some_string);\n"
"  data-&gt;some_int = some_int;\n"
"  data-&gt;some_object = g_object_ref (some_object);\n"
"\n"
"  /* Invoke the function. */\n"
"  g_main_context_invoke_full (thread1_main_context,\n"
"                              G_PRIORITY_DEFAULT, my_func_idle,\n"
"                              data,\n"
"                              (GDestroyNotify) my_func_data_free);\n"
"}"
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:792
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:806
msgid "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)."
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:818
msgid "Checking Threading"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:820
msgid "It is useful to document which thread each function should be called in, in the form of an assertion:"
msgstr ""

#. (itstool) path: section/code
#: C/main-contexts.page:824
#, no-wrap
msgid ""
"\n"
"g_assert (g_main_context_is_owner (expected_main_context));"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:827
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:835
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:844
msgid "For example, instead of using the following when emitting a signal:"
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:847
#, no-wrap
msgid ""
"\n"
"guint param1;  /* arbitrary example parameters */\n"
"gchar *param2;\n"
"guint retval = 0;\n"
"\n"
"g_signal_emit_by_name (my_object, \"some-signal\",\n"
"                       param1, param2, &amp;retval);"
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:855
msgid "The following can be used:"
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:858
#, no-wrap
msgid ""
"\n"
"static guint\n"
"emit_some_signal (GObject     *my_object,\n"
"                  guint        param1,\n"
"                  const gchar *param2)\n"
"{\n"
"  guint retval = 0;\n"
"\n"
"  g_assert (g_main_context_is_owner (expected_main_context));\n"
"\n"
"  g_signal_emit_by_name (my_object, \"some-signal\",\n"
"                         param1, param2, &amp;retval);\n"
"\n"
"  return retval;\n"
"}"
msgstr ""

#. (itstool) path: section/title
#: C/main-contexts.page:877
msgid "<code>GTask</code>"
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:879
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/main-contexts.page:886
msgid "<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."
msgstr ""

#. (itstool) path: example/p
#: C/main-contexts.page:894
msgid "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:"
msgstr ""

#. (itstool) path: example/code
#: C/main-contexts.page:900
#, no-wrap
msgid ""
"\n"
"/* This will be invoked in thread1. */\n"
"static gboolean\n"
"my_func_idle (gpointer user_data)\n"
"{\n"
"  GTask *task = G_TASK (user_data);\n"
"  MyFuncData *data;\n"
"  gboolean retval;\n"
"\n"
"  /* Call my_func() and propagate its returned boolean to\n"
"   * the main thread. */\n"
"  data = g_task_get_task_data (task);\n"
"  retval = my_func (data-&gt;some_string, data-&gt;some_int,\n"
"                    data-&gt;some_object);\n"
"  g_task_return_boolean (task, retval);\n"
"\n"
"  return G_SOURCE_REMOVE;\n"
"}\n"
"\n"
"/* Whichever thread this is invoked in, the @callback will be\n"
" * invoked in, once my_func() has finished and returned a result. */\n"
"static void\n"
"invoke_my_func_with_result (GMainContext        *thread1_main_context,\n"
"                            const gchar         *some_string,\n"
"                            guint                some_int,\n"
"                            GObject             *some_object,\n"
"                            GAsyncReadyCallback  callback,\n"
"                            gpointer             user_data)\n"
"{\n"
"  MyFuncData *data;\n"
"\n"
"  /* Create a data closure to pass all the desired variables\n"
"   * between threads. */\n"
"  data = g_new0 (MyFuncData, 1);\n"
"  data-&gt;some_string = g_strdup (some_string);\n"
"  data-&gt;some_int = some_int;\n"
"  data-&gt;some_object = g_object_ref (some_object);\n"
"\n"
"  /* Create a GTask to handle returning the result to the current\n"
"   * thread-default main context. */\n"
"  task = g_task_new (NULL, NULL, callback, user_data);\n"
"  g_task_set_task_data (task, data,\n"
"                        (GDestroyNotify) my_func_data_free);\n"
"\n"
"  /* Invoke the function. */\n"
"  g_main_context_invoke_full (thread1_main_context,\n"
"                              G_PRIORITY_DEFAULT, my_func_idle,\n"
"                              task,\n"
"                              (GDestroyNotify) g_object_unref);\n"
"}"
msgstr ""

#. (itstool) path: info/desc
#: C/memory-management.page:17
msgid "Managing memory allocation and deallocation in C"
msgstr ""

#. (itstool) path: page/title
#: C/memory-management.page:20
msgid "Memory Management"
msgstr ""

#. (itstool) path: page/p
#: C/memory-management.page:50
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/memory-management.page:57
msgid "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>."
msgstr ""

#. (itstool) path: synopsis/p
#: C/memory-management.page:67
msgid "There are three situations to avoid, in order of descending importance:"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:72
msgid "Using memory after freeing it (use-after-free)."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:73
msgid "Using memory before allocating it."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:74
msgid "Not freeing memory after allocating it (leaking)."
msgstr ""

#. (itstool) path: synopsis/p
#: C/memory-management.page:77
msgid "Key principles, in no particular order:"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:82
msgid "Determine and document whether each variable is owned or unowned. They must never change from one to the other at runtime. (<link xref=\"#principles\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:87
msgid "Determine and document the ownership transfers at function boundaries. (<link xref=\"#principles\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:91
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:96
msgid "Use reference counting rather than explicit finalization where possible. (<link xref=\"#reference-counting\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:100
msgid "Use GLib convenience functions like <link xref=\"#g-clear-object\"><code>g_clear_object()</code></link> where possible. (<link xref=\"#convenience-functions\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:105
msgid "Do not split memory management across code paths. (<link xref=\"#principles\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:109
msgid "Use the single-path cleanup pattern for large or complex functions. (<link xref=\"#single-path-cleanup\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:113
msgid "Leaks should be checked for using Valgrind or the address sanitizer. (<link xref=\"#verification\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:121
msgid "Principles of Memory Management"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:123
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:140
msgid "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?"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:149
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:155
msgid "For example, consider the functions:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:159
#, no-wrap
msgid ""
"gchar *generate_string (const gchar *template);\n"
"void print_string (const gchar *str);"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:162
msgid "The following code has been annotated to note where the ownership transfers happen:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:167
#, no-wrap
msgid ""
"gchar *my_str = NULL;  /* owned */\n"
"const gchar *template;  /* unowned */\n"
"GValue value = G_VALUE_INIT;  /* owned */\n"
"g_value_init (&amp;value, G_TYPE_STRING);\n"
"\n"
"/* Transfers ownership of a string from the function to the variable. */\n"
"template = \"XXXXXX\";\n"
"my_str = generate_string (template);\n"
"\n"
"/* No ownership transfer. */\n"
"print_string (my_str);\n"
"\n"
"/* Transfer ownership. We no longer have to free @my_str. */\n"
"g_value_take_string (&amp;value, my_str);\n"
"\n"
"/* We still have ownership of @value, so free it before it goes out of scope. */\n"
"g_value_unset (&amp;value);"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:185
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:195
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:208
msgid "(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.)"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:216
msgid "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:"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:229
msgid "Function name"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:230
msgid "Convention 1 (standard)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:231
msgid "Convention 2 (alternate)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:232
msgid "Convention 3 (<cmd>gdbus-codegen</cmd>)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:237
msgid "get"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:238
#: C/memory-management.page:254
#: C/memory-management.page:259
#: C/memory-management.page:260
#: C/memory-management.page:261
msgid "No transfer"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:239
msgid "Any transfer"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:240
#: C/memory-management.page:245
#: C/memory-management.page:266
#: C/memory-management.page:273
#: C/memory-management.page:274
#: C/memory-management.page:275
msgid "Full transfer"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:244
msgid "dup"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:246
#: C/memory-management.page:247
#: C/memory-management.page:252
#: C/memory-management.page:253
#: C/memory-management.page:267
#: C/memory-management.page:268
msgid "Unused"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:251
msgid "peek"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:258
msgid "set"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:265
msgid "take"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:272
msgid "steal"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:280
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:288
msgid "If the type has an introspection <code>(transfer)</code> annotation, look at that."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:292
msgid "Otherwise, if the type is <code>const</code>, there is no transfer."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:295
msgid "Otherwise, if the function documentation explicitly specifies the return value must be freed, there is full or container transfer."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:299
msgid "Otherwise, if the function is named ‘dup’, ‘take’ or ‘steal’, there is full or container transfer."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:303
msgid "Otherwise, if the function is named ‘peek’, there is no transfer."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:306
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:314
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:322
msgid "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\"/>."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:331
msgid "Assignments"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:338
msgid "Assignment from/to"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:339
msgid "Owned destination"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:340
msgid "Unowned destination"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:346
#: C/memory-management.page:394
#: C/memory-management.page:441
msgid "Owned source"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:348
msgid "Copy or move the source to the destination."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:351
#, no-wrap
msgid ""
"owned_dest = copy (owned_src)"
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:352
#, no-wrap
msgid ""
"owned_dest = owned_src; owned_src = NULL"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:355
msgid "Pure assignment, assuming the unowned variable is not used after the owned one is freed."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:359
#, no-wrap
msgid ""
"unowned_dest = owned_src"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:364
#: C/memory-management.page:411
#: C/memory-management.page:457
msgid "Unowned source"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:366
msgid "Copy the source to the destination."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:367
#, no-wrap
msgid ""
"owned_dest = copy (unowned_src)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:370
msgid "Pure assignment."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:371
#, no-wrap
msgid ""
"unowned_dest = unowned_src"
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:379
msgid "Function Calls"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:386
msgid "Call from/to"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:387
msgid "Transfer full parameter"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:388
msgid "Transfer none parameter"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:396
msgid "Copy or move the source for the parameter."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:399
#, no-wrap
msgid ""
"function_call (copy (owned_src))"
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:400
#, no-wrap
msgid ""
"function_call (owned_src); owned_src = NULL"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:403
#: C/memory-management.page:417
msgid "Pure parameter passing."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:406
#, no-wrap
msgid ""
"function_call (owned_src)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:413
msgid "Copy the source for the parameter."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:414
#, no-wrap
msgid ""
"function_call (copy (unowned_src))"
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:418
#, no-wrap
msgid ""
"function_call (unowned_src)"
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:426
msgid "Function Returns"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:433
msgid "Return from/to"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:434
msgid "Transfer full return"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:435
msgid "Transfer none return"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:443
msgid "Pure variable return."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:446
#, no-wrap
msgid ""
"return owned_src"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:449
msgid "Invalid. The source needs to be freed, so the return value would use freed memory — a use-after-free error."
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:459
msgid "Copy the source for the return."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:460
#, no-wrap
msgid ""
"return copy (unowned_src)"
msgstr ""

#. (itstool) path: td/p
#: C/memory-management.page:463
msgid "Pure variable passing."
msgstr ""

#. (itstool) path: td/code
#: C/memory-management.page:464
#, no-wrap
msgid ""
"return unowned_src"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:475
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:482
msgid "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."
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:497
#, no-wrap
msgid ""
"/**\n"
" * g_value_take_string:\n"
" * @value: (transfer none): an initialized #GValue\n"
" * @str: (transfer full): string to set it to\n"
" *\n"
" * Function documentation goes here.\n"
" */\n"
"\n"
"/**\n"
" * generate_string:\n"
" * @template: (transfer none): a template to follow when generating the string\n"
" *\n"
" * Function documentation goes here.\n"
" *\n"
" * Returns: (transfer full): a newly generated string\n"
" */"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:514
msgid "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."
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:519
#, no-wrap
msgid ""
"GObject *some_owned_object = NULL;  /* owned */\n"
"GObject *some_unowned_object;  /* unowned */"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:522
msgid "The documentation for <link xref=\"#container-types\"/> is similarly only a convention; it includes the type of the contained elements too:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:526
#, no-wrap
msgid ""
"GPtrArray/*&lt;owned gchar*&gt;*/ *some_unowned_string_array;  /* unowned */\n"
"GPtrArray/*&lt;owned gchar*&gt;*/ *some_owned_string_array = NULL;  /* owned */\n"
"GPtrArray/*&lt;unowned GObject*&gt;*/ *some_owned_object_array = NULL;  /* owned */"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:530
msgid "Note also that owned variables should always be initialized so that freeing them is more convenient. See <link xref=\"#convenience-functions\"/>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:536
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:546
msgid "Reference Counting"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:548
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:555
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:569
msgid "See <link xref=\"#g-clear-object\"/> for a convenient way of handling GObject references."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:574
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:596
msgid "Floating References"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:598
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:610
msgid "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."
msgstr ""

#. (itstool) path: example/p
#: C/memory-management.page:618
msgid "Floating references allow the following code to be simplified:"
msgstr ""

#. (itstool) path: example/code
#: C/memory-management.page:621
#, no-wrap
msgid ""
"GtkWidget *new_widget;\n"
"\n"
"new_widget = gtk_some_widget_new ();\n"
"gtk_container_add (some_container, new_widget);\n"
"g_object_unref (new_widget);"
msgstr ""

#. (itstool) path: example/p
#: C/memory-management.page:627
msgid "Instead, the following code can be used, with the <code>GtkContainer</code> assuming ownership of the floating reference:"
msgstr ""

#. (itstool) path: example/code
#: C/memory-management.page:632
#, no-wrap
msgid ""
"\n"
"gtk_container_add (some_container, gtk_some_widget_new ());"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:636
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:643
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:650
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:658
msgid "Convenience Functions"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:660
msgid "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)."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:669
msgid "<code>g_clear_object()</code>"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:671
msgid "<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>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:679
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:685
msgid "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\"/>:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:691
#, no-wrap
msgid ""
"void\n"
"my_function (void)\n"
"{\n"
"  GObject *some_object = NULL;  /* owned */\n"
"\n"
"  if (rand ())\n"
"    {\n"
"      some_object = create_new_object ();\n"
"      /* do something with the object */\n"
"    }\n"
"\n"
"  g_clear_object (&amp;some_object);\n"
"}"
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:707
msgid "<code>g_list_free_full()</code>"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:709
msgid "<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."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:721
msgid "<code>g_hash_table_new_full()</code>"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:723
msgid "<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>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:734
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:741
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:750
msgid "Container Types"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:752
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:762
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:770
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:776
#, no-wrap
msgid ""
"/**\n"
" * g_ptr_array_add:\n"
" * @array: a #GPtrArray\n"
" * @str: (transfer full): string to add\n"
" */\n"
"void\n"
"g_ptr_array_add (GPtrArray *array,\n"
"                 gchar     *str);"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:785
msgid "So, for example, constant (unowned) strings must be added to the array using <code>g_ptr_array_add (array, g_strdup (\"constant string\"))</code>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:790
msgid "Whereas if the elements are unowned, the definition is effectively:"
msgstr ""

#. (itstool) path: section/code
#: C/memory-management.page:793
#, no-wrap
msgid ""
"/**\n"
" * g_ptr_array_add:\n"
" * @array: a #GPtrArray\n"
" * @str: (transfer none): string to add\n"
" */\n"
"void\n"
"g_ptr_array_add (GPtrArray   *array,\n"
"                 const gchar *str);"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:802
msgid "Here, constant strings can be added without copying them: <code>g_ptr_array_add (array, \"constant string\")</code>."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:807
msgid "See <link xref=\"#documentation\"/> for examples of comments to add to variable definitions to annotate them with the element type and ownership."
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:814
msgid "Single-Path Cleanup"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:816
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:827
msgid "This approach has two requirements:"
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:831
msgid "The function returns from a single point, and uses <code>goto</code> to reach that point from other paths."
msgstr ""

#. (itstool) path: item/p
#: C/memory-management.page:835
msgid "All owned variables are set to <code>NULL</code> when initialized or when ownership is transferred away from them."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:841
msgid "The example below is for a small function (for brevity), but should illustrate the principles for application of the pattern to larger functions:"
msgstr ""

#. (itstool) path: listing/title
#: C/memory-management.page:848
msgid "Single-Path Cleanup Example"
msgstr ""

#. (itstool) path: listing/desc
#: C/memory-management.page:849
msgid "Example of implementing single-path cleanup for a simple function"
msgstr ""

#. (itstool) path: listing/code
#: C/memory-management.page:852
#, no-wrap
msgid ""
"GObject *\n"
"some_function (GError **error)\n"
"{\n"
"  gchar *some_str = NULL;  /* owned */\n"
"  GObject *temp_object = NULL;  /* owned */\n"
"  const gchar *temp_str;\n"
"  GObject *my_object = NULL;  /* owned */\n"
"  GError *child_error = NULL;  /* owned */\n"
"\n"
"  temp_object = generate_object ();\n"
"  temp_str = \"example string\";\n"
"\n"
"  if (rand ())\n"
"    {\n"
"      some_str = g_strconcat (temp_str, temp_str, NULL);\n"
"    }\n"
"  else\n"
"    {\n"
"      some_operation_which_might_fail (&amp;child_error);\n"
"\n"
"      if (child_error != NULL)\n"
"        {\n"
"          goto done;\n"
"        }\n"
"\n"
"      my_object = generate_wrapped_object (temp_object);\n"
"    }\n"
"\n"
"done:\n"
"  /* Here, @some_str is either NULL or a string to be freed, so can be passed to\n"
"   * g_free() unconditionally.\n"
"   *\n"
"   * Similarly, @temp_object is either NULL or an object to be unreffed, so can\n"
"   * be passed to g_clear_object() unconditionally. */\n"
"  g_free (some_str);\n"
"  g_clear_object (&amp;temp_object);\n"
"\n"
"  /* The pattern can also be used to ensure that the function always returns\n"
"   * either an error or a return value (but never both). */\n"
"  if (child_error != NULL)\n"
"    {\n"
"      g_propagate_error (error, child_error);\n"
"      g_clear_object (&amp;my_object);\n"
"    }\n"
"\n"
"  return my_object;\n"
"}"
msgstr ""

#. (itstool) path: section/title
#: C/memory-management.page:903
msgid "Verification"
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:905
msgid "Memory leaks can be checked for in two ways: static analysis, and runtime leak checking."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:910
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:924
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:933
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/memory-management.page:942
msgid "See <link xref=\"tooling#valgrind\"/> for more information on using Valgrind."
msgstr ""

#. (itstool) path: credit/years
#: C/namespacing.page:12
msgid "2015, 2016"
msgstr ""

#. (itstool) path: info/desc
#: C/namespacing.page:17
msgid "Avoiding symbol conflicts between libraries by namespacing all APIs"
msgstr ""

#. (itstool) path: page/title
#: C/namespacing.page:22
msgid "Namespacing"
msgstr ""

#. (itstool) path: synopsis/p
#: C/namespacing.page:27
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/namespacing.page:36
msgid "GObject APIs"
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:38
msgid "Consistent and complete namespacing of symbols (functions and types) and files is important for two key reasons:"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:43
msgid "Establishing a convention which means developers have to learn fewer symbol names to use the library — they can guess them reliably instead."
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:47
msgid "Ensuring symbols from two projects do not conflict if included in the same file."
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:53
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:63
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:70
msgid "Functions should use <code>lower_case_with_underscores</code>."
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:73
msgid "Structures, types and objects should use <code>CamelCaseWithoutUnderscores</code>."
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:77
msgid "Macros and constants should use <code>UPPER_CASE_WITH_UNDERSCORES</code>."
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:81
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:86
msgid "All methods of a class should also be prefixed with the class name."
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:91
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:98
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:105
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:111
msgid "<file><var>$(includedir)</var>/walbottle-<var>$API_MAJOR</var>/walbottle/schema.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:114
msgid "<file><var>$(includedir)</var>/walbottle-<var>$API_MAJOR</var>/walbottle/writer.h</file>"
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:119
msgid "(The use of <var>$API_MAJOR</var> above is for <link xref=\"parallel-installability\">parallel installability</link>.)"
msgstr ""

#. (itstool) path: section/p
#: C/namespacing.page:124
msgid "For the schema class, the following symbols would be exported (amongst others), following GObject conventions:"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:129
msgid "<code>WblSchema</code> structure"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:130
msgid "<code>WblSchemaClass</code> structure"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:131
msgid "<code>WBL_TYPE_SCHEMA</code> macro"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:132
msgid "<code>WBL_IS_SCHEMA</code> macro"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:133
msgid "<code>wbl_schema_get_type</code> function"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:134
msgid "<code>wbl_schema_new</code> function"
msgstr ""

#. (itstool) path: item/p
#: C/namespacing.page:135
msgid "<code>wbl_schema_load_from_data</code> function"
msgstr ""

#. (itstool) path: credit/name
#: C/parallel-installability.page:10
msgid "Havoc Pennington"
msgstr ""

#. (itstool) path: credit/years
#: C/parallel-installability.page:12
msgid "2002"
msgstr ""

#. (itstool) path: info/desc
#: C/parallel-installability.page:25
msgid "Writing libraries to be future proof through parallel installation"
msgstr ""

#. (itstool) path: page/title
#: C/parallel-installability.page:30
msgid "Parallel Installability"
msgstr ""

#. (itstool) path: synopsis/p
#: C/parallel-installability.page:35
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:43
msgid "Ensure all versions of a library are parallel installable. (<link xref=\"#justification\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:47
msgid "Version all files installed by a library. (<link xref=\"#solution\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:51
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:57
msgid "Install C header files to <file><var>$(includedir)</var>/lib<var>library</var>-<var>version</var>/<var>library</var>/</file>. (<link xref=\"#header-files\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:62
msgid "Install library binaries to <file><var>$(libdir)</var>/lib<var>library</var>-<var>version</var>.so.<var>soname</var></file>. (<link xref=\"#libraries\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:67
msgid "Install pkg-config files to <file><var>$(libdir)</var>/pkgconfig/<var>library</var>-<var>version</var>.pc</file>. (<link xref=\"#pkg-config\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:72
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:78
msgid "Set <code>GETTEXT_PACKAGE</code> to <code><var>library</var>-<var>version</var></code>. (<link xref=\"#gettext\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:83
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:91
msgid "Install daemon binaries to <file><var>$(libexecdir)</var>/<var>library</var>-daemon-<var>version</var></file>. (<link xref=\"#programs\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:96
msgid "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\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:106
msgid "Justification"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:108
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:117
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:123
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:131
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:138
msgid "The alternative, and equally valid, solution is for the library to never break API — the approach taken by <code>libc</code>."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:145
msgid "Solution"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:147
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:154
msgid "For example, say that library <code>Foo</code> traditionally installs these files:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:159
#: C/parallel-installability.page:284
msgid "<file>/usr/include/foo.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:160
msgid "<file>/usr/include/foo-utils.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:161
msgid "<file>/usr/lib/libfoo.so</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:162
msgid "<file>/usr/lib/pkgconfig/foo.pc</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:163
msgid "<file>/usr/share/doc/foo/foo-manual.txt</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:164
msgid "<file>/usr/bin/foo-utility</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:167
msgid "You might modify <code>Foo</code> version 4 to install these files instead:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:172
#: C/parallel-installability.page:261
msgid "<file>/usr/include/foo-4/foo/foo.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:173
msgid "<file>/usr/include/foo-4/foo/utils.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:174
#: C/parallel-installability.page:338
msgid "<file>/usr/lib/libfoo-4.so</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:175
#: C/parallel-installability.page:397
msgid "<file>/usr/lib/pkgconfig/foo-4.pc</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:176
msgid "<file>/usr/share/doc/foo-4/foo-manual.txt</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:177
msgid "<file>/usr/bin/foo-utility-4</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:180
msgid "It could then be parallel installed with version 5:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:184
#: C/parallel-installability.page:262
msgid "<file>/usr/include/foo-5/foo/foo.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:185
msgid "<file>/usr/include/foo-5/foo/utils.h</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:186
#: C/parallel-installability.page:339
msgid "<file>/usr/lib/libfoo-5.so</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:187
#: C/parallel-installability.page:398
msgid "<file>/usr/lib/pkgconfig/foo-5.pc</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:188
msgid "<file>/usr/share/doc/foo-5/foo-manual.txt</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:189
msgid "<file>/usr/bin/foo-utility-5</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:192
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:204
msgid "Version Numbers"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:206
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:214
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:221
msgid "The examples in the following sections assume that the API version and soname are exported from <file>configure.ac</file> using the following code:"
msgstr ""

#. (itstool) path: listing/title
#: C/parallel-installability.page:227
msgid "API Versioning in Autoconf"
msgstr ""

#. (itstool) path: listing/desc
#: C/parallel-installability.page:228
msgid "Code to export the API version and soname from <file>configure.ac</file>"
msgstr ""

#. (itstool) path: listing/code
#: C/parallel-installability.page:231
#, no-wrap
msgid ""
"# Before making a release, the <var>LIBRARY</var>_LT_VERSION string should be modified.\n"
"# The string is of the form c:r:a. Follow these instructions sequentially:\n"
"#\n"
"#  1. If the library source code has changed at all since the last update,\n"
"#     then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).\n"
"#  2. If any interfaces have been added, removed, or changed since the last update,\n"
"#     increment current, and set revision to 0.\n"
"#  3. If any interfaces have been added since the last public release,\n"
"#     then increment age.\n"
"#  4. If any interfaces have been removed or changed since the last public release,\n"
"#     then set age to 0.\n"
"AC_SUBST([<var>LIBRARY</var>_LT_VERSION],[1:0:0])\n"
"\n"
"AC_SUBST([<var>LIBRARY</var>_API_VERSION],[4])"
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:249
msgid "C Header Files"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:251
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/parallel-installability.page:256
#, no-wrap
msgid ""
"#include &lt;foo/foo.h&gt;"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:257
msgid "then I should install these files:"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:265
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:271
msgid "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>?"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:279
msgid "There’s some temptation to keep one of the header files outside of any subdirectory:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:285
msgid "<file>/usr/include/foo-5/foo.h</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:288
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:296
msgid "Versioned header files can be installed from automake using the following code:"
msgstr ""

#. (itstool) path: listing/title
#: C/parallel-installability.page:301
msgid "Header Files in Automake"
msgstr ""

#. (itstool) path: listing/desc
#: C/parallel-installability.page:302
msgid "Code to install versioned header files from <file>Makefile.am</file>"
msgstr ""

#. (itstool) path: listing/code
#: C/parallel-installability.page:305
#, no-wrap
msgid ""
"<var>library</var>includedir = $(includedir)/lib<var>library</var>-@<var>LIBRARY</var>_API_VERSION@/<var>library</var>\n"
"<var>library</var>_headers = \\\n"
"\tlib<var>library</var>/example1.h \\\n"
"\tlib<var>library</var>/example2.h \\\n"
"\t$(NULL)\n"
"\n"
"# The following headers are private, and shouldn't be installed:\n"
"private_headers = \\\n"
"\tlib<var>library</var>/example-private.h \\\n"
"\t$(NULL)\n"
"# The main header simply #includes all other public headers:\n"
"main_header = lib<var>library</var>/<var>library</var>.h\n"
"public_headers = \\\n"
"\t$(main_header) \\\n"
"\t$(<var>library</var>_headers) \\\n"
"\t$(NULL)\n"
"\n"
"<var>library</var>include_HEADERS = $(public_headers)"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:325
msgid "As well as correct versioning, all APIs in installed headers should be <link xref=\"namespacing\">namespaced correctly</link>."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:332
msgid "Libraries"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:334
msgid "Library object files should have a versioned name. For example:"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:342
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:347
msgid "Versioned libraries can be built and installed from automake using the following code:"
msgstr ""

#. (itstool) path: listing/title
#: C/parallel-installability.page:352
msgid "Libraries in Automake"
msgstr ""

#. (itstool) path: listing/desc
#: C/parallel-installability.page:353
msgid "Code to build and install versioned libraries from <file>Makefile.am</file>"
msgstr ""

#. (itstool) path: listing/code
#: C/parallel-installability.page:357
#, no-wrap
msgid ""
"lib_LTLIBRARIES = lib<var>library</var>/lib<var>library</var>-@<var>LIBRARY</var>_API_VERSION@.la\n"
"\n"
"lib<var>library</var>_lib<var>library</var>_@<var>LIBRARY</var>_API_VERSION@_la_SOURCES = \\\n"
"\t$(private_headers) \\\n"
"\t$(<var>library</var>_sources) \\\n"
"\t$(NULL)\n"
"lib<var>library</var>_lib<var>library</var>_@<var>LIBRARY</var>_API_VERSION@_la_CPPFLAGS = …\n"
"lib<var>library</var>_lib<var>library</var>_@<var>LIBRARY</var>_API_VERSION@_la_CFLAGS = …\n"
"lib<var>library</var>_lib<var>library</var>_@<var>LIBRARY</var>_API_VERSION@_la_LIBADD = …\n"
"lib<var>library</var>_lib<var>library</var>_@<var>LIBRARY</var>_API_VERSION@_la_LDFLAGS = \\\n"
"\t-version-info $(<var>LIBRARY</var>_LT_VERSION) \\\n"
"\t$(AM_LDFLAGS) \\\n"
"\t$(NULL)"
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:373
msgid "Library sonames"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:375
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:382
msgid "For this reason, sonames should be used, but <em>in addition</em> to versioned names for libraries. The two solutions address different problems."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:391
msgid "pkg-config Files"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:393
msgid "pkg-config files should have a versioned name. For example:"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:401
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:409
msgid "Versioned pkg-config files can be installed from autoconf and automake using the following code:"
msgstr ""

#. (itstool) path: listing/title
#: C/parallel-installability.page:414
msgid "pkg-config Files in Autoconf and Automake"
msgstr ""

#. (itstool) path: listing/desc
#: C/parallel-installability.page:415
msgid "Code to install versioned pkg-config files from <file>configure.ac</file> and <file>Makefile.am</file>"
msgstr ""

#. (itstool) path: listing/code
#: C/parallel-installability.page:420
#, no-wrap
msgid ""
"AC_CONFIG_FILES([\n"
"lib<var>library</var>/<var>library</var>-$<var>LIBRARY</var>_API_VERSION.pc:lib<var>library</var>/<var>library</var>.pc.in\n"
"],[],\n"
"[<var>LIBRARY</var>_API_VERSION='$<var>LIBRARY</var>_API_VERSION'])"
msgstr ""

#. (itstool) path: listing/code
#: C/parallel-installability.page:425
#, no-wrap
msgid ""
"# Note that the template file is called <var>library</var>.pc.in, but generates a\n"
"# versioned .pc file using some magic in AC_CONFIG_FILES.\n"
"pkgconfigdir = $(libdir)/pkgconfig\n"
"pkgconfig_DATA = lib<var>library</var>/<var>library</var>-$(<var>LIBRARY</var>_API_VERSION).pc\n"
"\n"
"DISTCLEANFILES += $(pkgconfig_DATA)\n"
"EXTRA_DIST += lib<var>library</var>/<var>library</var>.pc.in"
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:436
msgid "Configuration Files"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:438
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:448
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:455
msgid "Gettext Translations"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:457
msgid "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>:"
msgstr ""

#. (itstool) path: section/code
#: C/parallel-installability.page:465
#, no-wrap
msgid ""
"GETTEXT_PACKAGE=foo-4\n"
"AC_SUBST([GETTEXT_PACKAGE])\n"
"AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE],[\"$GETTEXT_PACKAGE\"])"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:469
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:482
msgid "D-Bus Interfaces"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:484
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:492
msgid "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:"
msgstr ""

#. (itstool) path: list/title
#: C/parallel-installability.page:499
msgid "Service Names"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:500
msgid "<code>org.example.Foo4</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:501
msgid "<code>org.example.Foo5</code>"
msgstr ""

#. (itstool) path: list/title
#: C/parallel-installability.page:504
msgid "Interface Names"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:505
msgid "<code>org.example.Foo4.InterfaceA</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:506
msgid "<code>org.example.Foo4.InterfaceB</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:507
msgid "<code>org.example.Foo5.InterfaceA</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:508
msgid "<code>org.example.Foo5.InterfaceB</code>"
msgstr ""

#. (itstool) path: list/title
#: C/parallel-installability.page:511
msgid "Object Paths"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:512
msgid "<code>/org/example/Foo4/Controller</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:513
msgid "<code>/org/example/Foo4/Client</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:514
msgid "<code>/org/example/Foo5/Controller</code>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:515
msgid "<code>/org/example/Foo5/Client</code>"
msgstr ""

#. (itstool) path: section/title
#: C/parallel-installability.page:527
msgid "Programs, Daemons and Utilities"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:529
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:536
msgid "Given a daemon and utility program:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:540
msgid "<file>/usr/libexec/foo-daemon</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:541
msgid "<file>/usr/bin/foo-lookup-utility</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:543
msgid "these should be versioned as:"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:547
msgid "<file>/usr/libexec/foo-daemon-4</file>"
msgstr ""

#. (itstool) path: item/p
#: C/parallel-installability.page:548
msgid "<file>/usr/bin/foo-lookup-utility-4</file>"
msgstr ""

#. (itstool) path: section/p
#: C/parallel-installability.page:551
msgid "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."
msgstr ""

#. (itstool) path: info/desc
#: C/preconditions.page:18
msgid "Contract programming with checks on function input and output"
msgstr ""

#. (itstool) path: page/title
#. (itstool) path: section/title
#: C/preconditions.page:21
#: C/preconditions.page:24
msgid "Pre- and Post-Conditions"
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:26
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:33
msgid "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:"
msgstr ""

#. (itstool) path: item/title
#: C/preconditions.page:40
msgid "Assertions"
msgstr ""

#. (itstool) path: item/p
#: C/preconditions.page:41
msgid "Check for programmer errors and abort the program on failure."
msgstr ""

#. (itstool) path: item/title
#: C/preconditions.page:46
msgid "Validation"
msgstr ""

#. (itstool) path: item/p
#: C/preconditions.page:47
msgid "Check for invalid input and return an error gracefully on failure."
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:53
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:67
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:76
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/preconditions.page:83
msgid "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."
msgstr ""

#. (itstool) path: info/desc
#: C/threading.page:18
msgid "Moving computation out of the main thread into worker threads"
msgstr ""

#. (itstool) path: page/title
#: C/threading.page:21
msgid "Threading"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:27
msgid "Do not use threads if at all possible. (<link xref=\"#when-to-use-threading\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:31
msgid "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\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:37
msgid "Use <code>g_thread_join()</code> to avoid leaking thread resources if using <code>GThread</code> manually. (<link xref=\"#using-threading\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:42
msgid "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\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/threading.page:52
msgid "When to Use Threading"
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:54
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:64
msgid "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."
msgstr ""

#. (itstool) path: example/code
#: C/threading.page:82
#, no-wrap
msgid ""
"\n"
"int\n"
"some_blocking_function (void *param1,\n"
"                        void *param2);\n"
""
msgstr ""

#. (itstool) path: example/p
#: C/threading.page:87
msgid "Should be wrapped as:"
msgstr ""

#. (itstool) path: example/code
#: C/threading.page:90
#, no-wrap
msgid ""
"\n"
"void\n"
"some_blocking_function_async (void                 *param1,\n"
"                              void                 *param2,\n"
"                              GCancellable         *cancellable,\n"
"                              GAsyncReadyCallback   callback,\n"
"                              gpointer              user_data);\n"
"int\n"
"some_blocking_function_finish (GAsyncResult        *result,\n"
"                               GError             **error);\n"
""
msgstr ""

#. (itstool) path: example/p
#: C/threading.page:102
msgid "With an implementation something like:"
msgstr ""

#. (itstool) path: example/code
#: C/threading.page:105
#, no-wrap
msgid ""
"/* Closure for the call’s parameters. */\n"
"typedef struct {\n"
"  void *param1;\n"
"  void *param2;\n"
"} SomeBlockingFunctionData;\n"
"\n"
"static void\n"
"some_blocking_function_data_free (SomeBlockingFunctionData *data)\n"
"{\n"
"  free_param (data-&gt;param1);\n"
"  free_param (data-&gt;param2);\n"
"\n"
"  g_free (data);\n"
"}\n"
"\n"
"static void\n"
"some_blocking_function_thread_cb (GTask         *task,\n"
"                                  gpointer       source_object,\n"
"                                  gpointer       task_data,\n"
"                                  GCancellable  *cancellable)\n"
"{\n"
"  SomeBlockingFunctionData *data = task_data;\n"
"  int retval;\n"
"\n"
"  /* Handle cancellation. */\n"
"  if (g_task_return_error_if_cancelled (task))\n"
"    {\n"
"      return;\n"
"    }\n"
"\n"
"  /* Run the blocking function. */\n"
"  retval = some_blocking_function (data-&gt;param1, data-&gt;param2);\n"
"  g_task_return_int (task, retval);\n"
"}\n"
"\n"
"void\n"
"some_blocking_function_async (void                 *param1,\n"
"                              void                 *param2,\n"
"                              GCancellable         *cancellable,\n"
"                              GAsyncReadyCallback   callback,\n"
"                              gpointer              user_data)\n"
"{\n"
"  GTask *task = NULL;  /* owned */\n"
"  SomeBlockingFunctionData *data = NULL;  /* owned */\n"
"\n"
"  g_return_if_fail (validate_param (param1));\n"
"  g_return_if_fail (validate_param (param2));\n"
"  g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));\n"
"\n"
"  task = g_task_new (NULL, cancellable, callback, user_data);\n"
"  g_task_set_source_tag (task, some_blocking_function_async);\n"
"\n"
"  /* Cancellation should be handled manually using mechanisms specific to\n"
"   * some_blocking_function(). */\n"
"  g_task_set_return_on_cancel (task, FALSE);\n"
"\n"
"  /* Set up a closure containing the call’s parameters. Copy them to avoid\n"
"   * locking issues between the calling thread and the worker thread. */\n"
"  data = g_new0 (SomeBlockingFunctionData, 1);\n"
"  data-&gt;param1 = copy_param (param1);\n"
"  data-&gt;param2 = copy_param (param2);\n"
"\n"
"  g_task_set_task_data (task, data, some_blocking_function_data_free);\n"
"\n"
"  /* Run the task in a worker thread and return immediately while that continues\n"
"   * in the background. When it’s done it will call @callback in the current\n"
"   * thread default main context. */\n"
"  g_task_run_in_thread (task, some_blocking_function_thread_cb);\n"
"\n"
"  g_object_unref (task);\n"
"}\n"
"\n"
"int\n"
"some_blocking_function_finish (GAsyncResult  *result,\n"
"                               GError       **error)\n"
"{\n"
"  g_return_val_if_fail (g_task_is_valid (result,\n"
"                                         some_blocking_function_async), -1);\n"
"  g_return_val_if_fail (error == NULL || *error == NULL, -1);\n"
"\n"
"  return g_task_propagate_int (G_TASK (result), error);\n"
"}"
msgstr ""

#. (itstool) path: example/p
#: C/threading.page:187
msgid "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\"/>.)"
msgstr ""

#. (itstool) path: section/title
#: C/threading.page:200
msgid "Using Threading"
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:202
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:210
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:222
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:232
msgid "If it is not possible to use a <code>GThreadPool</code> (which is rarely the case):"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:239
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:248
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:257
msgid "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>."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:265
msgid "If mutexes must be used:"
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:271
msgid "Isolate threading code as much as possible, keeping mutexes private within classes, and tightly bound to very specific class members."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:278
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/threading.page:288
msgid "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\"/>.)"
msgstr ""

#. (itstool) path: section/title
#: C/threading.page:304
msgid "Debugging"
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:306
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/threading.page:312
msgid "However, if a threading issue does arise, <link xref=\"tooling#helgrind-and-drd\">Valgrind’s drd and helgrind tools are useful</link>."
msgstr ""

#. (itstool) path: info/desc
#: C/tooling.page:17
msgid "Using the right tool for various tasks"
msgstr ""

#. (itstool) path: page/title
#: C/tooling.page:20
msgid "Tooling"
msgstr ""

#. (itstool) path: page/p
#: C/tooling.page:22
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/tooling.page:31
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/tooling.page:39
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:48
msgid "Compile frequently with a second compiler. (<link xref=\"#gcc-and-clang\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:52
msgid "Enable a large selection of compiler warnings and make them fatal. (<link xref=\"#gcc-and-clang\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:56
msgid "Use GDB to debug and step through code. (<link xref=\"#gdb\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:59
msgid "Use Valgrind to analyze memory usage, memory errors, cache and CPU performance and threading errors. (<link xref=\"#valgrind\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:63
msgid "Use gcov and lcov to analyze unit test coverage. (<link xref=\"#gcov-and-lcov\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:67
msgid "Use compiler sanitizers to analyze memory, thread and undefined behavior problems. (<link xref=\"#sanitizers\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:71
msgid "Submit to Coverity as a cronjob and eliminate static analysis errors as they appear. (<link xref=\"#coverity\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:75
msgid "Use Clang static analyzer and Tartan regularly to eliminate statically analysable errors locally. (<link xref=\"#clang-static-analyzer\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:83
msgid "GCC and Clang"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:85
msgid "<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\"/>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:97
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:112
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:121
msgid "<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:"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:136
msgid "<code>ax_append_compile_flags.m4</code>"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:137
msgid "<code>ax_append_flag.m4</code>"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:138
msgid "<code>ax_check_compile_flag.m4</code>"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:139
msgid "<code>ax_require_defined.m4</code>"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:142
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:151
msgid "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>:"
msgstr ""

#. (itstool) path: section/code
#: C/tooling.page:157
#, no-wrap
msgid ""
"AX_IS_RELEASE([git])\n"
"AX_COMPILER_FLAGS([WARN_CFLAGS],[WARN_LDFLAGS],[$ax_is_release])"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:160
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:169
msgid "GDB"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:171
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:179
msgid "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>"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:184
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:190
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:202
msgid "Valgrind"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:204
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:211
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:224
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:230
msgid "Add <code>AX_VALGRIND_CHECK</code> to <file>configure.ac</file>."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:233
msgid "Add <code>@VALGRIND_CHECK_RULES@</code> to the <file>Makefile.am</file> in each directory which contains unit tests."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:239
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:251
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:264
msgid "Suppression files are supported by the <code>AX_VALGRIND_CHECK</code> macro:"
msgstr ""

#. (itstool) path: section/code
#: C/tooling.page:268
#, no-wrap
msgid ""
"@VALGRIND_CHECK_RULES@\n"
"VALGRIND_SUPPRESSIONS_FILES = my-project.supp glib.supp\n"
"EXTRA_DIST = $(VALGRIND_SUPPRESSIONS_FILES)"
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:273
msgid "memcheck"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:275
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:286
msgid "To run memcheck manually on an installed program, use:"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:289
msgid "<cmd>valgrind --tool=memcheck --leak-check=full <var>my-program-name</var></cmd>"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:293
msgid "Or, if running your program from the source directory, use the following to avoid running leak checking on the libtool helper scripts:"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:297
msgid "<cmd>libtool exec valgrind --tool=memcheck --leak-check=full <var>./my-program-name</var></cmd>"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:301
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:307
msgid "A full tutorial on using memcheck is <link href=\"http://valgrind.org/docs/manual/mc-manual.html\">here</link>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:314
msgid "cachegrind and KCacheGrind"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:316
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:326
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:335
msgid "A full tutorial on using cachegrind is <link href=\"http://valgrind.org/docs/manual/cg-manual.html\">here</link>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:342
msgid "helgrind and drd"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:344
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:352
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:362
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:369
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:378
msgid "sgcheck"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:380
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:387
msgid "As it is experimental, sgcheck must be run by passing <cmd>--tool=exp-sgcheck</cmd> to Valgrind, rather than <cmd>--tool=sgcheck</cmd>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:393
msgid "A full tutorial on using sgcheck is <link href=\"http://valgrind.org/docs/manual/sg-manual.html\">here</link>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:401
msgid "gcov and lcov"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:403
msgid "<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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:413
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:424
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:432
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:442
msgid "To add <code>AX_CODE_COVERAGE</code> support to a project:"
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:446
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:452
msgid "Add <code>AX_CODE_COVERAGE</code> to <file>configure.ac</file>."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:455
msgid "Add <code>@CODE_COVERAGE_RULES</code> to the top-level <file>Makefile.am</file>."
msgstr ""

#. (itstool) path: item/p
#: C/tooling.page:459
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:468
msgid "Documentation on using gcov and lcov is <link href=\"http://ltp.sourceforge.net/coverage/lcov.php\">here</link>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:475
msgid "Address, Thread and Undefined Behavior Sanitizers"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:477
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:487
msgid "All sanitizers are available for both GCC and Clang, accepting the same set of compiler options."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:500
msgid "Address Sanitizer"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:502
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:512
msgid "Thread Sanitizer"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:514
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:525
msgid "Undefined Behavior Sanitizer"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:527
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:538
msgid "Coverity"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:540
msgid "<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)."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:553
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:566
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:574
msgid "Clang Static Analyzer"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:576
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:585
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:593
msgid "A full tutorial on using Clang is <link href=\"http://clang-analyzer.llvm.org/scan-build.html\">here</link>."
msgstr ""

#. (itstool) path: section/title
#: C/tooling.page:599
msgid "Tartan"
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:601
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:612
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/tooling.page:621
msgid "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."
msgstr ""

#. (itstool) path: info/desc
#: C/unit-testing.page:17
msgid "Designing software to be tested and writing unit tests for it"
msgstr ""

#. (itstool) path: page/title
#: C/unit-testing.page:20
msgid "Unit Testing"
msgstr ""

#. (itstool) path: synopsis/p
#: C/unit-testing.page:25
msgid "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."
msgstr ""

#. (itstool) path: synopsis/p
#: C/unit-testing.page:31
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:38
msgid "Write unit tests to be as small as possible, but no smaller. (<link xref=\"#writing-unit-tests\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:42
msgid "Use code coverage tools to write tests to get high code coverage. (<link xref=\"#writing-unit-tests\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:46
msgid "Run all unit tests under Valgrind to check for leaks and other problems. (<link xref=\"#leak-checking\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:50
msgid "Use appropriate tools to automatically generate unit tests where possible. (<link xref=\"#test-generation\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:54
msgid "Design code to be testable from the beginning. (<link xref=\"#writing-testable-code\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:62
msgid "Writing Unit Tests"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:64
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:79
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:90
msgid "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>."
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:101
msgid "Installed Tests"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:103
msgid "All unit tests should be installed system-wide, following the <link href=\"https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests\">installed-tests standard</link>."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:109
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:116
msgid "To add support for installed-tests, add the following to <file>configure.ac</file>:"
msgstr ""

#. (itstool) path: section/code
#: C/unit-testing.page:120
#, no-wrap
msgid ""
"# Installed tests\n"
"AC_ARG_ENABLE([modular_tests],\n"
"              AS_HELP_STRING([--disable-modular-tests],\n"
"                             [Disable build of test programs (default: no)]),,\n"
"              [enable_modular_tests=yes])\n"
"AC_ARG_ENABLE([installed_tests],\n"
"              AS_HELP_STRING([--enable-installed-tests],\n"
"                             [Install test programs (default: no)]),,\n"
"              [enable_installed_tests=no])\n"
"AM_CONDITIONAL([BUILD_MODULAR_TESTS],\n"
"               [test \"$enable_modular_tests\" = \"yes\" ||\n"
"                test \"$enable_installed_tests\" = \"yes\"])\n"
"AM_CONDITIONAL([BUILDOPT_INSTALL_TESTS],[test \"$enable_installed_tests\" = \"yes\"])"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:134
msgid "Then in <file>tests/Makefile.am</file>:"
msgstr ""

#. (itstool) path: section/code
#: C/unit-testing.page:137
#, no-wrap
msgid ""
"insttestdir = $(libexecdir)/installed-tests/[project]\n"
"\n"
"all_test_programs = \\\n"
"\ttest-program1 \\\n"
"\ttest-program2 \\\n"
"\ttest-program3 \\\n"
"\t$(NULL)\n"
"if BUILD_MODULAR_TESTS\n"
"TESTS = $(all_test_programs)\n"
"noinst_PROGRAMS = $(TESTS)\n"
"endif\n"
"\n"
"if BUILDOPT_INSTALL_TESTS\n"
"insttest_PROGRAMS = $(all_test_programs)\n"
"\n"
"testmetadir = $(datadir)/installed-tests/[project]\n"
"testmeta_DATA = $(all_test_programs:=.test)\n"
"\n"
"testdatadir = $(insttestdir)\n"
"testdata_DATA = $(test_files)\n"
"\n"
"testdata_SCRIPTS = $(test_script_files)\n"
"endif\n"
"\n"
"EXTRA_DIST = $(test_files)\n"
"\n"
"%.test: % Makefile\n"
"\t$(AM_V_GEN) (echo '[Test]' &gt; $@.tmp; \\\n"
"\techo 'Type=session' &gt;&gt; $@.tmp; \\\n"
"\techo 'Exec=$(insttestdir)/$&lt;' &gt;&gt; $@.tmp; \\\n"
"\tmv $@.tmp $@)"
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:171
msgid "Leak Checking"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:173
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:183
msgid "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.)"
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:193
msgid "Test Generation"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:195
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:205
msgid "JSON"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:207
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:216
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/unit-testing.page:221
#, no-wrap
msgid ""
"\n"
"json-schema-generate --valid-only schema.json\n"
"json-schema-generate --invalid-only schema.json"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:225
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/unit-testing.page:234
msgid "Writing Testable Code"
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:236
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:242
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:246
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:260
msgid "Expose utility functions where they might be generally useful."
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:263
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/unit-testing.page:274
msgid "The topic of software testability is covered in the following articles:"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:278
msgid "<link href=\"http://msdn.microsoft.com/en-us/magazine/dd263069.aspx\">Design for testability</link>"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:282
msgid "<link href=\"http://en.wikipedia.org/wiki/Software_testability\">Software testability</link>"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:286
msgid "<link href=\"http://en.wikipedia.org/wiki/Dependency_injection\">Dependency injection</link>"
msgstr ""

#. (itstool) path: item/p
#: C/unit-testing.page:290
msgid "<link href=\"http://c2.com/cgi/wiki?SoftwareDesignForTesting\">Software design for testing</link>"
msgstr ""

#. (itstool) path: info/desc
#: C/version-control.page:17
msgid "Source code version control with git"
msgstr ""

#. (itstool) path: page/title
#: C/version-control.page:20
msgid "Version Control"
msgstr ""

#. (itstool) path: synopsis/p
#: C/version-control.page:25
msgid "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>."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:34
msgid "Make atomic, revertable commits. (<link xref=\"#guidelines-for-making-commits\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:38
msgid "Include full reasoning in commit messages, plus links to relevant bug reports or specifications. (<link xref=\"#guidelines-for-making-commits\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:43
msgid "Keep large changes, such as renames, in separate commits. (<link xref=\"#guidelines-for-making-commits\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:47
msgid "Merge changes from feature branches by rebasing. (<link xref=\"#use-of-git\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/version-control.page:55
msgid "Use of Git"
msgstr ""

#. (itstool) path: section/p
#: C/version-control.page:57
msgid "Most GNOME repositories follow these rules:"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:61
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:66
msgid "Rebase commits rather than merging, to have a linear history (which is easier to follow)."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:70
msgid "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>."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:76
msgid "Hide <link href=\"https://sethrobertson.github.io/GitBestPractices/#sausage\">sausage making</link> by squashing commits before merging."
msgstr ""

#. (itstool) path: section/title
#: C/version-control.page:84
msgid "Guidelines for Making Commits"
msgstr ""

#. (itstool) path: section/p
#: C/version-control.page:86
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/version-control.page:98
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/version-control.page:106
msgid "The following principles give the reasoning for all the advice above:"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:110
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:116
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:122
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:129
msgid "Each commit should be written once, and designed to be read many times, by many reviewers and future programmers."
msgstr ""

#. (itstool) path: section/title
#: C/version-control.page:137
msgid "Merging Procedure"
msgstr ""

#. (itstool) path: section/p
#: C/version-control.page:139
msgid "To merge a feature branch named <code>my-branch</code> into master, use the following commands:"
msgstr ""

#. (itstool) path: section/code
#: C/version-control.page:143
#, no-wrap
msgid ""
"\n"
"git checkout master\n"
"git pull\n"
"\n"
"git checkout wip/<var>my-branch</var>\n"
"git rebase --interactive master\n"
"# Ensure the rebase is successful; test the changes\n"
"\n"
"git checkout master\n"
"git merge wip/<var>my-branch</var>\n"
"git push\n"
"\n"
"# wip/<var>my-branch</var> can now be deleted\n"
"git push origin :wip/<var>my-branch</var>\n"
"git branch -D wip/<var>my-branch</var>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:164
msgid "<link href=\"https://sethrobertson.github.io/GitBestPractices/\">Git best practices</link>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:167
msgid "<link href=\"https://help.github.com/categories/using-git/\">Git FAQ</link>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:170
msgid "<link href=\"https://www.atlassian.com/git/tutorials/\">Atlassian git tutorial</link>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:173
msgid "<link href=\"http://git-scm.com/docs/gittutorial\">Official git tutorial</link>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:176
msgid "<link href=\"https://try.github.io/\">Interactive git tutorial</link>"
msgstr ""

#. (itstool) path: item/p
#: C/version-control.page:179
msgid "<link href=\"http://www.git-tower.com/learn/\">git-tower tutorial</link>"
msgstr ""

#. (itstool) path: info/desc
#: C/versioning.page:17
msgid "Versioning and releasing libraries and applications"
msgstr ""

#. (itstool) path: synopsis/p
#: C/versioning.page:25
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:32
msgid "Libraries and applications have a package version of the form <em>major.minor.micro</em>. (<link xref=\"#package-versioning\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:36
msgid "Libraries additionally have a libtool version of the form <em>current:revision:age</em>. (<link xref=\"#libtool-versioning\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:40
msgid "Version numbers should be updated for each release (using release and post-release increments). (<link xref=\"#release-process\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:44
msgid "Package versions should be incremented for feature changes or additions. (<link xref=\"#package-versioning\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:48
msgid "Libtool versions should be updated for API changes or additions. (<link xref=\"#libtool-versioning\"/>)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:52
msgid "Even/odd <em>minor</em> package versions can be used respectively for stable/unstable releases. (<link xref=\"#stable-unstable-versions\"/>)"
msgstr ""

#. (itstool) path: section/title
#: C/versioning.page:60
msgid "Package Versioning"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:62
msgid "Both libraries and applications have a package version of the form <em>major.minor.micro</em>."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:67
msgid "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:"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:77
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:83
msgid "Otherwise, if changing or adding a feature, or adding any API, increment minor and set micro to 0."
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:87
msgid "Otherwise (if making a release containing only bug fixes and translation updates), increment micro."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:93
msgid "Note that the minor version number should be updated if any API is added."
msgstr ""

#. (itstool) path: section/title
#: C/versioning.page:99
msgid "Libtool Versioning"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:101
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:112
msgid "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>."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:121
msgid "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:"
msgstr ""

#. (itstool) path: section/code
#: C/versioning.page:127
#, no-wrap
msgid ""
"\n"
"# Before making a release, the LT_VERSION string should be modified. The\n"
"# string is of the form c:r:a. Follow these instructions sequentially:\n"
"#   1. If the library source code has changed at all since the last update, then\n"
"#      increment revision (‘c:r:a’ becomes ‘c:r+1:a’).\n"
"#   2. If any interfaces have been added, removed, or changed since the last\n"
"#      update, increment current, and set revision to 0.\n"
"#   3. If any interfaces have been added since the last public release, then\n"
"#      increment age.\n"
"#   4. If any interfaces have been removed or changed since the last public\n"
"#      release, then set age to 0.\n"
"AC_SUBST([LT_VERSION],[0:0:0])"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:140
msgid "The following snippet can be used in a <file>Makefile.am</file> to pass that version info to libtool:"
msgstr ""

#. (itstool) path: section/code
#: C/versioning.page:144
#, no-wrap
msgid ""
"my_library_la_LDFLAGS = -version-info $(LT_VERSION)"
msgstr ""

#. (itstool) path: section/title
#: C/versioning.page:148
msgid "Stable and Unstable Package Versions"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:150
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:158
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:166
msgid "The libtool version should be updated only for stable package versions."
msgstr ""

#. (itstool) path: section/title
#: C/versioning.page:172
msgid "Release Process"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:174
msgid "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)."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:181
msgid "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."
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:189
msgid "The release process (based on the <link href=\"https://wiki.gnome.org/MaintainersCorner/Releasing\">GNOME release process</link>):"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:195
msgid "Make sure code is up to date: <cmd>git pull</cmd>"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:199
msgid "Make sure you have no local changes: <cmd>git status</cmd>"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:202
msgid "If the release is for a stable package version, increment the libtool version number in <file>configure.ac</file> (if it exists)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:206
msgid "Add an entry to the <file>NEWS</file> file"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:210
msgid "Run <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> and ensure it succeeds"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:216
msgid "Fix any issues which come up, commit those changes, and restart at step 3"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:222
msgid "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)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:228
#: C/versioning.page:263
msgid "Run <cmd>git push</cmd>"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:232
msgid "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."
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:242
msgid "Tag the release: <cmd>git tag -s x.y.z</cmd> (where ‘x.y.z’ is the package version number)"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:246
msgid "Run <cmd>git push origin x.y.z</cmd> (where ‘x.y.z’ is the package version number)"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:252
msgid "The release is now complete, and the post-release version increment can be done:"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:257
msgid "Increment the package version number in <file>configure.ac</file>"
msgstr ""

#. (itstool) path: item/p
#: C/versioning.page:260
msgid "Run <cmd>git commit -a -m \"Post-release version increment\"</cmd>"
msgstr ""

#. (itstool) path: section/p
#: C/versioning.page:268
msgid "The package archive generated by <cmd>make distcheck</cmd> can now be uploaded to download.gnome.org or distributed in other ways."
msgstr ""

#. (itstool) path: info/desc
#: C/writing-good-code.page:25
msgid "Good, readable code keeps the project maintainable"
msgstr ""

#. (itstool) path: page/title
#: C/writing-good-code.page:28
msgid "The Importance of Writing Good Code"
msgstr ""

#. (itstool) path: page/p
#: C/writing-good-code.page:30
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/writing-good-code.page:43
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/writing-good-code.page:51
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/writing-good-code.page:58
msgid "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."
msgstr ""

#. (itstool) path: page/p
#: C/writing-good-code.page:71
msgid "The following are some important qualities of good code:"
msgstr ""

#. (itstool) path: item/title
#: C/writing-good-code.page:77
msgid "Cleanliness"
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:78
msgid "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."
msgstr ""

#. (itstool) path: item/title
#: C/writing-good-code.page:87
msgid "Consistency"
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:88
msgid "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."
msgstr ""

#. (itstool) path: item/title
#: C/writing-good-code.page:99
msgid "Extensibility"
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:100
msgid "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."
msgstr ""

#. (itstool) path: item/title
#: C/writing-good-code.page:112
msgid "Correctness"
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:113
msgid "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."
msgstr ""

#. (itstool) path: section/title
#: C/writing-good-code.page:126
msgid "Book References"
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:129
msgid "<link href=\"http://www.cc2e.com\">Code Complete</link>, by Steve McConnell."
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:132
msgid "<link href=\"http://martinfowler.com/books/refactoring.html\"> Refactoring: Improving the Design of Existing Code </link>, by Martin Fowler."
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:137
msgid "<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."
msgstr ""

#. (itstool) path: item/p
#: C/writing-good-code.page:142
msgid "<link href=\"http://astore.amazon.com/gnomestore-20/detail/020163385X\"> Object-Oriented Design Heuristics </link>, by Arthur Riel."
msgstr ""