Difference between revisions of "Pmbootstrap development guide"

From postmarketOS
Jump to: navigation, search
(Code: update and link to https://github.com/postmarketOS/pmbootstrap/pull/1316)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Tips ==
+
=== Installation code (<code>pmb.install.*</code>) ===
If happens often that we commit changes and then we realize that we forgot to regenerate APKBUILD checksums. This is noticed by Travis ([https://travis-ci.org/postmarketOS/pmbootstrap/builds/261056579 example]) but you might want to avoid it.
+
Whenever you change the installation process, also adjust the recovery zip installer (which performs a good part of the installation procedure directly on the Android device with a shell script).
 
 
You can install the following git hook that is run every time before you commit.
 
 
 
Copy the following code to <code>.git/hooks/pre-commit</code> inside your <code>pmbootstrap</code> repository:
 
 
 
<pre class="shell">#!/bin/sh
 
#
 
# postmarketOS pre-commit hook
 
# Checks for bad checksums
 
 
 
./test/check_checksums.py</pre>
 
Now this is what happens when you forgot to regenerate checksums for some aport and try to commit
 
  
<pre class="shell">$ git commit -a
+
=== What is this <code>args</code> variable used everywhere? ===
Checking device-qemu-aarch64 for correct checksums
+
See the big comment at the top of [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/helpers/args.py <code>pmb/helpers/args.py</code>].
[13:45:23] (native) generate checksums for device-qemu-aarch64
 
[13:45:23] Done
 
MM aports/device/device-qemu-aarch64/APKBUILD
 
  
diff --git a/aports/device/device-qemu-aarch64/APKBUILD b/aports/device/device-qemu-aarch64/APKBUILD
+
=== Executing shell commands ===
index 99b811b..c4cee6c 100644
+
Use one of the following functions instead of Python's built in <code>subprocess</code>:
--- a/aports/device/device-qemu-aarch64/APKBUILD
 
+++ b/aports/device/device-qemu-aarch64/APKBUILD
 
@@ -21,4 +21,4 @@ package() {
 
                &quot;$pkgdir&quot;/etc/deviceinfo
 
}
 
 
-sha512sums=&quot;a18ab789c19d8802be6a9e9c842f4c304f267bd78f46b096b4ba6609430d1544e0a9eca9bc22db67a0728efae3aad6c2def9f7e64157d31aeb31b4bb839076d5  deviceinfo&quot;
 
+sha512sums=&quot;8df46383685a40a96b7c604c29d413ecdd4b4a9b92cb61f452283042f189b1ca01cb70632fec0711dd67229e0501729762c6841359ac7ea455f516b512abce9c  deviceinfo&quot;
 
  
** The checksums are not correct</pre>
+
* [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/helpers/run.py <code>pmb.helpers.run.user()</code>]
After that, simply do <code>git commit -a --amend -n</code> (<code>-n</code> is necessary so that this time the hook is not triggered).
+
* [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/helpers/run.py <code>pmb.helpers.run.root()</code>]
 +
* [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/chroot/user.py <code>pmb.chroot.user()</code>]
 +
* [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/chroot/root.py <code>pmb.chroot.root()</code>]
  
== Code ==
+
These functions call [https://gitlab.com/postmarketOS/pmbootstrap/blob/master/pmb/helpers/run_core.py <code>pmb.helpers.run_core.core()</code>] internally to write to the log file (that you can read with <code>pmbootstrap log</code>) and timeout when there is no output. A lot of function parameters are passed through to <code>core()</code> as well, see its docstring for a detailed description of what these parameters do.
=== pmb.helpers.run ===
 
Use <code>pmb.helpers.run.root()</code> and <code>pmb.helpers.run.user()</code> instead of <code>subprocess</code> because these logs to the log file.
 
  
==== Shell commands ====
+
==== Writing to files ====
 
{{note|See also: {{github|1316}} Properly escape commands in pmb.chroot.user()}}
 
{{note|See also: {{github|1316}} Properly escape commands in pmb.chroot.user()}}
 
The passed commands gets interpreted as single command, and not executed in a shell. This means something like the following '''will not work''':
 
The passed commands gets interpreted as single command, and not executed in a shell. This means something like the following '''will not work''':
Line 62: Line 39:
 
pmb.chroot.root(args, ["mv", "/tmp/somefile", "/etc/somefile"])
 
pmb.chroot.root(args, ["mv", "/tmp/somefile", "/etc/somefile"])
 
</syntaxhighlight>
 
</syntaxhighlight>
 
=== pmb.install ===
 
Whenever you change the installation process, also adjust the recovery zip installer (which performs a good part of the installation procedure directly on the Android device with a shell script).
 
  
 
== See also ==
 
== See also ==
 
* [[Testsuite]]
 
* [[Testsuite]]
 +
 +
[[Category:Guide]]

Latest revision as of 04:23, 17 December 2018

Installation code (pmb.install.*)

Whenever you change the installation process, also adjust the recovery zip installer (which performs a good part of the installation procedure directly on the Android device with a shell script).

What is this args variable used everywhere?

See the big comment at the top of pmb/helpers/args.py.

Executing shell commands

Use one of the following functions instead of Python's built in subprocess:

These functions call pmb.helpers.run_core.core() internally to write to the log file (that you can read with pmbootstrap log) and timeout when there is no output. A lot of function parameters are passed through to core() as well, see its docstring for a detailed description of what these parameters do.

Writing to files

See also: #1316 Properly escape commands in pmb.chroot.user()

The passed commands gets interpreted as single command, and not executed in a shell. This means something like the following will not work:

pmb.chroot.root(args, ["echo", "test", ">", "/tmp/test"])

Instead, if you need shell functionality in the call, you can wrap the call with sh -c. Here's one example with the parameters correctly escaped (you don't need to do that for the strings in this example, but if you pass variables then they should be escaped properly):

shell_cmd = "echo " + shutil.quote("test") + " > " + shutil.quote("/tmp/test")
pmb.chroot.root(args, ["sh", "-c", shell_cmd])

Another technique (especially if you need to run many commands in the shell at once) is writing all commands down into a temporary file and executing it with the shell, see for example pmb/chroot/initfs.py.

Writing files to the chroot

The users in the chroots (root and pmos) have different user IDs than the user of the host system. Therefore we can't just write a file to anywhere in the chroot. But we can write to /tmp and move the file afterwards:

with open("tmp/somefile", "w") as handle:
    handle.write("It works")
pmb.chroot.root(args, ["mv", "/tmp/somefile", "/etc/somefile"])

See also