LATEST RELEASE August, 28th 2014 - "Emerald b3"

What is YAXX?

One could consider YAXX as a collection of many pieces of code that have been developed along a period of 25 years of fun at doing programming.

• toolslib gathers C++ objects that were missing from the original C++ libraries (and, in my opinion, the gap was never filled the way Java designers did it later.)

• decnblib is Mike Cowlishaw's decimal number library, getting rid of the 16-bit arithmetic barrier

• stdiolib makes a bridge from the C-stdio to java, easing the exchange of data via streams.

• yasp3lib is an SGML Parser (SGML being the precursor of XML)

• rexxlib provides all objects and methods required by the implementation of the Rexx interpreter (Restructured extended editor)

Fortunately, YAXX is not just a miscellany of heterogeneous (although usefull) routines. It provides the means to build a REXX interpreter (ANSI X3.274), and this is how most people will understand YAXX.

Any doc?

No real detailed documentation. After all, Rexx is … Rexx, a well documented programming language and the Rexxoid application should be enough intuitive to get you up and running quite immediately.
REXX scripts can be found here: on a time permits basis, I will try to add the most relevant examples. Also, you will find here a series of screenshots describing in short how Rexx shows up on an Android device.

Installing REXX

If you don't want to build Rexx or Rexxoid, but just install it, pre-built executables are provided for Android, Linux and Windows.

• For Rexxoid -- Rexx for Android -- the recommended way is to install it from Google Play Store, or, only as an alternative, you can download it using the procedure described next and mail the Rexxoid.apk file to your email account on your android device.
• To download Rexx to your computer:
  • Navigate to the releases page
  • Download the appropriate version and file
  • Install it on your device.
• If the proposed pre-builts do not match your OS versions, you will have to build it by yourself. As explained below, the repository provides the appropriate makefiles and it's not so difficult to do.

Importing my beloved REXX scripts in Android

• Insert a comment in the first line of each script, with a couple of words identifying the script.
• Send the script(s) as mail attachments to your email account on your android device, open the mail, save the attachment.
• Start REXX and press to the (hardware) left button on your phone. In the options menu, choose import.

Note that tapping on a file or on an email attachment with a .rexx extension automatically launch Android REXX.

Building REXX

The libraries have been tested in several OS environments, which ascertains their portability and robustness. Besides classical OS's (Linux, MS Windows), Palm OS was one of the first candidate for writing "REXX for Palm OS" at the beginning of the 2000's. In 2010, REXX was ported to Android...

Rexx on Android

• First is to create the .so libraries required by the Java Native Interface.
• Then, to build the rexxoid.apk. It adds the Android's Graphic User Interface (GUI layer) leading to the final and only piece to upload to the Android device. We will make this Application PacKage by creating an Android Project under the Eclipse IDE.

Summary, only for experts

cd ~/yaxx/android
(your path to the android ndk)/ndk-build

This produces the .SO files in ~/yaxx/android/libs/armeabi
"libs/armeabi" needs to be ln -s'ed from your Android project directory.

cd ~/yaxx/android
ant clean release

produces the final Rexxoid-release.apk in the android/bin directory.

My Personal Cheatsheet

• the ~/yaxx/android/jni directory contains the android makefiles;
  
• to examine .so entries, do

     nm -gC libtoolslib.so     or,
     readelf -Ws libtoolslib.so | awk "{print $8}"
  

• to start an emulator from the console:

     android create avd --force -n petrus -t 10 -c 2G
     emulator -avd petrus
  

Detailed Instructions

• These instructions have been tested on Linux Ubuntu 12.04
  
• In what follows, you must replace the symbol [\$home] with the fully qualified name of your home directory.
  Ex: [\$home] -> /home/myuserid

Building the .so files

1. First is to get yaxx from this git

   cd ~
   git clone https://github.com/Jaxo/yaxx.git
   

   creates the yaxx directory in your home (i.e.:  [$home]/yaxx)
   
2. Install the Android NDK: android-ndk-r9-linux-x86.tar.bz2 from here
   
   "NDK" — not to be confused with "SDK" — is a complementary tool. 
   To install it, after download, I did:

   cd /usr/local
   sudo mv ~/Downloads/android-ndk-r9-linux-x86.tar.bz2 .
   sudo tar -xjvf android-ndk-r9-linux-x86.tar.bz2
   sudo rm android-ndk-r9-linux-x86.tar.bz2
   cd ~

3. Build the .so:

   cd ~/yaxx/android
   /usr/local/android-ndk-r9/ndk-build
   

   The ".so" files are created in ~/yaxx/android/libs/armeabi.  Later, these will be symbolically linked from the Eclipse Android project.

Create and run the "Rexxoid" project in Eclipse

Before to start, you may want you get acquainted to Android debug mechanism at reading this document.

1. Install Eclipse.  you can download it from here
   
2. Install the Android plugin for Eclipse.  Go to that page and carefully follow the instructions.
   
3. Start Eclipse, File -> Import… -> Android -> Existing Android Code Into Workspace -> Next
   
4. In the dialog Import Projects:

     Root Directory:  [$home]/yaxx/android
     Copy projects into workspace stays unchecked
     Add project to working sets stays unchecked
   

   Press Finish.
   
5. Right click on the project name "rexxoid" in the Package Explorer pane, then Debug As -> Android Application.
   It is Android Application, do not choose Android Native Application
6. If you get interrupted by this infamous message:

   Unable to execute dex: java.nio.BufferOverflowException.

   (from http://stackoverflow.com/questions/20778767)
   1. Right click on project and go to properties
   2. Go to Java Build Path Screen (from left menu)
   3. Select Libraries Pane
   4. Highlight Android dependencies
   5. Click Remove
   6. Click Ok and restart at previous step.
7. The Android Device Chooser dialog will probably show up, since you didn't tell what Android Virtual Device you wanted to run with.
   • check Launch a new Android Virtual Device
   • Press the Manager… button
   • In the Android Virtual Device Manager dialog, press the New… button
   • In the Create a new Android Virtual Device (AVD) dialog, press the New… button, and enter:

        AVD Name:    RexxDevice
        Device:      3.2" QVGA (ADP2)
        Target:      Android 2.2 - API Level 8
        SD Card:     10MiB
     

     The 3rd parameter (Target) is important: you must select a device with min API level 8! For the other parameters, it's up to your taste.
   • Press OK and close the Create a new Android Virtual Device (AVD) dialog
   • Back to the Android Device Chooser dialog, press Refresh, select the newly created device, press OK
   • Wait 2 or 3 minutes until the Android device gets ready
   
   
8. You must then see the Rexx Android King. Run qheure to test that everything is OK.

Create the APK

1. Right click on the project name "rexxoid" in the Package Explorer pane, then Android Tools -> Export Signed Application Package.
2. If you don't yet have a keystore, select Create new keystore
3. I suggest the target directory of your rexxoid.apk be [$home]/yaxx/android/bin

If you prefer, the android tool provides a mean to create a build.xml file for Apache Ant. Such one can be found under the android directory. You could recreate it by entering

(path to your SDK/tools directory)android update project -p (your eclipse project directory)

Install the APK on your device

Use the Android adb tool, from your [android sdk root]/platform-tools directory.
With your phone device adb-connected to your computer, do

cd ~/android-sdks/platform-tools
cp ~/yaxx/android/bin/rexxoid.apk .
adb install rexxoid.apk
rm rexxoid.apk

Rexx on Linux, Windows, …

On a Linux build machine, to produce the Linux-executable REXX module requires the build tools to be installed first:

sudo apt-get update
sudo apt-get install build-essential

Then, enter:

make clean rexx

This is it!

To produce a WIN32 executable, (aka rexx.exe) is also doable. You need a cross-compiler, that is, mingw-w64:

sudo apt-get install mingw-w64
make os=win32 clean rexx

On a MS Windows machine, you might be able to produce an executable using MS development tools. The repository has still the dsp/dsw files required by Visual C++ and the like. I didn't test it -- I no more use MS-Windows since years -- but it has chances to work. The "makeall.bat" file might help.