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  * `-Xemulator:(vm)`
  40    * Specifies the backend emulator to use, the supported options are:
  41      * `hosted` -- Uses the host JVM to run all the software.
  42      * `springcoat` -- SpringCoat, interpreter written in Java.
  43      * `nanocoat` -- NanoCoat, interpreter written in C.
  44  * `-Xsnapshot:(path-to-nps)`
  45    * Profile the virtual machine and store the profile results into the
  46      given VisualVM snapshot file.
  47  * `-Xlibraries:(class:path:...)`
  48    * Specifies libraries that should be available to the virtual machine
  49      and the suite management system, note that this is not the same as
  50      the `-classpath` option as that is for the _current_ application.
  51    * Wildcard directories may be specified in the following way, depending
  52      on the operating system and possible shell expansion:
  53      * `/path/to/directory/*`
  54      * `/path/to/directory/**`
  55      * `/path/to/directory/*.*`
  56      * `wildcard=/path/to/directory`
  57  * `-Xentry:id`
  58    * Used with `-jar`, this allows one to specify an entry point index,
  59      application name, or application entry point to determine which one to
  60      launch within the Jar as there may be multiple.
  61    * By default, if not specified, the first is always used.
  62  * `-Xjdwp:[hostname]:port`
  63    * Enable debugging.
  64    * If `hostname` is specified then the debugger will connect to the
  65      remote host that is a listening JDWP debugger.
  66    * Otherwise, if only `port` is specified then the debugger will wait and
  67      listen on the given port for an incoming connection.
  68  * `-Xclutter:(release|debug)`
  69    * Use the given core libraries with the given clutter level.
  70    * `release` includes obfuscation and no debugging and thus runs faster.
  71    * `debug` does not have any obfuscation and may work in cases where
  72      obfuscation and optimization may cause issues.
  73  * `-Xdebug[:fork|nofork]`
  74    * Enable debugging but with the internal built-in SquirrelJME debugger and
  75      not a JDWP connection over TCP.
  76    * This is supported under the `hosted` emulator, however if you launch
  77      another application within it will not debug that process, therefor if
  78      you wish to debug you should use `-jar`.
  79    * Optionally, `fork` or `nofork` can be specified to where the
  80      internal debugger to launched as a separate process or not.
  81  * `-Xscritchui:(ui)`
  82    * Rather than the default, use a specific user interface library.
  83    * This may also be set by using `cc.squirreljme.scritchui`.
  84  * `-Xthread:(single|coop|multi|smt)`
  85    * Sets the threading mode of the virtual machine.
  86    * `single`/`coop` -- Single threaded using cooperative multitasking.
  87    * `multi`/`smt` -- Multi threaded using asynchronous multitasking.
  88  * `-Xtrace:option[,option[,...]]` -- Trace options
  89    * `all` -- Enable all.
  90    * `allocation` -- Allocations such as `new`.
  91    * `classInitialize` -- Class is initialized.
  92    * `ignoredException` -- Exception that may be ignored.
  93    * `instructions` -- Instructions being executed.
  94    * `invokeStatic` -- Static invocations.
  95    * `methodEntry` -- Entry of methods.
  96    * `methodExit` -- Exit of methods.
  97    * `missingClass` -- Class does not exist.
  98    * `mleCall` -- SquirrelJME MLE Native Calls.
  99    * `monitorEnter` -- Monitor is entered.
 100    * `monitorExit` -- Exiting a monitor.
 101    * `monitorNotify` -- Monitor is notified.
 102    * `monitorWait` -- Monitor is waited on.
 103    * `threadNew` -- New thread is created.
 104    * `vmException` -- Virtual machine exceptions.
 105  * `-Dsysprop=value`
 106    * Defines the given system property.
 107  * `-classpath (class:path:...)`
 108    * Specifies the class path to use for the current application, the entries
 109      must be visible from the library path.
 110  * `-zero` -- Alias for `-Xemulator:springcoat`.
 111  * `-Xint` -- Alias for `-Xemulator:springcoat`.
 112  * `-client` -- Ignored.
 113  * `-server` -- Ignored.
 114
 115 ## Default Configuration and Library Paths
 116
 117 SquirrelJME may be configured automatically via files on the file system. The
 118 following paths are considered for automatic configuration and classpath
 119 inclusion.
 120
 121  * Windows:
 122    * Cache: `%LOCALAPPDATA%/squirreljme/cache`
 123      * Or otherwise `%PROGRAMDATA%/squirreljme/cache`
 124    * Configuration: `%APPDATA%/squirreljme/config`
 125      * Or otherwise `%PROGRAMDATA%/squirreljme/config`
 126    * Data: `%APPDATA%/squirreljme/data`
 127      * Or otherwise `%PROGRAMDATA%/squirreljme/data`
 128  * Linux, macOS, BSD, and other UNIX/UNIX-like systems:
 129   * Cache: `$XDG_CACHE_HOME/squirreljme`
 130     * Or otherwise `$HOME/.cache/squirreljme`
 131   * Configuration: `$XDG_CONFIG_HOME/squirreljme`
 132     * Or otherwise `$HOME/.config/squirreljme`
 133   * Data: `$XDG_DATA_HOME/squirreljme`
 134     * Or otherwise `$HOME/.local/share/squirreljme`
 135
 136 To override the defaults, you may instead use the following, if any start
 137 with `~` that is replaced with `$HOME` or `%USERPROFILE%`:
 138
 139  * `SQUIRRELJME_CACHE_HOME` for _Cache_ path.
 140  * `SQUIRRELJME_CONFIG_HOME` for _Configuration_ path.
 141  * `SQUIRRELJME_DATA_HOME` for _Data_ path.
 142
 143 SquirrelJME will automatically add to system properties for a properties file:
 144
 145  * `$SQUIRRELJME_JAVA_OPTS`
 146    * In the form of `"-Dproperty=value -Dcute=squirrel"`
 147  * `{Configuration}/squirreljme.properties`
 148    * In the form of `property=value` on individual lines.
 149
 150 SquirrelJME will automatically add to the classpath from:
 151
 152  * `$SQUIRRELJME_CLASSPATH/`
 153  * `$SQUIRRELJME_JAVA_HOME/lib/`
 154  * `$SQUIRRELJME_JAVA_HOME/jre/lib/`
 155  * `{Data}/lib/`