Creating a mobile-nixos Installer


Currently mobile-nixos has no non-nix friendly installation method. The current method involves many annoying imperative steps that do not follow nix best practices. Eg. To install mobile-nixos the setup process has the following steps:

  1. git clone the mobile-nixos repository.
  2. Find the latest revision of mobile-nixos that successfully builds on hydra.
  3. git clone nixpkgs and checkout the target revision.
  4. Change NIXPATH to the local nixpkgs repository.
  5. Create a local.nix to apply configuration options to the image being built.
  6. Use nix-build to compile mobile-nixos.

These steps imply users have knowledge of nixpkgs, nix-build and how nix expressions work for importing local.nix. To remove this barrier to the nix ecosystem, mobile-nixos requires an installer similar to the the one on desktop NixOS. Adding an installer to mobile-nixos gives users the ability to trial NixOS and the Nix ecosystem when they might have passed over the desktop distribution.

Introduction to Calamares

Creating an installer for mobile-nixos would require the use of the installer framework Calamares, the same framework used for desktop NixOS.

nixos calamares screenshot

Calamares solves the problem of introducing new users mobile-nixos since provides an intuitive GUI to step users through the different configuration options when installing mobile-nixos. postmarketOS has already implemented a mobile Calamares extension which allows postmarketOS to capture users looking to use mobile friendly Linux distributions without a large barrier to entry.

postmarketos calamares screenshot

Calamares allows developers to define and customize the following setup steps:

  1. Welcome
  2. Location
  3. Keyboard
  4. Partitions
  5. Users
  6. Summary
  7. Install
  8. Flash

Calamares Internals & NixOS

Calamares defines three different consumers of Calamares:

  1. Developer - Those who work on Calamares itself.
  2. Deployer - Those who use Calamares to deploy their Linux distribution.
  3. User - Those who use Calamares to install a given Linux distribution.

Deployer's must create Calamares modules to deploy their distribution. In the case of NixOS, modules are packaged in a Calamares extension which is then included in the NixOS installer image.

From a deployer's perspective, Calamares uses two methods of customizing the installer experience for the end user:

  1. viewmodule - User visible modules. C++, Widgets, QML.
  2. jobmodule - Non-user visible modules. C++, Python, external process (not recommended).

Python Job Module

NixOS' Calamares extension includes a python job which is responsible for creating a new nix configuration file which contains sections of nix code which correspond with the user's choices when moving through the Calamares setup process. For example:

In the file there is a string block corresponding to gnome being enabled:

cfggnome = """  # Enable the X11 windowing system.
  services.xserver.enable = true;
  # Enable the GNOME Desktop Environment.
  services.xserver.displayManager.gdm.enable = true;
  services.xserver.desktopManager.gnome.enable = true;

which is eventually enabled with the following logic:

if gs.value("packagechooser_packagechooser") == "gnome":
		cfg += cfggnome

More information about Calamares python jobs can be found in the Python Modules section of the documentation.

QML View Module

The NixOS Calamares extension uses QML for the customization of it's viewmodule which handles the user interface and NixOS specific branding. In addition to the python module and the view module, the extension also includes the use of the following base Calamares modules:

Calamares and postmarketOS

Calamares also has C++, QML bindings to create modules that are a hybrid of job and views but unfortunately these bindings are currently undocumented; however postmarketOS has created a mobile extension that demonstrates this view+job module.

postmarketOS has also implemented the ability to load other OS' into using it's own device setup process however this process seems to add unneeded complexity when installing the target OS since it installs the target OS to the same disk where the installation medium lives.

on-device installer diagram

mobile-nixos assumes that your device uses SPI flash to enable Tow-Boot therefore it is preferable to write the image

Requirements for Calamares integration on Mobile NixOS

samueldr has listed his requirements for mobile-nixos in a GitHub issue. His requirements are outlined as the following