[TUTORIAL] Making Flashable ZIPs, EDIFY Script, ZIP Signing & Key Creation [19.01.13]
Recent Updates: Command Line Edify Script Tester, Further 'update-binary' info clarification, helpful links, additional credits. post#1
Hi all,
In the process of creating my [BOOTANIMATIONS - LINKS & INFO] thread I realised I needed to know more about how boot animations worked, as by default people tend to ask questions in that type of thread, so I wanted to be able to help.
This meant I came across the problem of creating flash-able ZIP files and Edify scripting and in the interests of sharing and helping this great community I would like to share what I have found and hopefully learn more through discussion, I certainly am no expert and am always willing to learn.
I have checked xda and various other websites whilst reseraching for this post and there is nothing that really explains all the basic concepts to just get up and running, also a lot of threads are quite old and focus on the old Amend scripting syntax or are a confusing mixture of the two.
I hope this helps people get started and that we can all collaborate to make this a thread a source of valuable information.
Contents:
Post #1: Tutorials
Post #2: Edify Commands
***Please, if there are any mistakes on this thread then let me know what I have done incorrectly in reply to this post and I will update the thread to correct it***
***As always, I accept no responsibiltiy for your handset, you modify it at your own risk, nobody is forcing you...be aware you can seriously bork your phone by flashing its internal partitions! Always make a nandroid back-up and think before you flash!***
***Have you made a nandroid back-up...no? Then make one!!***
You will need the following:
Android SDK, ADB & Fastboot set up for your handset.
Notepad++ [LINK]
7zip [LINK]
Setting up your zip directories:
you will need to create the following folder structure (these are case sensitive):
All flash-able zips include this file structure, the final folder 'android' will contain two files:
update-binary: I have been unable to find much information on the update-binary file other than they seem to be chip set specific (if anyone can shed further light on these I will include it here). For the sake of compatibility I have attached the update binary from the latest CyanogenMod Nightlies for the maguro at the bottom of this thread - You can of course download the latest nightly and extract the update-binary file yourself as the attached one will obviously begin to date (all credit to the great devs at CyanogenMod for this, many thanks).
Update: For more detailed info on the update binary you can find the sources in the bootable/recovery/updater directory at AndroidXRef here: [ xref: /bootable/recovery/updater/ ]. There is also an edify directory which looks like it handles the parsing of the script. Obviously with the sources there's nothing to stop you extending syntax/functionality should you wish given the fact the each zip comes with its own version. It will also help you understand how signature checking is handled.
Update II: For anybody having problems flashing it is worth ensuring you have an up to date version of the update-binary (obviously the one attached to this thread will gradually become out of date).
It is advisable to use the update-binary from the latest OTA image for your device, these images can be found in the following link:
Official Google OTA update URLs - efrant
updater-script: This we can create ourselves, to ensure it works properly we will use Notepad++.
Open Notepad++ and start a new file, with the following settings:
Format: Unix
Encoding: ANSI
Default Language: Normal Text
Save this file as:
File name: updater-script
File type: All types (*.*)
You can now edit this file, add the following text:
Ok, I've colour coded this so we can break it down, the lines of code in RED are the actual commands, everything else is cosmetic.
assert(getprop("ro.product.device") == "maguro" || getprop("ro.build.product") == "maguro"); This is checking you are flashing the correct handset, this is not a requirement, but is best practice. Just insert another device name in the place of "maguro" if you so wish, or remove the command all together.
mount("ext4", "EMMC", "/dev/block/platform/omap/omap_hsmmc.0/by-name/system", "/system"); This is the specific mount point for the maguro system partition, if you wish to flash a different partition, data for instance you can get the mount points for your device by entering the following code over ADB:
This will place a text file on your sdcard with the mount points for your specific device (remember to swap 'PHONENAME' with your device name e.g. 'maguro')
package_extract_dir("system", "/system"); This command extracts the files you wish to flash from the zip and flashes them to the phone, it is formatted as follows ("package-path", "/destination-path"). So for this example you are telling it to flash everything from the 'system' folder in your zip to the /system partition of your handset. You can obviously change these values for different partitions.
unmount("/system"); This simply unmounts whatever partition you previously mounted.
ui_print(" "); Shows text in the recovery whilst the flash is ongoing, you can put whatever you please between the speech marks, you must leave a space if you wish to have a blank line.
show_progress(0.200000, 5); Controls what the progress bar in the background is displaying, it is formatted as follows (fragment, seconds).
***EMPTY LINE*** This is not actually text, you simply need to leave a blank line at the end of your script before you save it for it to work.
FYI, this means in fact your script could look like this and still work:
But that just isn't that pretty, or as deceptively complicated lol!
Make sure you save your edify script.
Files to flash:
You now need to create a further folder, this needs to be named based on where within the system you are flashing, for the sake of this example we are flashing to the system partition, so:
Place whatever files you wish to flash within this file e.g:
Creating your .zip file:
Select both of your top directories and their contents 'META-INF' and 'system' and package them into a .zip file with 7zip using the following settings:
Archive: name_of_your_file
Archive Format: zip
Compression level: Store
Update mode: Add and replace files
And there you have it, your very own flash-able .zip file.
I have attached an example flashable .zip file that includes this updater-script and the above mentioned CM update-binary.
How to sign your update.zip:
You don't actually need to sign your zip file for it to work as most custom recoveries now support unsigned zips, for aspiring developers and the more cautious among us though, here is how.
You will need to download the following files:
SignApk [LINK]
Java JDK (Java Development Kit) & JRE (Java Runtime Environment) [LINK]
Install Java JRE and JDK and restart your PC.
You then need to create a folder in the root of your c:\ drive named 'signapk' and extract the contents of the SignApk download (signapk.jar, key.pk8, certificate.pem) to this folder.
Place your .zip file into the same folder and then open cmd line. Input the following commands (remeber to change the name of 'myupdate.zip' to the name of your file and 'myupdate-signed.zip' to whatever you want your resulting .zip to be named):
You should find that you now have the the following files in your 'META-INF' folder: CERT.RSA, CERT.SF, MANIFEST.MF
This can also to be used to sign .apk files using the below command (same stipulations for file name changing applies as above):
How to create your own private signing key & certificate:
You will need the following download:
OpenSSL [LINK]
The above signapk file includes test keys, if you want to create your own private keys for signing, here's what you need to do.
As before extract the OpenSSL files to a folder in the root of your c:\ drive, preferably named 'openssl' for ease of cmd line navigation. Then input the following:
You can then replace 'key.pk8' & 'certificate.pem' with your own files.
I really hope this has helped folks out, if so please consider hitting the 'Thanks' button!
Happy flashing!
Testing your script before you flash:
If you would like to test if your script commands are valid and will run properly on your PC first before you use them on your handset, therefore removing the fear of borking your current install/handset in the process then head to this post:
Command Line Edify Script Tester by: trevd
This great tool developed by trevd currently has the following features:
Validates function name.
Validates function parameter count.
It is available for Linux and Windows, so head over and check it out. Be sure to click trevd's thanks button if you find this useful.
Other helpful links & threads:
xda-developers: Edify script language wiki
Edify scripts in CWM recovery by: NFHimself
Phandroid - Edify Script Language Reference by: Koumajutsu
Introduction to edify updater script by: kurotsugi
Intelligent EDIFY updater-script - (Decides things during flash) by: lotherius
Credits:
CyanogenMod for (update-binary)
Lorenz's Blog for (SignAPK & Info)
JoeSyr for (Help with File Permissions)
efrant for (Help with various commands)
trevd for (further update-binary clarification and source links)
osm0sis for (Helpful info & forum links & help with update-binary info)
Recent Updates: Command Line Edify Script Tester, Further 'update-binary' info clarification, helpful links, additional credits. post#1
Hi all,
In the process of creating my [BOOTANIMATIONS - LINKS & INFO] thread I realised I needed to know more about how boot animations worked, as by default people tend to ask questions in that type of thread, so I wanted to be able to help.
This meant I came across the problem of creating flash-able ZIP files and Edify scripting and in the interests of sharing and helping this great community I would like to share what I have found and hopefully learn more through discussion, I certainly am no expert and am always willing to learn.
I have checked xda and various other websites whilst reseraching for this post and there is nothing that really explains all the basic concepts to just get up and running, also a lot of threads are quite old and focus on the old Amend scripting syntax or are a confusing mixture of the two.
I hope this helps people get started and that we can all collaborate to make this a thread a source of valuable information.
Contents:
Post #1: Tutorials
Post #2: Edify Commands
***Please, if there are any mistakes on this thread then let me know what I have done incorrectly in reply to this post and I will update the thread to correct it***
***As always, I accept no responsibiltiy for your handset, you modify it at your own risk, nobody is forcing you...be aware you can seriously bork your phone by flashing its internal partitions! Always make a nandroid back-up and think before you flash!***
***Have you made a nandroid back-up...no? Then make one!!***
You will need the following:
Android SDK, ADB & Fastboot set up for your handset.
Notepad++ [LINK]
7zip [LINK]
Setting up your zip directories:
you will need to create the following folder structure (these are case sensitive):
Code:
/META-INF/com/google/android
All flash-able zips include this file structure, the final folder 'android' will contain two files:
Code:
update-binary
updater-script
update-binary: I have been unable to find much information on the update-binary file other than they seem to be chip set specific (if anyone can shed further light on these I will include it here). For the sake of compatibility I have attached the update binary from the latest CyanogenMod Nightlies for the maguro at the bottom of this thread - You can of course download the latest nightly and extract the update-binary file yourself as the attached one will obviously begin to date (all credit to the great devs at CyanogenMod for this, many thanks).
Update: For more detailed info on the update binary you can find the sources in the bootable/recovery/updater directory at AndroidXRef here: [ xref: /bootable/recovery/updater/ ]. There is also an edify directory which looks like it handles the parsing of the script. Obviously with the sources there's nothing to stop you extending syntax/functionality should you wish given the fact the each zip comes with its own version. It will also help you understand how signature checking is handled.
Update II: For anybody having problems flashing it is worth ensuring you have an up to date version of the update-binary (obviously the one attached to this thread will gradually become out of date).
It is advisable to use the update-binary from the latest OTA image for your device, these images can be found in the following link:
Official Google OTA update URLs - efrant
updater-script: This we can create ourselves, to ensure it works properly we will use Notepad++.
Open Notepad++ and start a new file, with the following settings:
Format: Unix
Encoding: ANSI
Default Language: Normal Text
Save this file as:
File name: updater-script
File type: All types (*.*)
You can now edit this file, add the following text:
Code:
[COLOR="Red"]assert(getprop("ro.product.device") == "maguro" || getprop("ro.build.product") == "maguro");[/COLOR]
[COLOR="Green"]ui_print(" ");[/COLOR]
[COLOR="green"]ui_print("confirming device maguro");[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
[COLOR="green"]ui_print("success");[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
[COLOR="DarkOrange"]show_progress(0.200000, 5);[/COLOR]
[COLOR="green"]ui_print("mounting system");[/COLOR]
[COLOR="red"]mount("ext4", "EMMC", "/dev/block/platform/omap/omap_hsmmc.0/by-name/system", "/system");[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
[COLOR="DarkOrange"]show_progress(0.200000, 5);[/COLOR]
[COLOR="green"]ui_print("updating system files");[/COLOR]
[COLOR="red"]package_extract_dir("system", "/system");[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
[COLOR="DarkOrange"]show_progress(0.200000, 5);[/COLOR]
[COLOR="green"]ui_print("unmounting system");[/COLOR]
[COLOR="red"]unmount("/system");[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
[COLOR="DarkOrange"]show_progress(0.200000, 5);[/COLOR]
[COLOR="green"]ui_print("by yourusername");[/COLOR]
[COLOR="DarkOrange"]show_progress(0.200000, 5);[/COLOR]
[COLOR="green"]ui_print(" ");[/COLOR]
***EMPTY LINE***
Ok, I've colour coded this so we can break it down, the lines of code in RED are the actual commands, everything else is cosmetic.
assert(getprop("ro.product.device") == "maguro" || getprop("ro.build.product") == "maguro"); This is checking you are flashing the correct handset, this is not a requirement, but is best practice. Just insert another device name in the place of "maguro" if you so wish, or remove the command all together.
mount("ext4", "EMMC", "/dev/block/platform/omap/omap_hsmmc.0/by-name/system", "/system"); This is the specific mount point for the maguro system partition, if you wish to flash a different partition, data for instance you can get the mount points for your device by entering the following code over ADB:
Code:
adb shell "mount > /sdcard/PHONENAME_mountinfo.txt"
package_extract_dir("system", "/system"); This command extracts the files you wish to flash from the zip and flashes them to the phone, it is formatted as follows ("package-path", "/destination-path"). So for this example you are telling it to flash everything from the 'system' folder in your zip to the /system partition of your handset. You can obviously change these values for different partitions.
unmount("/system"); This simply unmounts whatever partition you previously mounted.
ui_print(" "); Shows text in the recovery whilst the flash is ongoing, you can put whatever you please between the speech marks, you must leave a space if you wish to have a blank line.
show_progress(0.200000, 5); Controls what the progress bar in the background is displaying, it is formatted as follows (fragment, seconds).
***EMPTY LINE*** This is not actually text, you simply need to leave a blank line at the end of your script before you save it for it to work.
FYI, this means in fact your script could look like this and still work:
Code:
[COLOR="Green"]ui_print(" ");[/COLOR]
[COLOR="DarkOrange"]show_progress(1.000000, 30);[/COLOR]
[COLOR="red"]mount("ext4", "EMMC", "/dev/block/platform/omap/omap_hsmmc.0/by-name/system", "/system");[/COLOR]
[COLOR="red"]package_extract_dir("system", "/system");[/COLOR]
[COLOR="red"]unmount("/system");[/COLOR]
[COLOR="Green"]ui_print(" ");[/COLOR]
***EMPTY LINE***
But that just isn't that pretty, or as deceptively complicated lol!
Make sure you save your edify script.
Files to flash:
You now need to create a further folder, this needs to be named based on where within the system you are flashing, for the sake of this example we are flashing to the system partition, so:
Code:
/META-INF/com/google/android
/system/app
Place whatever files you wish to flash within this file e.g:
Code:
/META-INF/com/google/android
/system/app/nameofapp.apk
Creating your .zip file:
Select both of your top directories and their contents 'META-INF' and 'system' and package them into a .zip file with 7zip using the following settings:
Archive: name_of_your_file
Archive Format: zip
Compression level: Store
Update mode: Add and replace files
And there you have it, your very own flash-able .zip file.
I have attached an example flashable .zip file that includes this updater-script and the above mentioned CM update-binary.
How to sign your update.zip:
You don't actually need to sign your zip file for it to work as most custom recoveries now support unsigned zips, for aspiring developers and the more cautious among us though, here is how.
You will need to download the following files:
SignApk [LINK]
Java JDK (Java Development Kit) & JRE (Java Runtime Environment) [LINK]
Install Java JRE and JDK and restart your PC.
You then need to create a folder in the root of your c:\ drive named 'signapk' and extract the contents of the SignApk download (signapk.jar, key.pk8, certificate.pem) to this folder.
Place your .zip file into the same folder and then open cmd line. Input the following commands (remeber to change the name of 'myupdate.zip' to the name of your file and 'myupdate-signed.zip' to whatever you want your resulting .zip to be named):
Code:
cd\signapk\
java -jar signapk.jar certificate.pem key.pk8 c:\signapk\myupdate.zip myupdate-signed.zip
You should find that you now have the the following files in your 'META-INF' folder: CERT.RSA, CERT.SF, MANIFEST.MF
This can also to be used to sign .apk files using the below command (same stipulations for file name changing applies as above):
Code:
java -jar signapk.jar certificate.pem key.pk8 c:\signapk\myapplication.apk myapplication-signed.apk
How to create your own private signing key & certificate:
You will need the following download:
OpenSSL [LINK]
The above signapk file includes test keys, if you want to create your own private keys for signing, here's what you need to do.
As before extract the OpenSSL files to a folder in the root of your c:\ drive, preferably named 'openssl' for ease of cmd line navigation. Then input the following:
Code:
cd\openssl\
openssl genrsa -out key.pem 1024
openssl req -new -key key.pem -out request.pem
openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem
openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt
You can then replace 'key.pk8' & 'certificate.pem' with your own files.
I really hope this has helped folks out, if so please consider hitting the 'Thanks' button!
Happy flashing!
Testing your script before you flash:
If you would like to test if your script commands are valid and will run properly on your PC first before you use them on your handset, therefore removing the fear of borking your current install/handset in the process then head to this post:
Command Line Edify Script Tester by: trevd
This great tool developed by trevd currently has the following features:
Validates function name.
Validates function parameter count.
It is available for Linux and Windows, so head over and check it out. Be sure to click trevd's thanks button if you find this useful.
Other helpful links & threads:
xda-developers: Edify script language wiki
Edify scripts in CWM recovery by: NFHimself
Phandroid - Edify Script Language Reference by: Koumajutsu
Introduction to edify updater script by: kurotsugi
Intelligent EDIFY updater-script - (Decides things during flash) by: lotherius
Credits:
CyanogenMod for (update-binary)
Lorenz's Blog for (SignAPK & Info)
JoeSyr for (Help with File Permissions)
efrant for (Help with various commands)
trevd for (further update-binary clarification and source links)
osm0sis for (Helpful info & forum links & help with update-binary info)
Attachments
Last edited: