Commit 8c76b800 authored by Stephanie Gawroriski's avatar Stephanie Gawroriski
Browse files

Merge heads; Add contributing document; Design document work.

parents cbace0e2 c1995d89
......@@ -1430,7 +1430,7 @@
* `--` `--`
* `06`
# 2017/08/03
## 23:08
So I do not have much time now, but I can at least get the basic block
representation implemented.
# Building
SquirrelJME requires the following before it can be built:
* Java 7 or newer Virtual Machine
* Java 7 or newer Compiler
# 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
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 ``.
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/`
# Contributing
Before you contribute you should read and understand the [license](license.mkd)
that SquirrelJME is under.
## Contributor License
You grant Multi-Phasic Applications and Stephanie Gawroriski an irrevocable
license that:
1. Grants a patent license, as per the GNU GPLv3.
2. The ability to re-license the contributing code under any license.
3. Specified that you have not derived your contribution and/or knowledge
from the specified virtual machine implementations via direct
source code or reverse engineering (but not limited to):
* Android (Google)
* Apache Harmony (Apache Foundation)
* CVM (Sun Microsystems/Oracle)
* Excelsior JET (Excelsior LLC)
* GNU Classpath (Free Software Foundation)
* GNU GCJ/GIJ (Free Software Foundation)
* JamVM (Robert Lougher)
* Microsoft Java Virtual Machine (Microsoft)
* Microsoft .NET (Microsoft)
* Mono (Microsoft)
* OpenJDK (Sun Microsystems/Oracle)
* PhoneME (Sun Microsystems/Oracle)
4. If employed by a company, you have a right by that company to provide
contributions to this project.
......@@ -4,10 +4,9 @@ This document outlines several decisions and design considerations for the
SquirrelJME Virtual Machine. This document should reflect the most recent
path that SquirrelJME will be taking in its design.
# Considerations
Java ME is a much lighter Java platform and here are the things which are
missing along with a reason as to why this may be a good thing:
Because Java ME is different from Java SE, there are some considerations,
advantages, and disadvantages to consider when reading this document. Note that
this document is mostly within the scope of Java ME and not Java SE.
* Reduced and subsetted class library.
* The main library is much smaller which means it will load faster and
......@@ -55,7 +54,59 @@ There are also disadvantages however:
and `Class.newInstance()`, plugins using a common interface can be
initialized when they are not directly known.
For specific APIs, one should read the [Project Scope](scope.mkd) document.
For specific APIs, one should read the [Project Scope](scope.mkd) document
which outlines the APIs which exist for Java ME and whether they would be
implemented in SquirrelJME or third party vendors.
# Programming
SquirrelJME is written entirely in Java. This means that it only requires a
Java virtual machine and a Java compiler to be built. There are also no other
dependencies apart from what is within SquirrelJME itself, it is entirely
standalone and self contained.
## Self Hosting
I intend SquirrelJME to be self hosting in that it can build itself.
In the future a Java compiler will be written which can run on SquirrelJME
itself and allow building and compiling itself from source. This would also
allow other programs to be built from source and can be used as a self
contained Java development environment.
## Compilation
One may ask why Java and not another language such as C? Well, Java is a much
simpler language compared to C when it comes to syntax (C has the preprocessor,
structures, pointers, typedefs, function pointers, etc.). One main advantage
of Java is the consistency of the code.
One misconception about using Java is that it is impossible to use native code
or one will require and assembler to assemble assembly code for things which
Java cannot do. This is not the case for SquirrelJME. The major and most
important part of SquirrelJME is the compiler which can turn Java byte code
into native machine code. Since the compiler is very much integrated into
SquirrelJME this means that certain aspects of interacting with the host
environment can be accessed by changing compilation for certain aspects in a
way where it remains compatible with Java but also provides native access when
needed. Native access is provided by replacing method calls to special static
methods within a special class by the appropriate machine code rather than
invoking a method call. These special rewrites are only available to a single
class which is called `net.multiphasicapps.squirreljme.unsafe.SquirrelJME`.
The choice of doing this allows this class to wrap native behavior in the
library in a way where it can be used on Java SE virtual machines along with
SquirrelJME using it itself.
On a Java SE host, the `SquirrelJME` class implements all of its methods and
it interacts directly with the host virtual machine.
On SquirrelJME, the `SquirrelJME` class invokes methods within a secretive and
internal `__Unsafe__`. Essentially `__Unsafe__` becomes a virtual class where
any invocation of its methods are renamed to another class which is specific to
a given operating system or machine. This means that there are no conflicts
when `__Unsafe__` is called and does not require magic to allow duplicate class
names to be called. So for example calling static methods from `__Unsafe__`
will just turn into `TargetSpecificUnsafe`.
# Garbage Collection
......@@ -71,3 +122,10 @@ on object B:
* A has a weak reference to B, B has a strong reference to A.
* A and B both have weak references to each other.
Although reference counting may increase lock contention on the CPU and memory
buses it simplifies the design greatly by not requiring complex garbage
collection algorithms. In most cases with reference counting, SquirrelJME is
capable of using always a minimum footprint of memory depending on whether that
memory should be freed to the operating system or within SquirrelJME's own
memory for other programs running in it.
......@@ -17,7 +17,9 @@ should be able to run a wide range of older J2ME software which would enable
this software to be used for archival purposes. It is written purely in Java
and requires only a Java compiler and virtual machine for it to be built.
* [Building](building.mkd)
* [Code of Conduct](code-of-conduct.mkd)
* [Contributing](contributing.mkd)
* [Design Document](design.mkd)
* [Project Scope](scope.mkd)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment