Lard Toolkit User Guide
Overview of most common usage
Introduction
The various programs that make up the LARD toolkit have many complex
options, but for most applications most of them can be ignored. This
overview explains a subset of the commands that can be used to compile
and execute most programs.
Source programs, which are given the extension .l, are
compiled, assembled and linked into a binary program. This binary,
which is given the extension .bcode, is executed using the
interpreter li.
Set-up
Prior to using the toolkit for the first time it may be necessary to
set two environment variables:
- LCD_OPTS specifies default options for the compiler
driver program lcd. It should normally be set to specify
which lard libraries are needed by default. Note that when
LCD_OPTS contains spaces your shell probably needs quotes
around it to set it properly.
- LI_LOAD_PATH specifies the directories that the
interpreter searches for tcl modules if they are not found in the
default location.
You must also add the toolkit binary directory to your path.
The recommended way of setting these variables is with the following
code (ksh/bash syntax):
LARDHOME=/home/amulinks/lard/v10 # or wherever you have it
BINFMT=`$LARDHOME/config/binfmt`
export LCD_OPTS="-lio -lchannels -ltime"
export PATH=$LARDHOME/bin/$BINFMT:$PATH
Whether you should put the channels and time libraries in your
LCD_OPTS variable depends on whether your programs always use them.
This arangement works with the default LARD installation arangements
where binaries and libraries are put in architecture-specific
directories.
Compiling
The compiler driver program, lcd, greatly simplifies the
compilation, optimisation, assembly and linking process. To compile a
source program foo.l into a binary foo.bcode, simply
use a command such as the following:
- lcd foo.l - compile, assemble and link
Making Libraries
When a project is split over several source files all but the "main
program" should be treated as libraries. See the lcd documentation for details of how to
compile a library.
Consider a project with four source files:
- defs.l declares some types used by all of the other files.
- block1.l describes one part of the system, refering to
types defined in defs.l
- block2.l describes another part of the system, also
refering to types defined in defs.l
- toplevel.l is the main program, instancing the blocks
described in block1.l and block2.l.
The following Makefile describes the dependencies between the files
and rules for compiling them:
all: toplevel.bcode
defs.dcode defs.bcode: defs.l
lcd -mklib defs.l
block1.dcode block1.bcode: block1.l defs.dcode
lcd -mklib -ldefs block1.l
block2.dcode block2.bcode: block2.l defs.dcode
lcd -mklib -ldefs block2.l
toplevel.bcode: toplevel.l defs.dcode defs.bcode block1.dcode \
block1.bcode block2.dcode block2.bcode
lcd -ldefs -lblock1 -lblock2 toplevel.l
With this Makefile in place it is only necessary to type make
and the minimum ammount of recompilation to produce an up-to-date
executable is carried out.
Execution
bcode files are executed using the program li.
li is based on the tcl command interpreter. If you start
li as follows
li foo.bcode
the bcode file is loaded and a prompt is displayed where you
can type tcl commands. Alternatively you can give additional command
line arguments that name "modules" to load. The two most usefull are
li foo.bcode run
which loads the bcode file and runs it with input/output from
the command line, and
li foo.bcode windows
which starts the tk graphical front end.
Note that li foo.bcode looks for a file li foo.lirc
containing tcl commands which it will execute at start up.