Bistro Documentation

Preparations

Bistro code development requires the JDK. Check with the Java™ web site for the latest JDK release. Follow their installation instructions to prepare your system. Bistro was developed originally with JDK v1.4, but has since been updated to use JDK v1.6.

The Eclipse IDE was used, along with Ant, in the more recent improvements to Bistro. If you intend to make use of Eclipse and/or the Ant build file (build.xml), follow their instructions for installing those tools on your system.

Installation

  1. Download the source release. The source code for Bistro is released as a ZIP file.
  2. After downloading the ZIP file, extract its contents into a project directory of your own choosing (e.g., Bistro).
  3. Read the source code license and the release notes.
  4. Include the Bistro class library (Bistro/lib/bistro.jar) and the ANTLR library (Bistro/lib/antlr-3.2.jar) in your class path.
  5. Write some Bistro code and experiment with the system!

When you extract the Bistro.zip file into your Bistro project directory, it will create the following subdirectory structure:

/Bistro - contains the Bistro license file
/builds - contains the Ant build.xml
/convert - contains the Smalltalk to Bistro conversion utility
/lib - contains the Bistro class JAR file
/src - contains the Bistro source code tree
/tools - contains the tools used by Bistro: ANTLR and Ant Contrib

Ant Build Targets

The Ant build file builds/build.xml contains the following significant targets:

Build Target Description
test.smalltalk Invokes the Java™ runtime with each of the Bistro test fixtures, including tests of Threads, Magnitudes, Geometry, Collections, Exceptions. You can find representative examples of Bistro code in the folder named src/smalltalk/example.
build.jar Rebuilds the Bistro library JAR file, which includes the compiler classes, the standard Smalltalk library classes, and the test classes.
compile.smalltalk Invokes the Bistro compiler to regenerate the standard Smalltalk library classes.
compile.compiler Invokes the Java™ compiler to regenerate the Bistro compiler classes.
build.bistro.parser Invokes ANTLR to regenerate the Bistro lexer and parser classes from their respective grammars.
clean.smalltalk Deletes the Bistro library JAR file and the generated Java™ source code for all the standard Smalltalk library classes.
build.docs Rebuilds the API documentation for the Bistro compiler and Smalltalk library classes.
compile.bistro.code Provides an example of how to invoke the Bistro compiler to generate Java™ source files and compile those into class files.

Bistro Compiler Usage

The Bistro compiler takes the following command line arguments:

Argument Description
sourceFolder The full or relative pathname of your Bistro source code base folder.
targetFolder The full or relative pathname of your Java™ source code base folder.
classFolder The full or relative pathname of your Java™ class library base folder.
packageName ...
className ... 		The fully qualified package name(s) or fully qualified class name(s) of the Bistro classes you want compiled.

The Bistro compiler translates Bistro code into Java™ class files. The Bistro compiler can translate multiple packages or classes. Given class dependencies, there will often be a specific order for compiling packages. The compilation of the classes in the Smalltalk library are a good example (see the package list in the compile.smalltalk build target).

The Bistro compiler provides error messages, but they are still rather cryptic. It will indicate the line number on which an error was located.

Oracle and Java™ are registered trademarks of Oracle and/or its affiliates.
SourceForge™ is a trademark of Geeknet, Inc.

Permission is granted to copy this document provided this copyright statement is retained in all copies.
Copyright 1999-2001 Nikolas S. Boyd.