How to build PC-Choices applications

(Version 0.5c, ftp distribution, 27 July 92)

What is the PC-Choices application development package

The PC-Choices application development package is for compiling
32-bit PC-Choices applications in the DOS environment. PC-Choices
applications are written using the Choices object-oriented
application programming interface; this means that PC-Choices
applications can use operating system services in an object-
oriented manner. PC-Choices applications are written in C++.

The package is currently available for alpha-testing. This release
lacks some documentation that will be provided in a future release.

PC-Choices application programming features

Dynamic creation of lightweight and heavyweight processes;
preemptive multitasking with multi-level feedback process
scheduling; synchronization via semaphores; free-running timers
and timeout timers; DOS/BIOS calls; sharing memory among
lightweight and heavyweight processes; simple object-oriented
filesystem.

System requirements

Same as PC-Choices, with 3 Meg additional disk space; DJGPP, the
DOS g++ compiler; Borland MAKE 3.1 and above or NDMAKE. Version 0.5c
of the PC-Choices kernel and application binaries is required.

What software does it contain

PC-Choices system include files, libraries and makefiles for
compiling and linking applications; source code for all
applications in the PC-Choices package; source code for the
PC-Choices kernel bootstrapper.

What documentation does it contain

A primer on PC-Choices application programming; the complete
PC-Choices class hierarchy chart; PC-Choices class index and
header file index; PC-Choices overview.

_____________________________________________________________________________
Installing the Application Development Package

This package must be used with version 0.5c of the PC-Choices
binary distribution. To find out what version of PC-Choices you
are using, run "pcc" and look at the top-left portion of the screen.
To get the correct version of the binary distribution, ftp to
choices.cs.uiuc.edu.

The package comes in a ZIP archive named pccapp.zip. Copy it to the
PC in the same directory where the pcc directory is located. For
example, if your pcc directory is at c:\pcc, then you should copy
pccapp.zip to c:\. Unpack the archive with an UNZIP utility like
this:

unzip -d pccapp.zip

When it asks whether you want to overwrite existing files, say "yes".
Several directories will be unpacked into the pcc directory. After
that, delete pccapp.zip. We now have to edit the Chocs (Choices
command shell) profile so that the shell can find your compiled
applications. Edit pcc\bin\profile and add pcc\app to the PATH.
For example, if your profile contains the line

c:/pcc/cbin

you should change it to

c:/pcc/cbin;c:/pcc/app

Now we have to edit pcc\app\makefile to specify the location of
a DJGPP library. Edit the file and look for the line

LIBS = ../lib/libPCC.a /djgpp/lib/libC.a

If DJGPP is not installed in \djgpp, then that line should be
changed to indicate the proper path of the DJGPP library. For
example, if DJGPP is installed in d:\compilers\djgpp, you should
change the line to

LIBS = ../lib/libPCC.a d:/compilers/djgpp/lib/libC.a

_____________________________________________________________________________
Building and Running Applications

Applications are written and compiled in the pcc\app directory.
The easiest way to build your own applications is to put your
source code into the file pcc\app\test.cc, then go to the
directory pcc\app and type "make test" to produce the executable
program pcc\app\test. To execute the compiled program, start
up PC-Choices the usual way, and type "test" at the shell prompt.
Because pcc\app has been added to your PATH, the shell will be
able to find your compiled application at pcc\app\test.

To compile the applications provided with the package, just type
"make PROG", where PROG is the name of the application. For
example, "make flash" compiles the "flash" application. Note
that if you type "flash" in the command shell, pcc\cbin\flash
will be executed instead of pcc\app\flash because of the order
of your PATH components. To change this, rearrange your PATH
or use pathnames (eg. "\pcc\app\flash").

For more complicated applications, you should edit the makefile
to add your own rules. The makefile contains rules for compiling
various applications - just copy a rule and customize it for your
application.

For information on how to write PC-Choices applications, refer
to the PostScript document pcc\doc\progapp.ps. If you don't
have access to a PostScript printer, you may look at
pcc\doc\progapp.txt, which looks untidy because it was generated
from a DVI file. See pcc\doc\readme for information about the
other files in pcc\doc.

Warning: Do not replace pcc\bin\Chocs by pcc\app\Chocs! The
kernel uses a special version of Chocs that cannot be generated
by DJGPP. See below for the explanation.

_____________________________________________________________________________
Getting Acquainted with the PC-Choices System

Here is a guide to the directory structure of the PC-Choices system:

doc Documentation.
bin PC-Choices kernel, bootstrapper and configuration.
cbin Applications.
app User-compiled applications and source code.
bitmaps Bitmaps for count and logo.
lib Libraries and makefiles for building libraries.
include System and library header files for compiling apps.
common Code common to kernel and applications.
dispatch Application dispatcher library.
file Filesystem library.
general General purpose library.
math Math constants.
sysint System interface library.
system Kernel interface (stripped version).
system2 Kernel interface (full version).

Differences between system and system2: the interface files in system
and system2 are used by applications to access kernel objects. For
example, they define the NameServer and Semaphore classes. Applications
do not need to use the same definitions of kernel classes as those
used for compiling the kernel. For example, applications are not
concerned with the protected and private members of these classes.
Also, it is desirable to allow the kernel to define certain methods
that are not callable by the application; these methods should not
be visible to applications.

In our setup, include\system2 contains the full, original header files,
the same ones used for compiling the kernel. include\system contains
the stripped header files - protected and private members have been
stripped, as well as methods that applications are not supposed to
use. The stripped version of the files should be used for compiling
applications, not the original version. The stripping is done
automatically by a program called Proxify++ that we developed
ourselves; it strips all methods not marked "proxiable" in the original
header files. Unfortunately, comments are also stripped from the
header files by Proxify++. Hence, the original header files are
provided in include\system2 so that you can look at the documentation.
Otherwise, they don't serve any purpose in the application development
package.

