[GUIDE] introduction to edify updater script (installer zip)

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
This guide purpose is to introduce you with edify scripting language used by Android to run updater-scripts. this guide is based on an article on this web http://www.freeyourandroid.com/guide/introdution_to_edify

why should you read this?
this guide will be usefull for someone who want to make a patch, install an apk, or modify a rom with a simple update.zip file. most of android devices are using edify script instead of amend script. this guide will be applicable in almost every android devices. a simpe example of these script we can found on installer for theme. while the complicated one is aroma installer which are used for GUI installation for rom.

below are examples of functions used in an Edify Updater-script:
Function Name: mount
Function Syntax: mount(fs_type, partition_type, location, mount_point)
Parameter Details:
fs_type = yaffs2 ext4 ext2 ext3 rfs vfat
partition_type="MTD" | "EMMC"
location = partition | device
mount_point = target folder to mount FS.
Action: Mounts a filesystem to the defined mount point
Returns: The mount point if successful, null if failed
/system partition is automatically mounted. this command is needed when you need to mount another partition beside /system or in any condition when recovery mode failed to mount your system partition. the system's location is /dev/stl9, cache /dev/stl10, and data /dev/stl11 (all partition type commonly rfs, will be differ if you have custom kernel or rom). if you want to mount sdcard, the location is mmcblk0pX with x is the partition number.
Function Name: is_mounted
Function Syntax: is_mounted(mount_point)
Parameter Details: mount_point = string, mount point to check if is mounted
Action: Checks if a filesystem is mounted.
Returns: The mount point if mounted, otherwise, returns null
Function Name: unmount
Function Syntax: unmount(mount_point)
Parameter Details: mount_point = string, mount point to unmount
Action: Unmounts the filesystem
Returns: The mount point that was dismounted if successful, otherwise it returns null
Function Name: format
Function Syntax: format(fs_type, partition_type, location)
Parameter Details:
fs_type = string,yaffs2 ext4 ext2 ext3 rfs vfat
partition_type= string, "MTD" | "EMMC"
location = string, partition | device
Action: Formats a filesystem as specified
Function Name: delete
Function Syntax: delete(file1, file2, ..., fileN)
Parameter Details: string, file to delete
Action: Deletes a file. Must specify at least one file; multiple files can be specified as multiple arguments
Function Name: delete_recursive
Function Syntax: delete_recursive(dir1, dir2,...,dirN)
Parameter Details: string, directory to recursively delete
Action: Deletes a folder and all of its contents. At least 1 directory must be specified; multiple directories can be specified as additional arguments.
Function Name: show_progress
Function Syntax: show_progress(frac, sec)
Parameter Details:
frac = fraction of progress completed
sec = total seconds
Action: Displays flashing progress in the recovery system
Function Name: set_progress
Function Syntax: set_prograss(frac)
Parameter Details: frac=fraction of progress
Function Name: package_extract_dir
Function Syntax: package_extract_dir(package_path, destination_path)
Parameter Details:
package_path = string, directory in package to extract
destination_path = string, target point to extract files to
Action: Extract the all of the files in a directory in the package to the target specified.
this command is the usefull one for app/mod installation. don't worry about same filename, the newer one will automatically delete the old one. if you want to make your file easier to use, you can use 'package_extract_dir("system", "/system")'. in this way, you don't need to make multiple command to copy your files and folders into system partition. everything under system folder will be copied into your system partition. see my example file below for further details.
Function Name: package_extract_file
Function Syntax:
package_extract_file(package_path)
or
package_extract_file(package_path, destination_path)
Parameter Details:
package_path = string, file in the package you want to extract
destination_path, target folder to extract the file to.
Action: Extracts a single file from your update package to the target specified
Function Name: file_getprop
Function Syntax: file_getprop(file, key)
Parameter Details:
file = string, filename to check
key = string, key in file to return the value of
Action: Checks for a value in a file?
Function Name: symlink
Function Syntax: symlink(target, src1, src2, ..., srcN)
Parameter Details:
target = string, the target of the symbolic link
srcX = the symbolic link to create that points to the target
Action: Unlinks any existing symbolic links before creating the new symbolic links.
Function Name: set_perm
Function Syntax: set_perm(uid, gid, mode, file1, file2, ..., fileN)
Parameter Details:
uid = user id
gid = group id
mode = permission mode
fileX = file to set permission on
Action: Sets permissions of a file or set of files specified. At least one file must be specified (the first four parameters are required)
Function Name: set_perm_recursive
Function Syntax: set_perm_recursive(uid, gid, dirmode, filemode, dir1, dir2, ...dirN)
Parameter Details:
uid = user id
gid = group id
dirmode = permission to set to directories contained within the specified directory
filemode = permission to set to files contained within the specified directory
dirX = directory to set permission on
Action: Set permissions of a directory or set of directories and all files and folders within them. At least one directory must be specified (The first 5 parameters are required)
Function Name: getprop
Function Syntax: getprop(key)
Parameter Details: key = string, the property you want the system to return
Action: This function returns the value of the property specified. This is used to query platform information from the build.props file.
Function Name: write_raw_image
Function Syntax: write_raw_image(file, partition)
Parameter Details:
file - string, the source .img file to be read from
partition - string, the destination partition to write the .img file to
Description: This function writes an img file to a partition.
this command usually used to install kernel. somehow it doesn't work for sgy. you'll need to run bmlunlock program to install the kernel on sgy. check faqbly's kernel installer for further information.
Function Name: apply_patch
Function Syntax: apply_patch(srcfile, tgtfile, tgtsha1, tgtsize, sha1_1, patch_1, ..., sha1_x, patch1_x)
Parameter Details:
srcfile - string, source file to be patched (file to read in)
tgtfile - string, destination file to write the patched file to
tgtsha1 - string, sha1 hash of the target file as it should hash out after the patches apply properly
sha1_x - string, sha1 hash of the patch data that's to be written to the target file
patch1_x- string, actual patch to apply to the target file
Action: This function is used to apply patches to a file.
Function Name: apply_patch_check
Function Syntax: apply_patch_check(file, sha1_1, ..., sha1_x)
Parameter Details:
file - string, file to check
sha1_x - hash to check for?
Action: Either checks if a file has been properly patched, or checks if a file can be patched. Need to check the source code of the "applypatch_check" function that is called from here.
Function Name: apply_patch_space
Function Syntax: apply_patch_space(bytes)
Parameter Details: bytes = number of bytes to check for
Action: Checks the cache to verify that there is enough space to write the patched files to it and returns something. Need to test this function to verify.
Function Name: read_file
Function Syntax: read_file(filename)
Parameter Details: filename - string, the filename to read the contents of
Action: This function returns the contents of a file.
Function Name: sha1_check
Function Syntax:
sha1_check(data)
or
sha1_check(data, sha1_hex, ..., sha1_hexN)
Parameter Details:
data - the contents of file to calculate the sha1 hash of - must be in the read_file format
sha1_hexN - A particular sha1_hex string that you want the file data to match
Action: If only data is specified, then the function returns the sha1_hex string of the data. The optional parameters are used if you want to verify that the file you are checking for is one of a list of hashes. It reutrns the hash it matches, or returns nothing if it doesn't match any of the mentioned hashses.
Function Name: ui_print
Function Syntax: ui_print(msg1, ..., msgN)
Parameter Details: msg - String, message to be outputted to the user during the patch process
Action: This function prints/echos a message to the console while the script is running. At least 1 parameter needs to be specified, you can specify additional msg parameters and they will be concatenated to the output.
Function Name: run_program
Function Syntax: run_program(prog, arg1, .., argN)
Parameter Details:
prog - string, program to execute
argN - string, arguments for the program that is being executed
Description: Executes a program with the arguments specified. Returns a string, I assume it is the buffer of the stdout of the program executed, need to test.
Function Name: ifelse
Function Syntax: ifelse(condition, truecondition, falsecondition)
Parameter Details:
condition - an expression to evaluate
truecondition - Edify script block to execute if true
falsecodnition - Edify script block to execute if false
Description: This is the if-then construct of the Edify scripting language. The truecondition or falsecondition arguments can be a single edify command or a script block. Script blocks can be formed by enclosing the parameter with parenthesis, and seperating the commands with semicolons\
Function Name: abort
Function Syntax: abort()
Parameter Details: no paremeters
Description: Aborts script execution.
Function Name: assert
Function Syntax: assert(condition)
Parameter Details: condition - boolean
Description: If condition evaluates to false, stops script execution, otherwise continues processing.
to run the script you'll need a binary file for edify script. you can find an example of the update.zip with the binary file here http://www.mediafire.com/download.php?rti5lc5358w51nn
this one is an example of updater script for roms
http://www.mediafire.com/download.php?nxgiz0993brp9re

