Guidelines

SDK guidelines for application developers, focusing on security. These are a series of guidelines and examples for various aspects of developing on and in the Apertis libraries and applications. They assume a good level of competence with programming in C, and familiarity with the underlying libraries Apertis uses, such as GLib. A good set of introductory guidelines for using GLib and related libraries are the GNOME Programming Guidelines.

To get started, skim each of the General guidelines pages, each of which has a summary at the top. Specific topics are covered in the Specific how-tos section, which can be used more like a reference manual.

The external links point to further resources, which can be quite comprehensive and are worth reading.

General guidelines

Specific how-tos

Add linters to a project

To add code linters to a project Install clang-format-linter locally A custom local install of the linter for C, C++, Python and Bash/POSIX shell can be easily done. On an Apertis image or on Debian install the relevant packages: apt install arcanist-clang-format-linter pep8 shellcheck Check the installation: arc linters # should list ‘clang-format’ as ‘configured’ Add a .clang-format file clang-format accepts its format options from a hidden file, defined in YAML format. [Read More]

Guidelines BuildingPatchingAndMaintainingTheApertisKernel

This guide will explore a number of workflows for retrieving, patching, building and packaging the Apertis kernel. This guide will suggest workflows both utilising the Debian infrastructure on which Apertis is built and a workflow that eschews the Debian infrastructure and thus is usable by third party integrators who may need access to a patched kernel tree for integration, but who's workflow would make using the Apertis infrastructure difficult. This document is targeted towards development of Apertis and where possible, we would strongly advise using the Apertis SDK image and the Debian tooling provided for it, as this workflow will be more efficient (“option 1” where present). [Read More]

Build and Integration infrastructure documentation

Build and Integration This is the page for the Build and Integration team. It includes links for B&I services, documentation and activities in the project. Services Wiki Issue Tracker OBS (Open Build Service) Images Repositories Build Suffix For every release (Developer, Preview, Product), we add a build suffix string to the packages, which relates to the release name of Apertis. The build suffix gets added to every built . [Read More]

Guidelines API design

This page describes some general API design principles which are useful to bear in mind when designing APIs (whether those APIs are for C, C++, JavaScript, D-Bus, or something else). Summary API designs must make sense from the point of view of a third-party app developer (start by designing high-level APIs, only add daemons if it is necessary) Interfaces that don't have to be API should not be API (minimize surface area) Follow GNOME/GObject conventions, so that we get JavaScript bindings automatically Use existing frameworks where we can; if we can't use them directly, learn from their design Identify privilege boundaries, do not trust less-privileged components, and consider whether some features should be restricted Minimize “surface area" The “SDK API” is intended to remain stable/compatible over time, which means that we are committing to interfaces in the “SDK API” continuing to work in future: third-party code that uses stable Apertis APIs must continue to work in future, without needing changes. [Read More]

Guidelines Logging

Logging 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. [Read More]

Guidelines Module setup

Module setup The layout and basic structure of a project’s source directory needs to be done when the project is created. If done well, with thought put into future maintainability and scalability of the build system, little maintenance time will be required on the build system in future. Summary Follow the standard root directory layout so users of the project can find information where they expect. (Root directory layout) Ensure the project and each source code file is clearly licenced. [Read More]

Add a git repository

Add a git repository Apertis hosts its own git repositories. These repositories are used to host code which makes up Apertis, but Apertis also makes use of code that is hosted elsewhere. Only projects of high quality can be added to the Apertis git repositories. To ensure this, the project must fulfil some criteria: The project must be free/open source software It must be part of Apertis You must make a commitment to maintain the project To the best of your knowledge, it must not infringe on patents If it re-uses free/open source code from elsewhere, it must comply with all licenses New projects are currently assessed for compliance with these rules by the Apertis sysadmins. [Read More]

Guidelines Git-based packaging workflow

Git-based packaging workflow Several OBS Apertis packages are kept in Git source repositories, to be able to maintain and update those packages several recomendations are being adopted: Use of DEP-14 Git layout proposal specification with the following conventions: upstream/{latest,$version} branches with the upstream project code (eg. upstream/2.48.x) apertis/{master,$distro} branches where the upstream branches above get merged with the Apertis packaging (eg. apertis/16.12) apertis/$version tags (eg. apertis/2.48.0-1ubuntu4co1) Packages maintained in Git shall contain a hint file in OBS package folder (MAINTAINED_IN_GIT. [Read More]