Android: An introduction to the Edify (Updater-Script) language

An introduction to the Edify (Updater-Script) language

2011-11-08 21:53:30

This is a basic introduction to the edify scripting language used by Android to run updater-scripts. Before I begin, I learned pretty much everything I know about edify scripting from E. Pete Karelis; so huge credit goes out to him for the contents of this guide.  Lesson number one: Pretty much all of the commands in Edify are functions; they return data to the script when the function call is complete.  You can, of course, use the function's return value to establish success or failure, like so: ifelse(mount("yaffs2", "MTD", "system", "/system") == "system", ui_print("Successfully Mounted!"), ui_print("Mount Failed!"); This command will attempt to mount the MTD partition named "system" to "/system". If the mount succeeds, the script will display Successfully Mounted!, otherwise(else) it will display Mount Failed! 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" 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 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" 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. 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. 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. There are more functions than have been mentioned above, and I will continue to update this list as and when possible!