NOTE:
1. that file used to enable bootanimation on dxlb or newer firmware. it is still in progress so don't install it. you can use that file as a base to create your own installer zip with edify script.
2. don't use notepad to edit the file. you can use notepad++ instead.
3. all syntax inside () is always within ". for an example, syntax for mount is 'mount(fs_type, partition_type, location, mount_point)', so if we want to mount the system partition we'll type 'mount("rfs", "EMMC", "/dev/block/stl19", "/system")'.
 
Last edited:

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
you're already used to work with custom roms. everything you need to know is already inside your rom. for a simple updater script used to install app or file I always use these script.
Code:
ui_print("Installing");
package_extract_dir("system", "/system");
ui_print("Completed");
ui_print("have a nice day");
ui_print("[email protected]");
 

Miche1asso

Senior Member
Apr 11, 2012
680
500
0
Treviso
Hi Kuro, great tutorial as usual.

Listen, any idea why in the S5570I stock recovery with the stock kernel the format command requires 4 parameters instead of 3?

Code:
format () expects 4 args. got 3
Do you know which one is the correct syntax? Also, what's the difference between EMMC and MTD??

I feel more and more about throwing this phone out of the window. The iPhone 5 is very tempting.
 

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
that problem comes from the binary file. I've found at least three version of the binary file. in my guide the syntax is format(fs_type, partition_type, location) or in an example format("EXT4", "MTD", "/dev/block/stl19") but some binary file need to specify more about the partition. the syntax in an example will be format("EXT4", "MTD", "/dev/block/stl19", "/system"). the differences between EMMC and MTD is the hardware of the memory device. an sdcard is an EMMC device, so that we should use EMMC. however, different phone vendor have different type of internal memory device. MTD is commonly used but in some case they use EMMC.

