Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 765 lines (571 sloc) 27.441 kb
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
1 Avian - A lightweight Java Virtual Machine (JVM)
2 ================================================
3
d53920a Edit README.md to work with ReadyTalk's Travis CI
Terek Campbell authored
4 [![Build Status](https://travis-ci.org/ReadyTalk/avian.png?branch=master)](https://travis-ci.org/ReadyTalk/avian)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
5
6 Quick Start
7 -----------
8
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
9 These are examples of building Avian on various operating systems for
10 the x86_64 architecture. You may need to modify JAVA_HOME according
11 to where the JDK is installed on your system. In all cases, be sure
12 to use forward slashes in the path.
13
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
14 #### on Linux:
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
15 $ export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
16 $ make
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
17 $ build/linux-x86_64/avian -cp build/linux-x86_64/test Hello
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
18
19 #### on Mac OS X:
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
20 $ export JAVA_HOME=$(/usr/libexec/java_home)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
21 $ make
23f4e4c @joshuawarner32 update README.md with darwin->{macosx,ios} rename
joshuawarner32 authored
22 $ build/macosx-x86_64/avian -cp build/macosx-x86_64/test Hello
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
23
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
24 #### on Windows (MSYS):
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
25 $ git clone git@github.com:ReadyTalk/win64.git ../win64
26 $ export JAVA_HOME="C:/Program Files/Java/jdk1.7.0_45"
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
27 $ make
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
28 $ build/windows-x86_64/avian -cp build/windows-x86_64/test Hello
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
29
30 #### on Windows (Cygwin):
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
31 $ git clone git@github.com:ReadyTalk/win64.git ../win64
32 $ export JAVA_HOME="/cygdrive/c/Program Files/Java/jdk1.7.0_45"
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
33 $ make
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
34 $ build/windows-x86_64/avian -cp build/windows-x86_64/test Hello
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
35
ce9d7c3 @dicej mention FreeBSD support in README.md
dicej authored
36 #### on FreeBSD:
076cdc7 @dicej update "Quick Start" examples in README.md
dicej authored
37 $ export JAVA_HOME=/usr/local/openjdk7
ce9d7c3 @dicej mention FreeBSD support in README.md
dicej authored
38 $ gmake
39 $ build/freebsd-x86_64/avian -cp build/freebsd-x86_64/test Hello
40
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
41
42 Introduction
43 ------------
44
45 Avian is a lightweight virtual machine and class library designed to
46 provide a useful subset of Java's features, suitable for building
47 self-contained applications. More information is available at the
48 project [web site](http://oss.readytalk.com/avian).
49
50 If you have any trouble building, running, or embedding Avian, please
51 post a message to our [discussion group](http://groups.google.com/group/avian).
52
53 That's also the place for any other questions, comments, or
54 suggestions you might have.
55
56
57 Supported Platforms
58 -------------------
59
60 Avian can currently target the following platforms:
61
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
62 * Linux (i386, x86_64, ARM, and ARM64)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
63 * Windows (i386 and x86_64)
c5d2cb0 @dicej tweaks to prepare for 0.7 release
dicej authored
64 * Mac OS X (i386 and x86_64)
575f595 @dicej add support for iOS/x86_64
dicej authored
65 * Apple iOS (i386, x86_64, ARM, and ARM64)
ce9d7c3 @dicej mention FreeBSD support in README.md
dicej authored
66 * FreeBSD (i386, x86_64)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
67
68
69 Building
70 --------
71
72 Build requirements include:
73
74 * GNU make 3.80 or later
9981569 @joshuawarner32 update README with new build requirements (gcc 4.6, MSVC 11)
joshuawarner32 authored
75 * GCC 4.6 or later
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
76 or LLVM Clang 3.1 or later (see use-clang option below)
9981569 @joshuawarner32 update README with new build requirements (gcc 4.6, MSVC 11)
joshuawarner32 authored
77 * JDK 1.6 or later
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
78 * MinGW 3.4 or later (only if compiling for Windows)
79 * zlib 1.2.3 or later
80
81 Earlier versions of some of these packages may also work but have not
82 been tested.
83
84 The build is directed by a single makefile and may be influenced via
85 certain flags described below, all of which are optional.
86
87 $ make \
23f4e4c @joshuawarner32 update README.md with darwin->{macosx,ios} rename
joshuawarner32 authored
88 platform={linux,windows,macosx,ios,freebsd} \
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
89 arch={i386,x86_64,arm,arm64} \
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
90 process={compile,interpret} \
91 mode={debug,debug-fast,fast,small} \
92 lzma=<lzma source directory> \
93 bootimage={true,false} \
94 tails={true,false} \
95 continuations={true,false} \
96 use-clang={true,false} \
97 openjdk=<openjdk installation directory> \
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
98 openjdk-src=<openjdk source directory> \
99 android=<android source directory>
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
100
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
101 * `platform` - the target platform
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
102 * _default:_ output of $(uname -s | tr [:upper:] [:lower:]),
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
103 normalized in some cases (e.g. CYGWIN_NT-5.1 -> windows)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
104
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
105 * `arch` - the target architecture
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
106 * _default:_ output of $(uname -m), normalized in some cases
107 (e.g. i686 -> i386)
108
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
109 * `process` - choice between pure interpreter or JIT compiler
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
110 * _default:_ compile
111
112 * `mode` - which set of compilation flags to use to determine
113 optimization level, debug symbols, and whether to enable
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
114 assertions
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
115 * _default:_ fast
116
117 * `lzma` - if set, support use of LZMA to compress embedded JARs and
118 boot images. The value of this option should be a directory
119 containing a recent LZMA SDK (available [here](http://www.7-zip.org/sdk.html)). Currently, only version 9.20 of
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
120 the SDK has been tested, but other versions might work.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
121 * _default:_ not set
122
2b11770 @dicej use armv7 memory barriers by default
dicej authored
123 * `armv6` - if true, don't use any instructions newer than armv6. By
124 default, we assume the target is armv7 or later, and thus requires explicit
125 memory barrier instructions to ensure cache coherency
126
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
127 * `bootimage` - if true, create a boot image containing the pre-parsed
128 class library and ahead-of-time compiled methods. This option is
129 only valid for process=compile builds. Note that you may need to
130 specify both build-arch=x86_64 and arch=x86_64 on 64-bit systems
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
131 where "uname -m" prints "i386".
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
132 * _default:_ false
133
134 * `tails` - if true, optimize each tail call by replacing the caller's
135 stack frame with the callee's. This convention ensures proper
136 tail recursion, suitable for languages such as Scheme. This
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
137 option is only valid for process=compile builds.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
138 * _default:_ false
139
140 * `continuations` - if true, support continuations via the
141 avian.Continuations methods callWithCurrentContinuation and
142 dynamicWind. See Continuations.java for details. This option is
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
143 only valid for process=compile builds.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
144 * _default:_ false
145
146 * `use-clang` - if true, use LLVM's clang instead of GCC to build.
147 Note that this does not currently affect cross compiles, only
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
148 native builds.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
149 * _default:_ false
150
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
151 * `openjdk` - if set, use the OpenJDK class library instead of the
152 default Avian class library. See "Building with the OpenJDK Class
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
153 Library" below for details.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
154 * _default:_ not set
155
156 * `openjdk-src` - if this and the openjdk option above are both set,
157 build an embeddable VM using the OpenJDK class library. The JNI
158 components of the OpenJDK class library will be built from the
159 sources found under the specified directory. See "Building with
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
160 the OpenJDK Class Library" below for details.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
161 * _default:_ not set
162
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
163 * `android` - if set, use the Android class library instead of the
164 default Avian class library. See "Building with the Android Class
165 Library" below for details.
166 * _default:_ not set
167
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
168 These flags determine the name of the directory used for the build.
169 The name always starts with _${platform}-${arch}_, and each non-default
170 build option is appended to the name. For example, a debug build with
171 bootimage enabled on Linux/i386 would be built in
172 _build/linux-i386-debug-bootimage_. This allows you to build with
173 several different sets of options independently and even
174 simultaneously without doing a clean build each time.
175
23f4e4c @joshuawarner32 update README.md with darwin->{macosx,ios} rename
joshuawarner32 authored
176 Note that not all combinations of these flags are valid. For instance,
177 non-jailbroken iOS devices do not allow JIT compilation, so only
178 process=interpret or bootimage=true builds will run on such
179 devices. See [here](https://github.com/ReadyTalk/hello-ios) for an
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
180 example of an Xcode project for iOS which uses Avian.
23f4e4c @joshuawarner32 update README.md with darwin->{macosx,ios} rename
joshuawarner32 authored
181
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
182 If you are compiling for Windows, you may either cross-compile using
183 MinGW or build natively on Windows under MSYS or Cygwin.
184
185 #### Installing MSYS:
186
187 __1.__ Download and install the current MinGW and MSYS packages from
188 mingw.org, selecting the C and C++ compilers when prompted. Use the
189 post-install script to create the filesystem link to the compiler.
190
191 __2.__ Download GNU Make 3.81 from the MSYS download page
192 (make-3.81-MSYS-1.0.11-2.tar.bz2) and extract the tar file into
193 _e.g. c:/msys/1.0_.
194
195 #### Installing Cygwin:
196
197 __1.__ Download and run setup.exe from [cygwin's website](http://www.cygwin.com), installing the base
198 system and these packages: make, gcc-mingw-g++,
199 mingw64-i686-gcc-g++, mingw64-x86_64-gcc-g++, and (optionally) git.
200
201 You may also find our win32 repository useful: (run this from the
202 directory containing the avian directory)
203
204 $ git clone git@github.com:ReadyTalk/win32.git
205
206 This gives you the Windows JNI headers, zlib headers and library, and
207 a few other useful libraries like OpenSSL, libjpeg, and libpng.
208 There's also a win64 repository for 64-bit builds:
209
210 $ git clone git@github.com:ReadyTalk/win64.git
211
212
213 Building with the Microsoft Visual C++ Compiler
214 -----------------------------------------------
215
216 You can also build using the MSVC compiler, which makes debugging with
217 tools like WinDbg and Visual Studio much easier. Note that you will
218 still need to have GCC installed - MSVC is only used to compile the
219 C++ portions of the VM, while the assembly code and helper tools are
220 built using GCC.
221
9981569 @joshuawarner32 update README with new build requirements (gcc 4.6, MSVC 11)
joshuawarner32 authored
222 *Note that the MSVC build isn't tested regularly, so is fairly likely to be broken.*
223
224 Avian targets MSVC 11 and above (it uses c++ features not available in older versions).
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
225
226 To build with MSVC, install Cygwin as described above and set the
227 following environment variables:
228
9981569 @joshuawarner32 update README with new build requirements (gcc 4.6, MSVC 11)
joshuawarner32 authored
229 $ export PATH="/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/cygdrive/c/Program Files/Microsoft Visual Studio 11.0/Common7/IDE:/cygdrive/c/Program Files/Microsoft Visual Studio 11.0/VC/BIN:/cygdrive/c/Program Files/Microsoft Visual Studio 11.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 11.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"
230 $ export LIBPATH="C:\WINDOWS\Microsoft.NET\Framework\v3.5;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 11.0\VC\LIB;"
231 $ export VCINSTALLDIR="C:\Program Files\Microsoft Visual Studio 11.0\VC"
232 $ export LIB="C:\Program Files\Microsoft Visual Studio 11.0\VC\LIB;C:\Program Files\Microsoft SDKs\Windows\v6.0A\lib;"
233 $ export INCLUDE="C:\Program Files\Microsoft Visual Studio 11.0\VC\INCLUDE;C:\Program Files\Microsoft SDKs\Windows\v6.0A\include;"
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
234
235 Adjust these definitions as necessary according to your MSVC
236 installation.
237
238 Finally, build with the msvc flag set to the MSVC tool directory:
239
9981569 @joshuawarner32 update README with new build requirements (gcc 4.6, MSVC 11)
joshuawarner32 authored
240 $ make msvc="/cygdrive/c/Program Files/Microsoft Visual Studio 11.0/VC"
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
241
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
242
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
243 Building with the OpenJDK Class Library
244 ---------------------------------------
245
246 By default, Avian uses its own lightweight class library. However,
247 that library only contains a relatively small subset of the classes
248 and methods included in the JRE. If your application requires
249 features beyond that subset, you may want to tell Avian to use
250 OpenJDK's class library instead. To do so, specify the directory
251 where OpenJDK is installed, e.g.:
252
253 $ make openjdk=/usr/lib/jvm/java-7-openjdk
254
255 This will build Avian as a conventional JVM (e.g. libjvm.so) which
256 loads its boot class library and native libraries (e.g. libjava.so)
4568ece @dicej add note about using an absolute path for the openjdk option
dicej authored
257 from _/usr/lib/jvm/java-7-openjdk/jre_ at runtime. Note that you must
258 use an absolute path here, or else the result will not work when run
259 from other directories. In this configuration, OpenJDK needs to
260 remain installed for Avian to work, and you can run applications like
261 this:
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
262
3812d01 @DamjanJovanovic update documentation to indicate that LD_LIBRARY_PATH is not (always)…
DamjanJovanovic authored
263 $ build/linux-x86_64-openjdk/avian-dynamic -cp /path/to/my/application \
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
264 com.example.MyApplication
265
266 Alternatively, you can enable a stand-alone build using OpenJDK by
267 specifying the location of the OpenJDK source code, e.g.:
268
269 $ make openjdk=$(pwd)/../jdk7/build/linux-amd64/j2sdk-image \
270 openjdk-src=$(pwd)/../jdk7/jdk/src
271
272 You must ensure that the path specified for openjdk-src does not have
273 any spaces in it; make gets confused when dependency paths include
274 spaces, and we haven't found away around that except to avoid paths
275 with spaces entirely.
276
277 The result of such a build is a self-contained binary which does not
278 depend on external libraries, jars, or other files. In this case, the
279 specified paths are used only at build time; anything needed at
280 runtime is embedded in the binary. Thus, the process of running an
281 application is simplified:
282
283 $ build/linux-x86_64-openjdk-src/avian -cp /path/to/my/application \
284 com.example.MyApplication
285
286 Note that the resulting binary will be very large due to the size of
287 OpenJDK's class library. This can be mitigated using UPX, preferably
288 an LZMA-enabled version:
289
290 $ upx --lzma --best build/linux-x86_64-openjdk-src/avian
291
292 You can reduce the size futher for embedded builds by using ProGuard
293 and the supplied openjdk.pro configuration file (see "Embedding with
294 ProGuard and a Boot Image" below). Note that you'll still need to use
295 vm.pro in that case -- openjdk.pro just adds additional constraints
296 specific to the OpenJDK port. Also see app.mk in
297 _git://oss.readytalk.com/avian-swt-examples.git_ for an example of using
298 Avian, OpenJDK, ProGuard, and UPX in concert.
299
300 Here are some examples of how to install OpenJDK and build Avian with
301 it on various OSes:
302
303 #### Debian-based Linux:
304 _Conventional build:_
305
306 $ apt-get install openjdk-7-jdk
307 $ make openjdk=/usr/lib/jvm/java-7-openjdk test
308
309 _Stand-alone build:_
310
311 $ apt-get install openjdk-7-jdk
312 $ apt-get source openjdk-7-jdk
313 $ apt-get build-dep openjdk-7-jdk
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
314 $ (cd openjdk-7-7~b147-2.0 && dpkg-buildpackage)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
315 $ make openjdk=/usr/lib/jvm/java-7-openjdk \
316 openjdk-src=$(pwd)/openjdk-7-7~b147-2.0/build/openjdk/jdk/src \
317 test
318
319 ####Mac OS X:
320 _Prerequisite:_ Build OpenJDK 7 according to [this site](https://wikis.oracle.com/display/OpenJDK/Mac+OS+X+Port).
321
322 _Conventional build:_
323
324 $ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image test
325
326 _Stand-alone build:_
327
328 $ make openjdk=$(pwd)/../jdk7u-dev/build/macosx-amd64/j2sdk-image \
329 openjdk-src=$(pwd)/../p/jdk7u-dev/jdk/src test
330
331 ####Windows (Cygwin):
2c12c9b @dicej add note about OpenJDK build infrastructure available on GitHub
dicej authored
332 _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). Alternatively, use https://github.com/alexkasko/openjdk-unofficial-builds.
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
333
334 _Conventional build:_
335
336 $ make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image test
337
338 _Stand-alone build:_
339
340 $ make openjdk=$(pwd)/../jdk7u-dev/build/windows-i586/j2sdk-image \
341 openjdk-src=$(pwd)/../p/jdk7u-dev/jdk/src test
342
343 Currently, only OpenJDK 7 is supported. Later versions might work,
344 but have not yet been tested.
345
346
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
347 Building with the Android Class Library
348 ---------------------------------------
349 As an alternative to both the Avian and OpenJDK class libaries, you
aeb87ff @bigfatbrowncat Instructions for Building with Android classpath
bigfatbrowncat authored
350 can also build with the Android class library. Now it should work on Linux, OS X and Windows.
351
352 The simpliest way to build Avian with Android classpath is to use `avian-pack` project: https://github.com/bigfatbrowncat/avian-pack
353
575f595 @dicej add support for iOS/x86_64
dicej authored
354 Avian-pack consists of Avian itself with some Android components (such as libcore and icu4c).
aeb87ff @bigfatbrowncat Instructions for Building with Android classpath
bigfatbrowncat authored
355
356 Note that we use the upstream OpenSSL repository and apply the
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
357 Android patches to it. This is because it is not clear how to build
358 the Android fork of OpenSSL directly without checking out and building
359 the entire platform. As of this writing, the patches apply cleanly
2a43e68 @dicej fix all the bugs
dicej authored
360 against OpenSSL 1.0.1h, so that's the tag we check out, but this may
d4a42c7 @dicej add Android class library instructions to README.md
dicej authored
361 change in the future when the Android fork rebases against a new
362 OpenSSL version.
363
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
364 Installing
365 ----------
366
367 Installing Avian is as simple as copying the executable to the desired
368 directory:
369
370 $ cp build/${platform}-${arch}/avian ~/bin/
371
372
373 Embedding
374 ---------
375
376 The following series of commands illustrates how to produce a
377 stand-alone executable out of a Java application using Avian.
378
379 Note: if you are building on Cygwin, prepend "x86_64-w64-mingw32-" or
380 "i686-w64-mingw32-" to the ar, g++, gcc, strip, and dlltool commands
381 below (e.g. x86_64-w64-mingw32-gcc).
382
383 __1.__ Build Avian, create a new directory, and populate it with the
384 VM object files and bootstrap classpath jar.
385
386 $ make
387 $ mkdir hello
388 $ cd hello
389 $ ar x ../build/${platform}-${arch}/libavian.a
390 $ cp ../build/${platform}-${arch}/classpath.jar boot.jar
391
392 __2.__ Build the Java code and add it to the jar.
393
394 $ cat >Hello.java <<EOF
395 public class Hello {
396 public static void main(String[] args) {
397 System.out.println("hello, world!");
398 }
399 }
400 EOF
401 $ javac -bootclasspath boot.jar Hello.java
402 $ jar u0f boot.jar Hello.class
403
404 __3.__ Make an object file out of the jar.
405
406 $ ../build/${platform}-${arch}/binaryToObject/binaryToObject boot.jar \
407 boot-jar.o _binary_boot_jar_start _binary_boot_jar_end ${platform} ${arch}
408
409 If you've built Avian using the `lzma` option, you may optionally
410 compress the jar before generating the object:
411
412 ../build/$(platform}-${arch}-lzma/lzma/lzma encode boot.jar boot.jar.lzma
413 && ../build/${platform}-${arch}-lzma/binaryToObject/binaryToObject \
414 boot.jar.lzma boot-jar.o _binary_boot_jar_start _binary_boot_jar_end \
415 ${platform} ${arch}
416
66bd7e0 @dicej use "lzma." prefix for LZMA-compressed embedded jars
dicej authored
417 Note that you'll need to specify "-Xbootclasspath:[lzma.bootJar]"
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
418 instead of "-Xbootclasspath:[bootJar]" in the next step if you've used
419 LZMA to compress the jar.
420
421 __4.__ Write a driver which starts the VM and runs the desired main
422 method. Note the bootJar function, which will be called by the VM to
423 get a handle to the embedded jar. We tell the VM about this jar by
424 setting the boot classpath to "[bootJar]".
425
426 $ cat >embedded-jar-main.cpp <<EOF
427 #include "stdint.h"
e07a1e2 @hydra1983 FIX : To run embeded application, it complains for missing libgcc_s_d…
hydra1983 authored
428 #include "jni.h"
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
429 #include "stdlib.h"
430
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
431 #if (defined __MINGW32__) || (defined _MSC_VER)
432 # define EXPORT __declspec(dllexport)
433 #else
434 # define EXPORT __attribute__ ((visibility("default"))) \
435 __attribute__ ((used))
436 #endif
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
437
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
438 #if (! defined __x86_64__) && ((defined __MINGW32__) || (defined _MSC_VER))
439 # define SYMBOL(x) binary_boot_jar_##x
440 #else
441 # define SYMBOL(x) _binary_boot_jar_##x
442 #endif
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
443
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
444 extern "C" {
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
445
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
446 extern const uint8_t SYMBOL(start)[];
447 extern const uint8_t SYMBOL(end)[];
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
448
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
449 EXPORT const uint8_t*
1fcc097 @joshuawarner32 use size_t instead of unsigned in a bunch of appropriate places
joshuawarner32 authored
450 bootJar(size_t* size)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
451 {
452 *size = SYMBOL(end) - SYMBOL(start);
453 return SYMBOL(start);
454 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
455
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
456 } // extern "C"
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
457
458 extern "C" void __cxa_pure_virtual(void) { abort(); }
459
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
460 int
461 main(int ac, const char** av)
462 {
463 JavaVMInitArgs vmArgs;
464 vmArgs.version = JNI_VERSION_1_2;
465 vmArgs.nOptions = 1;
466 vmArgs.ignoreUnrecognized = JNI_TRUE;
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
467
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
468 JavaVMOption options[vmArgs.nOptions];
469 vmArgs.options = options;
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
470
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
471 options[0].optionString = const_cast<char*>("-Xbootclasspath:[bootJar]");
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
472
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
473 JavaVM* vm;
474 void* env;
475 JNI_CreateJavaVM(&vm, &env, &vmArgs);
476 JNIEnv* e = static_cast<JNIEnv*>(env);
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
477
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
478 jclass c = e->FindClass("Hello");
479 if (not e->ExceptionCheck()) {
480 jmethodID m = e->GetStaticMethodID(c, "main", "([Ljava/lang/String;)V");
481 if (not e->ExceptionCheck()) {
482 jclass stringClass = e->FindClass("java/lang/String");
483 if (not e->ExceptionCheck()) {
484 jobjectArray a = e->NewObjectArray(ac-1, stringClass, 0);
485 if (not e->ExceptionCheck()) {
486 for (int i = 1; i < ac; ++i) {
487 e->SetObjectArrayElement(a, i-1, e->NewStringUTF(av[i]));
488 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
489
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
490 e->CallStaticVoidMethod(c, m, a);
491 }
492 }
493 }
494 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
495
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
496 int exitCode = 0;
497 if (e->ExceptionCheck()) {
498 exitCode = -1;
499 e->ExceptionDescribe();
500 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
501
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
502 vm->DestroyJavaVM();
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
503
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
504 return exitCode;
505 }
506 EOF
507
508 __on Linux:__
509
510 $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/linux \
511 -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp -o main.o
512
513 __on Mac OS X:__
514
2e828b4 @joshuawarner32 fix darwin embedding instructions in README.md
joshuawarner32 authored
515 $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin \
516 -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp -o main.o
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
517
518 __on Windows:__
519
e07a1e2 @hydra1983 FIX : To run embeded application, it complains for missing libgcc_s_d…
hydra1983 authored
520 $ g++ -fno-exceptions -fno-rtti -I"$JAVA_HOME/include" -I"$JAVA_HOME/include/win32" \
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
521 -D_JNI_IMPLEMENTATION_ -c embedded-jar-main.cpp -o main.o
522
523 __5.__ Link the objects produced above to produce the final
524 executable, and optionally strip its symbols.
525
526 __on Linux:__
527
528 $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello
529 $ strip --strip-all hello
530
531 __on Mac OS X:__
532
533 $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello -framework CoreFoundation
534 $ strip -S -x hello
535
536 __on Windows:__
537
538 $ dlltool -z hello.def *.o
539 $ dlltool -d hello.def -e hello.exp
e07a1e2 @hydra1983 FIX : To run embeded application, it complains for missing libgcc_s_d…
hydra1983 authored
540 $ gcc hello.exp *.o -L../../win32/lib -lmingwthrd -lm -lz -lws2_32 \
2689ec7 @dicej add "-lIphlpapi" to embedding example link command
dicej authored
541 -lIphlpapi -mwindows -mconsole -o hello.exe
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
542 $ strip --strip-all hello.exe
543
544 Embedding with ProGuard and a Boot Image
545 ----------------------------------------
546
547 The following illustrates how to embed an application as above, except
548 this time we preprocess the code using ProGuard and build a boot image
549 from it for quicker startup. The pros and cons of using ProGuard are
550 as follow:
551
552 * Pros: ProGuard will eliminate unused code, optimize the rest, and
553 obfuscate it as well for maximum space savings
554
555 * Cons: increased build time, especially for large applications, and
556 extra effort needed to configure it for applications which rely
557 heavily on reflection and/or calls to Java from native code
558
559 For boot image builds:
560
561 * Pros: the boot image build pre-parses all the classes and compiles
562 all the methods, obviating the need for JIT compilation at runtime.
563 This also makes garbage collection faster, since the pre-parsed
564 classes are never visited.
565
566 * Cons: the pre-parsed classes and AOT-compiled methods take up more
567 space in the executable than the equivalent class files. In
568 practice, this can make the executable 30-50% larger. Also, AOT
569 compilation does not yet yield significantly faster or smaller code
570 than JIT compilation. Finally, floating point code may be slower
571 on 32-bit x86 since the compiler cannot assume SSE2 support will be
572 available at runtime, and the x87 FPU is not supported except via
573 out-of-line helper functions.
574
575 Note you can use ProGuard without using a boot image and vice-versa,
576 as desired.
577
578 The following instructions assume we are building for Linux/i386.
579 Please refer to the previous example for guidance on other platforms.
580
581 __1.__ Build Avian, create a new directory, and populate it with the
582 VM object files.
583
584 $ make bootimage=true
585 $ mkdir hello
586 $ cd hello
587 $ ar x ../build/linux-i386-bootimage/libavian.a
588
589 __2.__ Create a stage1 directory and extract the contents of the
590 class library jar into it.
591
592 $ mkdir stage1
593 $ (cd stage1 && jar xf ../../build/linux-i386-bootimage/classpath.jar)
594
595 __3.__ Build the Java code and add it to stage1.
596
597 $ cat >Hello.java <<EOF
598 public class Hello {
599 public static void main(String[] args) {
600 System.out.println("hello, world!");
601 }
602 }
603 EOF
604 $ javac -bootclasspath stage1 -d stage1 Hello.java
605
606 __4.__ Create a ProGuard configuration file specifying Hello.main as
607 the entry point.
608
609 $ cat >hello.pro <<EOF
610 -keep class Hello {
611 public static void main(java.lang.String[]);
612 }
613 EOF
614
615 __5.__ Run ProGuard with stage1 as input and stage2 as output.
616
617 $ java -jar ../../proguard4.6/lib/proguard.jar \
618 -dontusemixedcaseclassnames -injars stage1 -outjars stage2 \
619 @../vm.pro @hello.pro
620
621 (note: The -dontusemixedcaseclassnames option is only needed when
622 building on systems with case-insensitive filesystems such as Windows
623 and OS X. Also, you'll need to add -ignorewarnings if you use the
624 OpenJDK class library since the openjdk-src build does not include all
625 the JARs from OpenJDK, and thus ProGuard will not be able to resolve
626 all referenced classes. If you actually plan to use such classes at
627 runtime, you'll need to add them to stage1 before running ProGuard.
628 Finally, you'll need to add @../openjdk.pro to the above command when
629 using the OpenJDK library.)
630
631 __6.__ Build the boot and code images.
632
a1e9315 @dicej fix LZMA/bootimage build
dicej authored
633 $ ../build/linux-i386-bootimage/bootimage-generator \
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
634 -cp stage2 \
635 -bootimage bootimage-bin.o \
636 -codeimage codeimage-bin.o
637
638 Note that you can override the default names for the start and end
639 symbols in the boot/code image by also passing:
640
641 -bootimage-symbols my_bootimage_start:my_bootimage_end \
642 -codeimage-symbols my_codeimage_start:my_codeimage_end
643
644 __7.__ Write a driver which starts the VM and runs the desired main
645 method. Note the bootimageBin function, which will be called by the
646 VM to get a handle to the embedded boot image. We tell the VM about
647 this function via the "avian.bootimage" property.
648
649 Note also that this example includes no resources besides class files.
650 If our application loaded resources such as images and properties
651 files via the classloader, we would also need to embed the jar file
652 containing them. See the previous example for instructions.
653
654 $ cat >bootimage-main.cpp <<EOF
655 #include "stdint.h"
656 #include "jni.h"
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
657
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
658 #if (defined __MINGW32__) || (defined _MSC_VER)
659 # define EXPORT __declspec(dllexport)
660 #else
661 # define EXPORT __attribute__ ((visibility("default")))
662 #endif
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
663
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
664 #if (! defined __x86_64__) && ((defined __MINGW32__) || (defined _MSC_VER))
665 # define BOOTIMAGE_BIN(x) binary_bootimage_bin_##x
666 # define CODEIMAGE_BIN(x) binary_codeimage_bin_##x
667 #else
668 # define BOOTIMAGE_BIN(x) _binary_bootimage_bin_##x
669 # define CODEIMAGE_BIN(x) _binary_codeimage_bin_##x
670 #endif
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
671
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
672 extern "C" {
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
673
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
674 extern const uint8_t BOOTIMAGE_BIN(start)[];
675 extern const uint8_t BOOTIMAGE_BIN(end)[];
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
676
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
677 EXPORT const uint8_t*
1fcc097 @joshuawarner32 use size_t instead of unsigned in a bunch of appropriate places
joshuawarner32 authored
678 bootimageBin(size_t* size)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
679 {
680 *size = BOOTIMAGE_BIN(end) - BOOTIMAGE_BIN(start);
681 return BOOTIMAGE_BIN(start);
682 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
683
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
684 extern const uint8_t CODEIMAGE_BIN(start)[];
685 extern const uint8_t CODEIMAGE_BIN(end)[];
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
686
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
687 EXPORT const uint8_t*
1fcc097 @joshuawarner32 use size_t instead of unsigned in a bunch of appropriate places
joshuawarner32 authored
688 codeimageBin(size_t* size)
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
689 {
690 *size = CODEIMAGE_BIN(end) - CODEIMAGE_BIN(start);
691 return CODEIMAGE_BIN(start);
692 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
693
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
694 } // extern "C"
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
695
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
696 int
697 main(int ac, const char** av)
698 {
699 JavaVMInitArgs vmArgs;
700 vmArgs.version = JNI_VERSION_1_2;
701 vmArgs.nOptions = 2;
702 vmArgs.ignoreUnrecognized = JNI_TRUE;
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
703
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
704 JavaVMOption options[vmArgs.nOptions];
705 vmArgs.options = options;
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
706
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
707 options[0].optionString
708 = const_cast<char*>("-Davian.bootimage=bootimageBin");
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
709
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
710 options[1].optionString
711 = const_cast<char*>("-Davian.codeimage=codeimageBin");
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
712
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
713 JavaVM* vm;
714 void* env;
715 JNI_CreateJavaVM(&vm, &env, &vmArgs);
716 JNIEnv* e = static_cast<JNIEnv*>(env);
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
717
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
718 jclass c = e->FindClass("Hello");
719 if (not e->ExceptionCheck()) {
720 jmethodID m = e->GetStaticMethodID(c, "main", "([Ljava/lang/String;)V");
721 if (not e->ExceptionCheck()) {
722 jclass stringClass = e->FindClass("java/lang/String");
723 if (not e->ExceptionCheck()) {
724 jobjectArray a = e->NewObjectArray(ac-1, stringClass, 0);
725 if (not e->ExceptionCheck()) {
726 for (int i = 1; i < ac; ++i) {
727 e->SetObjectArrayElement(a, i-1, e->NewStringUTF(av[i]));
728 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
729
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
730 e->CallStaticVoidMethod(c, m, a);
731 }
732 }
733 }
734 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
735
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
736 int exitCode = 0;
737 if (e->ExceptionCheck()) {
738 exitCode = -1;
739 e->ExceptionDescribe();
740 }
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
741
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
742 vm->DestroyJavaVM();
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
743
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
744 return exitCode;
745 }
746 EOF
7df5632 @dicej update README.md to indicate ARM64 support
dicej authored
747
cca7ade Changed the readme file to a Markdown file
Terek Campbell authored
748 $ g++ -I$JAVA_HOME/include -I$JAVA_HOME/include/linux \
749 -D_JNI_IMPLEMENTATION_ -c bootimage-main.cpp -o main.o
750
751 __8.__ Link the objects produced above to produce the final
752 executable, and optionally strip its symbols.
753
754 $ g++ -rdynamic *.o -ldl -lpthread -lz -o hello
755 $ strip --strip-all hello
756
757
758 Trademarks
759 ----------
760
761 Oracle and Java are registered trademarks of Oracle and/or its
762 affiliates. Other names may be trademarks of their respective owners.
763
3010aa1 @terekcampbell Updated README for Travis CI
terekcampbell authored
764 The Avian project is not affiliated with Oracle.
Something went wrong with that request. Please try again.