From d59a60accafcd988d6b0d6e04a4d4ae9edfadcd5 Mon Sep 17 00:00:00 2001 From: magdesign Date: Fri, 1 Nov 2024 19:55:21 +0000 Subject: [PATCH] docs: update chroot/debugging/usage (MR 2469) Add the content from README.md to these files. Tweaked-by: Oliver Smith --- docs/chroot.rst | 54 +++++++++++++++++++++++ docs/debugging.rst | 33 ++++++++++++++ docs/index.rst | 2 + docs/usage.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 194 insertions(+) create mode 100644 docs/chroot.rst create mode 100644 docs/debugging.rst diff --git a/docs/chroot.rst b/docs/chroot.rst new file mode 100644 index 00000000..ba14c3e1 --- /dev/null +++ b/docs/chroot.rst @@ -0,0 +1,54 @@ +###### +Chroot +###### + +chroot (short for "change root") is a system call and command that changes the apparent root directory. +This can come in very handy to make some modifications in the generated image file. + + + +Enter the armhf building chroot: + +.. code-block:: shell + + $ pmbootstrap chroot -b armhf + + +Run a command inside a chroot: + +.. code-block:: shell + + $ pmbootstrap chroot -- echo test + + +Safely delete all chroots: + +.. code-block:: shell + + $ pmbootstrap zap + + + +Use ``chroot`` to install a specific kernel version from an apk file. + + +copy your working kernel apk to the chroot dir of pmbootstrap: + +.. code-block:: shell + + $ sudo cp /path/of/linux-kernel.apk ~/.local/var/pmbootstrap/chroot_rootfs_oneplus-enchilada/ + +enter chroot + +.. code-block:: shell + + $ pmbootstrap chroot -r + + +and install the package: + +.. code-block:: shell + + $ apk add linux-kernel.apk + + diff --git a/docs/debugging.rst b/docs/debugging.rst new file mode 100644 index 00000000..a784750d --- /dev/null +++ b/docs/debugging.rst @@ -0,0 +1,33 @@ +######### +Debugging +######### + +pmbootstrap writes all log output and each shell command it runs to log.txt inside the work dir. +Use the following command to follow the log in a second terminal: + +.. code-block:: shell + + $ pmbootstrap log + + +Use ``-v`` on any action to get verbose logging: + +.. code-block:: shell + + $ pmbootstrap -v build hello-world + + +Parse a package from an APKINDEX and return it as JSON: + +.. code-block:: shell + + $ pmbootstrap apkindex_parse $WORK/cache_apk_x86_64/APKINDEX.8b865e19.tar.gz hello-world + + +``ccache`` statistics: + +.. code-block:: shell + + $ pmbootstrap stats --arch=armhf + + diff --git a/docs/index.rst b/docs/index.rst index 1f0dc3de..58074d19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,8 @@ For further information, please check out the `postmarketOS-wiki`_. installation usage + chroot + debugging api/modules mirrors diff --git a/docs/usage.rst b/docs/usage.rst index cbcd248e..caa44fba 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -18,6 +18,111 @@ If you already ran this before, run the following to update your local clone of $ pmbootstrap pull + +Quick health check and config overview: + +.. code-block:: shell + + $ pmbootstrap status + + +After successfully finishing the ``init`` sequence with answering all questions, its time to build the +installation: + +Devices like the PinePhone, Samsung Galaxy S II, Nokia N900, various laptops etc. can boot from an SD card, USB stick or other external storage. Find the name with lsblk first and make sure it is the right one as you will overwrite everything on it. Use a path without partition number at the end, such as /dev/mmcblk0. If your device is able to boot from SD card without flashing anything (such as the PinePhone), you should then be able to insert SD card into your device and boot it up. + +.. code-block:: shell + + $ pmbootstrap install --sdcard=/dev/mmcblk... --fde + + +For devices where you will flash directly to the internal storage, as mostly all sdm845 devices, you can build the installation as: + +.. code-block:: shell + + $ pmbootstrap install + + +or with full disk encryption: + +.. code-block:: shell + + $ pmbootstrap install --fde + +and then flash it with the ``pmbootstrap flasher`` while the device is in ``fastboot`` mode: + +.. code-block:: shell + + $ pmbootstrap flasher flash_rootfs + + +and also the kernel: + +.. code-block:: shell + + $ pmbootstrap flasher flash_kernel + + +For getting images on the local machine instead of directly flashing them, execute: + +.. code-block:: shell + + $ pmbootstrap export + + +To extract the generated initramfs: + +.. code-block:: shell + + $ pmbootstrap initfs extract + + +Build and flash Android recovery zip: + +.. code-block:: shell + + $ pmbootstrap install --android-recovery-zip + $ pmbootstrap flasher --method=adb sideload + + +Update existing installation on SD card: + +.. code-block:: shell + + $ pmbootstrap install --disk=/dev/mmcblk0 --rsync + + +Run the image in QEMU: + +.. code-block:: shell + + $ pmbootstrap qemu --image-size=1G + + +**Device Porting Assistance** + +Analyze Android boot.img files (also works with recovery OS images like TWRP): + +.. code-block:: shell + + $ pmbootstrap bootimg_analyze ~/Downloads/twrp-3.2.1-0-fp2.img + + +Check kernel configs: + +.. code-block:: shell + + $ pmbootstrap kconfig check + + +Edit a kernel config: + +.. code-block:: shell + + $ pmbootstrap kconfig edit + + + For further details on the different actions please see below and refer to the wiki-arcticle on `pmbootstrap`_. .. autoprogram:: pmb.parse:get_parser()