This document is intended to present the project's focus, philosophy and development best practices.
Focus
Mobian's goals are to:
- bring Debian GNU/Linux to mobile devices such as smartphones and tablets
- have a simple installation process
- provide a modern user experience
For these reasons, Mobian provides easy-to-use bootable images pre-configured to boot directly into the Phosh graphical environment. These images are pre-loaded with all the essential software needed on a mobile device: phone and messaging (SMS, XMPP) applications, e-mail client, Web browser, and several more!
Philosophy
Debian is an excellent and essential general-purpose Linux distribution, providing a high-quality system including tons of free and open-source software packages.
However, it can't be installed as-is on devices as specific as mobile phones and tablets, which all require significant customization due to the hardware they use. This is where Mobian will be useful: provide an overlay to Debian, as small as possible, to bring the full power of Debian to mobile devices.
Mobian is not intended to be a full-featured Linux distribution, but only to ease the installation and use of Debian on specific devices. As such, it is essential for us to:
- maintain as little software as possible as part of the Mobian project
- upstream as much of our work as possible to Debian, and maintain official Debian packages when needed
- work with upstream developers to make desktop applications usable on mobile devices, so that any mobile user can benefit from it
Developing for Mobian
System images
Mobian images are build using debos, a simple yet powerful tool for generating custom Debian images.
The mobian-recipes repository contains the build system for generating device-specific images. It consists of:
several generic debos recipes providing the base infrastructure
a build script (build.sh) which executes the proper commands in the right order to generate the flashable/bootable image
device-specific recipes and scripts under the devices folder, organized by device "family"
Device families can be interpreted as groups of devices sharing a similar hardware architecture. Currently, this translates to "devices using the same SoC".
Generic recipes
mobian-recipes contains the following debos recipes, each of those using the artifacts generated by the previous recipe:
rootfs.yaml is used to generate a per-architecture rootfs containing all userspace software to boot into the desired desktop environment (the target architecture being one of amd64, arm64 or armhf)
rootfs-device.yaml adds device-specific packages, which are defined in the devices/<family>/packages-base.yaml and devices/<family>/packages-<environment>.yaml sub-recipes. Please note Mobian only supports the phosh environment for now, but support for other environments such as Plasma Mobile may be added in the future
image.yaml is used to create the image file, partition it and deploy the generated rootfs to it. It also executes the devices/<family>/bootloader.sh script then includes the devices/<family>/bootloader.yaml for preparing and installing the bootloader.
2 additional recipes are present for generating the on-device installer:
installfs.yaml generates a minimal per-architecture rootfs for creating the installer image.
installer.yaml generates the installer image itself and is very similar to image.yaml, making use of the same bootloader script and recipe. As it embeds the device-specific rootfs, the latter must be generated beforehand using the rootfs.yaml and rootfs-device.yaml recipes.
Build script
Weekly image builds
mobian-recipes has a CI pipeline setup for generating images for all supported devices. This pipeline runs automatically on a weekly basis (every Sunday at 00:00 UTC).
Generated images can be downloaded from https://images.mobian.org/<device>/weekly.
For the ?PinePhone and ?PineTab, this pipeline also generates installer images, found under https://images.mobian.org/<device>/installer/weekly.
Creating images for (yet) unsupported devices
TODO
Hardware support
Whenever that's possible, we'd like to use upstream Debian packages. However, most devices will need at least a custom kernel, and a custom bootloader too. These will be stored in the devices subgroup, as well as any other device-specific package.
Device-specific tweaks
For example, the ?PinePhone requires custom configuration for pulseaudio, udev rules and a few additional scripts. Such device-specific tweaks can be carried in one of the following source packages:
mobile-tweaks is a Debian package carrying non-obtrusive, uncontroversial changes. It generates a single mobile-tweaks-common and several <device>-tweaks binary packages (one per supported device)
Mobian carries a number of <device>-tweaks source packages for customizations too important to be accepted as part of a Debian package. Each of those source packages generates a single mobian-<device>-tweaks binary package in order to avoid conflicts with Debian's <device>-tweaks packages
Note: as our goal is to be as close to Debian as possible, we're currently in the process of proposing the necessary changes upstream and/or in Debian so we can get rid of most of our tweaks and carry the remainder in Debian's mobile-tweaks.
Device-specific kernel packages
Most devices will require a number of patches on top of mainline to be able to run properly. For this reason, several device-specific kernel packages are present under the devices subgroup, preferably in the form of per-family repositories: the kernel repository for Allwinner A64-based devices (?PinePhone and ?PineTab) is sunxi64-linux; sdm845-linux targets all supported devices using a Qualcomm SDM845 SoC.
The kernel repo contains branches named mobian-x.y, with x.y being the kernel branch version (5.15 at the time of this writing). Each of those branches contains the debian packaging for the kernel, the source package name being linux-x.y-<device>, generating the linux-image-x.y-<device> and linux-headers-x.y-<device> binary packages.
For the ?PinePhone:
the kernel repository is sunxi64-linux
the current (as of this writing) branch is mobian-5.15
the source package name is linux-5.15-sunxi64
generated binary packages are linux-image-5.15-sunxi64 and linux-headers-5.15-sunxi64
Other device-specific packages
Other device-specific packages are:
<device>-support: metapackage pulling in the required dependencies for each devices (kernel, bootloader, and possibly proprietary firmware needed at runtime). Those packages will soon be deprecated and merged with the corresponding <device>-tweaks Mobian packages.
non-free firmware packages if needed; those can be packaged per-peripheral (e.g. firmware-ov5640 for the OV5640 camera sensor autofocus) or per-device (e.g. firmware-oneplus6)
<device>-<bootloader>: device-specific bootloader if any is needed. Using per-family packages instead of per-device is also strongly encouraged.
Software packages
As a Debian-based project, all software distributed through Mobian is using the .deb packaging format.
Contributors with little experience with Debian packaging should read the Guide for Debian Maintainers, as well as the Debian Policy (the latter is a tedious read, but understanding it will help get your packages accepted into Debian). The Debian Developer's Reference provides practical information and is a useful complement to the Debian Policy.
Note: the New Maintainer's Guide still holds relevant information but newer tooling exists, and the Guide for Debian Maintainers is intended as its successor.
The use of git-buildpackage is recommended to manage the packages' source code. You should also create a Debian unstable VM or container for building and/or testing your packages.
Cross compilation with debuild should be achieved with the -a<arch> option pattern, as other patterns suffer bugs in the debuild flow; see Debian bug #898706 for details.
Mobian does not cater to the non-maintainer-upload paradigm that Debian enables. debian/changelog entries should forgo this feature; dch can be instructed so as such: dch --no-auto-nmu.
Packaging for Mobian
Some packages are not suitable for Debian or are otherwise targeted to Mobian. In such cases, the software must still be packaged per Debian's guidelines.
For the package to be accepted into Mobian, it must be reviewed/acked by at least one Mobian Maintainer and one of the following:
- 1 Debian Developer
- 1 Debian or Mobian Maintainer
- 2 Mobian Developers
The maintainer of the package should also be willing to maintain the package in line with Debian's releases.
As Mobian aims to upstream all work into Debian, most packages should target Debian rather than the Mobian repositories.
The following page lists all packages currently in the Mobian archive as well as their version numbers. Version numbers of the Debian version