# Building

------------------------------------------------------------------------------

***Patience is required:***
***Currently SquirrelJME is in active development and although it can***
***run and produce binaries, there are limitations to consider.***
***Currently only a limited set of programs may be ran on SquirrelJME.***

------------------------------------------------------------------------------

SquirrelJME requires the following before it can be built:

 * Java 7 or newer Virtual Machine
 * Java 7 or newer Compiler

## Notes on Running

SquirrelJME uses a simplified error system which starts with a two capital
letter prefix followed by two digits and letters.

 * [List of Error Codes](http://multiphasicapps.net/uv/errors.mkd)

## Installing Java

SquirrelJME requires a Java 7 virtual machine in order to build itself.

### Common Linux Distributions

If you use a common and popular Linux distribution it likely has a JDK
available.

 * Arch
   * See <https://wiki.archlinux.org/index.php/Java>
 * Debian, Ubuntu, and derivatives
   * See <https://wiki.debian.org/Java>
   * One of the following depending on package availability
     * `apt-get install openjdk-7-jdk`
     * `apt-get install openjdk-8-jdk`
     * `apt-get install openjdk-9-jdk`
 * Gentoo
   * See <https://wiki.gentoo.org/wiki/Java>

### Oracle's JDK

Oracle's JDK supports the following (as of this writing):

 * Linux
 * Mac OS X
 * ReactOS (as Windows)
 * Solaris
 * Windows
 * Wine (as Windows)

Oracle's Java JDK can be downloaded from:

 * <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
 
Ensure that you **download and install** the ***JDK***.

If running on ReactOS/Windows/Wine, make sure that the `PATH` environment
variables refers to the JDK's binary directory:

 * `C:\Program Files\Java\jdk1.8.0_131\bin\`

# Bootstrap Build Environment

The main interaction with the SquirrelJME build environment is with the build
bootstrapper which initializes, compiles, and runs the build environment.

## System Specific

Each system has a different interface to the bootstrap environment, beyond this
the remainder of it is the same regardless of the system used.

### ReactOS and Windows

Oracle's Java JDK can be downloaded from:

 * <http://www.oracle.com/technetwork/java/javase/downloads/index.html>

The script used for building is `build.cmd`. This requires the command prompt
which may be accessed by running `cmd`. This may be found in the start menu
or may be accessed via **Windows Key + R**, typing `cmd`, then hitting enter.

Recommended setup for running the environment, assuming SquirrelJME source
code is located in the example `c:\users\stephanie\desktop\squirreljme`:

 * `cd c:\users\stephanie\temp`
 * `mkdir squirreljme-build`
 * `cd squirreljme-build`
 * `c:\users\stephanie\desktop\squirreljme\build.cmd`

### UNIX-Like: Linux, Mac OS X, Solaris, BSD, etc.

The script used for building is `build.sh`.

Recommended setup for running the environment, assuming SquirrelJME source
code is located in the example `/home/stephanie/squirreljme`:

 * `cd /tmp`
 * `mkdir squirreljme-build`
 * `cd squirreljme-build`
 * `/home/stephanie/squirreljme/build.sh`

# Building Shaded SquirrelJME JARs

Shaded SquirrelJME JARs are standalone JARs which can run on an existing
Java SE or Java ME system depending on which target it was built for.
Generally these JARs are just packaged by themselves and include the entire
set of libraries and applications from within SquirrelJME. These shaded JARs
are usually intended for demo projects and such. The JARs additionally are
pure Java code so they require a host Java VM. To contain the SquirrelJME
environment, an implementation of a virtual machine is used which is capable
of using and running the class library. This virtual machine has a speed
penalty because it is running the Java byte code itself however it is a
compatible environment.

Building of shaded JARs will result in two flavors:

 * _Bootstrapped_ -- Add code which is needed to make it operate in
   environments which may be different from Java ME, such as Java SE.
 * _Native_ -- Built without a bootstrap, requires that everything is naturally
   supported.

It is recommended that an out-of-tree build is performed (this means building
from another directory that is not in the SquirrelJME source tree). All the
commands pertain specifically to the build system itself.

## Building for Java SE (Or With Bootstrap)

This build requires a run-time that bridges what SquirrelJME needs with what
Java SE provides, as such it must be specified in the build.

 * `vmshade -b squirreljme-javase.jar`

If for some reason you wish to use an alternative bootstrap:

 * `vmshade -p bootstrap.jar -b squirreljme-other.jar`

## Building for Java ME

***NOTE:*** If the shaded JAR is not running on SquirrelJME, some features
will not be available for use. It should still run however.

 * `vmshade squirreljme-javame.jar`

