This is a guide for developers to follow for various parts of the repository. This is mostly intended for maintainers of SquirrelJME.

Accepting Changes

TO BE WRITTEN

Loading Contributions

TO BE WRITTEN

Via Fossil Bundles

TO BE WRITTEN

Via Git Bundles

TO BE WRITTEN

git am < my-branch.bun

Merging Branches

To merge a branch locally, do the following:

Update to the branch that will get submissions merged into:
- fossil update trunk
Merge the other branch into your current trunk:
- fossil merge other-branch
Commit the changes:
- fossil commit
- Be sure to have a meaningful commit message, if the code is from a merge request on a remote repository, have the following in the commit message:
  - GitHub: (GitHub Closes #1234)
  - GitLab: (GitLab Closes !1234)
Synchronize the repositories:
- fossil sync -u

Releasing

When a release is to be made, it is performed in another branch and becomes separate from trunk. This means that trunk is always in a state of perpetual development. Within these branches, there are bug fixes and releases. When a commit is ready for a release then it should just be tagged and built accordingly. It is best to avoid having releases and such in the trunk branch because it will complicate bug fixes and other things. So when a release is to be made:

Update the changelog with the planned release date if it is known at the time, otherwise it is not known.
Fork the branch and make a new branch from trunk for the release to be done, an example would be release-0.2.x.
In the new release-0.2.x branch, update the version numbers in the appropriate places so things are updated.
Tag the commit as 0.2.0 or an increasing release version (example: 0.2.1) for each increasing release.
Do all the common release stuff.
While in trunk, do the following:
- The development version can be bumped in which case the version will be incremented by two and will be odd (3, 5, 7, etc.).
- Add the next version to the changelog, so that it may be updated when there is a new major change.

RetroArch

For RetroArch, the SquirrelJME recipes should be updated to reflect the release tag.

https://github.com/libretro/libretro-super

Bug-fix and Otherwise Releases

If a bug-fix or otherwise has to be done on a release version, since the release is in its own branch, the work can be done in that branch. Any fixes should have already been made in trunk if applicable, then it can be cherry picked into the release branch. Then once the fixes have been made and a new version is released the release version should be incremented (that is 0.2.0 to 0.2.1 to 0.2.2). Then any of the release related stuff should be done.

Common Release Stuff

THIS IS OUT OF DATE AND WILL BE CHANGED TO BE DONE PURELY BY CI/CD, SO THAT IT IS AUTOMATICALLY DONE AND CHECKED WITHOUT ISSUE.

When a release is done, all of the binaries and according information must be updated. It is assumed that SQUIRRELJME is an environment variable to the root of the SquirrelJME source tree. Checkout the tag or commit which the release is to be done on. Then run the following command:

$SQUIRRELJME/utils-dev/uploadrelease.sh $__release_version__

This will perform an auto-build of everything and then store the release in the $__release_version__ directory, these binaries are important. Once the binaries and sources are built, they should be uploaded to the following locations:

Fossil (https://multiphasicapps.net/)
- The uploadrelease.sh script takes care of putting the files in the repository.
- You will need to edit the download page to add the new version, this will be done with fossil unversion edit download.mkd.
- Synchronize the repository with the unversioned space.
GitHub
- Go to releases.
- Draft a new release.
- Choose the release tag you just made. Note that there might be a delay before GitHub is updated, so be patient or force it to update manually.
- Title the release.
SourceForge
- Create a new directory for the release number.
- Upload all of the files into that directory.
- Appropriately set the operating systems for the binaries.

Importing SquirrelJME Into Another Project

Any one of SquirrelJME's modules can be used as a dependency for a project. Note that the versions that are used depend on if a release is being used or not, which is in the format of M.m.r for releases and M.m.r-SNAPSHOT for development versions. Note that even minor versions are releases (ex: 0.4.0), and odd minor versions are development versions (ex: 0.3.0-SNAPSHOT).

Snapshot Repository

<!-- Maven -->
<project>
    <repositories>
        <repository>
            <id>oss.sonatype.org-snapshot</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>
</project>

// Gradle
repositories {
    maven {
        url "https://oss.sonatype.org/content/repositories/snapshots"
    }
}

Debugging

SquirrelJME's VMs may be debugged by having it connect to a debugger or waiting for a debug connection. Debugging happens purely over TCP/IP. It is not possible to use existing debuggers to debug SquirrelJME virtual machines there are debug interfaces available through standardized JDWP. Note that it is not recommended for the debugger port to be open to the internet as it will allow the remote debugger to have access to all the virtual machine internals.

Arguments to the virtual machines for SpringCoat, SummerCoat, etc.:

Connect to remote debugger
- -Dsquirreljme.jdwp=localhost:5005
Listen for a remote connection
- -Dsquirreljme.jdwp=:5005

Instructions for specific debuggers:

jdb
- Connect:
  - jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=5005
- Listen:
  - jdb -connect com.sun.jdi.SocketListen:port=5005
IntelliJ
Eclipse

IntelliJ

SquirrelJME uses IntelliJ IDEA Ultimate which is highly recommended for development.

Recommended Plugins

The following plugins are recommended:

EmbeddedProjectJdk -- Allows for custom defined JDKs, which SquirrelJME is its own JDK.
- https://plugins.jetbrains.com/plugin/10480-embeddedprojectjdk

Custom File Type for Jasmin

IntelliJ supports custom file type definitions, the following is for Jasmin so that it has much better syntax highlighting.

Use the following setting:

Name: .j
Description: Jasmin Instructions
Line comment: ;
Line comment only at line start: Checked
Hex Prefix: 0x
Support String Escapes: Checked

Then associated with:

*.j

Keywords

The following goes into the keyword fields.

1

abstract
final
native
private
protected
public
static
synchronized
transient
volatile

2

default
boolean
byte
short
char
int
long
float
double

3

.catch
.class
.end
.end field
.end method
.field
.implements
.interface
.limit
.limit locals 
.limit stack
.line
.method
.source
.super
.throws
.var

4

aaload
aastore
aconst_null
aload
aload_0
aload_1
aload_2
aload_3
anewarray
areturn
arraylength
astore
astore_0
astore_1
astore_2
astore_3
athrow
baload
bastore
bipush
breakpoint
caload
castore
checkcast
d2f
d2i
d2l
dadd
daload
dastore
dcmpg
dcmpl
dconst_0
dconst_1
ddiv
dload
dload_0
dload_1
dload_2
dload_3
dmul
dneg
drem
dreturn
dstore
dstore_0
dstore_1
dstore_2
dstore_3
dsub
dup
dup2
dup2_x1
dup2_x2
dup_x1
dup_x2
f2d
f2i
f2l
fadd
faload
fastore
fcmpg
fcmpl
fconst_0
fconst_1
fconst_2
fdiv
fload
fload_0
fload_1
fload_2
fload_3
fmul
fneg
frem
freturn
fstore
fstore_0
fstore_1
fstore_2
fstore_3
fsub
getfield
getstatic
goto
goto_w
i2d
i2f
i2l
iadd
iaload
iand
iastore
iconst_0
iconst_1
iconst_2
iconst_3
iconst_4
iconst_5
iconst_m1
idiv
if_acmpeq
if_acmpne
if_icmpeq
if_icmpge
if_icmpgt
if_icmple
if_icmplt
if_icmpne
ifeq
ifge
ifgt
ifle
iflt
ifne
ifnonnull
ifnull
iinc
iload
iload_0
iload_1
iload_2
iload_3
imul
ineg
instanceof
int2byte
int2char
int2short
invokenonvirtual
invokestatic
invokevirtual
ior
irem
ireturn
ishl
ishr
istore
istore_0
istore_1
istore_2
istore_3
isub
iushr
ixor
jsr
jsr_w
l2d
l2f
l2i
ladd
laload
land
lastore
lcmp
lconst_0
lconst_1
ldc
ldc_w
ldiv
lload
lload_0
lload_1
lload_2
lload_3
lmul
lneg
lookupswitch
lor
lrem
lreturn
lshl
lshr
lstore
lstore_0
lstore_1
lstore_2
lstore_3
lsub
lushr
lxor
monitorenter
monitorexit
multianewarray
new
newarray
nop
pop
pop2
putfield
putstatic
ret
return
saload
sastore
sipush
swap
tableswitch

Developer Guide

Accepting Changes

Loading Contributions

Via Fossil Bundles

Via Git Bundles

Merging Branches

Releasing

RetroArch

Bug-fix and Otherwise Releases

Common Release Stuff

Importing SquirrelJME Into Another Project

Snapshot Repository

Debugging

IntelliJ

Recommended Plugins

Custom File Type for Jasmin

Keywords

1

2

3

4