Commit 0a85f0c1 authored by Stephanie Gawroriski's avatar Stephanie Gawroriski
Browse files

Split the extra stuff in the readme.mkd to their own package to become the manual.

parent 9b0cadf1
......@@ -18,6 +18,7 @@ Note that Java ME 8 has a Java 7 virtual machine with specific limitations.
* [Online repository](http://multiphasicapps.net:8080/squirreljme)
* [Sub-Reddit](https://www.reddit.com/r/SquirrelJME/)
* [Manual](src/squirreljme-manual/index.mkd)
* [Developer Notes](src/developer-notes/index.mkd)
## Goals
......@@ -65,130 +66,3 @@ APIS AND ASSOCIATED JSRS/JEPS IS CONSIDERED BY MYSELF TO BE IN THE FAIR USE
(AND IT ALSO HELPS THE JAVA ECOSYSTEM BY PERMITTING IT TO RUN IN MORE PLACES
WHERE IT IS NOT SUPPORTED BY ORACLE).***
# Supported Operating Systems and Freestanding Hardware
_% -- Only tested on emulators, not real hardware._
## Hosted
## Freestanding
## Virtual
# Differences Between Java SE and Java ME
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.
* No reflection.
* There is `Class.forName()` and `Class.newInstance()`, however they are
trivial to support.
* More secure because access checks do not have to be performed at run-time
to determine if it is permissable to access an object.
* Random object fields (and finals) can be cached because their reference
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`.
* 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.
* However, Java ME 3 (or so) added LIBlets which may be optional and provide
a slight alternative to plugins. These however are fixed to the JAR/JAD
which means that the difficulty is increased.
* Alternatively, Java ME 8 has `ServiceLoader` which enables JARs to
potentially be merged to provide services. Also using `Class.forName()`
and `Class.newInstance()`, plugins using a common interface can be
initialized when they are not directly known.
# 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.
## Supported Character Encodings
Only two character encodings are supported:
* ISO-8859-1
* This is essentially the first 256 unicode characters.
* UTF-8
# Programming Considerations
## 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
Error codes are located in [errors.mkd](errors.mkd).
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.
# 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)`.
# 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 `?`.
......@@ -95,3 +95,8 @@ I really lost was my idea of having an `index.mkd` for the blogs so they can be
indexed and I can have that info there. Luckily though my paragraph before this
I had an open web browser seeing what I wrote which is nice.
## 21:15
I can also setup a manual too which contains the needed operations and such
for how to build and run the stuff.
Manifest-Version: 1.0
X-Hairball-Name: squirreljme-manual
X-Hairball-UUID: 35a12598-0ff9-407a-91e0-ec9c52cb99d1
LIBlet-Title: SquirrelJME Manual
LIBlet-Vendor: Steven Gawroriski
LIBlet-Version: 1.8.0.20160407
LIBlet-Description: This package contains the manual which contains
the information that is needed to operate this.
# Differences Between Java SE and Java ME
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.
* No reflection.
* There is `Class.forName()` and `Class.newInstance()`, however they are
trivial to support.
* More secure because access checks do not have to be performed at run-time
to determine if it is permissable to access an object.
* Random object fields (and finals) can be cached because their reference
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`.
* 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.
* However, Java ME 3 (or so) added LIBlets which may be optional and provide
a slight alternative to plugins. These however are fixed to the JAR/JAD
which means that the difficulty is increased.
* Alternatively, Java ME 8 has `ServiceLoader` which enables JARs to
potentially be merged to provide services. Also using `Class.forName()`
and `Class.newInstance()`, plugins using a common interface can be
initialized when they are not directly known.
# SquirrelJME Manual
This is the manual for SquirrelJME which should contain and describe the
operation of this software.
# Table of Contents
* User's Manual
* [Supported Platforms](user/platforms.mkd)
* [Supported Character Encodings](user/encodings.mkd)
* [Limitations](user/limits.mkd)
* Developer's Manual
* [Differences between Java SE and Java ME](developer/differences.mkd)
* Maintainer's Manual
* [Style Requirements](maintainer/style.mkd)
* [Consistency Guidelines](maintainer/consistency.mkd)
# 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 `?`.
# 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.
# 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.
# 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.
# Supported Operating Systems and Freestanding Hardware
This contains the list of supported operating systems, architectures, and
hardware that is supported by SquirrelJME.
_% -- Only tested on emulators, not real hardware._
## Hosted
## Freestanding
## Virtual
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