1 Introduction

This part of the manual is aimed for the administrators; those who install and administrate the SCHEMESTATION distribution.

In this document, we mainly descibe the system and software requirements and the SCHEMESTATION unpacking, configuration, compilation and updating procedures.

2 Installation

2.1 Target System Requirements

SCHEMESTATION can be compiled and run on a system with the capabilities and features described below.

2.1.1 Software Requirements

• ANSI C compliant C compiler. The GNU C Compiler version 2.7.2 or later with the GNU standard C libraries included in the GCC distribution is recommended.

  Basically, an ANSI C compliant compiler is needed. Certain debugging support is not available with non-GCC compilers, but this is taken care of automatically. On some platforms you may gain more performance by using the native compiler instead of GCC. See below for instructions how to set the C compiler to use.

  EGCS is also a valid option for Intel-based system. Bear in mind, however, that there may be some difficulties with e.g. debugging. We do not recommend using an EGCS version earlier than 1.0.1 due to problems we encountered by ourselves.

• GNU Make.

  Even using compiler other than GCC, you still need to use GNU Make. The makefiles of the project depend heavily on the features provided by GNU Make, and you cannot build the system without tweaking the makefiles a lot if you cannot use GNU Make.

• The unix system has to implement the IEEE POSIX 1003.1 compliant system calls.

  This requirement is not too strict, propably any modern Unix

  • implements most of the calls, and
  • impements thereby enough system calls to run SCHEMESTATION.

  You should propably just try compiling the distribution; if it will fail it is still more propably due to some other reason. A more probable problem related to the system call interface is that the header files in your local system are in "wrong place" or "wrong" otherwise. You may need to patch the code if that happens. Multi-platform support is not very extensive yet.

• X11R6 libraries and header files in order to build the SCHEMESTATION console, which is not mandatory in order to make the system run. However, you should have at least system where you can run the terminal. Otherwise things get boring pretty fast.

• X11R6 X display server in use in order to use the console.

• Perl version 5.003 or later.

  Perl is required to run a few scripts during installation and compilation. No smart guy uses unix without Perl!

2.1.2 Acquiring Required Software

For more information about obtaining GNU software - GCC, GMake, Gzip - see GNU's Not Unix! --- the GNU project and the Free Software Foundation (FSF). Gnu software is under the General Public Licence.

Perl is available at Perl home site.

There is a free X11 server, XFree86, that is more than adequate for running the console on x86 platforms (Linux, FreeBSD and such). It also comes with full X11R6 headers and libraries, so compiling the console will be easy also.

2.1.3 Hardware Requirements

The simulator is based on a virtual machine, which makes the CPU demands of the system relatively heavy. Users who plan to use the system for extensive agent programming tests are advised to install the system to a computer with a CPU whose speed corresponds to at least a 200 MHz Intel Pentium. Hardware installations with less than 32 MB of main memory may also suffer from shortage of memory.

Using the network simulator requires that you have a TCP/IP network (which can ultimately be a single loopback device on your workstation - however you need the TCP/IP protocol compliance in your unix system).

If you'd like to just try the system out, you may do with a lot more modest configuration.

The disk space requirement for a complete source tree during compilation is about 20 MB. We advice you to assure that at least 30MB disk space is free before installing the SCHEMESTATION source.

2.1.4 Supported Platforms

The system is known to run on the following UNIX platforms:

• Linux kernel version 2 or above (x86)

  Tested on: Linux schemestation.cs.hut.fi, kernel 2.0.29 #1 i586 unknown, 166Mhx Pentium (non-MMX) 64 MB RAM

• FreeBSD (x86)

  Tested on:

• Digital UNIX Digital Alpha

  Tested on: Digital UNIX V4.0C (Rev. 564.32); Alpha 21164A-2 (EV56), 128 MB RAM

Potentional targets:

• Hewlett-Packard HPUX
• IBM AIX
• SGI IRIX version 5 or 6

2.1.5 Unpacking SCHEMESTATION distribution

Issue command

gzip -d schemestation-XX-XX-XX.tar.gz | tar xvf -

in order to unpack the SCHEMESTATION source tree. The source tree appears under the directory schemestation/ in the current working directory.

2.2 source tree

This and the following subsection describe the contents of the source distribution immediately after it has been unpacked.

2.2.1 Directories in the source tree

bin

SchemeStation binaries will be installed in this directory, by default, after they have been built. This directory is initially empty.

doc

This directory contains all SchemeStation documentation in hypertext form, ready to be read by your favourite web browser.

doc/htmldoc

This directory contains SchemeStation documentation HTML files.

libscm

SchemeStation cross-compiler standard library files will be installed in this directory, by default, when the compiler is built. Initially this directory is empty.

src

This is the parent directory of the full sources for the SchemeStation operating system simulator and related utilities, such as the SchemeStation cross-compiler.

