[Advice/Reference/Guide] The Definitive APK Modding & Theming Thread... [12/08/13]
I've wrote this as something I would have liked to have come across when I first joined because I know there is a lot to take in, and hearing you need to decompile, edit this or that xml, recompile, sign etc etc etc can be off putting for some especially if you struggle to get a program or apktool setup to begin with.
Knowing how to use command prompts will be beneficial in the long run so I've wrote a detailed guide below which covers it from start to finish along with how to Sign and Zipalign your apks, pulling them from the computer and so on. I've also covered some Theming basics with links to everything you're ever going to need, which will be extra handy if you're just getting started.
Minimum Requirements:
Theming Requirements:
To avoid any java not found issues you need to set up the PATH for it in Environment Variables, you can find a short Guide on how to HERE. This is how mine looks...
I would advise that you also install the Android SDK but if you don't want to you can download this APK_Mod.zip that you can extract to a folder and place it anywhere you want on your Computer (I recommend C:\APK_Mod) and run any adb, apktool, zipalign or signing command prompts from it. You can find a more detailed guide for this method below.
But first off all here are some of the most common Programs that you can use to modify and theme your apks, and I'll start with one of the best...
Virtuous Ten Studio (VTS)
AndroidSuite 2013
Tickle My Android 5.4
ApkManager V6.1
Command Prompt Editing
Basically this is just manually doing what all of the programs above need to do in order to decompile, recompile, sign and zipalign apks so it's worth knowing how to modify apks this way for occasions when the above programs for whatever reason gives you issues.
Use Linux or a Mac?
See the following threads for more information on using apktool on other Operating Systems...
APK Manager for Mac OS X
[Linux][UTILITY][TOOL] APK Multi-Tool
[tutorial] decompiling,recompiling and signing in linux (27-01-2013)
How to install and use Apktool with Ubuntu
Getting APKs To Your PC
You have two options here...
1. Use a file manager on your Phone to copy and paste files to your SD, then connect to your PC and use Windows Explorer to copy and paste to your desired location.
2. ADB. Open a command prompt window in the ADB folder (see below) and type/copy the following command...
...which will pull the whole app folder to your computer and create a new folder called Original_apps, which you can then simply copy apps to the main folder ready to be modified (keep the Original_apps folder as a backup). Then do the same for your framework folder...
...want to pull your Phones whole system...
...you can rename "Xperia_Z_System" to whatever you want.
Further Information: [WINDOWS][TUT]ADB tutorial, setting up ADB, usefull commands, collecting debug info.
This is a zip of the apktool folder I currently use - APK_Mod.zip - which as said above also contains the ADB files needed to pull and push apps from your Phone, or you can check out the following links...
Installing Resources
For apktool to work you need to install the resources needed by your apks for de and recompiling, and those resources are other apks, the first apk regardless of your Phones manufacturer is going to be your framework-res.apk. The second apk you need is dependent on the manufacturer so you need to check your framework folder for another apk such as twframework.apk or SemcGenericUXpres.apk, in some cases it might even be the SystemUI.apk but you would need to check if you have issues with the other two. Put those two apks in the APK_Mod folder to begin with then open a command prompt window. The easiest way for me is holding the shift key then right clicking the mouse and selecting Open command window here, but if you're not able to do that then click your Start button and search for Command Prompt, then open it. You then need to point it to the relevant folder, so type cd then copy and paste the location of the folder (cd C:\APK_Mod) and hit enter.
The install commands are...
...and for the second...
Decompiling
The command for decompiling is...
...and so on for each individual apk you want to modify. A new folder will be created that is named after the apk you are modding, then you can edit xmls, smali files and .9png images. You'll notice that there are a lot more folders when you decompile an apk, that's normal as those folders are from the resources.arsc and where you'll find the xml files you may need to edit to make the changes you want.
Recompiling
When you've done editing it's time to recompile, using the command...
...and if you've edited your files correctly then it should compile with no errors and create a folder named dist in the decompiled folder along with a new apk.
Signing
Before using the new apk you will need to sign it, to do this you need to extract (open the apk and simply drag and drop them to the dist folder) from the original apk the resources.arsc (only if you haven't changed anything in the values folder, the AndroidManifest.xml and META-INF folder (if it exists), then copy them into the new apk. In WinRar it will give you the option to choose the compression method, and it's vital that you choose Store as the compression method because if you don't then you WILL BOOT LOOP after restarting your Phone!
NOTE: If you have edited anything in the values folder then extract the resources.arsc from the new apk and copy (drag and drop) it back in the same manner described above.
Alternatively you can use the following command...
...notice the extra "S", the output name has to differ from the input name otherwise it will give an error, if done right it will create a new apk called framework-resS.apk, just remember to rename it back to the original before using it on your Phone.
If you plan on Publishing a Theme or any other app/apk to the Play Store then using the above method to sign your apks just wont work because you need to give it an individual signature that is unique to you, thankfully @AndroidGraphix has written a great guide that will show you how, it's a bit more fidgety than the above method but simple enough to follow...
- Noobs guide to signing an APK with a Private Key
Zipaligning
- SOURCE
The command for zipaligning is...
...notice the "ZA", again that can be anything you want so long as it differs from the original name, I use ZA for an obvious reason, and again don't forget to rename it before using on your Phone.
Getting apks back to your Phone
It's just a reversal of how you got them off your Phone to begin with, use a file explorer and put your apk on your SD Card, then move it to the Phones System folder and change it's permissions to rw-rw-r, then move and replace it with the original. Most apps should continue to work but if you change your framework-res or SystemUI you will most likely need to reboot. Or you can use adb to push and install them. Check the previous link for the commands.
If all the above has worked correctly you should now have your modified apk installed with the changes you've made displayed on your Phone.
Theming & Modifying
This is where the fun begins, once you've got setup to decompile your apks then obviously you're going to want to mod them, so here's a few pointers to clear up what seems like a daunting process to new comers...
To start with you'll probably just want to start with replacing images, so if that's all you want to do for now then here's a quick tip, you DON'T need to decompile or sign your apks!, simply edit and rename your replacment images on you computer, preferably using the same or similar dimensions then drag and drop them back into the right folders in the apk, always using Store as the compression method, but PLEASE NOTE; .9 pngs can be replaced in the same way, but if you want to edit them in Photoshop for example then you need DO need to decompile them.
A few things to note...
.9png Editing
I hope after reading this explanation you're left wondering what all the fuss is about, as it really is quite simple. I'll use the following two images, btn_default_pressed_holo.9 & status_bar_close_off.9 to illustrate the basic point of the borders...
Decompiled .9pngs:
Recompiled .9pngs:
Those borders control which part of the image is stretched, and we'll use Draw 9-patch which is for editing the borders of decompiled .9pngs and lets you see how the image, when stretched, will be displayed on the Phone. Notice that the borders are different sizes, well that's because I only want/need a certain part of the image to stretch to get the desired look on the Phone.
...in the image below the left side shows the stretched image and desired effect should look on the Phone and the right side shows how it would look if I had edited the borders incorrectly or used none at all...
You can get away by not using a border but you would need to edit your image to specific dimensions to accommodate for the stretching, for example it might look fine for a simple OK button but it might not look right if you used the same .9png for a screen press which stretches the whole length of the screen, so you're better off just using them to begin with, plus you'll more than likely get errors down the line while decompiling or recompiling your apk.
The use of the border is made even more clear when you add text to an image. For my status_bar_close_off.9 I've filled all four sides of the image (except for an empty pixel in all four corners as that is the max amount of border you can use) as I need it to stretch the image just how I've edited it...
...but if I used the same sized left side border as the btn_default_pressed_holo.9 then this is how it would look on the Phone...
...which is obviously not the look I'm trying to achieve, as the left side border is causing the image to stretch incorrectly.
So that's basically it, depending on the image you're editing you can usually leave the borders alone but if you create one from scratch then you might need to play about with them if your images doesn't look quite right when used on the Phone. Here's a few links that will assist you further, especially the batch editing...
Xposed Framework
- [FRAMEWORK ONLY!] Xposed - ROM modding without modifying APKs
CyanogenMod Theme Chooser
- [GUIDE] HOW TO THEME CM10.1 - Animated Book
See a few post below for more...
This is why I love Virtuous Ten, as you can install multiple resources.
After reading jacknb1ack's comment I felt compelled to re-write this whole thread to accommodate for the various PC Programs that you use to do all of your apk modding which can and do make things a hell of a lot quicker.
I've wrote this as something I would have liked to have come across when I first joined because I know there is a lot to take in, and hearing you need to decompile, edit this or that xml, recompile, sign etc etc etc can be off putting for some especially if you struggle to get a program or apktool setup to begin with.Knowing how to use command prompts will be beneficial in the long run so I've wrote a detailed guide below which covers it from start to finish along with how to Sign and Zipalign your apks, pulling them from the computer and so on. I've also covered some Theming basics with links to everything you're ever going to need, which will be extra handy if you're just getting started.
- A Rooted Phone.
- Java SE Runtime Environment
- Java SE Development Kit
- Any of the apk modifying methods below.
- 7-Zip or WinRar
Theming Requirements:
To avoid any java not found issues you need to set up the PATH for it in Environment Variables, you can find a short Guide on how to HERE. This is how mine looks...
Code:
[B]C:\Program Files (x86)\Java\jre6\bin;[/B]I would advise that you also install the Android SDK but if you don't want to you can download this APK_Mod.zip that you can extract to a folder and place it anywhere you want on your Computer (I recommend C:\APK_Mod) and run any adb, apktool, zipalign or signing command prompts from it. You can find a more detailed guide for this method below.
But first off all here are some of the most common Programs that you can use to modify and theme your apks, and I'll start with one of the best...
Virtuous Ten Studio (VTS)
- www.virtuous-ten-studio.com
AndroidSuite 2013
- (App) Androidsuite 2013 v117 (01/04/2013) Jelly Bean Support!
Tickle My Android 5.4
- [TOOL]Tickle My Android 5.4 - DE/RECOMPILE APPS, CHANGE ICONS...AND MORE!!!!
ApkManager V6.1
- wanamlite.com
Command Prompt Editing
Basically this is just manually doing what all of the programs above need to do in order to decompile, recompile, sign and zipalign apks so it's worth knowing how to modify apks this way for occasions when the above programs for whatever reason gives you issues.
Use Linux or a Mac?
See the following threads for more information on using apktool on other Operating Systems...
APK Manager for Mac OS X
[Linux][UTILITY][TOOL] APK Multi-Tool
[tutorial] decompiling,recompiling and signing in linux (27-01-2013)
How to install and use Apktool with Ubuntu
Getting APKs To Your PC
You have two options here...
1. Use a file manager on your Phone to copy and paste files to your SD, then connect to your PC and use Windows Explorer to copy and paste to your desired location.
2. ADB. Open a command prompt window in the ADB folder (see below) and type/copy the following command...
Code:
adb pull /system/app/ Original_apps...which will pull the whole app folder to your computer and create a new folder called Original_apps, which you can then simply copy apps to the main folder ready to be modified (keep the Original_apps folder as a backup). Then do the same for your framework folder...
Code:
adb pull /system/framework/ Original_framework...want to pull your Phones whole system...
Code:
adb pull /system/ Xperia_Z_System...you can rename "Xperia_Z_System" to whatever you want.
Further Information: [WINDOWS][TUT]ADB tutorial, setting up ADB, usefull commands, collecting debug info.
This is a zip of the apktool folder I currently use - APK_Mod.zip - which as said above also contains the ADB files needed to pull and push apps from your Phone, or you can check out the following links...
Installing Resources
For apktool to work you need to install the resources needed by your apks for de and recompiling, and those resources are other apks, the first apk regardless of your Phones manufacturer is going to be your framework-res.apk. The second apk you need is dependent on the manufacturer so you need to check your framework folder for another apk such as twframework.apk or SemcGenericUXpres.apk, in some cases it might even be the SystemUI.apk but you would need to check if you have issues with the other two. Put those two apks in the APK_Mod folder to begin with then open a command prompt window. The easiest way for me is holding the shift key then right clicking the mouse and selecting Open command window here, but if you're not able to do that then click your Start button and search for Command Prompt, then open it. You then need to point it to the relevant folder, so type cd then copy and paste the location of the folder (cd C:\APK_Mod) and hit enter.
The install commands are...
Code:
[B]apktool if[/B] framework-res.apk...and for the second...
Code:
[B]apktool if[/B] SemcGenericUXpres.apkDecompiling
The command for decompiling is...
Code:
[B]apktool d[/B] framework-res.apk...and so on for each individual apk you want to modify. A new folder will be created that is named after the apk you are modding, then you can edit xmls, smali files and .9png images. You'll notice that there are a lot more folders when you decompile an apk, that's normal as those folders are from the resources.arsc and where you'll find the xml files you may need to edit to make the changes you want.
Recompiling
When you've done editing it's time to recompile, using the command...
Code:
[B]apktool b[/B] -insert folder name-...and if you've edited your files correctly then it should compile with no errors and create a folder named dist in the decompiled folder along with a new apk.
Signing
Before using the new apk you will need to sign it, to do this you need to extract (open the apk and simply drag and drop them to the dist folder) from the original apk the resources.arsc (only if you haven't changed anything in the values folder, the AndroidManifest.xml and META-INF folder (if it exists), then copy them into the new apk. In WinRar it will give you the option to choose the compression method, and it's vital that you choose Store as the compression method because if you don't then you WILL BOOT LOOP after restarting your Phone!
NOTE: If you have edited anything in the values folder then extract the resources.arsc from the new apk and copy (drag and drop) it back in the same manner described above.
Alternatively you can use the following command...
Code:
[B]java -jar signapk.jar testkey.x509.pem testkey.pk8[/B] framework-res.apk.apk framework-resS.apk...notice the extra "S", the output name has to differ from the input name otherwise it will give an error, if done right it will create a new apk called framework-resS.apk, just remember to rename it back to the original before using it on your Phone.
Signing For The Play Store
If you plan on Publishing a Theme or any other app/apk to the Play Store then using the above method to sign your apks just wont work because you need to give it an individual signature that is unique to you, thankfully @AndroidGraphix has written a great guide that will show you how, it's a bit more fidgety than the above method but simple enough to follow...
- Noobs guide to signing an APK with a Private Key
Zipaligning
- SOURCE
The command for zipaligning is...
Code:
[B]zipalign -v 4[/B] framework-res.apk ZAframework-res.apk...notice the "ZA", again that can be anything you want so long as it differs from the original name, I use ZA for an obvious reason, and again don't forget to rename it before using on your Phone.
Getting apks back to your Phone
It's just a reversal of how you got them off your Phone to begin with, use a file explorer and put your apk on your SD Card, then move it to the Phones System folder and change it's permissions to rw-rw-r, then move and replace it with the original. Most apps should continue to work but if you change your framework-res or SystemUI you will most likely need to reboot. Or you can use adb to push and install them. Check the previous link for the commands.
If all the above has worked correctly you should now have your modified apk installed with the changes you've made displayed on your Phone.
Theming & Modifying
This is where the fun begins, once you've got setup to decompile your apks then obviously you're going to want to mod them, so here's a few pointers to clear up what seems like a daunting process to new comers...
To start with you'll probably just want to start with replacing images, so if that's all you want to do for now then here's a quick tip, you DON'T need to decompile or sign your apks!, simply edit and rename your replacment images on you computer, preferably using the same or similar dimensions then drag and drop them back into the right folders in the apk, always using Store as the compression method, but PLEASE NOTE; .9 pngs can be replaced in the same way, but if you want to edit them in Photoshop for example then you need DO need to decompile them.
A few things to note...
Smali code is real Developer territory, it's Matrix code to me, thankfully there's usually a guide to follow so you can simply copy and paste code without having to fully understand how it works, so don't fret about this.
.9pngs are simply png images with a 1 pixel border. You can edit anything within that border but anything on or over will give errors when building. Unless you're creating an image from scratch then you can leave the border as it is, it's that simple! Sure there's a bit more to .9png editing but you can find a few links below that go into more detail about .9s and how they work.
xmls are relatively simple and edited with Notepad++, much simpler to understand than smali and again, there's usually a guide to be found for most mods you may want to make yourself, but if you're feeling brave you can experiment with it when you have a basic understanding of how it works.
Restoring modified files if you mess up is easier and quicker with a CWM.zip, especially if you're modifying any framework apks! Just because an apk might build with no errors doesn't mean it won't give you any when installed to the Phone.
.9png Editing
I hope after reading this explanation you're left wondering what all the fuss is about, as it really is quite simple.
I'll use the following two images, btn_default_pressed_holo.9 & status_bar_close_off.9 to illustrate the basic point of the borders...Decompiled .9pngs:
Recompiled .9pngs:
Those borders control which part of the image is stretched, and we'll use Draw 9-patch which is for editing the borders of decompiled .9pngs and lets you see how the image, when stretched, will be displayed on the Phone. Notice that the borders are different sizes, well that's because I only want/need a certain part of the image to stretch to get the desired look on the Phone.
...in the image below the left side shows the stretched image and desired effect should look on the Phone and the right side shows how it would look if I had edited the borders incorrectly or used none at all...
You can get away by not using a border but you would need to edit your image to specific dimensions to accommodate for the stretching, for example it might look fine for a simple OK button but it might not look right if you used the same .9png for a screen press which stretches the whole length of the screen, so you're better off just using them to begin with, plus you'll more than likely get errors down the line while decompiling or recompiling your apk.
The use of the border is made even more clear when you add text to an image. For my status_bar_close_off.9 I've filled all four sides of the image (except for an empty pixel in all four corners as that is the max amount of border you can use) as I need it to stretch the image just how I've edited it...
...but if I used the same sized left side border as the btn_default_pressed_holo.9 then this is how it would look on the Phone...
...which is obviously not the look I'm trying to achieve, as the left side border is causing the image to stretch incorrectly.
So that's basically it, depending on the image you're editing you can usually leave the borders alone but if you create one from scratch then you might need to play about with them if your images doesn't look quite right when used on the Phone. Here's a few links that will assist you further, especially the batch editing...
- How to edit .9.pngs
- [TUTO] Create your 9.png !
- [UTILITY][TOOL] 9patchPngSuite [Windows&Linux]
- How to draw NinePatch images with Photoshop - .9.PNG
- [TOOL][Multi-Platform][.9.png][ALL DPIs] Android Resizer Tool
- [Tutorial][Commentary] How To Batch Edit .9PNG/PNG Images
Xposed Framework
In this thread, I'm presenting a framework which gives you the possibility to modify your ROM - without modifying any APK (developers) or flashing (users)!
...
Advantages:
- No need to modify any APKs. This means:
- No need to decompile, change things in smali, compile, sign, ...
- It will work for odexed and deodexed ROMs.
- Your mod is not bound to a specific version of the ROM. Unless there is a major change in the methods called for a certain functionality, your mod will continue to work even when you upgrade your ROM. Hell, it will probably even work with different ROMs.
- Multiple mods can be installed at the same time, even if they change the same package. So you can use these battery icons and those quick toggles. Even hooking the same method twice is possible. Of course, this only works properly if the mods are not trying to do incompatible things.
- It does its magic at runtime. That means you can implement options to let the user decide if they prefer the bikeshed to be painted in red or blue. Or you can have some extra logic for certain ROMs without building different mod versions.
- It can be disabled easily without having to reflash.
- It's open source.
- [FRAMEWORK ONLY!] Xposed - ROM modding without modifying APKs
- [Guide] Porting XTheme themes
- [Guide] Xposed Framework/TabletUI (Noob-Friendly)
- [INDEX][WiP] List of APPs & MODs that use XPOSED Module
- [MOD][XPOSED][4.0+] XThemeEngine beta5 - Theme engine for any rooted phone
CyanogenMod Theme Chooser
CM10.1-THEME_BOOK
Theme book was created by Annex and Ebs512. I've been asked alot of questions from how to get started? what do I need to get started? to What Graphics program do I use? etc. We made a real simple theme guide to help get you started. This is in Layman Terms.. Nothing fancy.
ONLY THING FANCY IS MY FLASH BOOK
YOU MUST HAVE A FLASH PLAYER INSTALLED TO VIEW THIS!!!
- [GUIDE] HOW TO THEME CM10.1 - Animated Book
- [Tool] [Theme Creator] [CM/Avatar] Theme creator tool
- [Tool] nhnt11's XML Generator Revived V2+Extended UPDATED!
- [DEV/GUIDE]Creating APKs for use with TMobile Theme engine
- [GUIDE] T-mobile theme engine for the faint at heart (non-linux users)
- [1/30/2013] Mega 4.2.1 BlackBean Theme Template [XXHDPI/XHDPI/HDPI/TVDPI]
- -·=»‡«=·-[JB][CM10] Theme Engine Template Updated To V4 [8-7-12][XHDPI/HDPI]-·=»‡«=·-
See a few post below for more...
Last edited:
