# Basic Dalvik VM Invocation

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.

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:

`% echo 'class Foo {'\
> 'public static void main(String[] args) {'\
> 'System.out.println("Hello, world"); }}' > Foo.java
% javac Foo.java
% dx --dex --output=foo.jar Foo.class
% adb push foo.jar /sdcard
% adb shell dalvikvm -cp /sdcard/foo.jar Foo
Hello, world`

The `-cp` option sets the classpath. The initial directory for `adb shell` may not be what you expect it to be, so it's usually best to specify absolute pathnames.

The `dx` command accepts lists of individual class files, directories, or Jar archives. When the `--output` filename ends with `.jar`, `.zip`, or `.apk`, a file called `classes.dex` is created and stored inside the archive.

Run `adb shell dalvikvm -help` to see a list of command-line options.

## Using a debugger

You can debug stand-alone applications with any JDWP-compliant debugger. There are two basic approaches.

The first way is to connect directly through TCP. Add, to the "dalvikvm" invocation line above, an argument like:

`-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y`

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:

`% adb forward tcp:8000 tcp:8000`

and then connect to it with your favorite debugger (using `jdb` as an example here):

`% jdb -attach localhost:8000`

When the debugger attaches, the VM will be in a suspended state. You can set breakpoints and then tell it to continue.

You can also connect through DDMS, like you would for an Android application. Add, to the "dalvikvm" command line:

`-agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y`

Note the `transport` 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.:

`% jdb -attach localhost:8700`

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.

See Dalvik Debugger Support for more information about using debuggers with Dalvik.

## Working with the desktop build

The Dalvik VM can also be used directly on the desktop. This is somewhat more complicated however, because you won't have certain things set up in your environment, and several native code libraries are required to support the core Dalvik libs.

Start with:

      . build/envsetup.sh
      lunch sim-eng

You should see something like:

      ============================================
      TARGET_PRODUCT=sim
      TARGET_BUILD_VARIANT=eng
      TARGET_SIMULATOR=true
      TARGET_BUILD_TYPE=debug
      TARGET_ARCH=x86
      HOST_ARCH=x86
      HOST_OS=linux
      HOST_BUILD_TYPE=release
      BUILD_ID=
      ============================================

This configures you to build for the desktop, linking against glibc. This mode is NOT recommended for anything but experimental use. It may go away in the future. You may see `TARGET_BUILD_TYPE=release` or `=debug` or possibly nothing there at all. You may want to replace the `lunch` command with `choosecombo Simulator debug sim eng`. Build the world (add a `-j4` if you have multiple cores):

      make

When that completes, you have a working dalvikm on your desktop machine:

      % dalvikvm
      E/dalvikvm(19521): ERROR: must specify non-'.' bootclasspath
      W/dalvikvm(19521): JNI_CreateJavaVM failed
      Dalvik VM init failed (check log file)

To actually do something, you need to specify the bootstrap class path and give it a place to put DEX data that it uncompresses from jar files. You can do that with a script like this:

>     #!/bin/sh

>     # base directory, at top of source tree; replace with absolute path
>     base=`pwd`

>     # configure root dir of interesting stuff
>     root=$base/out/debug/host/linux-x86/product/sim/system
>     export ANDROID_ROOT=$root

>     # configure bootclasspath
>     bootpath=$root/framework
>     export BOOTCLASSPATH=$bootpath/core.jar:$bootpath/ext.jar:$bootpath/framework.jar:$bootpath/android.policy.jar:$bootpath/services.jar

>     # this is where we create the dalvik-cache directory; make sure it exists
>     export ANDROID_DATA=/tmp/dalvik_$USER
>     mkdir -p $ANDROID_DATA/dalvik-cache

>     exec dalvikvm $@

The preparation with `dx` is the same as before:

      % cat > Foo.java
      class Foo { public static void main(String[] args) {
        System.out.println("Hello, world");
      } }
      (ctrl-D)
      % javac Foo.java
      % dx --dex --output=foo.jar Foo.class
      % ./rund -cp foo.jar Foo
      Hello, world

As above, you can get some info about valid arguments like this:

      % ./rund -help

This also shows what options the VM was configured with. The sim "debug" build has all sorts of additional assertions and checks enabled, which slows the VM down, but since this is just for experiments it doesn't matter. All of the above applies to x86 Linux. Anything else will likely require a porting effort. If libffi supports your system, the amount of work required should be minor.