Jump to content

Installation guide: Difference between revisions

From postmarketOS Wiki
pmbootstrap flash: mention "fastboot format system" (thanks @MartijnBraam!)
m Punctuation and capitalization corrections. Small wording changes.
Line 9: Line 9:


=== Requirements ===
=== Requirements ===
* We assume, that you are using Linux. If you don't have Linux installed, please [http://www.brianlinkletter.com/installing-debian-linux-in-a-virtualbox-virtual-machine/ set up a virtual machine with VirtualBox] first.
* We assume that you are using Linux. If you don't have Linux installed, please [http://www.brianlinkletter.com/installing-debian-linux-in-a-virtualbox-virtual-machine/ 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)
* Python 3.4+ and git must be installed (look at your distribution's documentation on installing packages)
* The host operating system needs to run Linux 3.17 or newer (first kernel with getrandom syscall)
* The host operating system needs to run Linux 3.17 or newer (first kernel with getrandom syscall)
Line 19: Line 19:
Fortunately, most Android-based devices are fairly foolproof; even if your flashed images don't boot, you can still access the flashing mode and fix the mistakes. For details, have a look at your [[devices|device-specific wiki page]].
Fortunately, most Android-based devices are fairly foolproof; even if your flashed images don't boot, you can still access the flashing mode and fix the mistakes. For details, have a look at your [[devices|device-specific wiki page]].


{{Todo|Explain what alterations can hard-brick a device. Where is fastboot itself stored? Can the partition table be fixed via fastboot? What's the significance of all the extra partitions on Android devices? etc...}}
{{Todo:|Explain what alterations can hard-brick a device. Where is fastboot itself stored? Can the partition table be fixed via fastboot? What's the significance of all the extra partitions on Android devices? etc...}}


=== Initialization ===
=== Initialization ===
Line 30: Line 30:
</syntaxhighlight>
</syntaxhighlight>


Type in the code name of your device as listed [[Devices|here]] and optionally a custom username.
Type in the code name of your device as listed [[Devices|here]], and optionally a custom username.
<pre>
<pre>
Target device (either an existing one, or a new one for porting).
Target device (either an existing one, or a new one for porting).
Line 39: Line 39:


==== User interface ====
==== User interface ====
Carefully choose the user interface you would like to install. Check your [[devices|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-Interfaces|user interface]] article for information about how usable each interface is and keep in mind that most of them are not that usable yet.
Carefully choose the user interface you would like to install. Check your [[devices|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-Interfaces|user interface]] article for information about how usable each interface is and keep in mind that most of them are not that usable yet.
<pre>
<pre>
Available user interfaces (5):
Available user interfaces (5):
Line 52: Line 52:


==== Work path ====
==== 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.
Make sure that the location has a few GB of space available, and that it is a relatively standard Linux filesystem (one that supports device nodes and symbolic links). Notably ''unsupported'' are: eCryptFS, encfs, fat, ntfs, nfs shares, tmpvs, and VirtualBox shared folders.
<pre>
<pre>
Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there.
Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there.
Line 75: Line 75:
=== Installation and flashing ===
=== Installation and flashing ===
{{note|We assume that you have a [[Porting_to_a_new_device#Shortcut|shortcut]] for <code>pmbootstrap</code> set up, that points to <code>./pmbootstrap.py</code>.}}
{{note|We assume that you have a [[Porting_to_a_new_device#Shortcut|shortcut]] for <code>pmbootstrap</code> set up, that points to <code>./pmbootstrap.py</code>.}}
{{note|Not all installation and flash methods work for all devices. '''Please check your [[devices|device wiki page]] for further instructions!''' Below you will find generic explanations of what the <code>install</code> and <code>flash</code> actions do, just in case the installation instructions are missing for your device. If that is the case, please extend the wiki accordingly.}}
{{note|Not all installation and flash methods work for all devices. '''Please check your [[devices|device wiki page]] for further instructions!''' Below you will find generic explanations of what the <code>install</code> and <code>flash</code> actions do, just in case the installation instructions are missing for your device. If that is the case, please extend the device wiki accordingly.}}


==== pmbootstrap install ====
==== pmbootstrap install ====
The install action essentially does the following:
The install action essentially does the following:
* build a chroot with the full installation as it will be placed on the device
* Build a chroot with the full installation as it will be placed on the device
* copy that to an encrypted system image file
* Copy that to an encrypted system image file
* ask you for the user and encryption passwords
* Ask you for the user and encryption passwords


It is possible to disable the full disk encryption (FDE) with the <code>--no-fde</code> parameter (it might be that the FDE interface [[osk-sdl]] has not been ported to your device yet).
It is possible to disable the full disk encryption (FDE) with the <code>--no-fde</code> parameter (if, for example, 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.
Furthermore you can change the output type (system image) to something else with the following parameters.
Line 98: Line 98:


==== pmbootstrap flash ====
==== 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):
This command wraps various flash programs (e.g. fastboot and heimdall) with a common syntax, and automatically fills 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):


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 104: Line 104:
</syntaxhighlight>
</syntaxhighlight>


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 <code>fastboot format system</code> for fastboot compatible devices, or simply install the known working OS, e.g. Android, on it. And if you really know what you are doing, you might consider using <code>dd</code>). Using multiple partitions with LVM is planned ({{github|60}}).
In case your system partition is too small for the generated image (e.g. because you chose Plasma Mobile as your 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 <code>fastboot format system</code> for fastboot compatible devices, or simply install the known working OS, e.g. Android, on it. And if you really know what you are doing, you might consider using <code>dd</code>). Using multiple partitions with LVM is planned ({{github|60}}).
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap flasher flash_rootfs --partition userdata
$ pmbootstrap flasher flash_rootfs --partition userdata

Revision as of 05:46, 20 October 2018

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)
  • The host operating system needs to run Linux 3.17 or newer (first kernel with getrandom syscall)
  • A few gigabytes of free space

Safety first

Beware that by following these instructions, you will overwrite everything that is currently on your device. You will lose all data and it might not be possible to restore the original operating system. There is a risk of hard-bricking your device, meaning it may be impossible to recover without specialist tools.

Fortunately, most Android-based devices are fairly foolproof; even if your flashed images don't boot, you can still access the flashing mode and fix the mistakes. For details, have a look at your device-specific wiki page.

Template:Todo:

Initialization

Run the following commands in a Linux terminal to get started. See installing pmbootstrap for more detailed instructions with a shortcut and tab completion.

$ 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 (one that supports device nodes and symbolic links). Notably unsupported are: eCryptFS, encfs, fat, ntfs, nfs shares, tmpvs, and 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

Note We assume that you have a shortcut for pmbootstrap set up, that points to ./pmbootstrap.py.
Note 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 device 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 (if, for example, 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 automatically fills 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 your 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 fastboot format system for fastboot compatible devices, or simply install the known working OS, e.g. Android, on it. And if you really know what you are doing, you might consider using dd). 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). To boot from SD, with the device in fastboot mode (with device off, press Power + Volume Down until it enters fastboot mode), type the first line into your computer:

$ 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