Installation guide

From postmarketOS
Revision as of 06:11, 30 June 2018 by Ollieparanoid (talk | contribs) (update clone URL to gitlab)
Jump to: navigation, search

Introduction

If you own a device which has been ported to postmarketOS, then this page will help you to obtain, build, and install postmarketOS to this device.

Any commands that are expected to be entered into a terminal are prefixed with $. You should not enter that character, it is merely to designate that the following commands are intended to be input/executed within a terminal. For example, the following command to list contents of the current working directory, ls, will be mentioned on this page as:

$ ls

Requirements

  • We assume, that you are using Linux. If you don't have Linux installed, please set up a virtual machine with VirtualBox first.
  • Python 3.4+ and git must be installed (look at your distribution's documentation on installing packages)
  • A few gigabytes of free space

Initialization

Run the following commands in a Linux terminal to get started.

$ git clone https://gitlab.com/postmarketOS/pmbootstrap.git
$ cd pmbootstrap
$ ./pmbootstrap.py init

Type in the code name of your device as listed here and optionally a custom username.

Target device (either an existing one, or a new one for porting).
Available (39): amazon-thor, asus-flo, asus-grouper, fairphone-fp2, google-glass, ...
Device [samsung-i9100]: samsung-i9070
Username [user]: yourusernamegoeshere

User interface

Carefully choose the user interface you would like to install. Check your device's wiki page for interfaces, that are known to be working with your device. Weston and XFCE4 are usable on devices which do not have hardware 3D acceleration (most of them!), the others are notably slowed down. Please read the corresponding user interface article for information about how usable each interface is and keep in mind that most of them are not that usable yet.

Available user interfaces (5):
* none: No graphical environment
* hildon: (X11) Lightweight GTK+2 UI (optimized for single-touch touchscreens)
* luna: (Wayland) webOS UI, ported from the LuneOS project (Not working yet)
* plasma-mobile: (Wayland) Mobile variant of KDE Plasma, optimized for touchscreen
* weston: (Wayland) Reference compositor (demo, not a phone interface)
* xfce4: (X11) Lightweight GTK+2 desktop (stylus recommended)
User interface [weston]:

Work path

Make sure that the location has a few GB of space available, and that it is a relatively standard Linux filesystem (so it supports device nodes and symbolic links). Notably unsupported are: eCryptFS, encfs, fat, ntfs, nfs shares, tmpvs, VirtualBox shared folders.

Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there.
Work path [/home/user/.local/var/pmbootstrap]:

More questions

Unless you know that you want to change something, it's fine to anwer with the defaults here by just pressing the return key.

Build options: Parallel jobs: 3, ccache per arch: 5G, timestamp based rebuilds: True
Change them? (y/n) [n]:
Additional packages that will be installed to rootfs. Specify them in a comma separated list (e.g.: vim,file) or "none"
Extra packages [none]:
Your host timezone: Europe/London
Use this timezone instead of GMT? (y/n) [y]:
WARNING: The applications in the chroots do not get updated automatically.
Run 'pmbootstrap zap' to delete all chroots once a day before working with pmbootstrap!
It only takes a few seconds, and all packages are cached.
Done!

Installation and flashing

We assume that you have a shortcut for pmbootstrap set up, that points to ./pmbootstrap.py.
Not all installation and flash methods work for all devices. Please check your device wiki page for further instructions! Below you will find generic explanations of what the install and flash actions do, just in case the installation instructions are missing for your device. If that is the case, please extend the wiki accordingly.

pmbootstrap install

The install action essentially does the following:

  • build a chroot with the full installation as it will be placed on the device
  • copy that to an encrypted system image file
  • ask you for the user and encryption passwords

It is possible to disable the full disk encryption (FDE) with the --no-fde parameter (it might be that the FDE interface osk-sdl has not been ported to your device yet).

Furthermore you can change the output type (system image) to something else with the following parameters.

  • --sdcard: Format and copy everything to an SD card
  • --android-recovery-zip: Create a zip file, that can be used with TWRP, CWM or other Android recovery systems.

Example commands (only using one at a time makes sense):

$ pmbootstrap install
$ pmbootstrap install --no-fde --sdcard=/dev/mmcblk
$ pmbootstrap install --android-recovery-zip
$ pmbootstrap install --help

pmbootstrap flash

This command wraps various flash programs (e.g. fastboot and heimdall) with a common syntax and with automatically filling out the paths to the generated files. Usually you need to flash the system image (unless you did the SD card or recovery zip installation):

$ pmbootstrap flasher flash_rootfs

In case your system partition is too small for the generated image (e.g. because you chose Plasma Mobile as UI), it is possible to flash to another partition as well. Just be sure to erase any previous installations of postmarketOS in other partitions, because the init script will start with the first one that it encounters. (To delete a previous version either use dd or simply install the known working OS, e.g. Android, on it). Using multiple partitions with LVM is planned (#60).

$ pmbootstrap flasher flash_rootfs --partition userdata

And then you need to boot or flash the kernel (so run only one of the commands). Again, this is not necessary when you have used the recovery zip. But it is necessary in most cases with the SD card (unless the device can boot the kernel from the SD card like the N900).

$ pmbootstrap flasher boot
$ pmbootstrap flasher flash_kernel

As with all pmbootstrap commands, you can check the help pages for details:

$ pmbootstrap flasher --help
$ pmbootstrap flasher flash_rootfs --help

See also