Guides

JSON parsing JSON is used for various formats within Apertis, and potentially also for various web APIs. It is a well defined format, and several mature libraries exist for parsing it. However, the JSON being parsed typically comes from untrusted sources (user input or untrusted web APIs), so must be validated extremely carefully to prevent exploits. Summary Use a standard library to parse JSON, such as json-glib. (Parsing JSON) Be careful to pair up JSON reader functions on all code paths. [Read More]

Apetis uses Plymouth to implement the animation on boot. To customize its boot animation, Plymouth has support to define a set of splash themes. From the Plymouth README file: “Plymouth supports various “splash” themes which are analogous to screensavers, but happen at boot time. There are several sample themes shipped with plymouth, but most distributions that use plymouth ship something customized for their distribution.” You can list the available themes on your system by executing: [Read More]

XML parsing XML is used for a few formats within Apertis, although not as many as JSON. It is more commonly used internally by various GLib systems and tools, such as GSettings and D-Bus. In situations where it is parsed by Apertis code, the XML being parsed typically comes from untrusted sources (untrusted web APIs or user input), so must be validated extremely carefully to prevent exploits. Summary Use a standard library to parse XML, such as libxml2. [Read More]

Summary Use gtk-doc with up-to-date settings for API documentation. (gtk-doc) Use XML entities for including external symbols into the documentation. (Build system) Use a consistent, standard, table of contents for all API documentation to maintain familiarity. (Standard layout) Use gdbus-codegen to generate D-Bus API documentation to include in the gtk-doc build. (D-Bus APIs) Add introspection annotations to all API documentation. (Introspection annotations) Add Since lines to all API documentation. (Symbol versioning) Enable gtk-doc tests. [Read More]

Summary Do not use threads if at all possible. (When to use threading) If threads have to be used, use GTask or GThreadPool and isolate the threaded code as much as possible. (Using threading) Use g_thread_join() to avoid leaking thread resources if using GThread manually. (Using threading) Be careful about the GMainContext which code is executed in if using threads. Executing code in the wrong context can cause race conditions, or block the main loop. [Read More]

The proxy used by a specific interface can be configured for connman on the command line with: connmanctl config <service> --proxy manual <proxy url and port> Where <service> is the name of the interface and <proxy url and port> is the proxy to be used. You can list services with connmanctl services: $ connmanctl services *AO Wired ethernet_525400a6d228_cable So to set the wired ethernet interface from the example above to use a HTTP proxy on 127. [Read More]

QA Report App is the Apertis tool for reporting and viewing the results of both manual and automated (via LAVA) QA testing. Primary Configuration File QA Report App’s configuration is handled via the file secrets/config.yaml. General Options Resource Links and virtual location QA Report App needs to be able to generate links to the test cases and images: 1 2 app-url: https://qa.apertis.org image-root: https://images.apertis.org app-url should be the URL where QA Report App is running at, and image-root should point to the web location where images downloads are available at. [Read More]

Documenting with gtk-doc gtk-doc has been selected as the recommended tool to generate documentation for software API in Apertis. Why gtk-doc 3 tools were good candidates: gtk-doc gi-docgen doxygen The main reasons behind choosing gtk-doc are: Supports GObject introspection Supports documentation generated by gdbus-codegen Supports devhelp Can be used for any C library Doxygen lacks GObject introspection and devhelp support but can parse multiple languages. gi-docgen is to be used only with GObject Introspection code and the project recommends to only use it for that. [Read More]

This document outlines the APT snapshot retention policy that has been defined and implemented along with the OBS aptly publisher integration. Background APT snapshot functionality is supported in Apertis using the aptly publisher backend integrated to OBS. Snapshots are periodically created from the published repositories increasing the storage consumption over time, see Repository Storage Usage. To overcome this potential storage issue, a snapshot retention mechanism is provided to drop/retain snapshots. [Read More]

This document outlines the OBS aptly publisher backend that has been implemented on the Collabora instance of OBS. The upstreaming process of this feature is currently in-progress. Background Apertis relies on OBS for building and publishing binary packages. However, upstream OBS provides an APT publisher based on dpkg-scanpackages, which is not suitable for a project the scale of Apertis, where a single OBS project contains a lot of packages. For a period of time, our OBS instance used a custom publisher based on reprepro, but it is still subject to some limitations that became more noticeable as the scale of Apertis increased considerably. [Read More]