Read Me

* HPLUA - LUA for HP Calculators including HP49g+ and HP50g
*
*

* QUICK START:
If you want to try the binaries first or don't want to compile. here's
how.

The HPLua runtime is "flua.hp" (now called Formlua). currently you have to
lunch this from the ARMToolbox which you have to install first.
The ARM Toolbox is part of hpgcc but i have put the runtime into
the directory ARMToolbox as a convenience for people who don't want to
install hpgcc. I think its ok to redistribute this.

(1) Install ARM Toolbox 

Send the SETUP.BIN file to your HP49g+/50g. I do this by writing to
the SD card then putting the card in the calculator, although it
should be possible to send to the calculator connected by USB.

Choose the port number for the installation library for the calculator and put
this number on the stack (eg 0 enter). 

Then run SETUP.BIN

When the installation is done, reset your calculator to attach the
library (ON+C, turn off/on).

(2) Put FLUA.HP onto the calculator (eg copy to the sd card again).

(3) Launch FORMLUA. this is done by bringing up the menu for the toolbox
then recalling the binary onto the stack and "PrRun" it as follows.
eg:

 -> LIB ARMTo 
 <- Files SD OK LUA.HP RCL ON PrRun

This should run HPLUA in interactive mode and you should see the copyright
message. try something like:

 ->(hold) = 1 + 2 ENTER
 exit ENTER ON

To run programs either load them inside lua. eg

dofile("sunset.lua")
[press key LS FILES for dofile( abbreviation]

or put the name on the stack (as a quoted string) before running lua. eg.

"SUNSET.LUA" ENTER
Files SD OK LUA.HP RCL ON PrRun

* IMPORTANT RUNTIME NOTES

read keyboard.txt for description of how the keyboard works.
remember LUA is case sensitive!

To exit LUA, type the following onto a single line:
exit 
then ENTER then ON.
this takes you back to calculator normality. 

good luck and be sure to try some of the sample programs.

* NOTES ON THE DP version

see DP.txt

-------------------------------------------------------------------------

* HOW TO COMPILE and IMPORTANT NOTES:
To compile, you need hpgcc from www.hpgcc.org. This release was compiled
with hpgcc version 2.0. 

The source code for hplua lives in hplua/src and also in hplua/src/stubs
the `src' directory contains essentially the LUA-5.1.1 release, although
there are changes that depend on the #define HPLUA that i had to make,
otherwise its pretty much the same. For example "main" was changed for
HPLUA so that argc & argv can be taken from the HP stack (see lua.c for
details).

the base LUA-5.1.1 release has been patched to include Thierry Grellier's
bitwise operators. These are (mainly) | & ^^ << and >>. I wanted these
in hplua so I'm considering binary operations as standard. see
http://lua-users.org/wiki/LuaPowerPatches for details.

the hpgcc support for standard C libraries is patchy and also inconsistent.
Some things are wrong. src/stubs directory contains C runtime stubs and
bits of code that i found or wrote to fill the missing functionality.
In many cases, i have taken the source code from the hpgcc libc implementation,
copied it into stubs and hacked it to work. in theory some of these fixes
could be propagated back to hpgcc, but bear in mind the "fixes" are in
the direction of getting hplua to work rather than fixing hpgcc.

For example, hpgcc libc does not define stdout so if you
fprintf(stdout, "bla"); it bombs. I have fixed this for hplua stubs, but it
is done by giving stdout, stderr and stdin special values. Also, none of
the io could handle ungetc before, this was needed too for lua io.

Differences in input, output, number formatting and so on between the
desktop LUA 5.1.1 and HPLUA will almost certainly be something not
there or not done or broken in src/stubs so check that first.

There is one assembler file i wrote, "long.s" this is the implementation of
setjmp/longjmp that LUA needs for exceptions and coroutines. This appears to
work, although i don't save the floating point state in these functions.
if this becomes an issue, its easy to remedy.

So, looking at the Makefile, you will see that the strategy is to both include 
and link to stubs *before* the standard libraries. this means that my includes
get seen first and my stubs get linked first. missing functions from stubs are
provided by the libc with hpgcc and these are the things which are ok and
i didn't need to change.

OTHER NOTES:
As described above, the keycaps are handled differently from normal. For
the gory details, look at the file stubs/getchar.c here you will see the
nasty keymapping for unshifted mode and the three shifted modes. Feel free
to change these where there's something missing. I've tried to make the
values as much as possible the same as normal aside from having the different
shifting mechanism. At some point i need to figure out how to handle special
characters like pi. 

Also, i'd like to hook in key interrupts so that we can break out of LUA.
right now, i think if you have an infinite loop, you are hosed.


good luck,

hugh@voidware.com

---------------------

* HOW TO COMPILE 0.2 NOTES

As of version 0.2, hplua makes limited use of C++. It's convienient in the
implementation of hplua to use a BCD number type with C++ operators. this
saves a heck of a lot of messing about with function calls and macros in 
the source code.

consequently the release version of arm-elf-gcc is not up to it. instead
get the prebuilt arm-elf-gcc (and others) from www.gnuarm.com.
i'm using gcc-4.0 toolchain version gcc-4.0.2, download the binary installer
and run it. de-select big-endian and floating point, then unpack to
somewhere like c:\gnuarm

change your path to point to c:\gnuarm\bin rather than c:\arm-hp
keep the variable HPGCC pointing to c:\arm-hp so that all the other stuff
works.

Note that this does not automatically give you a C++ compiler for the 
calculator. I'm avoiding any C++ usage that leads to before and after
main constructors/destructors and also C++ things that usually bloat out
code such as use of the C++ runtime library (and STL), exceptions and RTTI.

finally, there's a new version of elf2hp.exe needed. this lives in hplua/bin
and is used by the makefile to generate .hp files. right now its built
dynamically so you might need to get msvcr80.dll before it works.

* notes for hpgcc SP2

you need to add the -ffriend-injection to the compile options.