Skip to content

GitLab

Commit cbace0e2 authored by Stephanie Gawroriski's avatar Stephanie Gawroriski
Browse files

Remove the manual directory and move the important bits to the design document... 

Remove the manual directory and move the important bits to the design document (where my design decisions will go).
parent ed38ecbb
Hide whitespace changes
Inline Side-by-side
assets/manual/caveats.mkd deleted 100644 → 0
View file @ ed38ecbb
# Caveats
These are caveats for SquirrelJME. Anything listed here is an intended design
and is not a bug.
# Garbage Collection
For simplicity the garbage collector is a reference counter with sweeping when
no more memory is available (or GC is called manually). As such, cyclic
object references will not be freed unless one or both directions are
weakly referenced (using `WeakReference`). This means that if object A depends
on object B:
* A has a strong reference to B, B does not reference A.
* A has a weak reference to B, B does not reference A.
* A has a strong reference to B, B has a weak reference to A.
* A has a weak reference to B, B has a strong reference to A.
* A and B both have weak references to each other.
assets/manual/developer/pitfalls.mkd deleted 100644 → 0
View file @ ed38ecbb
# Pitfalls
These are some pitfalls that may occur when writing cross platform SquirrelJME
applications.
# The Host Filesystem
When using `FileChannel` and other NIO related classes to access the native
file system, there may be some issues on older and more limited systems when
it comes to files.
This does not affect using JAR resources however.
## File Names
Some operating systems and filesystems place limits on the characters which
are valid in file names along with potential case sensitivity and the length
of the file name.
For the file name length, some filesystems treat the name and extension as
just a single name, while others treat them as separate entities.
assets/manual/index.mkd deleted 100644 → 0
View file @ ed38ecbb
# Multi-Phasic Applications: SquirrelJME
* Copyright (C) 2013-2016 Stephanie Gawroriski
<xer@multiphasicapps.net>
* Copyright (C) 2013-2016 Multi-Phasic Applications
<http://multiphasicapps.net/>
* _Lex_ (The SquirrelJME Mascot) was drawn by...
* "_Puppenstein_" <http://www.furaffinity.net/user/puppenstein/>
**SquirrelJME** is intended to be a Java ME 8 compatible environment for
strange and many other devices. That is, you would be able to have a Java
environment on a wide range of _Internet of Things_ devices, older computers
(such as the _Amiga_), embedded devices, and mobile devices from old to new.
The source is written in pure Java and is designed to use small amounts of
memory, where simplicity increases operation speed without sacrificing
quality.
Note that Java ME 8 has a Java 7 virtual machine with specific limitations.
# Licenses
* Source:
[GNU General Public License, Version 3 or later](license.mkd)
* Non-Source:
[Creative Commons CC-BY-SA 4.0](license.mkd)
# Table of Contents
* User's Manual
* [Lex The SquirrelJME Mascot](usr/lex.mkd)
* [Build Instructions](user/building.mkd)
* [Limitations](user/limits.mkd)
* [Supported Character Encodings](user/encodings.mkd)
* [Why Use This?](user/why.mkd)
* Developer's Manual
* [Differences between Java SE and Java ME](developer/differences.mkd)
* [Pitfalls](developer/pitfalls.mkd)
* Maintainer's Manual
* [Consistency Guidelines](maintainer/consistency.mkd)
* [Style Requirements](maintainer/style.mkd)
# Donations
You may donate to SquirrelJME to help keep the author alive and to possibly
help the purchase of various hardware:
* BitCoin (**BTC/XBT**): [`1HNRD44krsCFUzUvVWaXr5jqvuyZDZy71M`](
bitcoin:1HNRD44krsCFUzUvVWaXr5jqvuyZDZy71M)
* LiteCoin (**LTC**): [`LKytAQcbPyox75uYMKo1NH1w2k1SqBaELi`](
litecoin:LKytAQcbPyox75uYMKo1NH1w2k1SqBaELi)
* DogeCoin (**DOGE**): [`DPsW21MV8RMuXhA3GoN8VPjkmQEugrEn8h`](
dogecoin:DPsW21MV8RMuXhA3GoN8VPjkmQEugrEn8h)
* [FreedomSponsors](https://freedomsponsors.org/user/mpasteven/)
assets/manual/maintainer/consistency.mkd deleted 100644 → 0
View file @ ed38ecbb
# Consistency Requirements
## Unknown Characters Representation
When the target is UTF-8 the unknown character will become `0xFFFD`.
When the target is ISO-8859-1 the unknown character will become `?`.
assets/manual/maintainer/style.mkd deleted 100644 → 0
View file @ ed38ecbb
# Style Requirements
## Always Tab With Size 4
Indentation is not done with spaces at all, it is pure tab. The tab size used
is 4 spaces.
## Never Exceed 79 Characters Per Column
There is a maxiumum limit of 79 characters per line of source code and in
other files also.
## Always Surround Ternary Operators With Parenthesis
When using ternary operators, you must always surround them in parenthesis even
if they are obvious. That is they must appear in the form of
`(condition ? true : false)`.
## Do Not Use Default Methods
Default methods in interfaces are not supported.
## Do Not Use Static Modifiable/Mutable Globals In Standalone Classes
The garbage collector upon determining that a class (which may contain static
variables treated as globals) is no longer referenced, it may be garbage
collected. This means that if you set a global in a class such as that and
then reference it later, it may be reset to its default value. This is more
likely to happen on lower memory systems where the garbage collector will act
more aggressively.
## Use Error Codes
Although descriptive details of why an exception is thrown is a nice thing, it
can waste much space on the static constant data and some extra time building
the messages. In general cases, exceptions that require detailed messages
might not always occur while in the case where they are needed the details
are important. All appearences of error codes must have the following
before it declared in a comment:
{@squirreljme.error CODE What this means. (Any extra values which are
displayed in the message)}
All files are scanned for these sequences to build the error table which is
used by maintainers and developers for debugging.
## Use Property Descriptions
Similar to error codes, this lists the system properties that are defined by
the code. Since there may be a multitude of system properties which are
available, they must be documented.
{@squirrejme.property net.multiphasicapps.some.property A description of
what the system property is for, which kind of values it takes, and how it
may potentially modify execution if at all.}
All files would be scanned to extract this information placed into the system
property documentation.
## Use Service Identifiers
If a kernel IPC service identifier is used then it must be documented so that
potential collisions are avoided. Each service identifier is a positive number
that specifies the use and potentially the protocol of the IPC service.
{@squirreljme.serviceid 1 shortname The description of the service.}
## Command Line Options
If a command line option is made available then the following must be used:
{@squirreljme.cmdline -foo=(bar) The description of the command line
switch.}
assets/manual/user/building.mkd deleted 100644 → 0
View file @ ed38ecbb
# Build Instructions
SquirrelJME is designed for a wide range of systems, thus there are specific
requirements so that the system may be built and cross compiled for all of the
platforms that are supported.
# Compiling On Sane Development Systems
Currently the build system supports POSIX and Windows hosts when building. To
build SquirrelJME a Java 7 JDK or higher is required. The build system is
written in Java and requires a bootstrap be performed to start it.
## Invoking the Build System
Since the build system is bootstrapped, it must be initialized by a script
before it can be called.
### POSIX Systems (Linux, BSD, Solaris, Mac OS X, etc.)
### Windows
Building requires the command line interface (`cmd`) be used.
# Compiling In SquirrelJME Environments
This does not exist yet, so it cannot be written.
assets/manual/user/encodings.mkd deleted 100644 → 0
View file @ ed38ecbb
# Supported Character Encodings
Only two character encodings are supported on all targets:
* `ISO-8859-1`
* This is essentially the first 256 unicode characters.
* `UTF-8`
It should be noted that `ASCII` is 7-bit and **NOT** the values which are above
the 127's character, this is known as `Extended ASCII` and is not supported.
Other encodings and codepages are not supported unless it is required by a
target.
A target may require an extra encoding to exist (such as Palm OS since it has
characters which do not map directly to Unicode). In the event that a target
specific encoding is required, it will be in the form of the following:
`x-squirreljme-<target>`. The host filesystems as provided by an operating
system may require these encodings so that files are located and accessed
correctly, especially if they appeared before the common adoption of Unicode.
assets/manual/user/limits.mkd deleted 100644 → 0
View file @ ed38ecbb
# Limitations
These are planned limitations:
* Only _4,096_ classes may be used at any one time, provided there is enough
memory to load all of them. Note that in standard desktop Java, this would
mean that almost the entire standard class library has been loaded.
# Filesystems
If there is a limitation to the length of a file name and an attempt is made
to open or create a file that exceeds the length limitations, then those
attempts will fail. File names will not be truncated to fit within the
limitations. This is to prevent cases where multiple files may attempted to
be created which all share the same truncated name, where they would instead
potentially overwrite and replace each other. For resources that a program
uses, it is highly recommended to place them within the JAR rather than use
the filesystem.
assets/manual/user/why.mkd deleted 100644 → 0
View file @ ed38ecbb
# Why Use This?
Here are a number of reasons why one should use this environment.
# Portability
With the code being written purely in Java, a port to another system requires
modifying the compiler to support that system along with having a backend which
interacts with the hardware and software. This is a bonus, because due to
Java's consistency across platforms this means that the code that runs the
virtual machine itself is written for the virtual machine itself. This means
that there are no quirks to workaround or having to require the proprocessor
to differentiate and flag differing platforms.
# Consistency
Java and the virtual machine it runs on is intended to be write once and run
anywhere. SquirrelJME is intended to take the lightest variant of Java and aims
to be 100% compatible with it. There are many variations in software and
hardware that the environment inside of Java is layered on top of. This
provides a single execution environment and in the general case programs which
run inside of it could not tell the difference if the platform is 8-bit or
4096-bit. This means that
assets/manual/developer/differences.mkd → design.mkd
View file @ cbace0e2
# Differences Between Java SE and Java ME
# Design Document
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:
* No finalizers (the `finalize()` method).
* Finalizers are very integrated with how the garbage collector works.
* It is never known when they will actually be called (if ever).
* Timing attacks could be performed when finalizers are called between
garbage collection runs.
* No serialization.
* Not all objects are `Serializable`.
* Serialization uses virtual machine magic to access internal details.
* The `transient` keyword should never appear.
* Simplifies implementation.
* Reduced and subsetted class library.
* The main library is much smaller which means it will load faster and
use less memory. Less memory means it can run on smaller/weaker systems.
* No reflection.
* There is `Class.forName()` and `Class.newInstance()`, however they are
trivial to support.
......@@ -22,21 +21,29 @@ missing along with a reason as to why this may be a good thing:
or primitive values will never change.
* More secure because for example changing `Boolean.TRUE` to be `false` may
cause security exploits with code that relies on it being `true`.
* The resulting virtual machine is smaller because information such as
the types of fields and methods that exist and their type information does
not have to be included within the virtual machine. This reduces the bloat
within the virtual machine.
* Produces faster code because `final` variable and especially
`static final` values can directly be accessed rather than requiring a
read of a field pointer value.
* No finalizers (the `finalize()` method).
* Finalizers are very integrated with how the garbage collector works.
* It is never known when they will actually be called (if ever).
* Timing attacks could be performed when finalizers are called between
garbage collection runs.
* No serialization.
* No objects are `Serializable`.
* Serialization uses virtual machine magic to access internal details, since
there is no reflection the information that would be used for
serialization does not exist.
* The `transient` keyword becomes obsolete.
* Simplifies implementation.
* No `invokedynamic` instruction.
* Simplifies virtual machine operation, at the cost of lambdas (which could
be smartly wrapped in anonymous classes by a compiler).
However, given these differences there are advantages:
* Faster
* Due to the lack of reflection, optimization is safer because finals are
truly final. This means no exceptions are required to allow for this
change.
* Lighter
* The main library is much smaller which means it will load faster and
use less memory. Less memory means it can run on smaller systems such as
calculators.
There are also disadvantages however:
* Without reflection, one cannot include plugins dynamically from the program.
......@@ -48,3 +55,19 @@ 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.
# Garbage Collection
For simplicity the garbage collector is a reference counter with sweeping when
no more memory is available (or GC is called manually). As such, cyclic
object references will not be freed unless one or both directions are
weakly referenced (using `WeakReference`). This means that if object A depends
on object B:
* A has a strong reference to B, B does not reference A.
* A has a weak reference to B, B does not reference A.
* A has a strong reference to B, B has a weak reference to A.
* A has a weak reference to B, B has a strong reference to A.
* A and B both have weak references to each other.
readme.mkd
View file @ cbace0e2
......@@ -14,14 +14,12 @@ environment on a wide range of _Internet of Things_ devices, older computers
(such as the _Amiga_), embedded devices, and mobile devices from old to new.
It intends to be 99.9% compatible with Java ME 8 and older J2ME standards. It
should be able to run a wide range of older J2ME software which would enable
this software to be used for archival purposes.
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.
The source is written in pure Java and is designed to use small amounts of
memory, where simplicity increases operation speed without sacrificing
quality.
Note that Java ME 8 has a Java 7 virtual machine with specific limitations and
a few changes.
* [Code of Conduct](code-of-conduct.mkd)
* [Design Document](design.mkd)
* [Project Scope](scope.mkd)
## I Am Open For Hiring
......@@ -59,15 +57,14 @@ the following address: <xer@multiphasicapps.net>.
* [TAR.GZ](/tarball/squirreljme-trunk.tar.gz?uuid=trunk)
* [ZIP](/zip/squirreljme-trunk.zip?uuid=trunk)
* Read-Only Mirrors:
* _GitHub_: <https://github.com/XerTheSquirrel/SquirrelJME>
* Bitbucket: <https://bitbucket.org/mpasteven/squirreljme>
* GitHub: <https://github.com/XerTheSquirrel/SquirrelJME>
* GitLab: <https://gitlab.com/mpasteven/SquirrelJME>
* Tor: <http://squirrelzarhffxz.onion/>
(`fossil clone -u http://squirrelzarhffxz.onion/ squirreljme.fossil`)
## Documents
## Links
* [Code of Conduct](code-of-conduct.mkd)
* [Developer Notes](assets/developer-notes/index.mkd)
(In repository)
* [Unversioned Notes](/uv/developer-notes/index.mkd)
......@@ -75,24 +72,16 @@ the following address: <xer@multiphasicapps.net>.
* [Alternative URL](http://multiphasicapps.net/uv/developer-notes/index.mkd)
([HTTPS](https://multiphasicapps.net/uv/developer-notes/index.mkd);
Links to the main repository, do not follow via Tor use the direct link)
* [Manual](assets/manual/index.mkd)
* [Project Scope](scope.mkd)
* [Why?](assets/manual/user/why.mkd)
## Links
* Locations where you can get support:
* [Freenode #squirreljme](ircs://irc.freenode.net:6697/squirreljme)
* [Mailing List](https://sourceforge.net/p/squirreljme/mailman/)
* [SourceForge Project](http://www.sourceforge.net/projects/squirreljme)
* Front facing social media:
* [Mastodon](https://mastodon.social/@XerTheSquirrel)
* [Twitter](https://twitter.com/MultiPhasicApps)
* [YouTube](https://www.youtube.com/channel/UCbmC7qQjeXUEUyE5XfDX5RA)
* Personal Accounts (If you wish to contact me this way)
* [FurAffinity](https://www.furaffinity.net/user/mpasteven/)
* [GitHub](https://github.com/XerTheSquirrel/)
* [Mastodon](https://mastodon.social/@XerTheSquirrel)
* [LinkedIn](https://www.linkedin.com/in/xerthesquirrel/)
* [Twitter](https://twitter.com/MultiPhasicApps)
## Goals
......
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