Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / dalvik / aa336024f7044a79a5a1d337b45303811b617649 / . / docs / hello-world.html
blob: fbb7d97817087898039c688d4f1c9a19e5a49f34 [file] [log] [blame]
Andy McFaddenaa336022009-04-27 13:19:51 -0700[diff] [blame^]1<html>
2<head>
3 <title>Basic Dalvik VM Invocation</title>
4</head>
5
6<body>
7<h1>Basic Dalvik VM Invocation</h1>
8
9<p>
10On an Android device, the Dalvik virtual machine usually executes embedded
11in the Android application framework. It's also possible to run it directly,
12just as you would a virtual machine on your desktop system.
13</p><p>
14After compiling your Java language sources, convert and combine the .class
15files into a DEX file, and push that to the device. Here's a simple example:
16
17</p><p><code>
18% <font color="green">echo 'class Foo {'\</font><br>
19&gt; <font color="green">'public static void main(String[] args) {'\</font><br>
20&gt; <font color="green">'System.out.println("Hello, world"); }}' &gt; Foo.java</font><br>
21% <font color="green">javac Foo.java</font><br>
22% <font color="green">dx --dex --output=foo.jar Foo.class</font><br>
23% <font color="green">adb push foo.jar /sdcard</font><br>
24% <font color="green">adb shell dalvikvm -cp /sdcard/foo.jar Foo</font><br>
25Hello, world
26</code>
27</p><p>
28The <code>-cp</code> option sets the classpath. The initial directory
29for <code>adb shell</code> may not be what you expect it to be, so it's
30usually best to specify absolute pathnames.
31
32</p><p>
33The <code>dx</code> command accepts lists of individual class files,
34directories, or Jar archives. When the <code>--output</code> filename
35ends with <code>.jar</code>, <code>.zip</code>, or <code>.apk</code>,
36a file called <code>classes.dex</code> is created and stored inside the
37archive.
38</p><p>
39Run <code>adb shell dalvikvm -help</code> to see a list of command-line
40options.
41</p><p>
42
43
44
45<h2>Working with the desktop build</h2>
46
47<!-- largely lifted from
48http://groups.google.com/group/android-porting/browse_thread/thread/ab553116dbc960da/29167c58b3b49051#29167c58b3b49051
49-->
50
51<p>
52The Dalvik VM can also be used directly on the desktop. This is somewhat
53more complicated however, because you won't have certain things set up in
54your environment, and several native code libraries are required to support
55the core Dalvik libs.
56</p><p>
57Start with:
58
59<pre>
60 . build/envsetup.sh
61 lunch sim-eng
62</pre>
63
64You should see something like:
65
66<pre>
67 ============================================
68 TARGET_PRODUCT=sim
69 TARGET_BUILD_VARIANT=eng
70 TARGET_SIMULATOR=true
71 TARGET_BUILD_TYPE=debug
72 TARGET_ARCH=x86
73 HOST_ARCH=x86
74 HOST_OS=linux
75 HOST_BUILD_TYPE=release
76 BUILD_ID=
77 ============================================
78</pre>
79
80</p></p>
81This configures you to build for the desktop, linking against glibc.
82This mode is NOT recommended for anything but experimental use. It
83may go away in the future.
84</p></p>
85You may see <code>TARGET_BUILD_TYPE=release</code> or <code>=debug</code>
86or possibly nothing there at all. You may want to replace the
87<code>lunch</code> command with
88<code>choosecombo Simulator debug sim eng</code>.
89</p></p>
90Build the world (add a <code>-j4</code> if you have multiple cores):
91
92<pre>
93 make
94</pre>
95
96</p></p>
97When that completes, you have a working dalvikm on your desktop
98machine:
99
100<pre>
101 % dalvikvm
102 E/dalvikvm(19521): ERROR: must specify non-'.' bootclasspath
103 W/dalvikvm(19521): JNI_CreateJavaVM failed
104 Dalvik VM init failed (check log file)
105</pre>
106
107</p></p>
108To actually do something, you need to specify the bootstrap class path
109and give it a place to put DEX data that it uncompresses from jar
110files. You can do that with a script like this:
111
112<blockquote><pre>
113#!/bin/sh
114
115# base directory, at top of source tree; replace with absolute path
116base=`pwd`
117
118# configure root dir of interesting stuff
119root=$base/out/debug/host/linux-x86/product/sim/system
120export ANDROID_ROOT=$root
121
122# configure bootclasspath
123bootpath=$root/framework
124export BOOTCLASSPATH=$bootpath/core.jar:$bootpath/ext.jar:$bootpath/framework.jar:$bootpath/android.policy.jar:$bootpath/services.jar
125
126# this is where we create the dalvik-cache directory; make sure it exists
127export ANDROID_DATA=/tmp/dalvik_$USER
128mkdir -p $ANDROID_DATA/dalvik-cache
129
130exec dalvikvm $@
131</pre></blockquote>
132
133</p></p>
134The preparation with <code>dx</code> is the same as before:
135
136<pre>
137 % cat &gt; Foo.java
138 class Foo { public static void main(String[] args) {
139 System.out.println("Hello, world");
140 } }
141 (ctrl-D)
142 % javac Foo.java
143 % dx --dex --output=foo.jar Foo.class
144 % ./rund -cp foo.jar Foo
145 Hello, world
146</pre>
147
148As above, you can get some info about valid arguments like this:
149
150<pre>
151 % ./rund -help
152</pre>
153
154</p></p>
155This also shows what options the VM was configured with. The sim "debug"
156build has all sorts of additional assertions and checks enabled,
157which slows the VM down, but since this is just for experiments it
158doesn't matter.
159
160</p></p>
161All of the above applies to x86 Linux. Anything else will likely
162require a porting effort. If libffi supports your system, the amount of
163work required should be minor.
164
165</body>
166</html>