User:Knuxify/Draft:Porting guide/Generating device-specific packages
The first step of the porting process is to generate the initial device package and kernel package using pmbootstrap. The rough outline of the steps is:
- Install pmbootstrap, the postmarketOS build tool;
- Run
pmbootstrap init
to initialize it and tell it what device we're working with; - Let pmbootstrap generate the device package (and for downstream kernels, the kernel package);
- Fill the device package's
deviceinfo
file with information about the device; - Re-generate the checksum and build the
device-vendor-codename
package.
Installing pmbootstrap
We will be using pmbootstrap, the postmarketOS build tool, during the porting process.
Your distro may already have pmbootstrap available in its repositories. If it doesn't, or the packaged version is too old, you can also install pmbootstrap from git.
If you've already installed pmbootstrap before, run this command to update the local clone of the pmaports repository:
$ pmbootstrap pull
Initializing pmbootstrap and generating the initial packages
To begin the porting process, we must first initialize pmbootstrap and tell it what device we're working on. In this step, pmbootstrap will detect that we're trying to create a new port and generate the base for our device-specific packages for us.
To begin the process, run:
$ pmbootstrap init
When using pmbootstrap init, you will be prompted to answer some questions. In each prompt, the default answer is shown between brackets - to use the default, don't type anything and press Enter/Return. For example:
Continue? (y/n) [y]:
y . |
You will be asked to answer some questions to get your environment set up:
- Where to place the work path - this is where pmbootstrap will download files and set up chroots.
- For most users, the default suggested location (
~/.local/var/pmbootstrap
) is fine, but you can optionally move it e.g. to an external drive if more space is needed. - Note that only standard Linux filesystems like ext4 are supported - NTFS, VirtualBox shared folders and various exotic filesystems will not work. You should also have about ~10GB of free space.
- For most users, the default suggested location (
- The release channel to use - select
edge
here.edge
is the development branch of postmarketOS, and where new device ports go when upstreaming them.
Choosing the vendor/codename
You will be asked for the vendor (manufacturer) and codename of your device.
- The vendor will usually be the manufacturer's name, in lowercase. (If you're not sure, see how other devices from the same vendor do it.)
- The codename can be found in one of the following places:
- If your device is supported by a custom Android ROM, like LineageOS, the
android_device_...
repo contains the vendor and codename in its name. - If all else fails, you might be able to find the codename by looking up your device's name/model number followed by "codename".
- If your device is supported by a custom Android ROM, like LineageOS, the
At this point, you will get the following message:
[07:07:09] You are about to do a new device port for 'vendor-codename'.
[07:07:09] Continue? (y/n) [y]:
Answer y
here. You will be asked to answer some questions about the device (see also: How to find device-specific information):
TODO: Once pmbootstrap!2607 gets merged, add a point about selecting downstream/mainline according to point on previous page |
- Device architecture - aarch64 for 64-bit ARM, armv7 for 32-bit ARM. armhf is very rare, and only applies to very old ARMv6 devices with floating point units (FPUs).
- Manufacturer, Name, Year - metadata of the device, saved to the deviceinfo file and displayed in the OS.
- Chassis:
handset
for phones,tablet
for tablets,laptop
for laptops. - Does the device have a sdcard or other external storage medium? (y/n) -
y
if your device has an SD card slot or similar,n
otherwise.
Selecting the flash method
You will be prompted to select a flash method; this is what is used by pmbootstrap flasher
to know which set of commands to use to perform its operations.
[06:01:08] Which flash method does the device support?
[06:01:08] Flash method (0xffff/fastboot/heimdall/mtkclient/none/rkdeveloptool/uuu) [none]:
- fastboot - the most commonly used flashing format for most Android devices. If you use the
fastboot
command to communicate with the bootloader, select this option. - heimdall - implements the Odin protocol used in Samsung's Download Mode (all Samsung devices).
- SoC-specific options (try fastboot first, if available):
- mtkclient - used to flash directly to Mediatek devices, including ones with locked/broken bootloaders
- rkdeveloptool - used to flash directly to Rockchip devices with Rockchip's own download mode.
- uuu - used to flash directly to NXP devices with their own download mode.
- 0xffff - used for the Nokia N900 and no other devices.
If your device does not support flashing over USB with a command, select none. The selected flash method can be changed later by modifying the deviceinfo file.
Analyzing a boot.img
If you're working with a non-Android device, you can skip this step. |
To get the remaining flasher information, pmbootstrap needs to analyze a boot.img file. You can get this file from any Android ROM, or use a recovery image like TWRP instead.
[06:26:07] You can analyze a known working boot.img file to automatically fill out the flasher information for your deviceinfo file. Either specify the path to an image or press return to skip this step (you can do it later with 'pmbootstrap bootimg_analyze').
[06:26:07] Path:
You can either pass the path to the boot.img file here directly, or leave it empty for now and run pmbootstrap bootimg_analyze path/to/boot.img
later.
Remaining pmbootstrap configuration
At this point, the device-specific packages will be generated:
[06:28:49] *** pmaport generated: /home/user/.local/var/pmbootstrap/cache_git/pmaports/device/downstream/device-vendor-codename
[06:28:49] *** pmaport generated: /home/user/.local/var/pmbootstrap/cache_git/pmaports/device/downstream/linux-vendor-codename
Keep these locations in mind; you will need to modify the files in them shortly.
Afterwards, pmbootstrap will ask you the usual setup questions. For most questions, the defaults are fine; if you have any doubts, follow the steps from Installation/Using pmbootstrap#Initializing pmbootstrap.
When you're asked to select the user interface to install - xfce4 is a good first choice for both downstream and (close to) mainline ports. |
Watching the pmbootstrap log
Throughout this guide, you might see references to "the pmbootstrap log". Some information that is useful when porting, such as download or build errors, is only printed to the pmbootstrap log and not displayed immediately to the user.
It is recommended to run the following command in another terminal to watch the logs update live:
$ pmbootstrap log
The log can also be found in the work directory (~/.local/var/pmbootstrap/log.txt
by default).