Sun Mar 7 17:16:06 CET 2010

Getting started with Staapl

(see also [1])

To try Staapl it's best to use the darcs version.  The PLaneT version
is not up-to-date and contains only the compiler and not the Makefiles
& examples.

These are instructions for linux.  If you try on OSX or Cygwin and it
doesn't work, drop me a line.

$ darcs get http://zwizwa.be/darcs/staapl
$ cd staapl
$ make

At this point it's possible to compile applications.  To compile the
blink-a-led try:

$ cd app
$ make blink-a-led.hex

This produces a HEX file that can be uploaded to a 18f452 chip with a
40 MHz XTAL.  To use different configuration, see the config bits in
any of the .fm files.

The simplest interactive app is 1220-8.fm which has the serial console
attached.  This is for an 18F1220 with internal osciallator.

To produce only the dictionary (and hex) do:

$ make 1220-8.dict

The .dict files are PLT Scheme modules that can be executed.  They
configure a front-end console to the binary code in the HEX file once
uploaded to the target.  If the target running, the console can be
started as:

$ mzscheme 1220-8.dict
Connected (/dev/ttyUSB0 38400)
Press ctrl-D to quit.

If you use a PicKit2 programmer and a USB serial cable on
/dev/ttyUSB0, the following method can be used to compile, upload and

$ make 1220-8.live

See app/Makefile and the .fm files for more information.

Once at the console, you can execute commands and load 8-bit numbers
on the stack.  See the `words' and `commands' commands to display a
list of on-target compiled words and console commands respectively.
The `macros' command displays a list of macros that can be used inside
word definitions only.

Using standard forth syntax like

: foo 123 ;
: bar foo foo ;

you can compile and upload new word definitions into the scratch
buffer.  These are persistent: they go into Flash memory.

The scratch buffer is emptied whenever the console is started to make
sure the state is predictable.  The `empty' command does the same, but
it does not clean the dictionary.

Definitions can be placed in a file and loaded into the scratch buffer

load /tmp/definitions.f

It is possible to develop a small application like this by simply
leaving the last uploaded version on the target.  However for larger
applications it is better to use the forth module (.fm) approach to
build a new kernel that can be compiled to HEX file.

[1] entry://20090812-191903