src/apps

Source code for executable UNIX applications resides under this directory.

src/apps/compiler

The sources for SchemeStation cross-compiler are found under this directory.

src/apps/compiler/assembler

This directory is a part of the SchemeStation compiler and contains the full source for the assembler, which is an external program written in C (as opposed to the compiler itself that is written in Scheme.)

src/apps/compiler/aux

Part of the cross-compiler; auxiliary procedures.

src/apps/compiler/codegen

Part of the cross-compiler; byte code generation.

src/apps/compiler/main

Part of the cross-compiler; main procedures.

src/apps/compiler/silex

This file contains the SILex lexical parser generator for Scheme by Danny Dube.

src/apps/compiler/stdlib

SchemeStation standard library code. Will be installed to libscm/ during build.

src/apps/compiler/support

Part of the cross-compiler; miscallenous modules.

src/apps/compiler/syntax

Part of the cross-compiler; syntax procedures.

src/apps/compiler/test

Part of the cross-compiler; procedures to facilitate unit testing.

src/apps/compiler/test-cases

This subdirectory contains test cases that are used to unit test the compiler. Some of the test cases are generated. This directory contains also code to generate test cases.

src/apps/console

This directory contains the source code of the SchemeStation console.

src/apps/network

Source code for the SchemeStation network simulator.

src/apps/ssvm

SchemeStation virtual machine. This is a stand-alone version of the virtual machine that exists for testing purposes.

src/apps/station

This directory contains the source code for the SchemeStation domain simulator.

src/lib

In this directory, SchemeStation libraries are installed during build-up. This directory is initially empty.

src/libsrc

The sources for different SchemeStation (C-)libraries are found under this directory.

src/libsrc/comms

The comms library files. The comms library consists of the networking system, addressing system and the messaging system, and the external agent interface system.

src/libsrc/heap

Schemestation heap implementation.

src/libsrc/scheduler

SchemeStation Scheduler source directory

src/libsrc/terminal

Sources for a directory for communicating with the ssconsole application; implements a simple protocol.

src/libsrc/vm

The SchemeStation Virtual Machine (SSVM) source directory

station

The standard agents usually started by a SchemeStation domain are stored here; also other files that are required by the simulator during it is executed.

station/scheme-src

This directory contains originally source code for SchemeStation agents that are a part of the distribution.

2.2.2 Listing of all the files

---

bin/DIRECTORY

The contents of the directory.

---

doc/DIRECTORY

The contents of the directory.

---

doc/htmldoc/DIRECTORY

The contents of the directory.

---

libscm/DIRECTORY

The contents of the directory.

---

src/DIRECTORY

The contents of the directory.

src/INSTALL

Short installation instructions (see manual for more comprehensive documentation).

src/Makedefs.in

Template for creating "Makedefs" during build.

src/Makedepends

Makefile definitions to automatically build dependency information. Included from makefiles.

src/Makefile

GNU makefile.

src/README

Short welcome note (see manual for more comprehensive documentation).

src/StandardExecutable

Makefile definitions to be included from makefiles whose main target is an executable object.

src/StandardLibrary

Makefile definitions to be included from makefiles whose main target is a library.

src/TODO

List of unfinished features and bugs not fixed.

---

src/apps/DIRECTORY

The contents of the directory.

src/apps/Makefile

GNU makefile.

src/apps/TODO

List of unfinished features and bugs not fixed.

---

src/apps/compiler/DIRECTORY

The contents of the directory.

src/apps/compiler/Makefile

Makefile for the cross-compiler.

src/apps/compiler/TODO

List of unfinished features and bugs not fixed.

---

src/apps/compiler/assembler/DIRECTORY

The contents of the directory.

src/apps/compiler/assembler/Makefile

GNU makefile.

src/apps/compiler/assembler/TODO

List of unfinished features and bugs not fixed.

src/apps/compiler/assembler/asmintern.h

Declares certain types, structures and macros used by several source files.

src/apps/compiler/assembler/bc.c

Code for creating the binary byte code vector from the list of assembled instructions.

src/apps/compiler/assembler/bc.h

Interfaces to bc.c.

src/apps/compiler/assembler/constants.c

Code for creating the constants table from the symbolic constants table found from the assembler file.

src/apps/compiler/assembler/constants.h

Interfaces to constants.c.

src/apps/compiler/assembler/hashgen.pl

PERL code to create a fast hash table for assembler opcodes.

src/apps/compiler/assembler/lexdefs.h

Declarations that are required for the lexer code.

src/apps/compiler/assembler/lexsupport.c

Auxiliary procedures needed by the assembler lexer.

src/apps/compiler/assembler/main.c

Code for starting the assembler and parsing the assembler file.

src/apps/compiler/assembler/tokens.flex

Lexical grammar.

---

