User:Knuxify/Draft:Porting guide/First boot
With both the kernel and device packages created and built, the next step is to generate a postmarketOS image, flash it to the device and test it.
Generating the image
To generate the image, run pmbootstrap install
. This command does three things:
- Builds a chroot with the full postmarketOS installation, as it will be installed onto the device
- Asks for the user and disk encryption (if enabled) password
- Generates an image file that will later be flashed, and for SD card installations -- flashes the generated image to the specified SD card.
Depending on how you want to install postmarketOS, you may also want to append the following flags to the above command:
Usage examples
Choose one of the following depending on your usecase.
Generating a regular image
If you want to generate an image to flash to the device, run pmbootstrap install
without any parameters:
$ pmbootstrap install
Then continue to the #Flashing section.
Installing to the SD card or USB storage
WARNING: This will overwrite all data on the SD card! Make sure any important data is backed up, and double-check that you have the correct device selected. |
This works for any block device, including SD cards and USB drives. We will assume that an SD card is used, but these commands will work for any install target. |
Alternatively, you can place the rootfs on the SD card (the kernel still needs to be flashed to the device, or booted with pmbootstrap flasher boot
if the device supports it - more on that later).
First, find the path to your device using lsblk
. SD cards will usually begin with /dev/mmcblk
. If you're unsure, run sudo fdisk -l /dev/[yourdevice]
- this should print information about the device, including the model, which should be enough to tell whether it's the device you're looking for.
You'll need the path without the partition number at the end (for example, /dev/mmcblk0
, not /dev/mmcblk0p1
).
Then, run the following command (replace /dev/mmcblk...
with the path you got in the previous step):
$ pmbootstrap install --disk=/dev/mmcblk...
Continue to the #Flashing the kernel section.
Flashing
WARNING: This is your last chance to make sure all important data has been backed up from the device! |
If you chose the none flashing method, skip this section, and use your own method to flash the image to the device - see #Exporting the images. |
Once the image has been generated, the next step is to flash it to the device. This is handled by the pmbootstrap flasher
command, which automatically uses the correct flashing tool for your device, as declared in deviceinfo.
At this point, read the Installation section in your device's wiki page. The wiki page for your device might contain additional information or prerequisites for flashing (for example, some devices will require you to flash a secondary bootloader like lk2nd before flashing the other images).
Flashing the rootfs
If you chose an SD card/USB install, and used the --disk flag, you can skip this step; this is only used to flash the rootfs to the device. Proceed to #Flashing the kernel. |
Boot your device into its dedicated download/flashing mode; the exact steps differ depending on the device, but usually involve holding down a button combination while booting up the phone, or running adb reboot bootloader
. Check your device's wiki page for instructions.
Then, run the following command:
$ pmbootstrap flasher flash_rootfs
To specify the partition to flash the rootfs to, use the --partition
parameter:
$ pmbootstrap flasher flash_rootfs --partition=userdata
Flashing the kernel
Boot your device into its dedicated download/flashing mode; check your device's wiki page for instructions.
Then, run the following command:
$ pmbootstrap flasher flash_kernel
If your device uses fastboot, to reboot your device after flashing, run pmbootstrap chroot fastboot reboot . Using this command, rather than manually shutting down your device, ensures that writing finishes correctly. |
Exporting the images
If you chose the none
flash method, or otherwise want to get the raw image files, you can run:
$ pmbootstrap export
This will place symlinks in /tmp/postmarketOS-export
to the generated image files. The files you're most likely interested in are:
boot.img
- Android boot.img image;uImage
- U-Boot-style kernel image;vmlinuz
- raw kernel image;vendor-codename.img
(named after device codename) - combined rootfs partition (with both boot and root subpartitions).