you can try this one. http://www.mediafire.com/download.php?if08rvj22mw9abp it comes from maroc.
 

Miche1asso

Senior Member
Apr 11, 2012
680
500
0
Treviso
Ok, thanks. I've found another couple of update-binary as well in the meantime. One with the 3 parameters format coming from a CM for the Galaxy Min/Pop/Next. Another with a TWO (!!) parameters format, or at least it seems so, coming straight from the Samsung latest CSC for my phone (you know about that :laugh:). In the CSC updater-script the syntax is following (but it is commented out):

Code:
# format("MTD", "system");
# mount("MTD", "system", "/system");
Do they really love to make the most trivial things impossible with Android? Not even a well defined, fixed syntax? At least they could rename the update-binary. This software is blasphemy for a computer scientist!!! (sorry. It really makes me needing to blow out).
 

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
Code:
# format("MTD", "system");
# mount("MTD", "system", "/system");
it seems that there's a differences between the binary file comes from the factory the one come from community. the script from a factory always in a form like above. the one comes from community always comes in a form like format(fs_type, partition_type, location). IMO its not the factory fault if we found a lot of binary version. everyone can make their own update binary if they know the source code.
 
  • Like
Reactions: Miche1asso

Miche1asso

Senior Member
Apr 11, 2012
680
500
0
Treviso
Oh, I get it now. I stupidly thought they all came from Google. Let's say that a mechanism to use different names for the update-binary could be put in place (or there is one?). So one could name the update-binary with its version. Like CM7.2-binary, Merruk-binary and so on.

I'll check if I can run them from the phone, to see if they give out any version info, and maybe an help with a list of commands, so I can get the one I think is the best and use it once for all. We keep getting flashing problems in our phone, so we must investigate the issue at 360 degrees. Thanks again.
 

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
I doubt that. we can't rename the update binary into something else. even aroma which is using his own binary file still have to rename it to update-binary. in recovery mode it seems that when we flash a file, system will command "exec update-binary". while in update-binary it has something like "see the content of updaters-script then run it". if we made our own binary file, we can easily modify the second part. in aroma, the dev change the second part into "see the content of aroma-config then run it". in other hand, the first part is stored inside our recovery stuff. modfying it is hard and a lil bit risky so that no one ever interested to do it.
 
  • Like
Reactions: arbayong

Miche1asso

Senior Member
Apr 11, 2012
680
500
0
Treviso
Kuro, do you own a thread where we can freely discuss about kernel compilations? I have 4 or 5 questions, nothing complex, just about the gzip/lzma compression and the RAM disk size limit that are driving me crazy. A couple of kernels compile but then when I install them I get blank screens. With other details that I'd like to specify in a dedicated thread.

/off-topic
 

kurotsugi

Senior Member
Feb 12, 2012
2,507
1,794
0
yogyakarta
you can discuss that everywhere :p
you can make a new one or simply chat like as we did in maroc's thread. ah yes, our kernel max size is about 5024kb or about 4,88Mb. quite small indeed, but we can gain more spaces when we use lzma compression. btw, I got less problem when compiling a zImage file. as long as we didn't make a major change on the source, our kernel will eventually working. nevertheless, I got a lot of problem when trying to modify ramdisk. even a slight change on ramdisk in several occasieon made the kernel didn't work. you might want to test your zImage with a ramdisk from stock kernel or a working custom kernel available for your device to check whether if the problem comes from zImage or ramdisk. if you want to know more about ramdisk modification you can ask savie or yahya (maroc). they sure know better than me in that aspect.