$Id: README,v 1.2 2003/03/07 03:46:20 chl Exp $

kasm v1.0.0, Copyright (C) 2001 Eduardo M Kalinowski (ekalin@bol.com.br)


What is kasm?
=============

kasm is a System RPL/Machine Language assembler for the Saturn
microprocessor, used in the HP48/HP49 calculators. (This
microprocessor is also used in other HP calculators, but kasm is made
specifically for the HP48/HP49 calculators). It uses MASD syntax
(first instroduced in the MetaKernel program for HP48
calculators). This syntax, which has only very small incompatibilities
with the traditional syntax (used in the HP Tools, in the GNU Tools
and in JAZZ), supports a few constructs that make the assembly
language be closer to a high level programming language. It supports
all the structures (blocks, etc.) and shortcuts (RPL, SCREEN, etc.) of
the MASD compiler in the HP49G calculators.

kasm generates files for the HP48 and the HP49 calculators, based on a
command-line flag. It also supports condional code generation
depending on the calculator the file is meant to.

This file only gives a brief introduction to kasm usage. For more
detailed information, see the manual, in the doc/ subdirectory.


Compiling and Installing kasm
=============================

Since kasm uses GNU autoconf, you just need to do this three steps to
build kasm:

  ./configure
  make
  make install

For the last step, you will probably need to be the superuser. Read
the INSTALL files if you want more information about the configure
script.

The configure script supports an option to specify which is the
default calculator model for which files will be generated. If not
specified, kasm will by default output files for the HP49
calculator. Use the "--with-default=hp48" command line option in the
configure script to make kasm output HP48 files by default. Whichever
is the default mode, you can always specify the model for a particular
file with command line options; see below.


Supported Plataforms
====================

kasm has been successfully compiled and run in the following
plataforms:

- Linux i386 (RedHat 7.0)
- FreeBSD 4.3-RELEASE
- Solaris 7, with gcc 2.8.1

However, it should work on any UNIX-like system. If you have
successfully run kasm in another plataform, send me a note at
ekalin@bol.com.br so I can add it to this list.


Using kasm
==========

To use kasm with the default options, simply run kasm with the source
file as argument. This would be something like

  kasm mycode.s

This will generate the file mycode.o. By default, a file suitable for
the HP49 is generated. If you want a file for the HP48, just specify
the -8 option to kasm.

If you want to specify an alternate output file, give the
"-o outputfile" option to kasm.


The Source File
===============

The source file should be a file suitable for assembly with MASD, in
System RPL mode. Direct machine language mode is not supported, but
you can alwais include the code inside CODE/ENDCODE.

If a "@" is found in the source, compilation stops. However, unlike
MASD, kasm does not require the "@". Also, the "@" can appear
anywhere, as long as there is at least one space or new line before
and after it to separate it from the previous and next tokens. Any
text following the "@" is ignored.

There are a few minor incompatibilites with MASD. These are described
in the BUGS file, which also contains information on other problems
with kasm.


The Author
==========

kasm was written by Eduardo M Kalinowski (ekalin@bol.com.br). You can
visit kasm's homepage for more information and to get the latest
version:

http://k-asm.sourceforge.net

You should also visit kasm's project page on Sourceforge:

http://sourceforge.net/projects/k-asm

Use the features in that page to report bugs, request new features and
be aware of the latest news about kasm.

