flesh out readme.txt, including instructions for embedding a custom application

readme.txt

@@ -22,15 +22,25 @@ but patches to enable them are welcome.
 Building
 --------
 
+The build is directed by a single makefile and may be influenced via
+certain flags described below.
+
  $ make platform={linux,windows,darwin} arch={i386,x86_64} \
-     process={compile,interpret} mode={debug,fast}
+     process={compile,interpret} mode={debug,debug-fast,fast}
 
-The default values of the build flags are as follows:
+  * platform - the target platform
+      default: output of $(uname -s | tr [:upper:] [:lower:])
 
-  platform=$(uname -s | tr [:upper:] [:lower:])
-  arch=$(uname -m)
-  mode=fast
-  process=compile
+  * arch - the target architecture
+      default: output of $(uname -m)
+
+  * mode - which set of compilation flags to use, which determine
+    optimization level, debug symbols, and whether to enable
+    assertions.
+      default: fast
+
+  * process - choice between pure interpreter or JIT compiler
+      default: compile
 
 
 Installing
@@ -38,3 +48,151 @@ Installing
 
  $ cp build/${platform}-${arch}-${process}-${mode}/avian ~/bin/
  $ cp build/${platform}-${arch}-${process}-${mode}/libavian.a ~/lib/
+
+
+Embedding
+---------
+
+The following series of commands illustrates how to produce a
+stand-alone executable out of a Java application using Avian.
+
+Step 1: Build the Java code and jar it up.
+
+ $ cat >Hello.java <<EOF
+public class Hello {
+  public static void main(String[] args) {
+    System.out.println("hello, world!");
+  }
+}
+EOF
+ $ javac Hello.java
+ $ jar c0f hello.jar Hello.class
+
+
+Step 2: Make an object file out of the jar.
+
+For linux-i386:
+
+ $ objcopy -I binary hello.jar -O elf32-i386 -B i386 hello-jar.o
+
+For linux-x86_64:
+
+ $ objcopy -I binary hello.jar -O elf64-x86-64 -B i386:x86-64 hello-jar.o
+
+For windows-i386:
+
+ $ objcopy -I binary hello.jar -O pe-i386 -B i386 hello-jar.o
+
+For darwin-i386 (objcopy is not currently supported on this platform,
+so we use the binaryToMacho utility instead):
+
+ $ build/darwin-i386-compile-fast/binaryToMacho hello.jar \
+     __binary_hello_jar_start __hello_classpath_jar_size > hello-jar.o
+
+
+Step 3: Write a driver which starts the VM and runs the desired main
+method.  Note the helloJar function, which will be called by the VM to
+get a handle to the embedded jar.  We tell the VM about this jar by
+setting the classpath to "[helloJar]".
+
+ $ cat >main.cpp <<EOF
+#include "stdint.h"
+#include "jni.h"
+
+#ifdef __MINGW32__
+#  define EXPORT __declspec(dllexport)
+#  define SYMBOL(x) binary_hello_jar_##x
+#else
+#  define EXPORT __attribute__ ((visibility("default")))
+#  define SYMBOL(x) _binary_hello_jar_##x
+#endif
+
+extern "C" {
+
+  extern const uint8_t SYMBOL(start)[];
+  extern const uint8_t SYMBOL(size)[];
+
+  EXPORT const uint8_t*
+  helloJar(unsigned* size)
+  {
+    *size = reinterpret_cast<uintptr_t>(SYMBOL(size));
+    return SYMBOL(start);
+  }
+
+} // extern "C"
+
+#ifdef JNI_VERSION_1_6
+typedef struct JDK1_1InitArgs {
+    jint version;
+
+    char **properties;
+    jint checkSource;
+    jint nativeStackSize;
+    jint javaStackSize;
+    jint minHeapSize;
+    jint maxHeapSize;
+    jint verifyMode;
+    char *classpath;
+
+    jint (JNICALL *vfprintf)(FILE *fp, const char *format, va_list args);
+    void (JNICALL *exit)(jint code);
+    void (JNICALL *abort)(void);
+
+    jint enableClassGC;
+    jint enableVerboseGC;
+    jint disableAsyncGC;
+    jint verbose;
+    jboolean debugging;
+    jint debugPort;
+} JDK1_1InitArgs;
+#endif
+
+int
+main(int ac, const char** av)
+{
+  JDK1_1InitArgs vmArgs;
+  vmArgs.version = 0x00010001;
+  JNI_GetDefaultJavaVMInitArgs(&vmArgs);
+
+  vmArgs.classpath = const_cast<char*>("[helloJar]");
+
+  JavaVM* vm;
+  void* env;
+  JNI_CreateJavaVM(&vm, &env, &vmArgs);
+  JNIEnv* e = static_cast<JNIEnv*>(env);
+
+  jclass c = e->FindClass(MAIN_CLASS);
+  if (not e->ExceptionOccurred()) {
+    jmethodID m = e->GetStaticMethodID(c, "main", "([Ljava/lang/String;)V");
+    if (not e->ExceptionOccurred()) {
+      jclass stringClass = e->FindClass("java/lang/String");
+      if (not e->ExceptionOccurred()) {
+        jobjectArray a = e->NewObjectArray(ac-1, stringClass, 0);
+        if (not e->ExceptionOccurred()) {
+          for (int i = 1; i < ac; ++i) {
+            e->SetObjectArrayElement(a, i-1, e->NewStringUTF(av[i]));
+          }
+          
+          e->CallStaticVoidMethod(c, m, a);
+        }
+      }
+    }
+  }
+
+  int exitCode = 0;
+  if (e->ExceptionOccurred()) {
+    exitCode = -1;
+    e->ExceptionDescribe();
+  }
+
+  vm->DestroyJavaVM();
+
+  return exitCode;
+}
+EOF
+ $ g++ -c main.cpp -o main.o
+
+
+Step 4: Link the above with libavian.a to produce the final executable.
+
+ $ g++ hello-jar.o main.o -lavian -o hello