Will now look pretty when converted to .md

readme.txt

@@ -1,28 +1,26 @@
-Avian - a lightweight Java virtual machine (JVM)
+Avian - A lightweight Java Virtual Machine (JVM)
 ================================================
 
-// Put travis thing here
-
 Quick Start
 -----------
 
-on Linux:
+#### on Linux:
     $ export JAVA_HOME=/usr/local/java # or wherever you have the JDK installed
     $ make
     $ build/linux-i386/avian -cp build/linux-i386/test Hello
 
-on Mac OS X:
+#### on Mac OS X:
     $ export JAVA_HOME=/Library/Java/Home
     $ make
     $ build/darwin-i386/avian -cp build/darwin-i386/test Hello
  
-on Windows (MSYS):
+#### on Windows (MSYS):
     $ git clone git@github.com:ReadyTalk/win32.git ../win32
     $ export JAVA_HOME="C:/Program Files/Java/jdk1.6.0_07"
     $ make
     $ build/windows-i386/avian -cp build/windows-i386/test Hello
 
-on Windows (Cygwin):
+#### on Windows (Cygwin):
     $ git clone git@github.com:ReadyTalk/win32.git ../win32
     $ export JAVA_HOME="/cygdrive/c/Program Files/Java/jdk1.6.0_07"
     $ make
@@ -38,14 +36,10 @@ Introduction
 Avian is a lightweight virtual machine and class library designed to
 provide a useful subset of Java's features, suitable for building
 self-contained applications.  More information is available at the
-project web site:
+project [web site](http://oss.readytalk.com/avian).
-
-  http://oss.readytalk.com/avian
 
 If you have any trouble building, running, or embedding Avian, please
-post a message to our discussion group:
+post a message to our [discussion group](http://groups.google.com/group/avian).
-
-  http://groups.google.com/group/avian
 
 That's also the place for any other questions, comments, or
 suggestions you might have.
@@ -56,10 +50,10 @@ Supported Platforms
 
 Avian can currently target the following platforms:
 
-  Linux (i386, x86_64, ARM, and 32-bit PowerPC)
+  * Linux (i386, x86_64, ARM, and 32-bit PowerPC)
-  Windows (i386 and x86_64)
+  * Windows (i386 and x86_64)
-  Mac OS X (i386, x86_64 and 32-bit PowerPC)
+  * Mac OS X (i386, x86_64 and 32-bit PowerPC)
-  Apple iOS (i386 and ARM)
+  * Apple iOS (i386 and ARM)
 
 
 Building
@@ -95,102 +89,101 @@ certain flags described below, all of which are optional.
         openjdk=<openjdk installation directory> \
         openjdk-src=<openjdk source directory>
 
-  * platform - the target platform
+  * `platform` - the target platform  
-      default: output of $(uname -s | tr [:upper:] [:lower:]),
+    * _default:_ output of $(uname -s | tr [:upper:] [:lower:]),
 normalized in some cases (e.g. CYGWIN_NT-5.1 -> windows)  
 
-  * arch - the target architecture
+  * `arch` - the target architecture  
-      default: output of $(uname -m), normalized in some cases
+    * _default:_ output of $(uname -m), normalized in some cases
 (e.g. i686 -> i386)
 
-  * process - choice between pure interpreter or JIT compiler
+  * `process` - choice between pure interpreter or JIT compiler  
-      default: compile
+    * _default:_ compile
 
-  * mode - which set of compilation flags to use to determine
+  * `mode` - which set of compilation flags to use to determine
 optimization level, debug symbols, and whether to enable
 assertions  
-      default: fast
+    * _default:_ fast
 
-  * lzma - if set, support use of LZMA to compress embedded JARs and
+  * `lzma` - if set, support use of LZMA to compress embedded JARs and
 boot images.  The value of this option should be a directory
-    containing a recent LZMA SDK (available at
+containing a recent LZMA SDK (available [here](http://www.7-zip.org/sdk.html)).  Currently, only version 9.20 of
-    http://www.7-zip.org/sdk.html).  Currently, only version 9.20 of
 the SDK has been tested, but other versions might work.  
-      default: not set
+    * _default:_ not set
 
-  * ios - if true, cross-compile for iOS on OS X.  Note that
+  * `ios` - if true, cross-compile for iOS on OS X.  Note that
 non-jailbroken iOS devices do not allow JIT compilation, so only
 process=interpret or bootimage=true builds will run on such
-    devices.  See https://github.com/ReadyTalk/hello-ios for an
+devices.  See [here](https://github.com/ReadyTalk/hello-ios) for an
 example of an Xcode project for iOS which uses Avian.  
-      default: false
+    * _default:_ false
 
-  * bootimage - if true, create a boot image containing the pre-parsed
+  * `bootimage` - if true, create a boot image containing the pre-parsed
 class library and ahead-of-time compiled methods.  This option is
 only valid for process=compile builds.  Note that you may need to
 specify both build-arch=x86_64 and arch=x86_64 on 64-bit systems
 where "uname -m" prints "i386".  
-      default: false
+    * _default:_ false
 
-  * heapdump - if true, implement avian.Machine.dumpHeap(String),
+  * `heapdump` - if true, implement avian.Machine.dumpHeap(String),
 which, when called, will generate a snapshot of the heap in a
 simple, ad-hoc format for memory profiling purposes.  See
 heapdump.cpp for details.  
-      default: false
+    * _default:_ false
 
-  * tails - if true, optimize each tail call by replacing the caller's
+  * `tails` - if true, optimize each tail call by replacing the caller's
 stack frame with the callee's.  This convention ensures proper
 tail recursion, suitable for languages such as Scheme.  This
 option is only valid for process=compile builds.  
-      default: false
+    * _default:_ false
 
-  * continuations - if true, support continuations via the
+  * `continuations` - if true, support continuations via the
 avian.Continuations methods callWithCurrentContinuation and
 dynamicWind.  See Continuations.java for details.  This option is
 only valid for process=compile builds.  
-      default: false
+    * _default:_ false
 
-  * use-clang - if true, use LLVM's clang instead of GCC to build.
+  * `use-clang` - if true, use LLVM's clang instead of GCC to build.
 Note that this does not currently affect cross compiles, only
 native builds.  
-      default: false
+    * _default:_ false
 
-  * openjdk - if set, use OpenJDK class library instead of the default
+  * `openjdk` - if set, use OpenJDK class library instead of the default
 Avian class library.  See "Building with the OpenJDK Class
 Library" below for details.  
-      default: not set
+    * _default:_ not set
 
-  * openjdk-src - if this and the openjdk option above are both set,
+  * `openjdk-src` - if this and the openjdk option above are both set,
 build an embeddable VM using the OpenJDK class library.  The JNI
 components of the OpenJDK class library will be built from the
 sources found under the specified directory.  See "Building with
 the OpenJDK Class Library" below for details.  
-      default: not set
+    * _default:_ not set
 
 These flags determine the name of the directory used for the build.
-The name always starts with ${platform}-${arch}, and each non-default
+The name always starts with _${platform}-${arch}_, and each non-default
 build option is appended to the name.  For example, a debug build with
 bootimage enabled on Linux/i386 would be built in
-build/linux-i386-debug-bootimage.  This allows you to build with
+_build/linux-i386-debug-bootimage_.  This allows you to build with
 several different sets of options independently and even
 simultaneously without doing a clean build each time.
 
 If you are compiling for Windows, you may either cross-compile using
 MinGW or build natively on Windows under MSYS or Cygwin.
 
-Installing MSYS:
+#### Installing MSYS:
 
-  1. Download and install the current MinGW and MSYS packages from
+  __1.__ Download and install the current MinGW and MSYS packages from
   mingw.org, selecting the C and C++ compilers when prompted.  Use the
   post-install script to create the filesystem link to the compiler.
 
-  2. Download GNU Make 3.81 from the MSYS download page
+  __2.__ Download GNU Make 3.81 from the MSYS download page
   (make-3.81-MSYS-1.0.11-2.tar.bz2) and extract the tar file into
-  e.g. c:/msys/1.0.
+  _e.g. c:/msys/1.0_.
 
-Installing Cygwin:
+#### Installing Cygwin:
 
-  1. Download and run setup.exe from cygwin.com, installing the base
+  __1.__ Download and run setup.exe from [cygwin's website](http://www.cygwin.com), installing the base
   system and these packages: make, gcc-mingw-g++,
   mingw64-i686-gcc-g++, mingw64-x86_64-gcc-g++, and (optionally) git.
 
@@ -222,13 +215,9 @@ To build with MSVC, install Cygwin as described above and set the
 following environment variables:
 
     $ export PATH="/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/IDE:/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/BIN:/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/Tools:/cygdrive/c/WINDOWS/Microsoft.NET/Framework/v3.5:/cygdrive/c/WINDOWS/Microsoft.NET/Framework/v2.0.50727:/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/VCPackages:/cygdrive/c/Program Files/Microsoft SDKs/Windows/v6.0A/bin:/cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS:/cygdrive/c/WINDOWS/System32/Wbem"
-
     $ export LIBPATH="C:\WINDOWS\Microsoft.NET\Framework\v3.5;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB;"
-
     $ export VCINSTALLDIR="C:\Program Files\Microsoft Visual Studio 9.0\VC"
-
     $ export LIB="C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB;C:\Program Files\Microsoft SDKs\Windows\v6.0A\lib;"
-
     $ export INCLUDE="C:\Program Files\Microsoft Visual Studio 9.0\VC\INCLUDE;C:\Program Files\Microsoft SDKs\Windows\v6.0A\include;"
 
 Adjust these definitions as necessary according to your MSVC
@@ -238,7 +227,6 @@ Finally, build with the msvc flag set to the MSVC tool directory:
 
     $ make msvc="/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC"
 
-
 Building with the OpenJDK Class Library
 ---------------------------------------
 
@@ -253,7 +241,7 @@ where OpenJDK is installed, e.g.:
 
 This will build Avian as a conventional JVM (e.g. libjvm.so) which
 loads its boot class library and native libraries (e.g. libjava.so)
-from /usr/lib/jvm/java-7-openjdk/jre at runtime.  To run an
+from _/usr/lib/jvm/java-7-openjdk/jre_ at runtime.  To run an
 application in this configuration, you'll need to make sure the VM is
 in your library search path.  For example:
 
@@ -292,46 +280,50 @@ and the supplied openjdk.pro configuration file (see "Embedding with
 ProGuard and a Boot Image" below).  Note that you'll still need to use
 vm.pro in that case -- openjdk.pro just adds additional constraints
 specific to the OpenJDK port.  Also see app.mk in
-git://oss.readytalk.com/avian-swt-examples.git for an example of using
+_git://oss.readytalk.com/avian-swt-examples.git_ for an example of using
 Avian, OpenJDK, ProGuard, and UPX in concert.
 
 Here are some examples of how to install OpenJDK and build Avian with
 it on various OSes:
 
-  Debian-based Linux:
+#### Debian-based Linux:
-    # conventional build:
+_Conventional build:_
-    apt-get install openjdk-7-jdk
-    make openjdk=/usr/lib/jvm/java-7-openjdk test
 
-    # stand-alone build:
+    $ apt-get install openjdk-7-jdk
-    apt-get install openjdk-7-jdk
+    $ make openjdk=/usr/lib/jvm/java-7-openjdk test
-    apt-get source openjdk-7-jdk
+
-    apt-get build-dep openjdk-7-jdk
+_Stand-alone build:_
+
+    $ apt-get install openjdk-7-jdk
+    $ apt-get source openjdk-7-jdk
+    $ apt-get build-dep openjdk-7-jdk
     (cd openjdk-7-7~b147-2.0 && dpkg-buildpackage)
-    make openjdk=/usr/lib/jvm/java-7-openjdk \
+    $ make openjdk=/usr/lib/jvm/java-7-openjdk \
         openjdk-src=$(pwd)/openjdk-7-7~b147-2.0/build/openjdk/jdk/src \
         test
 
-  Mac OS X:
+####Mac OS X:
-    # Prerequisite: build OpenJDK 7 according to
+_Prerequisite:_ Build OpenJDK 7 according to [this site](https://wikis.oracle.com/display/OpenJDK/Mac+OS+X+Port).
-    # https://wikis.oracle.com/display/OpenJDK/Mac+OS+X+Port
 
-    # conventional build:
+_Conventional build:_
-    make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image test
 
-    # stand-alone build:
+    $ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image test
-    make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image \
+
+_Stand-alone build:_
+
+    $ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image \
         openjdk-src=$(pwd)/../p/jdk7u-dev/jdk/src test
 
-  Windows (Cygwin):
+####Windows (Cygwin):
-    # Prerequisite: build OpenJDK 7 according to
+_Prerequisite:_ Build OpenJDK 7 according to [this site](http://weblogs.java.net/blog/simonis/archive/2011/10/28/yaojowbi-yet-another-openjdk-windows-build-instruction).
-    # http://weblogs.java.net/blog/simonis/archive/2011/10/28/yaojowbi-yet-another-openjdk-windows-build-instruction
 
-    # conventional build:
+_Conventional build:_
-    make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image test
 
-    # stand-alone build:
+    $ make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image test
-    make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image \
+
+_Stand-alone build:_
+
+    $ make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image \
         openjdk-src=$(pwd)/../p/jdk7u-dev/jdk/src test
 
 Currently, only OpenJDK 7 is supported.  Later versions might work,
@@ -357,7 +349,7 @@ Note: if you are building on Cygwin, prepend "x86_64-w64-mingw32-" or
 "i686-w64-mingw32-" to the ar, g++, gcc, strip, and dlltool commands
 below (e.g. x86_64-w64-mingw32-gcc).
 
-Step 1: Build Avian, create a new directory, and populate it with the
+__1.__ Build Avian, create a new directory, and populate it with the
 VM object files and bootstrap classpath jar.
 
     $ make
@@ -366,7 +358,7 @@ VM object files and bootstrap classpath jar.
     $ ar x ../build/${platform}-${arch}/libavian.a
     $ cp ../build/${platform}-${arch}/classpath.jar boot.jar
 
-Step 2: Build the Java code and add it to the jar.
+__2.__ Build the Java code and add it to the jar.
 
     $ cat >Hello.java <<EOF
     public class Hello {
@@ -378,15 +370,15 @@ EOF
      $ javac -bootclasspath boot.jar Hello.java
      $ jar u0f boot.jar Hello.class
 
-Step 3: Make an object file out of the jar.
+__3.__ Make an object file out of the jar.
 
     $ ../build/${platform}-${arch}/binaryToObject/binaryToObject boot.jar \
          boot-jar.o _binary_boot_jar_start _binary_boot_jar_end ${platform} ${arch}
 
-If you've built Avian using the lzma option, you may optionally
+If you've built Avian using the `lzma` option, you may optionally
 compress the jar before generating the object:
 
- $ ../build/$(platform}-${arch}-lzma/lzma/lzma encode boot.jar boot.jar.lzma
+      ../build/$(platform}-${arch}-lzma/lzma/lzma encode boot.jar boot.jar.lzma
          && ../build/${platform}-${arch}-lzma/binaryToObject/binaryToObject \
            boot.jar.lzma boot-jar.o _binary_boot_jar_start _binary_boot_jar_end \
            ${platform} ${arch}
@@ -395,7 +387,7 @@ Note that you'll need to specify "-Xbootclasspath:[lzma:bootJar]"
 instead of "-Xbootclasspath:[bootJar]" in the next step if you've used
 LZMA to compress the jar.
 
-Step 4: Write a driver which starts the VM and runs the desired main
+__4.__ Write a driver which starts the VM and runs the desired main
 method.  Note the bootJar 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 boot classpath to "[bootJar]".
@@ -479,37 +471,42 @@ main(int ac, const char** av)
     }
     EOF
 
-on Linux:
+__on Linux:__
+
      $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/linux \
          -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp -o main.o
 
-on Mac OS X:
+__on Mac OS X:__
+
      $ g++ -I$JAVA_HOME/include -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp \
          -o main.o
 
-on Windows:
+__on Windows:__
+
      $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/win32 \
          -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp -o main.o
 
-Step 5: Link the objects produced above to produce the final
+__5.__ Link the objects produced above to produce the final
 executable, and optionally strip its symbols.
 
-on Linux:
+__on Linux:__
+
     $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello
     $ strip --strip-all hello
 
-on Mac OS X:
+__on Mac OS X:__
+
     $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello -framework CoreFoundation
     $ strip -S -x hello
 
-on Windows:
+__on Windows:__
+
     $ dlltool -z hello.def *.o
     $ dlltool -d hello.def -e hello.exp
     $ g++ hello.exp *.o -L../../win32/lib -lmingwthrd -lm -lz -lws2_32 \
         -mwindows -mconsole -o hello.exe
     $ strip --strip-all hello.exe
 
-
 Embedding with ProGuard and a Boot Image
 ----------------------------------------
 
@@ -547,7 +544,7 @@ as desired.
 The following instructions assume we are building for Linux/i386.
 Please refer to the previous example for guidance on other platforms.
 
-Step 1: Build Avian, create a new directory, and populate it with the
+__1.__ Build Avian, create a new directory, and populate it with the
 VM object files.
 
     $ make bootimage=true
@@ -555,13 +552,13 @@ VM object files.
     $ cd hello
     $ ar x ../build/linux-i386-bootimage/libavian.a
 
-Step 2: Create a stage1 directory and extract the contents of the
+__2.__ Create a stage1 directory and extract the contents of the
 class library jar into it.
 
     $ mkdir stage1
     $ (cd stage1 && jar xf ../../build/linux-i386-bootimage/classpath.jar)
 
-Step 3: Build the Java code and add it to stage1.
+__3.__ Build the Java code and add it to stage1.
 
      $ cat >Hello.java <<EOF
     public class Hello {
@@ -572,7 +569,7 @@ public class Hello {
     EOF
      $ javac -bootclasspath stage1 -d stage1 Hello.java
 
-Step 4: Create a ProGuard configuration file specifying Hello.main as
+__4.__ Create a ProGuard configuration file specifying Hello.main as
 the entry point.
 
      $ cat >hello.pro <<EOF
@@ -581,7 +578,7 @@ the entry point.
      }
     EOF
 
-Step 5: Run ProGuard with stage1 as input and stage2 as output.
+__5.__ Run ProGuard with stage1 as input and stage2 as output.
 
      $ java -jar ../../proguard4.6/lib/proguard.jar \
          -dontusemixedcaseclassnames -injars stage1 -outjars stage2 \
@@ -597,7 +594,7 @@ runtime, you'll need to add them to stage1 before running ProGuard.
 Finally, you'll need to add @../openjdk.pro to the above command when
 using the OpenJDK library.)
 
-Step 6: Build the boot and code images.
+__6.__ Build the boot and code images.
 
      $ ../build/linux-i386-bootimage/bootimage-generator
         -cp stage2 \
@@ -610,7 +607,7 @@ symbols in the boot/code image by also passing:
     -bootimage-symbols my_bootimage_start:my_bootimage_end \
     -codeimage-symbols my_codeimage_start:my_codeimage_end
 
-Step 7: Write a driver which starts the VM and runs the desired main
+__7.__ Write a driver which starts the VM and runs the desired main
 method.  Note the bootimageBin function, which will be called by the
 VM to get a handle to the embedded boot image.  We tell the VM about
 this function via the "avian.bootimage" property.
@@ -717,7 +714,7 @@ EOF
      $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/linux \
          -D_JNI_IMPLEMENTATION_ -c bootimage-main.cpp -o main.o
 
-Step 8: Link the objects produced above to produce the final
+__8.__ Link the objects produced above to produce the final
  executable, and optionally strip its symbols.
 
     $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello