Forth-eV Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Gforth — GNU Forth for Android ======

Project goal is to use [[https://bernd-paysan.de/gforth.html|Gforth]] as programming system on Android.
===== Project Status =====

  * There is [[https://play.google.com/store/apps/details?id=gnu.gforth&|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):

  * [[https://play.google.com/store/apps/details?id=org.pocketworkstation.pckeyboard|Hackers Keyboard]]
  * [[https://play.google.com/store/apps/details?id=de.ubuntix.android.mygermankeyboard|Deutsche Tastatur]]
  * [[https://play.google.com/store/apps/details?id=com.jb.gokeyboard|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]]
===== Examples =====

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

  * ''[[https://github.com/forthy42/gforth/tree/master/minos2/gl-sample.fs|minos2/gl-sample.fs]]'': A simple OpenGL demo
  * ''[[https://github.com/forthy42/gforth/tree/master/minos2/omx-example.fs|minos2/omx-example.fs]]'': Playing videos.  Download my [[http://bernd-paysan.de/jb.mkv|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''.
  * ''[[https://github.com/forthy42/gforth/tree/master/minos2/gl-slideshow.fs|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''.
  * ''[[https://github.com/forthy42/gforth/tree/master/minos2/android-recorder.fs|minos2/android-recorder.fs]]'': Records a video, when you start ''camera-test''.  The recorded video will end up in ''/storage/extSdCard/Filme/test.mp4''.
  * ''[[https://github.com/forthy42/gforth/tree/master/unix/sensors.fs|unix/sensors.fs]]'': Read out Android sensors

===== JNI Interface =====

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

===== OpenGL =====

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

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/''.
===== Documentation =====

Gforth has a [[http://www.complang.tuwien.ac.at/forth/gforth/Docs-html/|big manual]], which is also available as {{:projects:gforth-android:gforth.pdf|eBook PDF}} (some non-breakable texts are cut off in this small size).