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 # Building ROMs
 269
 270 Full ROMs can be built with the following tasks, note that test ROMs contain
 271 all the testing libraries and are generally used to ensure things are working:
 272
 273 # Full Suite Virtual Machines
 274
 275 There is a task which initializes a full suite of SquirrelJME, including
 276 every module. This can be used to run a specific program within SquirrelJME's
 277 environment through Gradle.
 278
 279  * Hosted Environment.
 280    * `fullHostedDebug`
 281  * SpringCoat
 282    * `fullSpringCoatRelease`
 283    * `fullSpringCoatDebug`
 284
 285 There are system properties that are available and can be used to modify
 286 the behavior:
 287
 288  * `full.libraries=path...` -- Additional libraries to place onto the
 289    suite path.
 290    * Same format as the `-classpath` argument. On Windows this will use `;`
 291      as separators, while other systems will use `:`.
 292  * `cc.squirreljme.vm.trace=option[,option[,...]]` -- Trace options
 293    * `all` -- Enable all.
 294    * `instructions` -- Instructions being executed.
 295    * `methodEntry` -- Entry of methods.
 296    * `methodExit` -- Exit of methods.
 297    * `mleCall` -- SquirrelJME MLE Native Calls.
 298    * `invokeStatic` -- Static invocations.
 299    * `allocation` -- Allocations such as `new`.
 300    * `classInitialize` -- Class is initialized.
 301    * `vmException` -- Virtual machine exceptions.
 302    * `missingClass` -- Class does not exist.
 303    * `monitorEnter` -- Monitor is entered.
 304    * `monitorExit` -- Exiting a monitor.
 305    * `monitorWait` -- Monitor is waited on.
 306    * `monitorNotify` -- Monitor is notified.
 307    * `threadNew` -- New thread is created.
 308
 309 # New Java Version Contingency
 310
 311 With regard to <https://github.com/SquirrelJME/SquirrelJME/issues/6> if in
 312 the event this occurs, building with Gradle will attempt to use the
 313 Eclipse Java Compiler to compile the project. It may be forced by passing
 314 to Gradle `-Dforce.ecj=true`.
 315
 316 # Standalone Java Based Emulators
 317
 318 A standalone Java emulator Jar which contains all of the available test
 319 virtual machine implementations is available when calling the task:
 320
 321  * `:emulators:standalone:shadowJar`
 322
 323 ## Flatpak
 324
 325 This is used with [Flatpak](https://www.flatpak.org/). This requires some dependencies first:
 326
 327  * Install `flatpak-builder`
 328  * `flatpak install flathub org.freedesktop.Platform//23.08`
 329  * `flatpak install flathub org.freedesktop.Sdk//23.08`
 330  * `flatpak install flathub org.freedesktop.Sdk.Extension.openjdk11`
 331
 332 With the dependencies installed, it may be built with:
 333
 334  * `flatpak-builder build-dir cc.squirreljme.SquirrelJME.yml`
 335  * `flatpak-builder --user --install build-dir `
 336    ` cc.squirreljme.SquirrelJME.yml`
 337
 338 To bundle into a single file, run the following:
 339
 340  * `flatpak build-bundle $HOME/.local/share/flatpak/repo squirreljme.flatpak `
 341    ` cc.squirreljme.SquirrelJME`
 342
 343 To run from the command line, you may want to add to your `PATH`:
 344
 345  * `$HOME/.local/share/flatpak/exports/bin/`
 346
 347 ## Mac OS
 348
 349 This is used with [Homebrew](https://brew.sh/), with checked
 350 out source code the following can be run:
 351
 352  * brew install --HEAD Formula/squirreljme-standalone.rb`