src/apps/compiler/aux/DIRECTORY

The contents of the directory.

src/apps/compiler/aux/misc.scm

Miscallenous Scheme procedures that are not necessarily provided by a Scheme system but that are required in the compiler code.

src/apps/compiler/aux/pp.scm

Scheme pretty-printer. Original code is by Marc Feeley.

src/apps/compiler/aux/printf.scm

An implementation of a powerful output procedure in Scheme.

src/apps/compiler/aux/trace.scm

Support for giving debug messages that can be output selectively.

---

src/apps/compiler/codegen/DIRECTORY

The contents of the directory.

src/apps/compiler/codegen/asm-macros.scm

Support for pseudo byte code instructions that are expanded only after the linearization.

src/apps/compiler/codegen/byte-code.scm

Procedures to create byte code instructions and to check the parameters and syntax of inlined assembly code.

src/apps/compiler/codegen/core-primitives.scm

Declarations of primitive procedures that are implemented directly using virtual machine instructions.

src/apps/compiler/codegen/inline-primitives.scm

Code for analyzing a semantic tree and inlining primitive procedures that appear at the operator position.

src/apps/compiler/codegen/lexaddrs.scm

Lexical-address calculation.

src/apps/compiler/codegen/newlinearizer.scm

Linearization procedure (converts semantic trees to instruction sequences).

src/apps/compiler/codegen/peephole.scm

Peephole optimizer; does not much, though.

---

src/apps/compiler/compiler-dump.scm

VSCM Scheme code to create an executable dump of the compiler.

src/apps/compiler/lexical-grammar.silex

The lexical grammar for the reader, ready to be fed to the scanners generator.

src/apps/compiler/load.scm

Top level Scheme file to load the compiler.

---

src/apps/compiler/main/DIRECTORY

The contents of the directory.

src/apps/compiler/main/compile-file.scm

Code for compiling one Scheme file. Controls the actual compilation process.

src/apps/compiler/main/compiler.scm

The top-level entry to the compiler. Get command-line arguments and run the compilation process.

src/apps/compiler/main/file-input.scm

Code for reading in source code files.

src/apps/compiler/main/initial-lex-env.scm

Creation of the initial lexical environment when a new program is compiled.

src/apps/compiler/main/myoptions.scm

Declaration of the options understood by the cross-compiler. The actual options line parsing is implemented in support/options.scm.

---

src/apps/compiler/modules.scm

Support for loading files from different directories, loaded by load.scm.

src/apps/compiler/resolv-require.pl

PERL script for generating compiler dependencies (could be implemented in Scheme, though).

---

src/apps/compiler/silex/DIRECTORY

The contents of the directory.

src/apps/compiler/silex/README

SILex welcome note.

src/apps/compiler/silex/TODO

List of unfinished features and bugs not fixed.

src/apps/compiler/silex/multilex.scm

SILex parser core code.

src/apps/compiler/silex/silex.ps

PostScript documentation of SILex.

src/apps/compiler/silex/silex.scm

Parser generator.

src/apps/compiler/silex/silex.texi

TeXInfo documentation of SILex.

---

src/apps/compiler/ssc.sh

Bone of a shell script that will execute the SchemeStation compiler.

src/apps/compiler/ssscheme.el

Load this into your emacs to turn Scheme mode automatically on when opening files with the .ssscm suffix.

---

src/apps/compiler/stdlib/DIRECTORY

The contents of the directory.

src/apps/compiler/stdlib/asynchronous.ssscm

Procedures to facilitate a sort of RPC in the asynchronous environment.

src/apps/compiler/stdlib/carcdr.ssscm

Definitions of the convenience procedures caar, cadr, etc.

src/apps/compiler/stdlib/control.ssscm

Definitions of the Scheme control procedures, such as apply and map.

src/apps/compiler/stdlib/display.ssscm

Procedures to convert arbitrary Scheme objects to strings.

src/apps/compiler/stdlib/exceptions.ssscm

SchemeStation virtual machine exception handling.

src/apps/compiler/stdlib/lists.ssscm

Standard procedures for list manipulation.

src/apps/compiler/stdlib/misc.ssscm

Miscallenous standard procedures, such as equal? or null?

src/apps/compiler/stdlib/read.ssscm

Procedures for implementing Scheme reading. Currently only string->integer conversion.

src/apps/compiler/stdlib/standard-agent.ssscm

Procedures and standard message handlers for "normal" agents.

src/apps/compiler/stdlib/standard-syntax.ssscm

Definitions of standard [derived] syntax forms.

src/apps/compiler/stdlib/stdinc.ssscm

File to be included by default when any program is compiled.

src/apps/compiler/stdlib/stdlib.ssscm

Main standard library file; includes a lot of others.

src/apps/compiler/stdlib/strings.ssscm

Procedures for string handling.

