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 8 or newer Virtual Machine and Compiler
• C++ Compiler (Utilized for Testing)
  • Clang
  • GCC
  • Microsoft Visual Studio 2010 or newer
  • XCode

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

Installing Java

SquirrelJME requires a Java 8 virtual machine in order to build itself. Gradle is used as well however it is available through Gradle Wrapper.

AdoptOpenJDK (Windows, Linux, and Mac OS X)

AdoptOpenJDK is the recommended way to build and setup SquirrelJME as it has long-term support and is easy to setup. You will need at least a Java 8 variant of AdoptOpenJDK.

• https://adoptopenjdk.net/releases.html?variant=openjdk8&jvmVariant=hotspot

Please note that Java 11 may be used as well.

Oracle's JDK (Windows, Linux, and Mac OS X)

Oracle's JDK supports modern systems and 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\

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-8-jdk
    • apt-get install openjdk-9-jdk
    • apt-get install openjdk-11-jdk
• Gentoo
  • See https://wiki.gentoo.org/wiki/Java

Running via IDEs

IntelliJ IDEA

SquirrelJME is developed on IntelliJ Ultimate, however Community Edition may still be used. This makes development easier and more integrated along with whatever code you write or contribute will match the style that is set in SquirrelJME.

• https://www.jetbrains.com/idea/

VSCode

The following extensions are required to build and run SquirrelJME in VSCode:

• Extension Pack for Java
  • ext install vscjava.vscode-java-pack
• Gradle for Java
  • ext install vscjava.vscode-gradle

Before running on VSCode you must run the following Gradle command, since this uses a similar code base that is borrowed from Eclipse:

• Setup Eclipse Project
  • Windows: gradlew eclipse
  • Linux/MacOS: ./gradlew eclipse

Eclipse

Before running on Eclipse you must run the following Gradle command:

• Setup Eclipse Project
  • Windows: gradlew eclipse
  • Linux/MacOS: ./gradlew eclipse

Then following this you may Import Existing Gradle Project and you will have access to the project for building.

Installing C++ Compiler

Common Linux Distributions

For the C++ Compiler which is needed for testing:

• Debian, Ubuntu, and derivatives
  • apt-get install build-essential g++
  • apt-get install build-essential clang

Windows

For Gradle to detect a C++ compiler, it needs either Microsoft Visual Studio or a GCC installation via Cygwin, or a GCC installation via Mingw-w64.

More information is located at https://docs.gradle.org/current/userguide/building_cpp_projects.html#windows.

Microsoft Visual Studio

Microsoft's Visual Studio may be used by Gradle to compile the code, note that it only uses the compiler tool from the installation (no GUI is needed).

