FORUMS
Remove All Ads from XDA

[TOOL] DexPatcher: Modify Android applications at source-level in Android Studio

2,672 posts
Thanks Meter: 4,446
 
By Lanchon, Senior Member on 21st March 2015, 08:04 PM
Post Reply Email Thread
DexPatcher
A toolchain for modifying Android APK files at source-level using Java, graphical resource editors, and the full power of Android Studio in all major platforms.

  • Fully integrated with Android Studio and the Gradle build system.
  • Includes support for coding assistance and on-demand class decompilation.
  • Patch Java code in Java using declarative syntax provided by the DexPatcher tool.
  • Manifest merging enables piece-wise changes to the original app manifest.
  • Modify existing resources or create new ones using Android Studio's standard resource editors.
  • Use Android Studio's code template wizards for creating activities, etc.
  • Pull in Android libraries (a.k.a. '.aar' Android archives) and have their manifests, code and resources automatically merged into the patched app.
  • And enjoy debugging support.
  • All in your favorite platform: Linux, Windows or macOS.





DexPatcher tool (Dalvik bytecode patcher)
Release notes: https://github.com/DexPatcher/dexpatcher-tool/releases
Sources: https://github.com/DexPatcher/dexpatcher-tool

DexPatcher Gradle plugins (Android build system and Android Studio integration)
Release notes: https://github.com/DexPatcher/dexpat...radle/releases
Artifacts: https://plugins.gradle.org/search?term=dexpatcher
Sources: https://github.com/DexPatcher/dexpatcher-gradle
Samples: https://github.com/DexPatcher/dexpatcher-gradle-samples

Deprecated tools
Release notes for DexPatcher Gradle v1 plugins: https://github.com/DexPatcher/dexpat...=v2.0.0-alpha1
Support tools for DexPatcher Gradle v1 plugins: https://github.com/DexPatcher/dexpatcher-gradle-tools
Workflow automation scripts (Linux-only): https://github.com/DexPatcher/dexpatcher-tool-scripts

License
GPL v3 (or later)


THANK YOU ! - The DexPatcher tool uses JesusFreke's dexlib2 (part of smali) to read and write dex files. Many thanks to him for repeatedly helping me in #smali on freenode. When creating apk libraries, the DexPatcher Gradle plugin uses iBotPeaches' Apktool to decode compiled resources and pxb1988's dex2jar to translate Dalvik bytecode. DexPatcher could not exist without the invaluable work of these guys.


Documentation

PATCHING JAVA CODE IN JAVA

The DexPatcher tool uses declarative semantics based on Java annotations to patch the bytecode of the source application. There is no formal definition but hopefully you will find everything you need in this sample:
START HERE !

With the new DexPatcher Gradle v2 plugins

Get the sample code working, here is how:
  1. Clone the samples.
  2. Start with the 'patched-app' sample: open the project with Android Studio, disable instant run, and run or debug your patched app!

Please review the release notes of recent versions of the Gradle plugins for more information on tool compatibility and environment setup.

In the 'patched-app' sample, browse the two 'build.gradle' files (main and app) to get an idea of what is happening. The plugins used are briefly described here. Next get inside the 'app' subproject and take a look at its manifest and resource files. These files are merged with the ones coming from the source app, which is located in the 'apk' directory. Finally look into the 'MainActivity.java' file to see how the compiled code of the app is patched using Java. This is handled by the DexPatcher tool, a key piece of the DexPatcher toolchain. See the section 'Patching Java code in Java' above for more details on this tool, and please review its recent release notes.

The DexPatcher Gradle plugins use Apktool to decode applications and optionally create APK libraries. They optionally use dex2jar to display decompiled application code and to import application code symbols into patch projects. They use the DexPatcher tool to patch the Dalvik bytecode of applications. And finally they use the Andoird build system to merge manifests, code, resources, assets, and extra files, and to repackage applications.


With the old DexPatcher Gradle v1 plugins

To get the old sample code working:
  1. Install the support tools by cloning the repo anywhere you like.
  2. Clone the 'v1' branch of the samples.
  3. Set the 'dexpatcher.dir=<support-tool-dir>' property in identical files named 'local.properties' in the root directory of each sample so that it points to your local clone of the support tools. Create the files if necessary, or have Android Studio create them for you by opening the samples.
  4. Start with the 'patched-app' sample: open the project with Android Studio, disable instant run, and run or debug your patched app!

Please review the old release notes of the Gradle v1 plugins for more information on tool compatibility and environment setup.


OLD NEWS: DexPatcher Featured On XDA Portal !

GermainZ wrote an excellent introductory article for XDA that walks you though the complete process of modding an app using the old deprecated Linux-only workflow automation scripts. This only covers the DexPatcher tool itself, ie: only patching of code, not resources. The workflow is deprecated, but the Java patch code and accompanying explanations are very valuable and continue to be current. I am grateful to him for having taken the time to do this. Please make sure you give it a read:
Also available: [WARNING: Deprecated, Linux-only]

LICENSING UPDATE:

tl;dr: DexPatcher patches are no longer forcefully covered by the GPL.

Recent versions of DexPatcher no longer require that users bundle the DexPatcher annotations with every patch (although continuing to do so has no ill effects). The DexPatcher licensing terms no longer impose licensing restrictions on patches, as long as users refrain from bundling the DexPatcher annotations with them. In particular, DexPatcher patches are no longer considered to be derivative works of DexPatcher and thus are no longer automatically covered by the GPL. Legals aside, the DexPatcher project urges you not to use copyright laws to introduce artificial scarcity in the world. Please give back to the community: share your work.



XDA:DevDB Information
DexPatcher, Tool/Utility for all devices (see above for details)

Contributors
Lanchon
Source Code: https://github.com/DexPatcher


Version Information
Status: Stable

Created 2015-03-21
Last Updated 2019-11-09
The Following 45 Users Say Thank You to Lanchon For This Useful Post: [ View ] Gift Lanchon Ad-Free
21st March 2015, 08:04 PM |#2  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
DEPRECATED: Workflow Automation Scripts HOW-TO
DEPRECATED: Workflow Automation Scripts HOW-TO

These scripts bundle several tools (including DexPatcher) and automate boilerplate actions that are part of a typical workflow. They are available only for Linux. Take the leap today, get yourself free, get Linux Mint Cinnamon 64-bit.

Installation

Code:
# cd to a suitable install dir such as '~/opt' or '~/android/tools'.

git clone https://github.com/Lanchon/DexPatcher-scripts.git dexpatcher
cd dexpatcher
chmod +x dxp-*

# edit 'dxp.config':
# -set the path to android sdk (defaults to '~/android/sdk').
# -disable bundled tools to use the ones in $PATH if desired.

# add 'dxp-*' scripts to $PATH:
# -symlink the 'dxp-*' scripts in a suitable dir in the $PATH such as '~/bin'.
# -or add the 'dexpatcher' dir to $PATH.
Sample Workflow

Code:
# cd to a suitable workspace dir.

dxp-setup-for-apk path/to/TheApk.apk 
cd TheApk
dxp-create-keystore

# in 'src-cfr' you will find decompilation of the app to Java (with errors).
# you can use these files to plan your changes.

# in 'src-cfr-nocode' you will find decompilation of empty method stubs.
# you can use selected files as a basis for your patch.
 
# create your patch as Java files in 'src'.
# the symbols of the original app will be accessible to your patch code.

dxp-make
adb install -r patched.apk
The Following 4 Users Say Thank You to Lanchon For This Useful Post: [ View ] Gift Lanchon Ad-Free
21st March 2015, 08:04 PM |#3  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
The Big TO-DO List
The Big TO-DO List

...of things I would like done in this project, but that I will probably not have the time to implement myself.

DexPatcher-tool

Moved here: https://github.com/Lanchon/DexPatcher-tool/issues

DexPatcher-gadle

Moved here: https://github.com/Lanchon/DexPatcher-gradle/issues

DexPatcher and javac
  • Modify javac so that all source symbols -even those defined inside edited classes- are available during compilation. This could produce a patched javac executable, or the standard javac could be patched in-memory using java agents, or its in-memory data structures hacked from an annotation processor (a la Project Lombok).
  • Decide if dex2jar and jar2dex/dx are transparent and mature enough to move DexPatcher 2.0 to the java bytecode realm, and stop operating at the dalvik bytecode level. [UPDATE: It is not.] Or a VM abstraction could be implemented as a backend to DexPatcher so that the same font end could be used for both dex and class files.
  • If the project is moved to the java bytecode realm, decide if the new DexPatcher should be a standalone tool like it is today, or a java agent/annotation processor that modifies javac to do the patching during compile time. This would make the tool very easy to integrate into most build systems.
The Following 5 Users Say Thank You to Lanchon For This Useful Post: [ View ] Gift Lanchon Ad-Free
22nd March 2015, 12:55 AM |#4  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
just added the documentation section
The Following User Says Thank You to Lanchon For This Useful Post: [ View ] Gift Lanchon Ad-Free
22nd March 2015, 12:41 PM |#5  
Senior Member
Thanks Meter: 2,383
 
More
I checked docs and wow, massive Maybe you can make some easier examples how to use it (some small patches).
The Following User Says Thank You to pyler For This Useful Post: [ View ] Gift pyler Ad-Free
22nd March 2015, 08:32 PM |#6  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
there is a lot of docs missing, especially regarding the workflow, how to extract and use symbols from the source apk, etc. for now im working on 0.2
23rd March 2015, 05:02 AM |#7  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
UPDATE: version 0.2.0 released!
23rd March 2015, 01:02 PM |#8  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
UPDATE: version 0.3.0 released!
23rd March 2015, 07:49 PM |#9  
PerfectSlayer's Avatar
Senior Member
Thanks Meter: 4,826
 
Donate to Me
More
Looks good
I will look at it more deeply when I found time.

I'm surprised there isn't so much feedback… May be could you add some examples / details in the OP?
The Following 2 Users Say Thank You to PerfectSlayer For This Useful Post: [ View ] Gift PerfectSlayer Ad-Free
23rd March 2015, 08:20 PM |#10  
Lanchon's Avatar
OP Senior Member
Thanks Meter: 4,446
 
Donate to Me
More
Quote:
Originally Posted by PerfectSlayer

Looks good
I will look at it more deeply when I found time.

I'm surprised there isn't so much feedback… May be could you add some examples / details in the OP?

i still need to evolve the tool a little with respect to handling of fields, and then it's mostly done. but i need to document a full workflow, including obtaining symbols against which to build the patch (you want your patch code to be able to use all of the source app's code).
The Following 2 Users Say Thank You to Lanchon For This Useful Post: [ View ] Gift Lanchon Ad-Free
23rd March 2015, 08:38 PM |#11  
agentdr8's Avatar
Senior Member
Flag Cowtown, CA
Thanks Meter: 1,850
 
Donate to Me
More
Very interested in seeing how this tool progresses.
The Following User Says Thank You to agentdr8 For This Useful Post: [ View ] Gift agentdr8 Ad-Free
Post Reply Subscribe to Thread

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

Advanced Search
Display Modes