<html>
<head>
    <title>Basic Dalvik VM Invocation</title>
</head>

<body>
<h1>Basic Dalvik VM Invocation</h1>

<p>
On an Android device, the Dalvik virtual machine usually executes embedded
in the Android application framework.  It's also possible to run it directly,
just as you would a virtual machine on your desktop system.
</p><p>
After compiling your Java language sources, convert and combine the .class
files into a DEX file, and push that to the device.  Here's a simple example:

</p><p><code>
% <font color="green">echo 'class Foo {'\</font><br>
&gt; <font color="green">'public static void main(String[] args) {'\</font><br>
&gt; <font color="green">'System.out.println("Hello, world"); }}' &gt; Foo.java</font><br>
% <font color="green">javac Foo.java</font><br>
% <font color="green">dx --dex --output=foo.jar Foo.class</font><br>
% <font color="green">adb push foo.jar /sdcard</font><br>
% <font color="green">adb shell dalvikvm -cp /sdcard/foo.jar Foo</font><br>
Hello, world
</code>
</p><p>
The <code>-cp</code> option sets the classpath.  The initial directory
for <code>adb shell</code> may not be what you expect it to be, so it's
usually best to specify absolute pathnames.

</p><p>
The <code>dx</code> command accepts lists of individual class files,
directories, or Jar archives.  When the <code>--output</code> filename
ends with <code>.jar</code>, <code>.zip</code>, or <code>.apk</code>,
a file called <code>classes.dex</code> is created and stored inside the
archive.
</p><p>
Run <code>adb shell dalvikvm -help</code> to see a list of command-line
options.
</p><p>


<h2>Using a debugger</h2>

<p>
You can debug stand-alone applications with any JDWP-compliant debugger.
There are two basic approaches.
</p><p>
The first way is to connect directly through TCP.  Add, to the "dalvikvm"
invocation line above, an argument like:
</p><p>
<code>&nbsp;&nbsp;-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</code>
</p><p>
This tells the VM to wait for a debugger to connect to it on TCP port 8000.
You need to tell adb to forward local port 8000 to device port 8000:
</p><p>
<code>% <font color="green">adb forward tcp:8000 tcp:8000</font></code>
</p><p>
and then connect to it with your favorite debugger (using <code>jdb</code>
as an example here):
</p><p>
<code>% <font color="green">jdb -attach localhost:8000</font></code>
</p><p>
When the debugger attaches, the VM will be in a suspended state.  You can
set breakpoints and then tell it to continue.


</p><p>
You can also connect through DDMS, like you would for an Android application.
Add, to the "dalvikvm" command line:
</p><p>
<code>&nbsp;&nbsp;-agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y</code>
</p><p>
Note the <code>transport</code> has changed, and you no longer need to
specify a TCP port number.  When your application starts, it will appear
in DDMS, with "?" as the application name.  Select it in DDMS, and connect
to it as usual, e.g.:
</p><p>
<code>% <font color="green">jdb -attach localhost:8700</font></code>
</p><p>
Because command-line applications don't include the client-side
DDM setup, features like thread monitoring and allocation tracking will not
be available in DDMS.  It's strictly a debugger pass-through in this mode.
</p><p>
See <a href="debugger.html">Dalvik Debugger Support</a> for more information
about using debuggers with Dalvik.


</p></p>
<address>Copyright &copy; 2009 The Android Open Source Project</address>

</body>
</html>