building.mkd

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