assets/doc/usage-standalone.mkd

   1 # Standalone Usage
   2
   3 SquirrelJME's Standalone JAR requires at least a Java SE 8 virtual
   4 machine. For most systems, it may be downloaded from the following locations:
   5
   6  * <https://adoptopenjdk.net/>
   7  * <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
   8  * In Debian/Ubuntu, OpenJDK is available in the repository.
   9
  10 Generally SquirrelJME will work best with at least a Java 8 virtual machine.
  11
  12 The JAR file `squirreljme-standalone.jar` may be run by running the following:
  13
  14  * `java -jar squirreljme-standalone.jar`
  15
  16 When run, it should start the launcher and provide a list of available
  17 programs.
  18
  19 ## Command Line Usage
  20
  21 The following may be used at the command line, the format is the same
  22 as `java`. An option within square brackets `[]` are optional, and
  23 any option within parenthesis `()` are required. The usage of SquirrelJME is
  24 in the following format:
  25
  26  * `java -jar squirreljme-standalone.jar [options]`
  27    * Start into the launcher.
  28  * `java -jar squirreljme-standalone.jar [options] -jar a.jar`
  29    * Directly launch the given Jar, bypassing the launcher.
  30  * `java -jar squirreljme-standalone.jar [options] mainClass [mainArgs|...]`
  31    * Standard launch into the specific classpath and main arguments.
  32    * For this option, `-classpath (class:path:...)` may be used
  33  * `java -jar squirreljme-standalone.jar -XdebuggerOnly [options]`
  34    * Only launch the built-in SquirrelJME debugger and not an actual virtual
  35      machine.
  36
  37 The available options are:
  38
  39  * `-Xclutter:(release|debug)`
  40    * Use the given core libraries with the given clutter level.
  41    * `release` includes obfuscation and no debugging and thus runs faster.
  42    * `debug` does not have any obfuscation and may work in cases where
  43      obfuscation and optimization may cause issues.
  44  * `-Xdebug[:fork|nofork]`
  45    * Enable debugging but with the internal built-in SquirrelJME debugger and
  46      not a JDWP connection over TCP.
  47    * This is supported under the `hosted` emulator, however if you launch
  48      another application within it will not debug that process, therefor if
  49      you wish to debug you should use `-jar`.
  50    * Optionally, `fork` or `nofork` can be specified to where the
  51      internal debugger to launched as a separate process or not.
  52  * `-XdebuggerOnly`
  53    * Launches the built-in SquirrelJME Debugger.
  54  * `-Xemulator:(vm)`
  55    * Specifies the backend emulator to use, the supported options are:
  56      * `hosted` -- Uses the host JVM to run all the software.
  57      * `springcoat` -- SpringCoat, interpreter written in Java.
  58      * `nanocoat` -- NanoCoat, interpreter written in C.
  59  * `-Xentry:id`
  60    * Used with `-jar`, this allows one to specify an entry point index,
  61      application name, or application entry point to determine which one to
  62      launch within the Jar as there may be multiple.
  63    * By default, if not specified, the first is always used.
  64  * `-Xint`
  65    * Alias for `-Xemulator:springcoat`.
  66  * `-Xjdwp:[hostname]:port`
  67    * Enable debugging.
  68    * If `hostname` is specified then the debugger will connect to the
  69      remote host that is a listening JDWP debugger.
  70    * Otherwise, if only `port` is specified then the debugger will wait and
  71      listen on the given port for an incoming connection.
  72  * `-Xlibraries:(class:path:...)`
  73    * Specifies libraries that should be available to the virtual machine
  74      and the suite management system, note that this is not the same as
  75      the `-classpath` option as that is for the _current_ application.
  76    * Wildcard directories may be specified in the following way, depending
  77      on the operating system and possible shell expansion:
  78      * `/path/to/directory/*`
  79      * `/path/to/directory/**`
  80      * `/path/to/directory/*.*`
  81      * `wildcard=/path/to/directory`
  82  * `-Xscritchui:(ui)`
  83    * Rather than the default, use a specific user interface library.
  84    * This may also be set by using `cc.squirreljme.scritchui`.
  85  * `-Xsnapshot:(path-to-nps)`
  86    * Profile the virtual machine and store the profile results into the
  87      given VisualVM snapshot file.
  88  * `-XstartOnFirstThread`
  89    * Ignored.
  90  * `-Xthread:(single|coop|multi|smt)`
  91    * Sets the threading mode of the virtual machine.
  92    * `single`/`coop` -- Single threaded using cooperative multitasking.
  93    * `multi`/`smt` -- Multi threaded using asynchronous multitasking.
  94  * `-Xtrace:option[,option[,...]]` -- Trace options
  95    * `all` -- Enable all.
  96    * `allocation` -- Allocations such as `new`.
  97    * `classInitialize` -- Class is initialized.
  98    * `ignoredException` -- Exception that may be ignored.
  99    * `instructions` -- Instructions being executed.
 100    * `invokeStatic` -- Static invocations.
 101    * `methodEntry` -- Entry of methods.
 102    * `methodExit` -- Exit of methods.
 103    * `missingClass` -- Class does not exist.
 104    * `mleCall` -- SquirrelJME MLE Native Calls.
 105    * `monitorEnter` -- Monitor is entered.
 106    * `monitorExit` -- Exiting a monitor.
 107    * `monitorNotify` -- Monitor is notified.
 108    * `monitorWait` -- Monitor is waited on.
 109    * `threadNew` -- New thread is created.
 110    * `vmException` -- Virtual machine exceptions.
 111  * `-Dsysprop=value`
 112    * Defines the given system property.
 113  * `-classpath (class:path:...)`
 114    * Specifies the class path to use for the current application, the entries
 115      must be visible from the library path.
 116  * `-jar (path.jar)`
 117    * Launches the given Jar file.
 118  * `-client`
 119    * Ignored.
 120  * `-server`
 121    * Ignored.
 122  * `-zero`
 123    * Alias for `-Xemulator:springcoat`.
 124
 125 ## Default Configuration and Library Paths
 126
 127 SquirrelJME may be configured automatically via files on the file system. The
 128 following paths are considered for automatic configuration and classpath
 129 inclusion.
 130
 131  * Windows:
 132    * Cache (Local):
 133      * Vista/7/8/10/11: `%LOCALAPPDATA%/squirreljme/cache`
 134      * 95/98/ME/2000/XP: `%APPDATA%/squirreljme/cache`
 135      * Or otherwise `%PROGRAMDATA%/squirreljme/cache`
 136    * Configuration (Roaming):
 137      * 95/98/ME/XP/Vista/7/8/10/11: `%APPDATA%/squirreljme/config`
 138      * Or otherwise `%PROGRAMDATA%/squirreljme/config`
 139    * Data (Roaming):
 140      * 95/98/ME/XP/Vista/7/8/10/11: `%APPDATA%/squirreljme/data`
 141      * Or otherwise `%PROGRAMDATA%/squirreljme/data`
 142    * State (Local):
 143      * Vista/7/8/10/11: `%LOCALAPPDATA%/squirreljme/data`
 144      * 95/98/ME/2000/XP: `%APPDATA%/squirreljme/data`
 145      * Or otherwise `%PROGRAMDATA%/squirreljme/data`
 146  * Linux, macOS, BSD, and other UNIX/UNIX-like systems:
 147   * Cache: `$XDG_CACHE_HOME/squirreljme`
 148     * Or otherwise `$HOME/.cache/squirreljme`
 149   * Configuration: `$XDG_CONFIG_HOME/squirreljme`
 150     * Or otherwise `$HOME/.config/squirreljme`
 151   * Data: `$XDG_DATA_HOME/squirreljme`
 152     * Or otherwise `$HOME/.local/share/squirreljme`
 153   * State: `$XDG_STATE_HOME/squirreljme`
 154     * Or otherwise `$HOME/.local/state/squirreljme`
 155
 156 To override the defaults, you may instead use the following, if any start
 157 with `~` that is replaced with `$HOME` or `%USERPROFILE%`:
 158
 159  * `SQUIRRELJME_CACHE_HOME` for _Cache_ path.
 160  * `SQUIRRELJME_CONFIG_HOME` for _Configuration_ path.
 161  * `SQUIRRELJME_DATA_HOME` for _Data_ path.
 162
 163 SquirrelJME will automatically add to system properties for a properties file:
 164
 165  * `$SQUIRRELJME_JAVA_OPTS`
 166    * In the form of `"-Dproperty=value -Dcute=squirrel"`
 167  * `{Configuration}/squirreljme.properties`
 168    * In the form of `property=value` on individual lines.
 169
 170 SquirrelJME will automatically add to the classpath from:
 171
 172  * `$SQUIRRELJME_CLASSPATH/`
 173  * `$SQUIRRELJME_JAVA_HOME/lib/`
 174  * `$SQUIRRELJME_JAVA_HOME/jre/lib/`
 175  * `{Data}/lib/`