Bistro Documentation

On-line Documentation

Preparations

Bistro requires a Java™ runtime environment that complies with Sun's Java™ specifications. Check with Sun's Java™ web site for the latest JRE or JDK release. Follow their installation instructions to prepare your system.

If you don't mind spending some money, there are commercial Java™ development environments available from several vendors. Bistro was developed using JDK 1.4.

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. You can use any of several available ZIP tools - e.g., WinZip (for Windows).
3. Read the source code license and the release notes.
4. Include the Bistro class library (bistro\lib) and the ANTLR library (bistro\lib\antlr.jar) in your class path.
5. Write some Bistro code and experiment with the system!

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

\bistro - contains example files and the Bistro license and release notes

\convert - contains the Smalltalk to Bistro conversion utility

\docs - contains the Bistro API documentation

\lib - contains the Bistro class package tree

\src - contains the Bistro source code tree

Compiler Usage

java smalltalk.compiler.BistroCompiler <sourceBase> <targetBase> <classBase> <package.*> ...

Using the package compilation option, you can translate multiple Bistro packages simultaneously.

or

java smalltalk.compiler.BistroCompiler <sourceBase> <targetBase> <classBase> <faceName> ...

Using the class compilation option, you can translate multiple individual Bistro classes simultaneously.

where

<sourceBase>

the full or relative pathname for the base directory of your Bistro source code tree

<targetBase>

the full or relative pathname for the base directory where you want the Bistro compiler to generate the Java source code tree

<classBase>

the full or relative pathname for the base directory where you want the Bistro compiler to generate the Java packages and class files

<package.*>

the full name of a Bistro package you want compiled

<faceName>

the full name of a Bistro class or type you want compiled

The Bistro compiler now translates Bistro code into Java™ class files. The compiler provides error messages, but they are still rather cryptic. It will indicate the line number on which an error was located.

Examples

See the file named test.bat to execute the test classes.

• smalltalk.example.TestThreads tests the thread and synchronization features.
• smalltalk.example.TestMagnitudes outputs some numeric performance results.
• smalltalk.example.TestCollections tests some of the collection features.
• smalltalk.example.TestGeometry performs simple geometry tests.
• smalltalk.example.TestStreams performs simple stream tests.
• smalltalk.example.SticBenchmark reports some basic performance measures.
• smalltalk.example.SimpleHanoi compares Bistro and Java performance.

You can also try out the applet and servlet examples.

• smalltalk.example.TestApplet displays a button that changes its label when clicked.
• smalltalk.example.TestServlet produces an HTML page with "Hello World".

Rebuilding the Smalltalk Classes

The file named bistro\build.bat rebuilds the Smalltalk class packages. It uses the batch file named bistro\bjc.bat. The file named bistro\bjc.bat provides an example of how to invoke the Bistro compiler. The build batch uses the following conventions:

build <packageName> <ClassName>

The <packageName> identifies one of the Bistro class packages, e.g., behavior, magnitude. The <ClassName> identifies a Bistro class in the identified package, or * indicates all the classes in the package. For example, to build all the classes in the smalltalk.behavior package:

build behavior *

To build just the OrderedCollection class:

build collection OrderedCollection

For convenience, there is also a batch to rebuild all the Bistro classes and update the bistro.jar file.

buildall

Rebuilding the Documentation

API documentation for the Bistro class library is contained in the bistro.api.zip available on SourceForge™. The file named bistro\gendocs.bat regenerates the Smalltalk class API documentation using javadoc. It needs the file named bistro\smalltalk.txt, which lists the packages for which to generate docs. You can regenerate the docs with the following command:

gendocs @smalltalk.txt

Rebuilding the Compiler

The file named bistro\rebuild.bat rebuilds the Bistro compiler and the Smalltalk behavior and magnitude packages.

The file named bistro\src\smalltalk\compiler\antlr.bat regenerates a lexer or parser given the name of the grammar file - e.g., Bistro.g. It presumes that you have obtained and installed the ANTLR development tools.

Java™ is a trademark of Sun Microsystems, Inc.
SourceForge™ is a trademark of VA Linux Systems, Inc.

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