Home | History | Annotate | Download | only in docs
      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>
     10 On an Android device, the Dalvik virtual machine usually executes embedded
     11 in the Android application framework.  It's also possible to run it directly,
     12 just as you would a virtual machine on your desktop system.
     13 </p><p>
     14 After compiling your Java language sources, convert and combine the .class
     15 files 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>
     25 Hello, world
     26 </code>
     27 </p><p>
     28 The <code>-cp</code> option sets the classpath.  The initial directory
     29 for <code>adb shell</code> may not be what you expect it to be, so it's
     30 usually best to specify absolute pathnames.
     31 
     32 </p><p>
     33 The <code>dx</code> command accepts lists of individual class files,
     34 directories, or Jar archives.  When the <code>--output</code> filename
     35 ends with <code>.jar</code>, <code>.zip</code>, or <code>.apk</code>,
     36 a file called <code>classes.dex</code> is created and stored inside the
     37 archive.
     38 </p><p>
     39 Run <code>adb shell dalvikvm -help</code> to see a list of command-line
     40 options.
     41 </p><p>
     42 
     43 
     44 
     45 <h2>Using a debugger</h2>
     46 
     47 <p>
     48 You can debug stand-alone applications with any JDWP-compliant debugger.
     49 There are two basic approaches.
     50 </p><p>
     51 The first way is to connect directly through TCP.  Add, to the "dalvikvm"
     52 invocation line above, an argument like:
     53 </p><p>
     54 <code>&nbsp;&nbsp;-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</code>
     55 </p><p>
     56 This tells the VM to wait for a debugger to connect to it on TCP port 8000.
     57 You need to tell adb to forward local port 8000 to device port 8000:
     58 </p><p>
     59 <code>% <font color="green">adb forward tcp:8000 tcp:8000</font></code>
     60 </p><p>
     61 and then connect to it with your favorite debugger (using <code>jdb</code>
     62 as an example here):
     63 </p><p>
     64 <code>% <font color="green">jdb -attach localhost:8000</font></code>
     65 </p><p>
     66 When the debugger attaches, the VM will be in a suspended state.  You can
     67 set breakpoints and then tell it to continue.
     68 
     69 
     70 </p><p>
     71 You can also connect through DDMS, like you would for an Android application.
     72 Add, to the "dalvikvm" command line:
     73 </p><p>
     74 <code>&nbsp;&nbsp;-agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y</code>
     75 </p><p>
     76 Note the <code>transport</code> has changed, and you no longer need to
     77 specify a TCP port number.  When your application starts, it will appear
     78 in DDMS, with "?" as the application name.  Select it in DDMS, and connect
     79 to it as usual, e.g.:
     80 </p><p>
     81 <code>% <font color="green">jdb -attach localhost:8700</font></code>
     82 </p><p>
     83 Because command-line applications don't include the client-side
     84 DDM setup, features like thread monitoring and allocation tracking will not
     85 be available in DDMS.  It's strictly a debugger pass-through in this mode.
     86 </p><p>
     87 See <a href="debugger.html">Dalvik Debugger Support</a> for more information
     88 about using debuggers with Dalvik.
     89 
     90 
     91 
     92 <h2>Working with the desktop build</h2>
     93 
     94 <!-- largely lifted from
     95 http://groups.google.com/group/android-porting/browse_thread/thread/ab553116dbc960da/29167c58b3b49051#29167c58b3b49051
     96 -->
     97 
     98 <p>
     99 The Dalvik VM can also be used directly on the desktop.  This is somewhat
    100 more complicated however, because you won't have certain things set up in
    101 your environment, and several native code libraries are required to support
    102 the core Dalvik libs.
    103 </p><p>
    104 Start with:
    105 
    106 <pre>
    107   . build/envsetup.sh
    108   lunch sim-eng
    109 </pre>
    110 
    111 You should see something like:
    112 
    113 <pre>
    114   ============================================
    115   TARGET_PRODUCT=sim
    116   TARGET_BUILD_VARIANT=eng
    117   TARGET_SIMULATOR=true
    118   TARGET_BUILD_TYPE=debug
    119   TARGET_ARCH=x86
    120   HOST_ARCH=x86
    121   HOST_OS=linux
    122   HOST_BUILD_TYPE=release
    123   BUILD_ID=
    124   ============================================
    125 </pre>
    126 
    127 </p></p>
    128 This configures you to build for the desktop, linking against glibc.
    129 This mode is NOT recommended for anything but experimental use.  It
    130 may go away in the future.
    131 </p></p>
    132 You may see <code>TARGET_BUILD_TYPE=release</code> or <code>=debug</code>
    133 or possibly nothing there at all.  You may want to replace the
    134 <code>lunch</code> command with
    135 <code>choosecombo Simulator debug sim eng</code>.
    136 </p></p>
    137 Build the world (add a <code>-j4</code> if you have multiple cores):
    138 
    139 <pre>
    140   make
    141 </pre>
    142 
    143 </p></p>
    144 When that completes, you have a working dalvikm on your desktop
    145 machine:
    146 
    147 <pre>
    148   % dalvikvm
    149   E/dalvikvm(19521): ERROR: must specify non-'.' bootclasspath
    150   W/dalvikvm(19521): JNI_CreateJavaVM failed
    151   Dalvik VM init failed (check log file)
    152 </pre>
    153 
    154 </p></p>
    155 To actually do something, you need to specify the bootstrap class path
    156 and give it a place to put DEX data that it uncompresses from jar
    157 files.  You can do that with a script like this:
    158 
    159 <blockquote><pre>
    160 #!/bin/sh
    161 
    162 # base directory, at top of source tree; replace with absolute path
    163 base=`pwd`
    164 
    165 # configure root dir of interesting stuff
    166 root=$base/out/debug/host/linux-x86/product/sim/system
    167 export ANDROID_ROOT=$root
    168 
    169 # configure bootclasspath
    170 bootpath=$root/framework
    171 export BOOTCLASSPATH=$bootpath/core.jar:$bootpath/ext.jar:$bootpath/framework.jar:$bootpath/android.policy.jar:$bootpath/services.jar
    172 
    173 # this is where we create the dalvik-cache directory; make sure it exists
    174 export ANDROID_DATA=/tmp/dalvik_$USER
    175 mkdir -p $ANDROID_DATA/dalvik-cache
    176 
    177 exec dalvikvm $@
    178 </pre></blockquote>
    179 
    180 </p></p>
    181 The preparation with <code>dx</code> is the same as before:
    182 
    183 <pre>
    184   % cat &gt; Foo.java
    185   class Foo { public static void main(String[] args) {
    186     System.out.println("Hello, world");
    187   } }
    188   (ctrl-D)
    189   % javac Foo.java
    190   % dx --dex --output=foo.jar Foo.class
    191   % ./rund -cp foo.jar Foo
    192   Hello, world
    193 </pre>
    194 
    195 As above, you can get some info about valid arguments like this:
    196 
    197 <pre>
    198   % ./rund -help
    199 </pre>
    200 
    201 </p></p>
    202 This also shows what options the VM was configured with.  The sim "debug"
    203 build has all sorts of additional assertions and checks enabled,
    204 which slows the VM down, but since this is just for experiments it
    205 doesn't matter.
    206 
    207 </p></p>
    208 All of the above applies to x86 Linux.  Anything else will likely
    209 require a porting effort.  If libffi supports your system, the amount of
    210 work required should be minor.
    211 
    212 </p></p>
    213 <address>Copyright &copy; 2009 The Android Open Source Project</address>
    214 
    215 </body>
    216 </html>
    217