README.md
1A Java-language API for doing compile time or runtime code generation targeting the Dalvik VM. Unlike
2[cglib](http://cglib.sourceforge.net/) or [ASM](http://asm.ow2.org/), this library creates Dalvik `.dex`
3files instead of Java `.class` files.
4
5It has a small, close-to-the-metal API. This API mirrors the
6[Dalvik bytecode specification](http://source.android.com/tech/dalvik/dalvik-bytecode.html) giving you tight
7control over the bytecode emitted. Code is generated instruction-by-instruction; you bring your own abstract
8syntax tree if you need one. And since it uses Dalvik's `dx` tool as a backend, you get efficient register
9allocation and regular/wide instruction selection for free.
10
11Class Proxies
12-------------
13
14Dexmaker includes a stock code generator for [class proxies](http://dexmaker.googlecode.com/git/javadoc/com/google/dexmaker/stock/ProxyBuilder.html).
15If you just want to do AOP or class mocking, you don't need to mess around with bytecodes.
16
17Mockito Mocks
18-------------
19
20Dexmaker includes class proxy support for [Mockito](http://code.google.com/p/mockito/). Add the mockito
21and the dexmaker `.jar` files to your Android test project's `libs/` directory and you can use Mockito
22in your Android unit tests.
23
24This requires Mockito 1.10.5 or newer.
25
26Runtime Code Generation
27-----------------------
28
29This example generates a class and a method. It then loads that class into the current process and invokes its method.
30```
31public final class HelloWorldMaker {
32 public static void main(String[] args) throws Exception {
33 DexMaker dexMaker = new DexMaker();
34
35 // Generate a HelloWorld class.
36 TypeId<?> helloWorld = TypeId.get("LHelloWorld;");
37 dexMaker.declare(helloWorld, "HelloWorld.generated", Modifier.PUBLIC, TypeId.OBJECT);
38 generateHelloMethod(dexMaker, helloWorld);
39
40 // Create the dex file and load it.
41 File outputDir = new File(".");
42 ClassLoader loader = dexMaker.generateAndLoad(HelloWorldMaker.class.getClassLoader(),
43 outputDir, outputDir);
44 Class<?> helloWorldClass = loader.loadClass("HelloWorld");
45
46 // Execute our newly-generated code in-process.
47 helloWorldClass.getMethod("hello").invoke(null);
48 }
49
50 /**
51 * Generates Dalvik bytecode equivalent to the following method.
52 * public static void hello() {
53 * int a = 0xabcd;
54 * int b = 0xaaaa;
55 * int c = a - b;
56 * String s = Integer.toHexString(c);
57 * System.out.println(s);
58 * return;
59 * }
60 */
61 private static void generateHelloMethod(DexMaker dexMaker, TypeId<?> declaringType) {
62 // Lookup some types we'll need along the way.
63 TypeId<System> systemType = TypeId.get(System.class);
64 TypeId<PrintStream> printStreamType = TypeId.get(PrintStream.class);
65
66 // Identify the 'hello()' method on declaringType.
67 MethodId hello = declaringType.getMethod(TypeId.VOID, "hello");
68
69 // Declare that method on the dexMaker. Use the returned Code instance
70 // as a builder that we can append instructions to.
71 Code code = dexMaker.declare(hello, Modifier.STATIC | Modifier.PUBLIC);
72
73 // Declare all the locals we'll need up front. The API requires this.
74 Local<Integer> a = code.newLocal(TypeId.INT);
75 Local<Integer> b = code.newLocal(TypeId.INT);
76 Local<Integer> c = code.newLocal(TypeId.INT);
77 Local<String> s = code.newLocal(TypeId.STRING);
78 Local<PrintStream> localSystemOut = code.newLocal(printStreamType);
79
80 // int a = 0xabcd;
81 code.loadConstant(a, 0xabcd);
82
83 // int b = 0xaaaa;
84 code.loadConstant(b, 0xaaaa);
85
86 // int c = a - b;
87 code.op(BinaryOp.SUBTRACT, c, a, b);
88
89 // String s = Integer.toHexString(c);
90 MethodId<Integer, String> toHexString
91 = TypeId.get(Integer.class).getMethod(TypeId.STRING, "toHexString", TypeId.INT);
92 code.invokeStatic(toHexString, s, c);
93
94 // System.out.println(s);
95 FieldId<System, PrintStream> systemOutField = systemType.getField(printStreamType, "out");
96 code.sget(systemOutField, localSystemOut);
97 MethodId<PrintStream, Void> printlnMethod = printStreamType.getMethod(
98 TypeId.VOID, "println", TypeId.STRING);
99 code.invokeVirtual(printlnMethod, null, localSystemOut, s);
100
101 // return;
102 code.returnVoid();
103 }
104}
105```
106
107Use it in your app
108------------------
109
110Maven users can get dexmaker from Sonatype's central repository. The Mockito dependency is optional.
111
112```
113 <dependency>
114 <groupId>com.google.dexmaker</groupId>
115 <artifactId>dexmaker</artifactId>
116 <version>1.2</version>
117 </dependency>
118 <dependency>
119 <groupId>com.google.dexmaker</groupId>
120 <artifactId>dexmaker-mockito</artifactId>
121 <version>1.2</version>
122 </dependency>
123```
124
125Download [dexmaker-1.2.jar](http://search.maven.org/remotecontent?filepath=com/google/dexmaker/dexmaker/1.2/dexmaker-1.2.jar)
126and [dexmaker-mockito-1.2.jar](http://search.maven.org/remotecontent?filepath=com/google/dexmaker/dexmaker-mockito/1.2/dexmaker-mockito-1.2.jar).
127
128Run the Unit Tests
129------------------
130
131The unit tests for dexmaker must be run on a dalvikvm. In order to do this, you can use [Vogar](https://code.google.com/p/vogar/) in the following fashion:
132
133```
134$ java -jar vogar.jar --mode device --sourcepath /path/to/dexmaker/dexmaker/src/test/java --sourcepath /path/to/dexmaker/dexmaker/src/main/java --sourcepath /path/to/dexmaker/dx/src/main/java --device-dir /data/dexmaker /path/to/dexmaker/dexmaker/src/test/
135```
136
137Download [vogar.jar](https://vogar.googlecode.com/files/vogar.jar).
138
README.version
1URL: https://github.com/linkedin/dexmaker/
2Version: master (8ff85edb2793cc1e0f6a93c67b127cb9c43d924e)
3License: Apache 2.0
4Description:
5Dexmaker is a Java-language API for doing compile time or runtime code generation targeting the Dalvik VM. Unlike cglib or ASM, this library creates Dalvik .dex files instead of Java .class files.
6
7It has a small, close-to-the-metal API. This API mirrors the Dalvik bytecode specification giving you tight control over the bytecode emitted. Code is generated instruction-by-instruction; you bring your own abstract syntax tree if you need one. And since it uses Dalvik's dx tool as a backend, you get efficient register allocation and regular/wide instruction selection for free.
8
9It includes a stock code generator for class proxies. If you just want to do AOP or class mocking, you don't need to mess around with bytecodes.
10
11Local Modifications:
12 Add ability to run dexmaker tests from within the source tree (I1b146841099b54f64d4a7dfe743b88717793619a)
13 Allow to share classloader via dexmaker.share_classloader system property (I324cddd644610eef811c620a1fccf6a24b2b9406)
14 Do not read Build.VERSION to allow non-standard Android distributions (Ia8c4ba4c82cd6f193c565f1bfe48faffc4aac08f)
15 Temporarily ignore failing test (Ibf7b6c2eb05c5ff83f0817f9224369e20c0b775d)
16 Restrict InspectClass to current thread. (Ic62951ff81bed60ac7512455fad65210e4b728a9, need upstreaming)
17