docs/hello-world.html

   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>Working with the desktop build</h2>
  46
  47 <!-- largely lifted from
  48 http://groups.google.com/group/android-porting/browse_thread/thread/ab553116dbc960da/29167c58b3b49051#29167c58b3b49051
  49 -->
  50
  51 <p>
  52 The Dalvik VM can also be used directly on the desktop.  This is somewhat
  53 more complicated however, because you won't have certain things set up in
  54 your environment, and several native code libraries are required to support
  55 the core Dalvik libs.
  56 </p><p>
  57 Start with:
  58
  59 <pre>
  60   . build/envsetup.sh
  61   lunch sim-eng
  62 </pre>
  63
  64 You 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>
  81 This configures you to build for the desktop, linking against glibc.
  82 This mode is NOT recommended for anything but experimental use.  It
  83 may go away in the future.
  84 </p></p>
  85 You may see <code>TARGET_BUILD_TYPE=release</code> or <code>=debug</code>
  86 or 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>
  90 Build the world (add a <code>-j4</code> if you have multiple cores):
  91
  92 <pre>
  93   make
  94 </pre>
  95
  96 </p></p>
  97 When that completes, you have a working dalvikm on your desktop
  98 machine:
  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>
 108 To actually do something, you need to specify the bootstrap class path
 109 and give it a place to put DEX data that it uncompresses from jar
 110 files.  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
 116 base=`pwd`
 117
 118 # configure root dir of interesting stuff
 119 root=$base/out/debug/host/linux-x86/product/sim/system
 120 export ANDROID_ROOT=$root
 121
 122 # configure bootclasspath
 123 bootpath=$root/framework
 124 export 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
 127 export ANDROID_DATA=/tmp/dalvik_$USER
 128 mkdir -p $ANDROID_DATA/dalvik-cache
 129
 130 exec dalvikvm $@
 131 </pre></blockquote>
 132
 133 </p></p>
 134 The 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
 148 As above, you can get some info about valid arguments like this:
 149
 150 <pre>
 151   % ./rund -help
 152 </pre>
 153
 154 </p></p>
 155 This also shows what options the VM was configured with.  The sim "debug"
 156 build has all sorts of additional assertions and checks enabled,
 157 which slows the VM down, but since this is just for experiments it
 158 doesn't matter.
 159
 160 </p></p>
 161 All of the above applies to x86 Linux.  Anything else will likely
 162 require a porting effort.  If libffi supports your system, the amount of
 163 work required should be minor.
 164
 165 </p></p>
 166 <address>Copyright &copy; 2009 The Android Open Source Project</address>
 167
 168 </body>
 169 </html>