Android, as it is on HTC devices, has quite an advanced system for installing the OS and updates thereof, not unlike install systems for PC's, like the Windows installer system and NullSoft Install System (NSIS).
"ROM"s for Android aren't necessarily ROMs, but packages. containing files. Technically, a Nandroid backup of a clean install could be considered a ROM.
The update-script file, found in /META-INF/com/google/android/update-script (relative to the package), is necessary for any ROM, no matter how simplistic, to be flashed through the recovery.
(Nandroid-style, or ROM Flash-images, found in a collection with [system|data|cache|boot|recovery|radio|bootloader|s plash|etc.].img files, can usually be flashed using fastboot, or adb/terminal via flash_image, but that is out of the scope of this guide.Examples! __________________________
They can, however, be flashed through an update.zip file, which will be discussed in detail below.
Goldcards, .nbh files and flashing from the bootloader is not covered; see an unbrick/root guide for details.)
Now that we got that out of the way, let's take a look at an update-script file, from KiNgxKxKlair-Hero-Eclair-v1.3_signed (since I have this readily at hand.) Code abridged somewhat (thousands of symlink commands trimmed off).
Commands bold, black
Integers/numbers and booleans orange
ROOT: green, bold, path/path green
Equal signs, etc pink
assert compatible_with("0.2") == "true" show_progress 0.1 0 format SYSTEM: copy_dir PACKAGE:system SYSTEM: symlink dumpstate SYSTEM:bin/dumpcrash symlink toolbox SYSTEM:bin/newfs_msdos symlink toolbox SYSTEM:bin/renice symlink toolbox SYSTEM:bin/notify [----------snip----------] symlink busybox SYSTEM:xbin/zcip symlink busybox SYSTEM:xbin/zcat symlink busybox SYSTEM:xbin/yes symlink busybox SYSTEM:xbin/xargs [----------snip----------] set_perm_recursive 0 0 0755 0644 SYSTEM: set_perm_recursive 0 2000 0755 0755 SYSTEM:bin set_perm_recursive 0 2000 0755 0755 SYSTEM:xbin set_perm 0 3004 02755 SYSTEM:bin/ping set_perm 0 0 04755 SYSTEM:bin/su set_perm 0 0 04755 SYSTEM:xbin/busybox set_perm 0 0 04755 SYSTEM:xbin/iptables set_perm 0 0 04755 SYSTEM:xbin/dnsmasq set_perm_recursive 1002 1002 0755 0440 SYSTEM:etc/bluez set_perm 0 0 0755 SYSTEM:etc/bluez set_perm 1002 1002 0440 SYSTEM:etc/dbus.conf set_perm 1014 2000 0550 SYSTEM:etc/dhcpcd/dhcpcd-run-hooks set_perm 0 2000 0550 SYSTEM:etc/init.goldfish.sh set_perm_recursive 0 0 0755 0555 SYSTEM:etc/ppp format DATA: copy_dir PACKAGE:data DATA: symlink /data/app_s SYSTEM:app symlink /data/system-framework SYSTEM:framework set_perm 1000 1000 0771 DATA:app show_progress 0.2 0 format BOOT: write_raw_image PACKAGE:boot.img BOOT: show_progress 0.2 10 format CACHE:
How It Works ________________________
The update-script seems greatly over-complicated, but a lot of it is simple (and some can just be copy-pasted as-is to make up the skeleton of the script.
assert compatible_with("0.2") == "true" show_progress 0.1 0
If the argument following the assert (a function, command, or "variable" condition) is true, the script continues, otherwise it halts.
If you are writing an update-script for a recovery that's compatible with specification v0.2 (which I cover here, and is on most modded post-Cupcake recovery systems to date), you MUST include this first line.The compatible_with() is a function, which itself returns true if "0.2" OR "0.1" is passed to it, in a v0.2-spec recovery (post-Cupcake).
The second line changes the progress-bar fill. It takes two arguments, a fraction and a duration. Half of the progress bar is taken by verification before this point, so the remaining fraction is relative to the second half (1.0 is half, 0.5 is a quarter, and so forth.)
The fraction is relative to 1.0, which is the post-verification progress.
The duration is in seconds, and specifies how slowly the fraction fills.
format SYSTEM: copy_dir PACKAGE:system SYSTEM:
The format command takes a "root", a.k.a partition name, as its only argument, and does exactly what it says on the tin - formats a "root" clean.
FORMATTING ERASES DATA IRREVERSIBLY. Just wanted to make that clear, in case it wasn't already.The available roots are listed in the appendix.
The copy_dir command is also fairly simple. It copies the contents of a folder from one place, to another, making the folder if it doesn't exist.
In this case, it copies from the update package's system folder to /system/.
symlink dumpstate SYSTEM:bin/dumpcrash symlink toolbox SYSTEM:bin/newfs_msdos symlink toolbox SYSTEM:bin/renice symlink toolbox SYSTEM:bin/notify [----------snip----------] symlink busybox SYSTEM:xbin/zcip symlink busybox SYSTEM:xbin/zcat symlink busybox SYSTEM:xbin/yes symlink busybox SYSTEM:xbin/xargs [----------snip----------]
- A linux executable that's in the $PATH environment (such as SYSTEM:/bin, :/sbin, :/xbin
- A file somewhere.
The command, in the source code, does the following:
- Counts arguments. Exactly two taken, or fail with error.
- Translates the ROOT: path notation into something POSIX compatible, or fails with an error
- Double-checks that ROOT: is mounted, and mounts, otherwise throws an error and stops
- symlink(argv, path) - standard C. Takes the first argument, and the translated ROOT: path, and links the path to the first argument. Or fails with an error.
The first argument is the target, i.e., what to link to.
The second argument is the link itself.
set_perm_recursive 1002 1002 0755 0440 SYSTEM:etc/bluez set_perm 0 0 0755 SYSTEM:etc/bluez set_perm 1002 1002 0440 SYSTEM:etc/dbus.conf set_perm 1014 2000 0550 SYSTEM:etc/dhcpcd/dhcpcd-run-hooks set_perm 0 2000 0550 SYSTEM:etc/init.goldfish.sh set_perm_recursive 0 0 0755 0555 SYSTEM:etc/ppp
You have two commands, set_perm and set_perm_recursive. They both set the ownership and UNIX permissions on files; one on a single file, or a folder (not its contents), and the other acts on everything within the folder.
v0.1: Initial version, explanation of recovery system and parts of the update-script from King's eclair hero
v0.2: Incomplete still, added more tear-apart of the King update-script. And... SYNTAX HIGLIGHTING!
Will continue on explaining set_perm/_recursive in v0.3, expected later tonight.