Gforth — GNU Forth for Android

Project goal is to use Gforth as programming system on Android.

• There is Gforth in Play Store, installable on Android 4.0 (Android 2.3 support dropped on 2018-03-31) or later (native activity)
• This has a OpenGL terminal emulation and allows remote telnet on port 4444 after you type in t and return.
• It recognizes touches, and the menu button/softkey toggles the software keyboard
• If the font is too small/large, use gl-fscale ( r – ) with a float number as scale factor (<1 makes the font smaller, >1 bigger). Example: 3e gl-fscale makes the font three times larger, 0.5e gl-fscale smaller by a factor of two.

Starting the app first time unpacks the Gforth sources to the SD card. That's a few megabytes, and therefore it takes its time. Gforth shows a spinning wheel while it's doing so, but can't respond to any input events. If the spinner shows you “Done; restart Gforth” for a while, you should kill and restart Gforth - it got stuck. If you still have problems, there's a gfortherr.log and a gforthout.log in /sdcard, which might provide more diagnosis.

The terminal uses a fragment shader, which implements a colored ASCII terminal - it uses two textures, one with the character set, and another with the characters and colors. An update of the terminal screen therefore only takes a few milliseconds - just like it used to be with in text mode. This has been tested with several really cheap phones with awful OpenGL implementations, so it should work on yours, too.

I recommend the following keyboards (in that order):

• Hackers Keyboard
• Deutsche Tastatur
• Go Keyboard

Since Android apps can't be started from the command line, you can enter options for starting Gforth in the file /sdcard/gforth/home/.options. One line per option. -d64k e.g. sets the stack to 64kB, -m16M the dictionary to 16MB, see http://www.complang.tuwien.ac.at/forth/gforth/Docs-html/Invoking-Gforth.html

All Android examples are packet into /sdcard/gforth/<version>/minos2. There is

• minos2/gl-sample.fs: A simple OpenGL demo
• minos2/omx-example.fs: Playing videos. Download my Jingle Bells as test stream into /storage/extSdCard/Filme, then you can start it with jb, or any other MPEG 2 transport stream file with “<filename>” play-ts, or a MKV file (H.264, MP3 or AAC) with “<filename>” play-mkv.
• minos2/gl-slideshow.fs: Plays a slideshow. Put photos into a directory, and a file listing all filenames (including path). Load that file with “<slidelist>” slide-show.
• minos2/android-recorder.fs: Records a video, when you start camera-test. The recorded video will end up in /storage/extSdCard/Filme/test.mp4.
• unix/sensors.fs: Read out Android sensors

Android's native API is Java. To access Java, the vocabulary jni contains helper words and some predefined interface words. Calls to Java are usually related to some object; the interface is compatible to Mini-OOF2 with its current objects.

• >o ( addr o:old – o:addr r:old ) makes addr the current object, and pushes the previous current object onto the return stack.
• o> ( o:addr r:old – o:old ) pops the previous object from the return stack.
• xref> ( o:addr r:old – o:old ) same as o>, but includes releasing a local reference. Unlike Java's heap and stack, JNI memory is not part of the garbage collector, and therefore uses reference counting. If you get an object from a Java call, you should use xref> to pop it after use, this allows the garbage collector to release this object. There is only a limited space for references, so release them soon. xref> determines, which sort of reference that is, and correctly handles global and temporary references.

To define a method or a field, you use the following words:

• jni-class: ( “name” – ) This sets the current class to “name”, which is the full scope hierarchy, using / as separator. Example jni-class: java/lang/String.
• jni-method: ( “forth-name” “java-name” “signature” – ) This defines a word “forth-name” which calls the Java method “java-name” on the current class with the specified API signature. Signatures have call parameters in parenthesis () and the return parameter afterwards:
  • Z boolean
  • B byte
  • C character
  • S short
  • I int
  • J long (double integer in Forth)
  • F float
  • D double
  • L<class>; object pointer of type <class>
  • [<type> array of the mentioned type
• jni-static: ( “forth-name” “java-name” “signature” – ) same as jni-method: but for static methods
• jni-new: ( “forth-name” “signature” – ) Constructor
• jni-field: ( “forth-name” “java-name” “signature” – ) field (i.e. instance variable), the signature here is only the return value
• jni-sfield: ( “forth-name” “java-name” “signature” – ) static field

The vocabulary OpenGL contains OpenGL ES 2.0 bindings (generated from the header files, including extensions and EGL bindings).

Gforth logs info into the files /sdcard/gfortherr.log and /sdcard/gforthout.log. If something goes wrong, look here if you find an error message. If a source file is missing or defect, you can remove /sdcard/gforth/; it is sufficient if you delete the file sha256sum in the subfolder with the current release name. Sometimes, files move after an update, in that case, you might better remove the entire /sdcard/gforth/.

Gforth has a big manual, which is also available as eBook PDF (some non-breakable texts are cut off in this small size).