src/apps/compiler/stdlib/test1.ssscm

Simple test procedures for the standard library (not very useful, you don't necessarily need this).

src/apps/compiler/stdlib/text.ssscm

Procedures for advanced text handling, such as substring search.

---

src/apps/compiler/support/DIRECTORY

The contents of the directory.

src/apps/compiler/support/comerror.scm

Printing of compiler messages.

src/apps/compiler/support/constants-table.scm

Code to keep track of the constants table during compilation.

src/apps/compiler/support/encodings.scm

Converting strings in different encodings to standard bit strings.

src/apps/compiler/support/environments.scm

Implementation of the frame-environment abstraction, used in various places.

src/apps/compiler/support/global-vars.scm

Keeping track of the global vars that are introduced during compilation.

src/apps/compiler/support/lexical-bindings.scm

Implementation of lexical bindings (i.e. variable denotations) abstraction.

src/apps/compiler/support/options.scm

Code to parse the command-line options list.

src/apps/compiler/support/trees.scm

Tree data type, for creating semantic trees.

src/apps/compiler/support/vardata.scm

Variable data container abstraction; a variable data container is an object that denotes unambiguously a variable in the Scheme program being compiled.

---

src/apps/compiler/syntax/DIRECTORY

The contents of the directory.

src/apps/compiler/syntax/lexer.scm

Procedures required by the lexical analyzer.

src/apps/compiler/syntax/macros.scm

Code for macro matching, expansion and definition.

src/apps/compiler/syntax/reader.scm

Scheme reader (i.e. conversion from a textual representation of a datum to the datum itself); uses the lexical parser generated by SILex.

src/apps/compiler/syntax/st-application.scm

Building a semantic trees for applications.

src/apps/compiler/syntax/st-asm.scm

Building semantic trees for inlined assembler.

src/apps/compiler/syntax/st-assign.scm

Building semantic trees for assignments.

src/apps/compiler/syntax/st-aux.scm

Building semantic trees for compilation errors.

src/apps/compiler/syntax/st-closure.scm

Building semantic trees for closures.

src/apps/compiler/syntax/st-literal.scm

Building semantic trees for literals (constant values).

src/apps/compiler/syntax/st-main-build.scm

The main procedure for creating (recursively) the semantic tree corresponding to a source code program.

src/apps/compiler/syntax/st-primitive.scm

Building semantic trees for primitive procedures.

src/apps/compiler/syntax/st-sequence.scm

Building semantic trees for sequences.

src/apps/compiler/syntax/st-syntax.scm

Building semantic trees for macro invocations.

src/apps/compiler/syntax/st-test.scm

Building semantic trees for conditionals.

src/apps/compiler/syntax/st-variable.scm

Building semantic trees for variable references.

src/apps/compiler/syntax/syntax-asm.scm

Analysis of the inlined assembler special form.

src/apps/compiler/syntax/syntax-begin.scm

Analysis of the "begin" special form.

src/apps/compiler/syntax/syntax-classifications.scm

Auxiliary procedures for classifying Scheme expressions according to their syntax properties.

src/apps/compiler/syntax/syntax-define.scm

Analysis of the "define" special form.

src/apps/compiler/syntax/syntax-if.scm

Analysis of the "if" special form.

src/apps/compiler/syntax/syntax-include.scm

Analysis of the "include" special form.

src/apps/compiler/syntax/syntax-lambda.scm

Analysis of the "lambda" special form.

src/apps/compiler/syntax/syntax-procedures.scm

Bindings of the core syntactic forms to keywords in the initial lexical environment.

src/apps/compiler/syntax/syntax-quote.scm

Analysis of the "quote" special form.

src/apps/compiler/syntax/syntax-set.scm

Analysis of the "set!" special form.

---

src/apps/compiler/sysdeps.scm

Scheme system dependent procedures. Actually only VSCM is currently supported, so this is not strictly necessary. However, we are foreseeing a port to another Scheme system.

---

src/apps/compiler/test-cases/DIRECTORY

The contents of the directory.

src/apps/compiler/test-cases/document-test-cases.sh

A shell script to generate a formatted hyper text document enumerating all the test cases.

src/apps/compiler/test-cases/make-test-cases.sh

A shell script to generate a certain set of test cases.

src/apps/compiler/test-cases/randexpr.scm

Scheme procedures to generate random Scheme expression in a controlled way.

---

src/apps/compiler/test/DIRECTORY

The contents of the directory.

src/apps/compiler/test/eval-test.scm

Semantic tree evaluation testing.

src/apps/compiler/test/eval-trees.scm

Procedures to evaluate semantic trees.

src/apps/compiler/test/reader-test.scm

Datum reader testing.

src/apps/compiler/test/testmain.scm

Generic support for testing.

src/apps/compiler/test/testreports.scm

Outputing test reports.

src/apps/compiler/test/testsupport.scm

Generic support for testing.

---

src/apps/compiler/vmtests.scm

Support for testing with the virtual machine.

src/apps/compiler/vmtests.sh

A shell script to perform testing with the virtual machine.

---

src/apps/console/DIRECTORY

The contents of the directory.

src/apps/console/Makefile

GNU makefile.

src/apps/console/TODO

List of unfinished features and bugs not fixed.

src/apps/console/main.c

Main file.

src/apps/console/terminal.c

Actual functionality is implemented in this file.

src/apps/console/terminal.h

Internal definitions.

src/apps/console/xincludes.h

File to include appropriate X header files. Need some kludging with symbols that are defined in both the SchemeStation project and the X11 header files.

---

src/apps/network/DIRECTORY

The contents of the directory.

src/apps/network/Makefile

GNU makefile.

src/apps/network/TODO

List of unfinished features and bugs not fixed.

src/apps/network/main.c

Most of the functionality is provided by the sscomms library, so the amount of additional code is small. This file implements all required functionality.

---

src/apps/ssvm/DIRECTORY

The contents of the directory.

src/apps/ssvm/Makefile

GNU makefile.

src/apps/ssvm/TODO

List of unfinished features and bugs not fixed.

src/apps/ssvm/ssvm.c

All the source code; most of the functionality is implemented in libraries elsewhere.

---

src/apps/station/DIRECTORY

The contents of the directory.

src/apps/station/MESSAGES

A rough list of messages sent and received by agents that are part of the distribution.

src/apps/station/Makefile

GNU makefile.

src/apps/station/TODO

List of unfinished features and bugs not fixed.

src/apps/station/addrctl.c

Interfacing with the addressing system library.

src/apps/station/addrctl.h

Interfaces to addrctl.c.

src/apps/station/boot.c

Booting the SchemeStation. Code to initialize different devices, and the kernel.

src/apps/station/boot.h

Interfaces to boot.c.

src/apps/station/dk.c

Implementation of the domain kernel agent.

src/apps/station/dk.h

Interfaces to dk.c.

src/apps/station/domainconfig.c

Configuration of a new station.

src/apps/station/domainconfig.h

Interfaces to domainconfig.c and the declaration of certain structures.

src/apps/station/extglue.c

Interfacing with the external agent communications library.

src/apps/station/extglue.h

Interfaces to extglue.c.

src/apps/station/initialos.c

Procedures to start an initial object server.

src/apps/station/initialos.h

Interfaces to initialos.c.

src/apps/station/main.c

Main file of the simulator.

src/apps/station/migration.c

Procedures to facilitate agent migration.

src/apps/station/migration.h

Interfaces to migration.c.

src/apps/station/netglue.c

Interfacing with the networking library.

src/apps/station/netglue.h

Interfaces to netglue.c.

src/apps/station/pershe.c

Writing and reading the header that prefixes SchemeStation core files.

src/apps/station/pershe.h

Interfaces to pershe.c.

src/apps/station/persistence.c

Writing and reading SchemeStation core files.

src/apps/station/persistence.h

Interfaces to persistence.c.

src/apps/station/pt.c

Persistence test program (you don't actually need this).

src/apps/station/sched.c

Interfacing with the scheduler library.

src/apps/station/sched.h

Interfaces to sched.c.

src/apps/station/shutdown.c

Shutting down a domain.

src/apps/station/shutdown.h

Interfaces to shutdown.c.

src/apps/station/stationmisc.c

Miscallenous procedures used in the simulator.

src/apps/station/stationmisc.h

Interfaces to stationmisc.c.

src/apps/station/statusbar.c

Procedures to display and update the status bar display.

src/apps/station/statusbar.h

Interfaces to statusbar.c.

src/apps/station/termcontrol.c

Procedures to interact with the terminal devices; an implementation of a terminal driver.

src/apps/station/termcontrol.h

Interfaces to termcontrol.c.

src/apps/station/tests.c

Some procedures that can be used to test the implementation. These tests can be activated from command line, but they are not very interesting and have been actually used only at the early stages of the development.

src/apps/station/tests.h

Interfaces to tests.c

---

src/config.h.in

Template for creating "include/config.h" during build.

src/configure.in

GNU Autoconf(1) input for creating the actual configure script. You do not need to have GNU Autoconf installed on your local system because the generated configure script is also distributed.

src/install-sh

A supplement for the install(1) command in systems where the command is broken.

---

src/lib/DIRECTORY

The contents of the directory.

src/lib/TODO

List of unfinished features and bugs not fixed.

---

src/libsrc/DIRECTORY

The contents of the directory.

src/libsrc/Makefile

GNU makefile.

src/libsrc/TODO

List of unfinished features and bugs not fixed.

---

src/libsrc/comms/DIRECTORY

The contents of the directory.

src/libsrc/comms/Makefile

GNU makefile.

src/libsrc/comms/TODO

List of unfinished features and bugs not fixed.

src/libsrc/comms/addressing-internal.h

The header files for internal functions of the comms library.

src/libsrc/comms/addressing-test.c

The test cases for the addressing module. Not part of the comms library.

src/libsrc/comms/addressing.c

The addressing system main C file. Addressing system functions.

src/libsrc/comms/comms-misc.c

Misc functions for comms testing. Not part of the library.

src/libsrc/comms/comms-misc.h

Header file for comms-misc.c.

src/libsrc/comms/extagent-connection.c

The per connection related functions of the SchemeStation side of the external agent interface.

src/libsrc/comms/extagent-eloop.c

The event loop related functions of the SchemeStation side of the external agent interface.

src/libsrc/comms/extagent-internal.h

The header file for the internal functions of the SchemeStation side of the external agent interface.

src/libsrc/comms/extagent-packet.c

The packet sending and receiving related functions of the SchemeStation side of the external agent interface.

src/libsrc/comms/extagent-packet.h

The header file for extagent-packet.c

src/libsrc/comms/extagent-test.c

The test cases for the SchemeStation side of the external agent interface.

src/libsrc/comms/extagent.c

The per connection related functions of the SchemeStation side of the external agent interface. The general functions of the SchemeStation side of the external agent interface.

src/libsrc/comms/messaging.c

The messaging system main C file. Messaging system functions.

src/libsrc/comms/network-internal.h

The header file for external functions in networking system.

src/libsrc/comms/network-packet.c

The packet sending and receivinfg functions for the network simulation.

src/libsrc/comms/network-packet.h

The header file for network-packet.c.

src/libsrc/comms/network-test.c

Test cases for the networking system. Not part of the comms library.

src/libsrc/comms/network.c

The networking system main C file. Networking system functions.

src/libsrc/comms/remap.c

Procedures to implement the on-the-fly remapping of addresses in inter-domain communications.

src/libsrc/comms/remap_test.c

A program to test the address remapping procedures.

---

src/libsrc/heap/DIRECTORY

The contents of the directory.

src/libsrc/heap/Makefile

GNU makefile.

src/libsrc/heap/TODO

List of unfinished features and bugs not fixed.

src/libsrc/heap/bstring_test.c

Testing procedures.

src/libsrc/heap/byteorder_test.c

Testing procedures.

src/libsrc/heap/heap.c

Heap implementation.

src/libsrc/heap/heap_internal.h

Internal heap definitions for heap.c.

src/libsrc/heap/heap_tests.c

Testing procedures.

src/libsrc/heap/heapconv.c

Procedures to create and parse conveniently heaps of certain structure. Used extensively in the core domain kernel.

src/libsrc/heap/lindump.c

Testing procedures.

src/libsrc/heap/remap_test.c

Testing procedures.

---

src/libsrc/scheduler/DIRECTORY

The contents of the directory.

src/libsrc/scheduler/Makefile

GNU makefile.

src/libsrc/scheduler/TODO

List of unfinished features and bugs not fixed.

src/libsrc/scheduler/list.c

List package for the scheduler.

src/libsrc/scheduler/list.h

List package header for the scheduler.

src/libsrc/scheduler/list_tests.c

List package test unit.

src/libsrc/scheduler/new_scheduler.c

The scheduler implementation.

src/libsrc/scheduler/new_tests.c

Scheduler test unit.

src/libsrc/scheduler/sch_test.c

Scheduler test unit.

---

src/libsrc/terminal/Makefile

GNU makefile.

src/libsrc/terminal/TODO

List of unfinished features and bugs not fixed.

src/libsrc/terminal/termlib.c

Sources of the terminal communications library.

src/libsrc/terminal/termtest.c

A program to test the terminal implementation.

---

src/libsrc/vm/DIRECTORY

The contents of the directory.

src/libsrc/vm/Makefile

Makefile for the SSVM

src/libsrc/vm/TODO

List of unfinished features and bugs not fixed.

src/libsrc/vm/mkinstr.c

SSVM instruction encoder test unit

src/libsrc/vm/vm_core.c

The SSVM core functions that are visible to the outside world.

src/libsrc/vm/vm_debug.c

Debug function vm_debug_print_opts() for dumping each instruction's arguments whenever necessary.

src/libsrc/vm/vm_debug.h

Header file for the vm_debug.c - the vm_debug_print_ops() prototype

src/libsrc/vm/vm_encode.c

SSVM instruction encoder; this is mainly for the assembler

src/libsrc/vm/vm_encode.h

SSVM instruction encoder function prototypes

src/libsrc/vm/vm_instr.c

SSVM instruction implementations

src/libsrc/vm/vm_instr.h

SSVM instruction implementation prototypes & memory layout

src/libsrc/vm/vm_tester.c

SSVM test unit (HUGE!)

---

src/make-vm-instrs.pl

A PERL script to parse the list of virtual machine instructions (vm-instructions) and converting it to several forms used by the cross-compiler and the virtual machine implementation.

src/makedepend.pl

A PERL script for generating dependencies for the makefiles. (We didn't use C compiler for this due to certain compatibility problems we faced.)

src/test-summary.pl

A PERL script for generating a summary report of test reports generated by test procedures in various modules.

src/vm-instructions

List of instructions implemented in the virtual machine. Processed by make-vm-instrs.pl.

---

station/DIRECTORY

The contents of the directory.

station/Makefile

GNU makefile.

---

station/scheme-src/DIRECTORY

The contents of the directory.

station/scheme-src/Makefile

GNU makefile.

station/scheme-src/WTCA.ssscm

Windowing Terminal Controlling Agent (WTCA). Implements a terminal controlling agent that provides rudimentary windowing, in conjunction with WTCAwin.

station/scheme-src/WTCAwin.ssscm

An agent to control one window that is displayed with help from WTCA.

station/scheme-src/blop.ssscm

A demonstration program that opens a window and increments a counter in the window with regular intervals.

station/scheme-src/eai.ssscm

External Agent Interface agent (EAI). An agent to communicate with external agents that connect through the external agent interface.

station/scheme-src/kernel.ssscm

SchemeStation Domain Kernel Interface agent (DKI).

station/scheme-src/login.ssscm

A simple login agent that is mainly a non-op.

station/scheme-src/migrate.ssscm

A demonstrative program to interactively migrate arbitrary agents.

station/scheme-src/object-server.ssscm

Object server.

station/scheme-src/promo.ssscm

A demonstrative program to display fine poetry.

station/scheme-src/shell.ssscm

A demonstrative user shell that is able to execute objects found from an object server and can also migrate itself to a remote domain.

station/scheme-src/shutdown.ssscm

A demonstrative program to shut down the domain where it is started.

station/scheme-src/taxman.ssscm

A demonstration program that plays the game of Taxman, in the way the implementor remembered it to have worked in an old CP/M machine.

---

station/scheme-src/tests/DIRECTORY

The contents of the directory.

station/scheme-src/tests/Makefile

GNU makefile.

station/scheme-src/tests/fsd-test.ssscm

File system external agent tests.

station/scheme-src/tests/life-test.ssscm

Centralised part of the distributed Game of Life test.

station/scheme-src/tests/life-test-cell.ssscm

Single cell implementation of the distributed Game of Life test.

station/scheme-src/tests/life-test-sync.ssscm

Distributed syncronisation facility of the distributed Game of Life test.

station/scheme-src/tests/messaging-test.ssscm

Distributed messenger end of the messaging test.

station/scheme-src/tests/messaging-tester.ssscm

Centralised controller of the messaging test.

station/scheme-src/tests/quicksort.ssscm

Simple quicksort test.

station/scheme-src/top.ssscm

A demonstration program that shows domain process information, updating the display with regular intervals.

---

2.3 Building the SCHEMESTATION simulator

In order to built the SCHEMESTATION simulator, the following steps are necessary or advised:

1. Configuring the distribution.
2. Building libraries, executables and run-time libraries.
3. Testing.
4. Installing.

2.3.1 Configuring the distribution

The distribution is configured via the means of the configure scripts that is found from schemestation/src/configure. This standard shell script examines the target systems and accumulates information for use during build. The script is created by the GNU Autoconf utility, but Autoconf is not needed to use the script. To automatically configure the system, you need in principle to type just

./configure

However, there are certain details that ./configure cannot possibly figure correctly out, and some things you would like to specify yourself. Particularly, the following things may need to be adjusted:

C compiler. configure tries by default to use GCC, but in some systems GCC can be broken (!) or produce much less efficient code than the system's own compiler. To override configure's decisions and use the compiler you want, set the environment variable CC to the appropriate executable name. For example,

  $ export CC=/usr/bin/cc
  $ ./configure

X includes and libraries. If you have multiple X libraries around, configure can choose the wrong ones. You can explicitly set the path where X header files and X library files will be found by giving the command-line switches --x-includes=DIR and --x-libraries=DIR to configure. For example,

  $ ./configure --x-libraries=/usr/shlib

Debugging support. The SCHEMESTATION simulator can be built with or without debugging support (this debugging support does not mean -g or anything to do with source-level debuggers, but support for debugging SCHEMESTATION domains). If you enable debugging support the programs are bound to run slower than without. You can choose whether or not to include debugging support by the command line switches (for configure) --without-debug and --with-debug. The default is to include debugging support.

Memory allocation control. The SCHEMESTATION simulator can be also built with an extra memory allocation layer that keeps track of where dynamically allocated memory has been really allocated, whether it has been freed or not and some other things. It slows things down a lot, does compile only under GCC and can break compilation on some platforms. For all these reasons, normally this layer is not included in compilation. If you wish to include it, give the --with-ssalloc flag to configure.

Cross-compiler. Normally the cross-compiler is built along all other software. However, it is possible that you do not have a working VSCM and thus cannot make the cross-compiler. In order to avoid errors (and premature abortion of "make all") you can give the flag --disable-compiler to configure. This disables building of the cross-compiler. The default is to build it.

Terminal. Normally the SCHEMESTATION terminal is built along all other software. However, if you do not have X libraries or do not for some other reason to build it, you can disable building it by giving the flag --disable-terminal to configure. This disables building of the terminal. The default is to build it.

Scheme. Normally configure assumes that your VSCM implementation has the name vscm and searches for it from the current path. If you wish to explicitly set the Scheme interprete to use, or at least change the name searched for, you can do this with the --with-scheme=SCHEME option to configure. For example,

  $ ./configure --with-scheme=/usr/local/bin/scheme

Finally, here is a concrete example that shows how the system can be configured for certain Alpha workstations in Helsinki University of Technology:

  $ export PATH=~ahuima/vscmV0r4:$PATH   # VSCM resides here
  $ export CC=cc
  $ export CFLAGS='-O5 -tune host'       # much optimization!
  $ ./configure --with-scheme=vscm --x-libraries=/usr/shlib --without-debug

2.3.2 Compiling and installing

Issue commands

gmake all

to build and install appropriate files, and then

gmake recsummary

to make comprehensive testing. A summary of the rest results appears after the tests have been made, which may take longer than a while. If you need to rebuild the complete distribution, use

gmake fullclean

first.

For more information, consult Development environment of the SchemeStation project: makefiles and related.

NOTE: If you run Linux or other system where Gnu Make is the default Make utility, you should use command "make" instead of "gmake".

3 Administrative operations

The SCHEMESTATION system is designed to be as easily administrable as possible. All administrative operations can be done remotely, either using the underlying UNIX system or the SCHEMESTATION network. Comprehensive test concerning the administration UI have been made by our UI developers (rather than by the beta testers, which may be the case with some other opertaing systems). This has lead to the happy situation where the SCHEMESTATION administrator has a minimal amount of regular tasks.

4 Updating the system

4.1 Installing a new version

Having aqcuired a new version of SCHEMESTATION system, you can simply follow the installation process outlined above. The SCHEMESTATION system does not use any such static settings that should be explicitely migrated to the new installation. We do however recommend you to install the new version in a separate directory, and only remove the old one after the functionality of the new one in your system has been adequately tested.

If you have used the unix file server external agent to store static data, remember to move the file server data directory (and it subdirectories) from wherever you have configured it to be before you remove the old directory tree.

4.2 Applying patches

The SCHEMESTATION team may provided pathces to the system, if serious bugs are revealed after the release of the system. If no further instruction on applying these patches are provided, the installation procedure will include unpacking (gzip -d patch-xxx.patch.gz; patch patch-xxx.patch) the patch package in the root directory of the SCHEMESTATION source tree. Of course, a recompilation is also needed to make the patch functional.

5 Reporting bugs

The bug report should include information on the system you are running the SCHEMESTATION on, The C compiler used, the SCHEMESTATION version, the possible error messages, and all information, that might lead us to the lcoation of the bug in the source.

You may also provide a suggestion for a patch.

6 Troubleshooting

Problem	Tentative solutions
The compilation fails.	(1) Make sure that you are using GNU make. It is mandatory. (2) Where does the compilation fail? If your C compiler crashes (which is known to have happened) you cannot do much but change the compiler. (3) If you get a "normal" error message from your compiler, this just means that you are probably not compiling on a supported platform. Resolving the situation may require patching the code.
The compilation succeeds, but the resulting executable dumps core quite immediately.	This can be due to a compiler problem. We have experienced trouble with e.g. the EGCS C compiler version 1.0.0. If you want to use EGCS instead of GCC, use version 1.0.2 or later.
The SCHEMESTATION station suddenly dumps core in random situations.	You may have discovered a bug in the implementation. If you can reproduce the core dump, there are very good changes that you can get the problem fixed by reporting it.
I can start the SCHEMESTATION simulator, and get a window, but then nothing happens.	This is not a problem; the software works, but you are not using it correctly. Read the User's Manual.
The computer I'm trying to run SCHEMESTATION on does not respond.	(1) Switch the power on. (2) Your computer is broken.
I have only Windows-based workstations but would like to run the SCHEMESTATION whatsoever.	There does not exist a Windows port and will probably never exist. You need to get your hands on a UNIX system anyway.