• Download from https://visualstudio.microsoft.com/downloads/.
• At the minimum, the following must be installed (pieces that are crossed out may be different for future versions of Microsoft's Compiler):
  • Windows Universal C Runtime
  • C++ Build Tools core Features
  • MSVC ~~v142~~ - VS ~~2019~~ C++ ~~x86/x64~~ build tools
  • C++ Redistributable Update
  • Windows 10 SDK
• Alternatively, you can run the Visual Studio installer and import the components file, this file can be found in the root and is called .vsconfig.

Mingw-w64

You can use Mingw-w64 as well, it is a freely available compiler.

• Main web site: https://mingw-w64.org.
• In the downloads section it is recommended to use MingW-W64-builds:
  • For the configuration use:
    • GCC Version: The latest (at time of writing it was 8.0.0).
    • Threads: win32.
    • Exception Handling: seh.
    • Install both 32-bit and 64-bit.

Cygwin

You can also download Cygwin at: https://www.cygwin.com/.

Mac OS X

You must install XCode, more information on XCode is at https://developer.apple.com/xcode/. Alternatively there is a command line tool to install the XCode command line utilities for example if you are using Brew:

• xcode-select --install

Build Environment

The main interaction with the SquirrelJME build environment is with Gradle which manages anything related to building and testing. All builds are performed through Gradle Wrapper which is used as the following:

• Windows: gradlew
• Others: ./gradlew

Gradle uses tasks of which multiple may be specified accordingly, such as running the tests within the repository:

• gradlew test

If using IntelliJ you may tap Ctrl twice (Ctrl+Ctrl) and type in the following to run Gradle commands, it should automatically use the wrapper:

• gradle

RetroArch

Building for RetroArch uses the makefilelibretro makefile. As such building SquirrelJME for your current system involves using the alternative makefile.

• make
• Windows:
  • make -f makefilelibretro CC=i686-w64-mingw32-gcc platform=mingw_x86
  • make -f makefilelibretro CC=x86_64-w64-mingw32-gcc platform=mingw_x86_64

Docker

In the root directory, execute the command:

• docker build .

This will create an image that you will be able to use to execute one of the built-in virtual machines.

Development Virtual Machines

For development purposes you may use the virtual machines provided by the SquirrelJME run-time. Modules within SquirrelJME have tasks which allow them to be ran accordingly.

• SpringCoat
  • :modules:<name>:runSpringCoatDebug (running)
  • :modules:<name>:runSpringCoatRelease (running)
  • :modules:<name>:testSpringCoat (testing)
• Native (runs on the host Java SE)
  • :modules:<name>:runHostedDebug (running)
  • :modules:<name>:testHostedDebug (testing)

Note that the test task is not supported and will throw an exception, it is not able to reliably test within SquirrelJME.

The following System properties are available:

• squirreljme.jdwp=[hostname]:port -- Enable JDWP.
  • Enables JDWP for the given virtual machine.
  • If only :port is specified it will listen for incoming connections from a debugger.
  • If both hostname:port is specified it will connect to a remote debugger.
  • Note that if the hosted environment is debugged, launched sub-tasks will not be run under the debugger.
• squirreljme.xjdwp=[hostname]:port -- Enable JDWP for Hosted environment.
  • Does the same as squirreljme.jdwp but takes priority if both are specified in the event that debugging should be done for the hosted process.
• squirreljme.midlet=value -- The MIDlet to run, in the following order:
  • If value is a number and is -1, then no MIDlet will be selected and the Main-Class attribute will be force selected.
  • If value is a number, then it will be treated as an index. If the index is in bounds it will run the given MIDlet by index.
  • If value is a string, then a search will be performed for a MIDlet with a matching case-insensitive title.
  • If value is a string and starts or ends with an asterisk (*) then it will find a midlet whose title contains the text with a case-insensitive search.
  • Otherwise if value is a string, it will construct a virtual MIDlet which executes the given value as the name of a class within the JAR.
• squirreljme.sysprop.<systemProperty>=value -- Add system property.
  • This allows any system properties that are prefixed with this to be added into the target virtual machine when running.
  • As an example squirreljme.sysprop.favorite.animal=squirrel:
    • Will define system property favorite.animal=squirrel within the virtual machine.
• squirreljme.thread=value -- The threading model to use.
  • single or coop -- Single Cooperatively Threaded.
  • multi or smt -- Simultaneous Multi-Threading.
• test.single=classname -- Run only the given test:
  • Will be the test class to be run.
  • Multi-parameter tests are in the form of classname@parameter, if a parameter is specified then only that one will be matched. Otherwise this will include all tests of that given parameter.

Building ROMs

Full ROMs can be built with the following tasks, note that test ROMs contain all the testing libraries and are generally used to ensure things are working:

Full Suite Virtual Machines

There is a task which initializes a full suite of SquirrelJME, including every module. This can be used to run a specific program within SquirrelJME's environment through Gradle.

• Hosted Environment.
  • fullHostedDebug
• SpringCoat
  • fullSpringCoatRelease
  • fullSpringCoatDebug

There are system properties that are available and can be used to modify the behavior:

• full.libraries=path... -- Additional libraries to place onto the suite path.
  • Same format as the -classpath argument. On Windows this will use ; as separators, while other systems will use :.
• cc.squirreljme.vm.trace=option[,option[,...]] -- Trace options
  • all -- Enable all.
  • instructions -- Instructions being executed.
  • methodEntry -- Entry of methods.
  • methodExit -- Exit of methods.
  • mleCall -- SquirrelJME MLE Native Calls.
  • invokeStatic -- Static invocations.
  • allocation -- Allocations such as new.
  • classInitialize -- Class is initialized.
  • vmException -- Virtual machine exceptions.
  • missingClass -- Class does not exist.
  • monitorEnter -- Monitor is entered.
  • monitorExit -- Exiting a monitor.
  • monitorWait -- Monitor is waited on.
  • monitorNotify -- Monitor is notified.
  • threadNew -- New thread is created.

New Java Version Contingency

With regard to https://github.com/SquirrelJME/SquirrelJME/issues/6 if in the event this occurs, building with Gradle will attempt to use the Eclipse Java Compiler to compile the project. It may be forced by passing to Gradle -Dforce.ecj=true.

Standalone Java Based Emulators

A standalone Java emulator Jar which contains all of the available test virtual machine implementations is available when calling the task:

• :emulators:standalone:shadowJar

Flatpak

This is used with Flatpak. This requires some dependencies first:

• Install flatpak-builder
• flatpak install flathub org.freedesktop.Platform//23.08
• flatpak install flathub org.freedesktop.Sdk//23.08
• flatpak install flathub org.freedesktop.Sdk.Extension.openjdk11

With the dependencies installed, it may be built with:

• flatpak-builder build-dir cc.squirreljme.SquirrelJME.yml
• flatpak-builder --user --install build-dir cc.squirreljme.SquirrelJME.yml

To bundle into a single file, run the following:

• flatpak build-bundle $HOME/.local/share/flatpak/repo squirreljme.flatpak cc.squirreljme.SquirrelJME

To run from the command line, you may want to add to your PATH:

• $HOME/.local/share/flatpak/exports/bin/

Mac OS

This is used with Homebrew, with checked out source code the following can be run:

• brew install --HEAD Formula/squirreljme-standalone.rb`