/Mimosa/Mimosa/Documentation/CedarPortOverview.tioga
Russ Atkinson (RRA) June 3, 1988 2:32:15 pm PDT
Eduardo Pelegri-Llopart September 5, 1989 7:57:35 am PDT
Christian Jacobi, May 12, 1992 5:08 pm PDT
CEDAR PORT OVERVIEW
CEDAR PORT OVERVIEW
Russ Atkinson
© Copyright 1988 Xerox Corporation. All rights reserved.
Abstract: This document provides an overview of the Cedar Port facilities: compilation, binding, execution, and debugging. This document is oriented towards a current Cedar programmer who wants to understand the overall structure of Cedar Port. The document LifeInPCedar.tioga contains detailed instructions on how to generate code for, and on, PCedar.
Created by: Russ Atkinson
Maintained by: Russ <Atkinson.pa>, Eduardo <Pelegri.pa>
Keywords: Cedar, Cedar Port, Cedar Runtime, Cinder, Mimosa, PCedar
XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304
1. Introduction
Purpose of this document
This document provides an overview of the principles to compile, run, and debug a Cedar/Mesa program using the interim version of the Portable Cedar (PCedar) environment running on the Portable Common Runtime (PCR) on Sun-4 systems running SunOS, which is itself a variant of Unix*.
This document gives the "big picture" of the Cedar Port, describing its architecture and providing enough detail to write, compile, and execute a small "hello world" program. The actual commands and conventions currently used in PCedar are described in the document
[PCedar2.0]<Documentation>LifeInPCedar.tioga
More details on the Cedar Port can be obtained from the document
[Cedar10.1]<CedarDoc>ExperiencesCreatingAPortableCedar.tioga
We assume some rough familiarity with programming in Cedar.
Some notational conventions
File names and characters typed to or by a machine are in a sans-serif font, as in
FileName. If the name is meant to be taken as an example, rather than literally, then the name is also italicized, as in
FileName. Characters typed by the machine are underlined, as in
machine output. Commands and long file names are set off on indented lines as in:
% command
If the command prompt is % , then the command is for the CommandTool on either Cedar7.0 or on PCedar. If the command prompt is Host% , then the command is a Unix shell command on the example machine Host. If we need to distinguish between a CommandTool on Cedar7.0 and PCedar, we will use %C7.0 for the former, and %PC for the later. Finally the prompt pcr represents the prompt of PCR. Exceptions to these rules are as likely as not to be editing mistakes.
Occasionally, it will be convenient to describe a feature that is not yet implemented. We will distinguish two different situations. Those features that we expect to be implemented in the 100KByHalloween program will be annotated with [100K], while those that we expect to implement "soon", but for which we do not have a fixed scheduled will be annotated with [NYI].
You must be a valid user
If you do not have an account on a Sun that is accessible from a Cedar machine, you must get one (typically this uses the Sun Yellow Pages, or YP, service). Similarly, you must be a valid Cedar user. If either of these is not true, contact your local administrator for help (in CSL, contact Sharon Johnson <SJohnson.pa> for both Cedar and Unix access).
Where things are
There are four servers involved: [Cedar7.0], [CedarChest7.0], [PCedar2.0], and [Mimosa]. They are all typically pseudo-servers, which means that the names go through a translation to become real server names. For technical reasons, the translations used in PCedar differ from those used in Cedar7.0. At PARC, as of August 31, 1989, the translations are as follows:
Cedar7.0 translations
Cedar7.0 [Nadreck-NFS]<Gris>Cedar7.0>
CedarChest7.0 [Nadreck-NFS]<Marron>CedarChest7.0>
PCedar2.0 [Nadreck-NFS]<Pixel1>PCedar2.0>
Mimosa [Indigo-STP]
PCedar translations
Cedar7.0 /net/nadreck/gris/Cedar7.0/
CedarChest7.0 /net/nadreck/marron/CedarChest7.0/
PCedar2.0 /volume/pixel1/PCedar2.0/
Mimosa Not accessible from PCedar
The translation can change with relatively little notice, and will almost certainly be different for locations outside of PARC. If any of these pseudo-servers is undefined (use the command
PSPrint to find out), you can add one via the
PSAdd command:
% PSAdd PseudoServer $ Host
Where
Host is the name of the server in your location. If you expect to store to the
PseudoServer server as well, you need to use:
% PSAdd PseudoServer Host Host
The default directory for PCedar DF files is [PCedar2.0]<Top>; documentation files are stored in [PCedar2.0]<Documentation>. The default directory for Mimosa DF files is [Mimosa]<Mimosa>Top>. Cedar7.0-specific files (e.g. BCD and Cedar7.0 specific sources) should live either in [Cedar7.0], [CedarChest7.0], or [Mimosa]. Shared sources should live on [PCedar2.0], but for technical reasons, those shared packages that are part of CedarChest7.0, like MakeDo, currently have their sources replicated in both [CedarChest7.0] and [PCedar2.0]. This situation will likely change.
Version Maps
The CedarChest and PCedar coordinators maintain version maps for the contents of [Cedar7.0], [CedarChest7.0] and [PCedar2.0]. These version maps are used by the CommandTool commands: Findp, Findr, Openp, Openph, Openr, Openrh. A typical User Profile entry could be as follows:
VersionMap.SourceMaps: /Cedar7.0/VersionMap/CedarSource.VersionMap /CedarChest7.0/VersionMap/CedarChestSource.VersionMap
VersionMap.PSourceMaps: [PCedar2.0]<VersionMap>PCedarSource.VersionMap
VersionMap.SymbolsMaps: /Cedar7.0/VersionMap/CedarSymbols.VersionMap /CedarChest7.0/VersionMap/CedarChestSymbols.VersionMap
VersionMap.SymbolsMaps is meaningless for PCedar.
DF files
DF files in [PCedar1.2] are organized in "Suites". A suite includes a number of related DF files that together describe the package in PCedar, and, maybe, also in Cedar7.0. All "Suite" DF files reside in
[PCedar2.0]<Top>, but the Cedar7.0 dependent files (organized in a "PrincOps" DF file) may be stored in [Cedar7.0], [CedarChest7.0],
or [Mimosa]. A form for PCedar DF files is stored as:
[PCedar2.0]<Forms>PCedarDF.form
A document describing the DF conventions is stored in
[PCedar2.0]<Documentation>DFSuitesDoc.tioga (maybe only in LifeInPCedar).
Unless otherwise indicated, all the tools described in this document exist in both worlds. LifeInPCedar.tioga describes in detail where to find these tools.
2. The Architecture
The Cedar Port compiler translates the Cedar language into machine dependent C. There is a front end, Mimosa, compiling into a simple intermediate form, and a back end, C2C, translating from the intermediate form to C code. C/Mesa files are processed by a replacement for the Binder called Cinder, which generates C code. Both Mimosa and Cinder also generate symbol table information which is stored in the so-called MOB files. Both Mimosa and Cinder run in both Cedar7.0 and PCedar. Mobs created by the PCedar compiler are completely interchangeable with those generated by the PrincOps Cedar7.0 Mimosa compiler. Obtaining executable code, thus, involves either Mimosa or Cinder, and then an additional C compilation.
There are a variety of documentation files for Mimosa, but the two most useful to the novice are:
[PCedar2.0]<Documentation>
MimosaDoc.tioga
(how to drive Mimosa)
[PCedar2.0]<Documentation>
LanguageChangesSummary.tioga
(how Cedar/Mesa has changed)
To compile the file named
Test.mesa, use the command:
% Mimosa Test
If compilation errors result, the error log will be written to Test.errlog. For successful compilations of definition modules, a single file, Test.mob, will be produced to hold the symbolic information. For successful compilations of implementation modules two files, Test.mob and Test.c2c.c will be produced. To actually execute the program the C compiler must be invoked to produce output.
The C/Mesa language* for configuration files is largely unchanged except for a few extensions to allow the binding of non-Cedar/Mesa components. The operation of Cinder, though, is quite different than the operation of the Binder. The output of Cinder is a C program that, when invoked from the PCR, will actually produce the intermodule bindings.
There is a user-level documentation file for Cinder:
[PCedar2.0]<Documentation>CinderDoc.tioga
(how to drive Cinder)
There is no C compiler in neither Cedar7.0 nor PCedar; instead the Unix C compiler is used and, in the case of Cedar7.0, files are sent back and forth between the PrincOps-machine and a Unix machine. ComplexCc takes care of these interactions. The C compiler will produce a file of the form Test.c2c.o. Moreover, since the executable is target-architecture dependent, we follow the convention of placing the O file in a target-architecture specific subdirectory, as in sun4/Test.c2c.o.
User-level documentation for ComplexCc is available ([100K] Cedar7.0 and PCedar documentation and sources will be merged):
[CedarChest7.0]<Documentation>CcCommandsDoc.tioga
(how to drive ComplexCc)
If desired, more complete documentation on the Unix C compiler can be found using the Unix command
Host% man cc
The example shown later in this document shows a direct invocation of the Unix C compiler. This is used in this document for didactic reasons, but it is not recommended.
[Old-style] Debugging is done using the standard Unix debugger, dbx, on a core image synthesized from a trace of the packages dynamically loaded into PCR. The whole process is invoked through a (csh script) named XrDBX. To allow Cedar-source level debugging, MS injects symbol table information obtained from the Mimosa compilation into the object files. MS, as well as Mimosa, Cinder, and ComplexCc, are routinely driven through MakeDo. We do not describe this process in any more detail in this document. Refer to LifeInCedar.tioga.
[100K] The new-style debugging uses Cirio. See the Cirio documentation for more details.
3. Getting to Unix from Cedar
Using Bridge
In Cedar7.0 the most common way to communicate with Sun Unix machines is via the Bridge software, which is a descendent of the Cornell Bridge software that runs on XDE. The Bridge package will also exist in PCedar [100K]. The DF file is stored in:
[CedarChest7.0]<Top>Bridge.df
The documentation is stored as:
[CedarChest7.0]<Documentation>BridgeDoc.tioga
Choosing a protocol
Cedar7.0 supports two protocols that can support Bridge sessions: XNS and TCP/IP. To make Bridge use a particular transport, use:
% BridgeChangeTransport Transport
where Transport is either XNS or TCP. Of the two, TCP is more widely supported by Unix. For historical reasons, the default transport is XNS, but you can change your default through an UserProfile entry.
Logging in to Unix
If your login name and password are different for the Sun world than the Cedar world (probably a good idea for security reasons), then before starting up a Bridge session, supply the credentials for the Sun world:
% BridgeCredentials
YourName YourPassword
(remember to delete your password)
You can also supply a different set of credentials to use for a particular machine:
% BridgeCredentials YourName YourPassword MachineName
If your credentials are set, or your login name and password are the same for Unix as for Cedar, then a simple command will start a Bridge session:
% Bridge MachineName
You can also supply a different set of credentials to use for a particular session:
% Bridge
MachineName -i
user name: YourName
password: YourPassword
This will establish your identity for the entire Bridge session to that machine, and will create a typescript window that behaves as a simple terminal on the remote Unix machine named by
MachineName. Further windows can be created using:
% Bridge MachineName
Note that since your credentials are already established, an explicit name and password are not needed. The descriptions of further Bridge commands assume that a session has been started.
Copying files
Cedar7.0 provides an implementation of RemoteFile based on the NFS protocol which can be used through the CommandTool command
copy to transfer files between a Unix machine and Cedar7.0. Unix files are referenced with (case-sensitive) filenames of the form
[host-UX]<Dir1>Dir2>...DirN>FileName
where Dir1/Dir2/...DirN/FileName is the path describing the desired file on host host. There are technical restrictions on the relationship between /Dir1/Dir2/...DirN/FileName and host, which in practice reduce to requiring that the filesystem on which /Dir1/Dir2/...DirN/FileName is located must be local (i.e. not remote) to, and exported by, host. For example, in CSL, a reference to /Palain-UX/palain/pelegri/foo is valid, while one to /Chroma-UX/palain/pelegri/foo is not.
An alternative approach is to use the Bridge command RCopy. See the Bridge documentation for details.
4. Loading and running (using PCR)
Programs produced by the Mimosa compiler must be run using the PCR. To start this support as a program, use the command:
Host% pcr
This will start up a program that has a small command interpreter of its own. To load and start the single-module program
sun4/
Test.c2c.o (produced from
Test.c, which was produced from
Test.mesa), use the cedarboot command:
pcr: LoadAndRun sun4/Test.c2c.o Test
This command will load in the object code for the module, run the installation code (which handles importing and exporting via interfaces, REF literals, and other functions related to the load state), and run the initialization code (which initializes the global frame). This is similar to the Cedar run command.
When done with this instance of cedarboot, type the command
pcr: quit
which will get you to the PCR threads debugger. Then type quit again
pcr: quit
and then confirm to exit to the normal Unix command interpreter (and perform some clean up on the way out).
Output using XR�ugPutChar will appear in the window used to start pcr. To assist debugging, the output is unbuffered, so the output will be properly synchronized with errors.
For more details on using PCR, refer to the document in file:
[Mimosa]<Mimosa>Documentation>PCRDoc.tioga
5. An example program
The following program will print "Hello world!\n" to the default output stream, then exit.
Test.mesa
Copyright Ó 1988 by Xerox Corporation. All rights reserved.
Russ Atkinson (RRA) February 29, 1988 10:18:01 pm PST
Test: CEDAR PROGRAM = BEGIN
PutChar:
PROC [c:
CHAR] =
TRUSTED
MACHINE
CODE {
"XR�ugPutChar"
};
PutText:
PROC [r:
REF
TEXT] = {
IF r #
NIL
THEN
FOR i:
NAT
IN [0..r.length)
DO
PutChar[r[i]];
ENDLOOP;
};
PutText["Hello world!\n"];
END.
The above program makes use of a MACHINE CODE procedure to call a procedure (XR�ugPutChar) written in C (note that "underscore" is the same character as '←). That procedure is present in the runtime support. Using such a low-level routine is, in most cases, unnecessary. The lower levels of PCedar export more convenient functionality.
6. Example: a simple program using "cross development"
Warning: do NOT use the sequence described in this section to build PCedar2.0 packages. First read LifeInPCedar.
This section runs through the steps a Cedar7.0 user will perform in order to run a simple program from his or her PrincOps machine. Host stands for your favorite Sparc-based workstation. YourHomeHost stands for whatever file server holds your home directory (Palain for many CSL users). Furthermore, we assume that there is a subdirectory sun4 in your home directory on Host. See LifeInPCedar.tioga for information on other scenarios.
Starting up
Use Bridge to establish a session with a Unix machine. If specifying user credentials (recommended), use the Cedar command:
% Bridge
Host -i
user name: YourName
password: YourPassword
Further bridge windows for the same session to the same machine with the same credentials can be opened using the Cedar command:
% Bridge Host
Editing
Use Tioga to create Test.mesa (use any name that you like, Test.mesa is just an example). Node structure is perfectly acceptable.
Compiling
Compile from Cedar to C using the Cedar command:
% Mimosa -l -c Test
Copy to the Unix host using the Cedar command:
% Copy /YourHomeHost-UX/YourHomeDirectory/Test.c2c.c ← Test.c2c.c
In a Bridge window to
Host, use the Unix command (case matters):
Host% cc -g -c -o sun4/Test.c2c.o Test.c2c.c
(For this example we have chosen the switches to maximize debugging, not speed)
Running
In a Bridge window to
Host, use the Unix command (case matters):
Host% pcr
In a Bridge window to
Host, use the
pcr command (case matters for file names):
Host% LoandAndRun sun4/Test.c2c.o Test