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.