building.mkd

   1 # Building
   2
   3 ------------------------------------------------------------------------------
   4
   5 ***Patience is required:***
   6 ***Currently SquirrelJME is in active development and although it can***
   7 ***run and produce binaries, there are limitations to consider.***
   8 ***Currently only a limited set of programs may be ran on SquirrelJME.***
   9
  10 ------------------------------------------------------------------------------
  11
  12 SquirrelJME requires the following before it can be built:
  13
  14  * Java 8 or newer Virtual Machine and Compiler
  15  * C++ Compiler (Utilized for Testing)
  16    * Clang
  17    * GCC
  18    * Microsoft Visual Studio 2010 or newer
  19    * XCode
  20
  21 ## Notes on Running
  22
  23 SquirrelJME uses a simplified error system which starts with a two capital
  24 letter prefix followed by two digits and letters.
  25
  26  * [List of Error Codes](http://multiphasicapps.net/uv/errors.mkd)
  27
  28 ## Installing Java
  29
  30 SquirrelJME requires a Java 8 virtual machine in order to build itself. Gradle
  31 is used as well however it is available through Gradle Wrapper.
  32
  33 ### AdoptOpenJDK (Windows, Linux, and Mac OS X)
  34
  35 AdoptOpenJDK is the recommended way to build and setup SquirrelJME as it has
  36 long-term support and is easy to setup. You will need at least a Java 8
  37 variant of AdoptOpenJDK.
  38
  39  * <https://adoptopenjdk.net/releases.html?variant=openjdk8&jvmVariant=hotspot>
  40
  41 Please note that Java 11 may be used as well.
  42
  43 ### Oracle's JDK (Windows, Linux, and Mac OS X)
  44
  45 Oracle's JDK supports modern systems and can be downloaded from:
  46
  47  * <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
  48
  49 Ensure that you **download and install** the ***JDK***.
  50
  51 If running on ReactOS/Windows/Wine, make sure that the `PATH` environment
  52 variables refers to the JDK's binary directory:
  53
  54  * `C:\Program Files\Java\jdk1.8.0_131\bin\`
  55
  56 ### Common Linux Distributions
  57
  58 If you use a common and popular Linux distribution it likely has a JDK
  59 available.
  60
  61  * Arch
  62    * See <https://wiki.archlinux.org/index.php/Java>
  63  * Debian, Ubuntu, and derivatives
  64    * See <https://wiki.debian.org/Java>
  65    * One of the following depending on package availability
  66      * `apt-get install openjdk-8-jdk`
  67      * `apt-get install openjdk-9-jdk`
  68      * `apt-get install openjdk-11-jdk`
  69  * Gentoo
  70    * See <https://wiki.gentoo.org/wiki/Java>
  71
  72 ### Running via IDEs
  73
  74 #### IntelliJ IDEA
  75
  76 SquirrelJME is developed on IntelliJ Ultimate, however Community Edition may
  77 still be used. This makes development easier and more integrated along with
  78 whatever code you write or contribute will match the style that is set in
  79 SquirrelJME.
  80
  81  * <https://www.jetbrains.com/idea/>
  82
  83 #### VSCode
  84
  85 The following extensions are required to build and run SquirrelJME in VSCode:
  86
  87  * [Extension Pack for Java](
  88  https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
  89    * `ext install vscjava.vscode-java-pack`
  90  * [Gradle for Java](
  91  https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle)
  92    * `ext install vscjava.vscode-gradle`
  93
  94 Before running on VSCode you must run the following Gradle command, since this
  95 uses a similar code base that is borrowed from Eclipse:
  96
  97  * Setup Eclipse Project
  98    * Windows: `gradlew eclipse`
  99    * Linux/MacOS: `./gradlew eclipse`
 100
 101 #### Eclipse
 102
 103 Before running on Eclipse you must run the following Gradle command:
 104
 105  * Setup Eclipse Project
 106    * Windows: `gradlew eclipse`
 107    * Linux/MacOS: `./gradlew eclipse`
 108
 109 Then following this you may _Import Existing Gradle Project_ and you will have
 110 access to the project for building.
 111
 112 ## Installing C++ Compiler
 113
 114 ### Common Linux Distributions
 115
 116 For the C++ Compiler which is needed for testing:
 117
 118  * Debian, Ubuntu, and derivatives
 119    * `apt-get install build-essential g++`
 120    * `apt-get install build-essential clang`
 121
 122 ### Windows
 123
 124 For Gradle to detect a C++ compiler, it needs either Microsoft Visual Studio
 125 or a GCC installation via Cygwin, or a GCC installation via Mingw-w64.
 126
 127 More information is located at
 128 <https://docs.gradle.org/current/userguide/building_cpp_projects.html#windows>.
 129
 130 #### Microsoft Visual Studio
 131
 132 Microsoft's Visual Studio may be used by Gradle to compile the code, note that
 133 it only uses the compiler tool from the installation (no GUI is needed).
 134
 135  * Download from <https://visualstudio.microsoft.com/downloads/>.
 136  * At the minimum, the following must be installed (pieces that are crossed
 137    out may be different for future versions of Microsoft's Compiler):
 138    * _Windows Universal C Runtime_
 139    * _C++ Build Tools core Features_
 140    * _MSVC ~~v142~~ - VS ~~2019~~ C++ ~~x86/x64~~ build tools_
 141    * _C++ Redistributable Update_
 142    * _Windows 10 SDK_
 143  * Alternatively, you can run the Visual Studio installer and import the
 144    components file, this file can be found in the root and is called
 145    `.vsconfig`.
 146
 147 #### Mingw-w64
 148
 149 You can use Mingw-w64 as well, it is a freely available compiler.
 150
 151  * Main web site: <https://mingw-w64.org>.
 152  * In the downloads section it is recommended to use _MingW-W64-builds_:
 153    * For the configuration use:
 154      * GCC Version: The latest (at time of writing it was 8.0.0).
 155      * Threads: _win32_.
 156      * Exception Handling: _seh_.
 157      * Install both 32-bit and 64-bit.
 158
 159 #### Cygwin
 160
 161 You can also download Cygwin at: <https://www.cygwin.com/>.
 162
 163 ### Mac OS X
 164
 165 You must install XCode, more information on XCode is at
 166 <https://developer.apple.com/xcode/>. Alternatively there is a command line
 167 tool to install the XCode command line utilities for example if you are
 168 using Brew:
 169
 170  * `xcode-select --install`
 171
 172 # Build Environment
 173
 174 The main interaction with the SquirrelJME build environment is with Gradle
 175 which manages anything related to building and testing. All builds are
 176 performed through Gradle Wrapper which is used as the following:
 177
 178  * Windows: `gradlew`
 179  * Others: `./gradlew`
 180
 181 Gradle uses tasks of which multiple may be specified accordingly, such as
 182 running the tests within the repository:
 183
 184  * `gradlew test`
 185
 186 If using IntelliJ you may tap _Ctrl_ twice (_Ctrl_+_Ctrl_) and type in the
 187 following to run Gradle commands, it should automatically use the wrapper:
 188
 189  * `gradle`
 190
 191 ## RetroArch
 192
 193 Building for RetroArch uses the `makefilelibretro` makefile. As such building
 194 SquirrelJME for your current system involves using the alternative makefile.
 195
 196  * `make`
 197  * Windows:
 198    * `make -f makefilelibretro CC=i686-w64-mingw32-gcc platform=mingw_x86`
 199    * `make -f makefilelibretro CC=x86_64-w64-mingw32-gcc platform=mingw_x86_64`
 200
 201 ## Docker
 202
 203 In the root directory, execute the command:
 204
 205  * `docker build .`
 206
 207 This will create an image that you will be able to use to execute one of
 208 the built-in virtual machines.
 209
 210 # Development Virtual Machines
 211
 212 For development purposes you may use the virtual machines provided by the
 213 SquirrelJME run-time. Modules within SquirrelJME have tasks which allow them
 214 to be ran accordingly.
 215
 216  * SpringCoat
 217    * `:modules:<name>:runSpringCoatDebug` (running)
 218    * `:modules:<name>:runSpringCoatRelease` (running)
 219    * `:modules:<name>:testSpringCoat` (testing)
 220  * Native (runs on the host Java SE)
 221    * `:modules:<name>:runHostedDebug` (running)
 222    * `:modules:<name>:testHostedDebug` (testing)
 223
 224 Note that the `test` task is not supported and will throw an exception, it
 225 is not able to reliably test within SquirrelJME.
 226
 227 The following _System_ properties are available:
 228
 229  * `squirreljme.jdwp=[hostname]:port` -- Enable JDWP.
 230    * Enables JDWP for the given virtual machine.
 231    * If only `:port` is specified it will listen for incoming connections from
 232      a debugger.
 233    * If both `hostname:port` is specified it will connect to a remote debugger.
 234    * Note that if the hosted environment is debugged, launched sub-tasks will
 235      not be run under the debugger.
 236  * `squirreljme.xjdwp=[hostname]:port` -- Enable JDWP for Hosted environment.
 237    * Does the same as `squirreljme.jdwp` but takes priority if both are
 238      specified in the event that debugging should be done for the hosted
 239      process.
 240  * `squirreljme.midlet=value` -- The MIDlet to run, in the following order:
 241    * If `value` is a number and is `-1`, then no MIDlet will be selected and
 242      the `Main-Class` attribute will be force selected.
 243    * If `value` is a number, then it will be treated as an index. If the index
 244      is in bounds it will run the given MIDlet by index.
 245    * If `value` is a string, then a search will be performed for a MIDlet
 246      with a matching case-insensitive title.
 247    * If `value` is a string and starts or ends with an asterisk (`*`) then
 248      it will find a midlet whose title contains the text with a
 249      case-insensitive search.
 250    * Otherwise if `value` is a string, it will construct a virtual MIDlet
 251      which executes the given value as the name of a class within the JAR.
 252  * `squirreljme.sysprop.<systemProperty>=value` -- Add system property.
 253    * This allows any system properties that are prefixed with this to be
 254      added into the target virtual machine when running.
 255    * As an example `squirreljme.sysprop.favorite.animal=squirrel`:
 256      * Will define system property `favorite.animal=squirrel` within the
 257        virtual machine.
 258  * `squirreljme.thread=value` -- The threading model to use.
 259    * `single` or `coop` -- Single Cooperatively Threaded.
 260    * `multi` or `smt` -- Simultaneous Multi-Threading.
 261  * `test.single=classname` -- Run only the given test:
 262    * Will be the test class to be run.
 263    * Multi-parameter tests are in the form of `classname@parameter`, if a
 264      parameter is specified then only that one will be matched. Otherwise
 265      this will include all tests of that given parameter.
 266
 267 # Building ROMs
 268
 269 Full ROMs can be built with the following tasks, note that test ROMs contain
 270 all the testing libraries and are generally used to ensure things are working:
 271
 272 # Full Suite Virtual Machines
 273
 274 There is a task which initializes a full suite of SquirrelJME, including
 275 every module. This can be used to run a specific program within SquirrelJME's
 276 environment through Gradle.
 277
 278  * Hosted Environment.
 279    * `fullHostedDebug`
 280  * SpringCoat
 281    * `fullSpringCoatRelease`
 282    * `fullSpringCoatDebug`
 283
 284 There are system properties that are available and can be used to modify
 285 the behavior:
 286
 287  * `full.libraries=path...` -- Additional libraries to place onto the
 288    suite path.
 289    * Same format as the `-classpath` argument. On Windows this will use `;`
 290      as separators, while other systems will use `:`.
 291  * `cc.squirreljme.vm.trace=option[,option[,...]]` -- Trace options
 292    * `all` -- Enable all.
 293    * `instructions` -- Instructions being executed.
 294    * `methodEntry` -- Entry of methods.
 295    * `methodExit` -- Exit of methods.
 296    * `mleCall` -- SquirrelJME MLE Native Calls.
 297    * `invokeStatic` -- Static invocations.
 298    * `allocation` -- Allocations such as `new`.
 299    * `classInitialize` -- Class is initialized.
 300    * `vmException` -- Virtual machine exceptions.
 301    * `missingClass` -- Class does not exist.
 302    * `monitorEnter` -- Monitor is entered.
 303    * `monitorExit` -- Exiting a monitor.
 304    * `monitorWait` -- Monitor is waited on.
 305    * `monitorNotify` -- Monitor is notified.
 306    * `threadNew` -- New thread is created.
 307
 308 # New Java Version Contingency
 309
 310 With regard to <https://github.com/SquirrelJME/SquirrelJME/issues/6> if in
 311 the event this occurs, building with Gradle will attempt to use the
 312 Eclipse Java Compiler to compile the project. It may be forced by passing
 313 to Gradle `-Dforce.ecj=true`.
 314
 315 # Standalone Java Based Emulators
 316
 317 A standalone Java emulator Jar which contains all of the available test
 318 virtual machine implementations is available when calling the task:
 319
 320  * `:emulators:standalone:shadowJar`
 321
 322 ## Mac OS
 323
 324 This is used with [Homebrew](https://brew.sh/), with checked
 325 out source code the following can be run:
 326
 327  * brew install --HEAD Formula/squirreljme-standalone.rb`