FORUMS
Remove All Ads from XDA

update-script syntax - A guide for ROM devs, modders, and themers

85 posts
Thanks Meter: 46
 
Post Reply Email Thread
Introduction ___________________________________
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.
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.)

Examples! __________________________
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).

Highlight syntax:
Commands bold, black
Functions light-blue
Strings red
Integers/numbers and booleans orange
Variables dark-blue
ROOT: green, bold, path/path green
Equal signs, etc pink
Parentheses light-purple

Code:
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:
Whoa . Lotsa weird numbers and long commands. But it installs a functioning, rooted Eclair Hero, with busybox, on the G1 with all the right permissions, with no hiccups.

Let's pull it apart.

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.

Code:
assert compatible_with("0.2")  == "true"
show_progress 0.1 0
The first line here is an "assert", a boolean condition.
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.

Code:
format SYSTEM:
copy_dir PACKAGE:system SYSTEM:
This looks easy. Because it is.

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/.

Code:
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----------]
These are important, too, especially for a rooted/modded rom. The symlink command takes two arguments. Not quite like your Linux/Unix/POSIX "ln -s" command, since it accepts a ROOT: path syntax. The first argument is taken as-is, though, and can be either of:
- 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[0], 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.

Code:
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
Permissions. Ugggh. Probably one of the more confusing things here, since if they're set wrong, some parts of, if not the entire Android system, will fail hard.

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.

__________________________________________________ ____

Changelog:
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.
The Following 24 Users Say Thank You to sirocyl For This Useful Post: [ View ] Gift sirocyl Ad-Free
 
 
3rd March 2010, 10:51 AM |#2  
sirocyl's Avatar
OP Member
Thanks Meter: 46
 
More
Space reserved for expansion: Command glossary and reference.
3rd March 2010, 10:51 AM |#3  
sirocyl's Avatar
OP Member
Thanks Meter: 46
 
More
Appendix A: Roots and Partitions ________
This is a list of all the available roots in the Android recovery, as scoped from roots.c in the source code, and df and mount on the device.

Code:
  ROOT:     (Linux block device) /mountpoint/ fs, size
    Description.

  BOOT:     (/dev/mtdblock[?]) / (RAM)  Raw
    Kernel, ramdisk and  boot config.
  DATA:     (/dev/mtdblock5)   /data/   yaffs2, 91904kb
    User, system config,  app config, and apps (without  a2sd)
  CACHE:    (/dev/mtdblock4)   /cache/  yaffs2, 30720kb
    OTA cache,  Recovery/update config and temp
  MISC:     (/dev/mtdblock[?]) N/A     Raw
    [TODO: Get info on MISC:]
  PACKAGE:  (Relative to package file) N/A
    Pseudo-filesystem for update  package.
  RECOVERY: (/dev/mtdblock[?]) / (RAM) Raw,     [?]kb
    The recovery  and update environment's kernel and ramdisk.
    Similar to BOOT:.
  SDCARD:   (/dev/mmcblk0(p1)) /sdcard/ fat32,  32MB-32GB
    The microSD card. Update zip is usually here.
  SYSTEM:   (/dev/mtdblock3)   /system/ yaffs2, 92160kb
    The OS partition,    static and read-only.
  TMP:                         /tmp/    in RAM
    Standard Linux temporary directory.
    Cleared on poweroff/reboot.
[TODO: Find mtd partition for BOOT:, RECOVERY:, MISC:]
The Following 2 Users Say Thank You to sirocyl For This Useful Post: [ View ] Gift sirocyl Ad-Free
3rd March 2010, 10:58 AM |#4  
sirocyl's Avatar
OP Member
Thanks Meter: 46
 
More
One more space, if I should need it in the near future. Hey, rom devs get away with it, why not the documenters, upon whom they depend?
The Following User Says Thank You to sirocyl For This Useful Post: [ View ] Gift sirocyl Ad-Free
3rd March 2010, 05:56 PM |#5  
RichieDaze's Avatar
Senior Member
Flag New York City
Thanks Meter: 131
 
Donate to Me
More
Talking
This is a great topic!

I know most of these commands, but always wanted to perfect my understanding towards it's use in general for different tasks.

Great tut!
3rd March 2010, 11:49 PM |#6  
sirocyl's Avatar
OP Member
Thanks Meter: 46
 
More
Quote:
Originally Posted by RichieDaze

This is a great topic!

I know most of these commands, but always wanted to perfect my understanding towards it's use in general for different tasks.

Great tut!


Thanks! I knew it would be useful. But I haven't even finished it yet, mainly 'cause I had to dash off to school at the last minute.

I'm going to add to it now that I'm back home.
16th March 2010, 10:23 PM |#7  
adlx.xda's Avatar
Recognized Developer
Flag Madrid
Thanks Meter: 1,766
 
Donate to Me
More
Command to remove/delete file/dirs
Great post.

You could also add:

write_radio_image PACKAGE:radio.img

(working for Motorola MB200 Cliq/Dext at least)

I was wondering is there is there any command that can be used in update-script to remove files and/or directories?

Any further reference about this?

Thanks in advance
16th March 2010, 11:11 PM |#8  
JAguirre1231's Avatar
Senior Member
Flag I'm Guessing your mom isn't a valid city
Thanks Meter: 37
 
More
Quote:
Originally Posted by adlxdum

Great post.

You could also add:

write_radio_image PACKAGE:radio.img

(working for Motorola MB200 Cliq/Dext at least)

I was wondering is there is there any command that can be used in update-script to remove files and/or directories?

Any further reference about this?

Thanks in advance


Pretty sure to delete it would be

delete SYSTEM:app/Mms.apk


This would remove the stock messaging app for example
20th March 2010, 06:35 PM |#9  
adlx.xda's Avatar
Recognized Developer
Flag Madrid
Thanks Meter: 1,766
 
Donate to Me
More
Lightbulb run sh script from update-script
You can also run a custom #!/sbin/sh script from update-script:

run_program PACKAGE:script.sh

cool!
14th April 2010, 12:11 AM |#10  
jackal424's Avatar
Senior Member
Flag Austin
Thanks Meter: 17
 
Donate to Me
More
great resource. What language is are these zip files written? There has to be a syntax guide out there.
14th April 2010, 07:19 AM |#11  
zimphishmonger's Avatar
Senior Member
Thanks Meter: 742
 
More
Simply awesome.....sticky!
Post Reply Subscribe to Thread

Tags
android, guide, recovery, tutorial, update

Guest Quick Reply (no urls or BBcode)
Message:
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes