Will now look pretty when converted to .md

This commit is contained in:
terekcampbell 2013-01-04 16:09:54 -07:00
parent ccbe01c16a
commit dfbc34c3a4

View File

@ -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:
http://oss.readytalk.com/avian
project [web site](http://oss.readytalk.com/avian).
If you have any trouble building, running, or embedding Avian, please
post a message to our discussion group:
http://groups.google.com/group/avian
post a message to our [discussion group](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)
Windows (i386 and x86_64)
Mac OS X (i386, x86_64 and 32-bit PowerPC)
Apple iOS (i386 and ARM)
* Linux (i386, x86_64, ARM, and 32-bit PowerPC)
* Windows (i386 and x86_64)
* Mac OS X (i386, x86_64 and 32-bit PowerPC)
* 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
default: output of $(uname -s | tr [:upper:] [:lower:]),
* `platform` - the target platform
* _default:_ output of $(uname -s | tr [:upper:] [:lower:]),
normalized in some cases (e.g. CYGWIN_NT-5.1 -> windows)
* arch - the target architecture
default: output of $(uname -m), normalized in some cases
* `arch` - the target architecture
* _default:_ output of $(uname -m), normalized in some cases
(e.g. i686 -> i386)
* process - choice between pure interpreter or JIT compiler
default: compile
* `process` - choice between pure interpreter or JIT compiler
* _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
http://www.7-zip.org/sdk.html). Currently, only version 9.20 of
containing a recent LZMA SDK (available [here](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:
# conventional build:
apt-get install openjdk-7-jdk
make openjdk=/usr/lib/jvm/java-7-openjdk test
#### Debian-based Linux:
_Conventional build:_
# stand-alone build:
apt-get install openjdk-7-jdk
apt-get source openjdk-7-jdk
apt-get build-dep openjdk-7-jdk
$ 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 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:
# Prerequisite: build OpenJDK 7 according to
# https://wikis.oracle.com/display/OpenJDK/Mac+OS+X+Port
####Mac OS X:
_Prerequisite:_ Build OpenJDK 7 according to [this site](https://wikis.oracle.com/display/OpenJDK/Mac+OS+X+Port).
# conventional build:
make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image test
_Conventional build:_
# stand-alone build:
make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image \
$ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image test
_Stand-alone build:_
$ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image \
openjdk-src=$(pwd)/../p/jdk7u-dev/jdk/src test
Windows (Cygwin):
# Prerequisite: build OpenJDK 7 according to
# http://weblogs.java.net/blog/simonis/archive/2011/10/28/yaojowbi-yet-another-openjdk-windows-build-instruction
####Windows (Cygwin):
_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).
# conventional build:
make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image test
_Conventional build:_
# stand-alone build:
make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image \
$ make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image test
_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