Each directory containing source files includes a file named CONTENTS.
Read that file to find out the original long filenames.

_____________________________________________________________________________
Documentation

Besides the files in pcc\doc, there are several other files you
should read if you want to know more about Choices. Some header
files contain interesting comments about the various parts of
Choices:

include\system2\si.h - Choices proxy mechanism.
include\file\fsi.h - Filesystem framework.
include\system2\class.h - Run-time class support.
include\system2\vpci.h, - VirtualPCInterface for calling DOS/BIOS
include\common\vpca.h from PC-Choices.

The Choices ftp server (choices.cs.uiuc.edu) contains many
papers about Choices. Look in the directory /Papers. A
reference manual for PC-Choices is located at
/PC-Choices/pccthesis.ps.Z.

_____________________________________________________________________________
Overview of Choices

Choices, the object-oriented operating system, is well-documented;
many papers have been written about it. It is an operating system
composed of C++ objects. When Choices is running, numerous
objects work together in the system in order to provide operating
system services. Examples of Choices objects are Processes, Domains,
MemoryObjects, CPUs, Semaphores and NameServers. A Domain is a virtual
memory space in which Processes run, and MemoryObjects represent data
regions in the Domain that are accessible to Processes. In Choices,
C++ classes are also objects, so that programs may ask an object to
return its class, and given a class, find out all the superclasses
and subclasses of the class. Programs may also find out all instances
of the class.

Many modern operating systems operating-systems are object-based,
but only Choices is a real object-oriented operating system, because
it uses class hierarchies. For example, SystemProcess is a subclass
of Process. ApplicationProcess is also a subclass of Process. A
SystemProcess is a special kind of Process that executes in supervisor
mode and is non-preemptable. An ApplicationProcess is a special
kind of Process that executes in user mode, and is preemptable.
Both SystemProcess and ApplicationProcess inherit methods from Process,
but because they have different characteristics, the two subclasses
define certain methods differently. MemoryObject is subclassed
to represent various types of data stores such as physical memory
ranges, files and disks.

Subclassing is also used to make the operating system as modular
as possible, and to encapsulate machine-dependent characteristics
in separate subclasses. For example, CPU has subclasses i386CPU,
NS32332CPU, MC68030CPU and SPARCCPU, all of which define their
methods differently to handle CPU-specific operations like
context-switching and exception-handling.

Choices application programs are written in C++ in an object-
oriented manner too. System calls in Unix and most other operating
systems are flat function calls. System calls in Choices are object-
oriented - the kernel gives an application program pointers to kernel
objects and the program may invoke methods on these kernel objects to
perform system functions. In the object-oriented interface,
applications may create kernel objects such as Processes, Semaphores,
Domains and MemoryObjects. Kernel objects are not literally handed
to the application program; Choices contains a secure kernel
interface whereby "proxies" representing kernel objects are actually
handed to the application program, and calling any method on that
proxy will cause a trap into the kernel, and after checking the method
arguments, the method call will be forwarded to the appropriate kernel
object.

Choices has been ported to the multiprocessor Encore Multimax,
AT&T 6386WGS, IBM PS/2, Apple Macintosh IIx, SPARCstation I & II,
and we are currently porting it to the Intel Hypercube iPSC/2 and
Silicon Graphics workstations. The Multimax port of Choices currently
has the most number of Choices applications. Many Unix applications
have been ported to Multimax Choices: g++, gas, bash, GNU file
utilities and GNU Smalltalk. Multimax Choices runs TCP/IP and
provides Telnet and FTP services.

PC-Choices is a new port of Choices to 386-based PCs running DOS.
This is an interesting project because this is the first time
that a minimal Choices kernel has been isolated. The PC-Choices
kernel is only concerned with process management, virtual memory
and interrupt handling. All other services are provided by DOS
and BIOS, which run as user processes. Application libraries are
provided to map the DOS and BIOS interface into an object-oriented
interface so that Choices applications built for other ports
of Choices will run easily under PC-Choices. Applications may call
DOS and BIOS routines through a special object-based interface, and
through this interface, applications may also spawn off DOS processes.

PC-Choices was compiled on a SPARCstation with a g++ cross-compiler
for fast compilation. The PC-Choices application libraries and
system interface header files have been ported to DOS, and PC-Choices
applications may be produced by simply compiling them with DOS g++
(DJGPP) and linking the object files with the PC-Choices libraries.

There is currently a small group of Choices researchers. These people
are involved in many diverse research projects, such as distributed
virtual memory, message-passing, transaction processing, networked
filesystems, networking protocols, Unix compatibility, performance
visualization and object-oriented graphical interfaces.

_____________________________________________________________________________
Source Code Availability

Source code for the entire PC-Choices system, covering the kernel,
libraries and applications, is available for free if you sign
a license agreement. This license is identical to the license
that covers the application development package, except that you are
not allowed to give away the source code. The source code is only
available in Unix form, not in DOS form, because PC-Choices (including
Chocs) is compiled on a 386 g++ cross-compiler that runs on a SPARC
machine. (Hence the funny filename-mangling scheme employed to fit
everything into the DOS environment.)

To obtain the PC-Choices source code license, send your name,
email address and postal address to Anda Harney ([email protected]).
Also let her know whether the source code will be for your personal
use or for your company or university department.

The PC-Choices group is Lup Yuen Lee, Bob McGrath and Dave Kohr.
Thank you for using PC-Choices.


Lee Lup Yuen
[email protected] Graduate Student PC-Choices Manager