developer-guide.mkd

   1 # Developer Guide
   2
   3 This is a guide for developers to follow for various parts of the repository.
   4 This is mostly intended for maintainers of _SquirrelJME_.
   5
   6  * See the [Building](building.mkd).
   7  * Also see [Contributing](contributing.mkd).
   8
   9 ## Accepting Changes
  10
  11 ***TO BE WRITTEN***
  12
  13 ### Loading Contributions
  14
  15 ***TO BE WRITTEN***
  16
  17 #### Via Fossil Bundles
  18
  19 ***TO BE WRITTEN***
  20
  21 #### Via Git Bundles
  22
  23 ***TO BE WRITTEN***
  24
  25  * `git am < my-branch.bun`
  26
  27 ### Merging Branches
  28
  29 To merge a branch locally, do the following:
  30
  31  * Update to the branch that will get submissions merged into:
  32    * `fossil update trunk`
  33  * Merge the other branch into your current `trunk`:
  34    * `fossil merge other-branch`
  35  * Commit the changes:
  36    * `fossil commit`
  37    * Be sure to have a meaningful commit message, if the code is from a
  38      merge request on a remote repository, have the following in the commit
  39      message:
  40      * GitHub: `(GitHub Closes #1234)`
  41      * GitLab: `(GitLab Closes !1234)`
  42  * Synchronize the repositories:
  43    * `fossil sync -u`
  44
  45 ## Releasing
  46
  47 When a release is to be made, it is performed in another branch and becomes
  48 separate from `trunk`. This means that `trunk` is always in a state of
  49 perpetual development. Within these branches, there are bug fixes and
  50 releases. When a commit is ready for a release then it should just be tagged
  51 and built accordingly. It is best to avoid having releases and such in the
  52 `trunk` branch because it will complicate bug fixes and other things. So
  53 when a release is to be made:
  54
  55  * Update the changelog with the planned release date if it is known at the
  56    time, otherwise it is not known.
  57  * Fork the branch and make a new branch from `trunk` for the release to
  58    be done, an example would be `release-0.2.x`.
  59  * In the new `release-0.2.x` branch, update the version numbers in the
  60    appropriate places so things are updated.
  61  * Tag the commit as `0.2.0` or an increasing release version
  62    (example: `0.2.1`) for each increasing release.
  63  * Do all the common release stuff.
  64  * While in `trunk`, do the following:
  65    * The development version can be bumped in which case
  66      the version will be incremented by two and will be odd (3, 5, 7, etc.).
  67    * Add the next version to the changelog, so that it may be updated when
  68      there is a new major change.
  69
  70 ### RetroArch
  71
  72 For RetroArch, the SquirrelJME recipes should be updated to reflect the
  73 release tag.
  74
  75  * <https://github.com/libretro/libretro-super>
  76
  77 ### Bug-fix and Otherwise Releases
  78
  79 If a bug-fix or otherwise has to be done on a release version, since the
  80 release is in its own branch, the work can be done in that branch. Any fixes
  81 should have already been made in `trunk` if applicable, then it can be
  82 cherry picked into the release branch. Then once the fixes have been made and
  83 a new version is released the release version should be incremented (that is
  84 `0.2.0` to `0.2.1` to `0.2.2`). Then any of the release related stuff should
  85 be done.
  86
  87 ### Common Release Stuff
  88
  89 ***THIS IS OUT OF DATE AND WILL BE CHANGED TO BE DONE PURELY BY CI/CD,***
  90 ***SO THAT IT IS AUTOMATICALLY DONE AND CHECKED WITHOUT ISSUE.***
  91
  92 When a release is done, all of the binaries and according information must be
  93 updated. It is assumed that `SQUIRRELJME` is an environment variable to the
  94 root of the SquirrelJME source tree. Checkout the tag or commit which the
  95 release is to be done on. Then run the following command:
  96
  97  * `$SQUIRRELJME/utils-dev/uploadrelease.sh $__release_version__`
  98
  99 This will perform an auto-build of everything and then store the release in
 100 the `$__release_version__` directory, these binaries are important. Once the
 101 binaries and sources are built, they should be uploaded to the following
 102 locations:
 103
 104  * Fossil (<https://multiphasicapps.net/>)
 105    * The `uploadrelease.sh` script takes care of putting the files in the
 106      repository.
 107    * You will need to edit the download page to add the new version, this
 108      will be done with `fossil unversion edit download.mkd`.
 109    * Synchronize the repository with the unversioned space.
 110  * GitHub
 111    * Go to releases.
 112    * Draft a new release.
 113    * Choose the release tag you just made. Note that there might be a delay
 114      before GitHub is updated, so be patient or force it to update manually.
 115    * Title the release.
 116  * SourceForge
 117    * Create a new directory for the release number.
 118    * Upload all of the files into that directory.
 119    * Appropriately set the operating systems for the binaries.
 120
 121 ## Importing SquirrelJME Into Another Project
 122
 123 Any one of SquirrelJME's modules can be used as a dependency for a project.
 124 Note that the versions that are used depend on if a release is being used or
 125 not, which is in the format of `M.m.r` for releases and `M.m.r-SNAPSHOT` for
 126 development versions. Note that even minor versions are releases (ex: `0.4.0`),
 127 and odd minor versions are development versions (ex: `0.3.0-SNAPSHOT`).
 128
 129 ### Snapshot Repository
 130
 131 ```xml
 132 <!-- Maven -->
 133 <project>
 134     <repositories>
 135         <repository>
 136             <id>oss.sonatype.org-snapshot</id>
 137             <url>https://oss.sonatype.org/content/repositories/snapshots</url>
 138             <releases>
 139                 <enabled>false</enabled>
 140             </releases>
 141             <snapshots>
 142                 <enabled>true</enabled>
 143             </snapshots>
 144         </repository>
 145     </repositories>
 146 </project>
 147 ```
 148
 149 ```groovy
 150 // Gradle
 151 repositories {
 152     maven {
 153         url "https://oss.sonatype.org/content/repositories/snapshots"
 154     }
 155 }
 156 ```
 157
 158 # Debugging
 159
 160 SquirrelJME's VMs may be debugged by having it connect to a debugger or
 161 waiting for a debug connection. Debugging happens purely over TCP/IP. It
 162 is not possible to use existing debuggers to debug SquirrelJME virtual machines
 163 there are debug interfaces available through standardized JDWP. Note that
 164 it is _not_ recommended for the debugger port to be open to the internet as
 165 it will allow the remote debugger to have access to all the virtual machine
 166 internals.
 167
 168 Arguments to the virtual machines for _SpringCoat_, _SummerCoat_, etc.:
 169
 170  * Connect to remote debugger
 171    * `-Dsquirreljme.jdwp=localhost:5005`
 172  * Listen for a remote connection
 173    * `-Dsquirreljme.jdwp=:5005`
 174
 175 Instructions for specific debuggers:
 176
 177  * [jdb](
 178    https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/jdb.html)
 179    * Connect:
 180      * `jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=5005`
 181    * Listen:
 182      * `jdb -connect com.sun.jdi.SocketListen:port=5005`
 183  * [IntelliJ](
 184    https://www.jetbrains.com/help/idea/attaching-to-local-process.html)
 185  * [Eclipse](
 186    https://www.eclipse.org/community/eclipse_newsletter/2017/june/article1.php)
 187
 188 # IntelliJ
 189
 190 SquirrelJME uses IntelliJ IDEA Ultimate which is highly recommended for
 191 development.
 192
 193 ## Recommended Plugins
 194
 195 The following plugins are recommended:
 196
 197  * _EmbeddedProjectJdk_ -- Allows for custom defined JDKs, which SquirrelJME
 198    is its own JDK.
 199    * <https://plugins.jetbrains.com/plugin/10480-embeddedprojectjdk>
 200
 201 ## Custom File Type for Jasmin
 202
 203 IntelliJ supports custom file type definitions, the following is for
 204 Jasmin so that it has much better syntax highlighting.
 205
 206 Use the following setting:
 207
 208  * Name: `.j`
 209  * Description: `Jasmin Instructions`
 210  * Line comment: `;`
 211  * Line comment only at line start: `Checked`
 212  * Hex Prefix: `0x`
 213  * Support String Escapes: `Checked`
 214
 215 Then associated with:
 216
 217  * `*.j`
 218
 219 ### Keywords
 220
 221 The following goes into the keyword fields.
 222
 223 #### 1
 224
 225 ```text
 226 abstract
 227 final
 228 native
 229 private
 230 protected
 231 public
 232 static
 233 synchronized
 234 transient
 235 volatile
 236 ```
 237
 238 #### 2
 239
 240 ```text
 241 default
 242 boolean
 243 byte
 244 short
 245 char
 246 int
 247 long
 248 float
 249 double
 250 ```
 251
 252 #### 3
 253
 254 ```text
 255 .catch
 256 .class
 257 .end
 258 .end field
 259 .end method
 260 .field
 261 .implements
 262 .interface
 263 .limit
 264 .limit locals
 265 .limit stack
 266 .line
 267 .method
 268 .source
 269 .super
 270 .throws
 271 .var
 272 ```
 273
 274 #### 4
 275
 276 ```text
 277 aaload
 278 aastore
 279 aconst_null
 280 aload
 281 aload_0
 282 aload_1
 283 aload_2
 284 aload_3
 285 anewarray
 286 areturn
 287 arraylength
 288 astore
 289 astore_0
 290 astore_1
 291 astore_2
 292 astore_3
 293 athrow
 294 baload
 295 bastore
 296 bipush
 297 breakpoint
 298 caload
 299 castore
 300 checkcast
 301 d2f
 302 d2i
 303 d2l
 304 dadd
 305 daload
 306 dastore
 307 dcmpg
 308 dcmpl
 309 dconst_0
 310 dconst_1
 311 ddiv
 312 dload
 313 dload_0
 314 dload_1
 315 dload_2
 316 dload_3
 317 dmul
 318 dneg
 319 drem
 320 dreturn
 321 dstore
 322 dstore_0
 323 dstore_1
 324 dstore_2
 325 dstore_3
 326 dsub
 327 dup
 328 dup2
 329 dup2_x1
 330 dup2_x2
 331 dup_x1
 332 dup_x2
 333 f2d
 334 f2i
 335 f2l
 336 fadd
 337 faload
 338 fastore
 339 fcmpg
 340 fcmpl
 341 fconst_0
 342 fconst_1
 343 fconst_2
 344 fdiv
 345 fload
 346 fload_0
 347 fload_1
 348 fload_2
 349 fload_3
 350 fmul
 351 fneg
 352 frem
 353 freturn
 354 fstore
 355 fstore_0
 356 fstore_1
 357 fstore_2
 358 fstore_3
 359 fsub
 360 getfield
 361 getstatic
 362 goto
 363 goto_w
 364 i2d
 365 i2f
 366 i2l
 367 iadd
 368 iaload
 369 iand
 370 iastore
 371 iconst_0
 372 iconst_1
 373 iconst_2
 374 iconst_3
 375 iconst_4
 376 iconst_5
 377 iconst_m1
 378 idiv
 379 if_acmpeq
 380 if_acmpne
 381 if_icmpeq
 382 if_icmpge
 383 if_icmpgt
 384 if_icmple
 385 if_icmplt
 386 if_icmpne
 387 ifeq
 388 ifge
 389 ifgt
 390 ifle
 391 iflt
 392 ifne
 393 ifnonnull
 394 ifnull
 395 iinc
 396 iload
 397 iload_0
 398 iload_1
 399 iload_2
 400 iload_3
 401 imul
 402 ineg
 403 instanceof
 404 int2byte
 405 int2char
 406 int2short
 407 invokenonvirtual
 408 invokestatic
 409 invokevirtual
 410 ior
 411 irem
 412 ireturn
 413 ishl
 414 ishr
 415 istore
 416 istore_0
 417 istore_1
 418 istore_2
 419 istore_3
 420 isub
 421 iushr
 422 ixor
 423 jsr
 424 jsr_w
 425 l2d
 426 l2f
 427 l2i
 428 ladd
 429 laload
 430 land
 431 lastore
 432 lcmp
 433 lconst_0
 434 lconst_1
 435 ldc
 436 ldc_w
 437 ldiv
 438 lload
 439 lload_0
 440 lload_1
 441 lload_2
 442 lload_3
 443 lmul
 444 lneg
 445 lookupswitch
 446 lor
 447 lrem
 448 lreturn
 449 lshl
 450 lshr
 451 lstore
 452 lstore_0
 453 lstore_1
 454 lstore_2
 455 lstore_3
 456 lsub
 457 lushr
 458 lxor
 459 monitorenter
 460 monitorexit
 461 multianewarray
 462 new
 463 newarray
 464 nop
 465 pop
 466 pop2
 467 putfield
 468 putstatic
 469 ret
 470 return
 471 saload
 472 sastore
 473 sipush
 474 swap
 475 tableswitch
 476 ```
 477