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

Search This thread

Lanchon

Senior Member
Jun 19, 2011
2,751
4,487
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/dexpatcher-gradle/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/dexpatcher-gradle/releases?after=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
 

Lanchon

Senior Member
Jun 19, 2011
2,751
4,487
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 [url]https://github.com/Lanchon/DexPatcher-scripts.git[/url] 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
 
Last edited:

Lanchon

Senior Member
Jun 19, 2011
2,751
4,487
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.
 
Last edited:

pyler

Senior Member
Jan 13, 2013
1,279
2,372
I checked docs and wow, massive :) Maybe you can make some easier examples how to use it (some small patches).
 
Last edited:
  • Like
Reactions: Lanchon

Lanchon

Senior Member
Jun 19, 2011
2,751
4,487
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 :)
 

Lanchon

Senior Member
Jun 19, 2011
2,751
4,487
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).
 

Top Liked Posts

  • There are no posts matching your filters.
  • 58
    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/dexpatcher-gradle/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/dexpatcher-gradle/releases?after=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
    6
    UPDATE: DexPatcher-gradle v1.0.0 is out, finally!

    also, the 'patched-dex' sample has been heavily updated to match.

    https://github.com/DexPatcher/dexpatcher-gradle/releases
    https://github.com/DexPatcher/dexpatcher-gradle-samples/blob/master/patched-dex/build.gradle
    5
    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.
    4
    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 [url]https://github.com/Lanchon/DexPatcher-scripts.git[/url] 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
    4
    UPDATE: version 1.0.0-beta2 released!

    Changelog in the previous link. Do you use DexPatcher? Say hi on this thread!