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.
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.
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:
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
- 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
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.
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
- Windows:
Eclipse
Before running on Eclipse you must run the following Gradle command:
- Setup Eclipse Project
- Windows:
gradlew eclipse
- Linux/MacOS:
./gradlew eclipse
- Windows:
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.
- For the configuration use:
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.
- Does the same as
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 theMain-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.
- If
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.
- Will define system property
squirreljme.thread=value
-- The threading model to use.single
orcoop
-- Single Cooperatively Threaded.multi
orsmt
-- 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.
Custom Jar Runners
There are tasks that start with runJar
in the root project which can run
a Jar specified by a property or environment variable, this is to ease
debugging in running a specific target accordingly.
-Djar=(path)
-- The path to the Jar to run.$SQUIRRELJME_JAR
-- The path to the Jar to run.
As an example you can run the following:
./gradlew runJarHostedDebug1 -Djar="application.jar"
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:
.
- Same format as the
cc.squirreljme.vm.trace=option[,option[,...]]
-- Trace optionsall
-- 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 asnew
.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`