CEDAR PORT OVERVIEW CEDAR PORT OVERVIEW Russ Atkinson c 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 , Eduardo 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]LifeInPCedar.tioga More details on the Cedar Port can be obtained from the document [Cedar10.1]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 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]Cedar7.0> CedarChest7.0 [Nadreck-NFS]CedarChest7.0> PCedar2.0 [Nadreck-NFS]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]; documentation files are stored in [PCedar2.0]. The default directory for Mimosa DF files is [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]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], 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]PCedarDF.form A document describing the DF conventions is stored in [PCedar2.0]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]MimosaDoc.tioga (how to drive Mimosa) [PCedar2.0]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]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]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]Bridge.df The documentation is stored as: [CedarChest7.0]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]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_DebugPutChar 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]Documentation>PCRDoc.tioga 5. An example program The following program will print "Hello world!\n" to the default output stream, then exit. Test: CEDAR PROGRAM = BEGIN PutChar: PROC [c: CHAR] = TRUSTED MACHINE CODE { "XR_DebugPutChar" }; 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_DebugPutChar) 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 Δ/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 * UNIX is a trademark of AT&T Bell Laboratories. Sun-3, Sun-4, and SunOS are trademarks of Sun Microsystems. None of this should be surprising. * The C/Mesa language has little to do with the Mesa programming language and even less to do with the C programming language. If this bothers you, just remember that in France "french fries" are really "pommes frites." Test.mesa Copyright Σ 1988 by Xerox Corporation. All rights reserved. Russ Atkinson (RRA) February 29, 1988 10:18:01 pm PST Κα– "cedar" style•NewlineDelimiter ˜šœ4™4Icode™/K™8K™*—J™Iunleaded•Mark centerHeaderšœΟsœœ˜L– centerFooter˜Ititlešœœœ˜Iauthors˜ IabstractšΠms8˜9OšΟb œΩ˜βOšŸ œ˜OšŸœ)˜7OšŸ œ9˜BO˜I boilerplateš ΟqœΟoœ‘œ‘œ‘Ρbox˜sheadšœ˜ ˜Iblock˜šI footseparator– footSeparator™Ifootnote•InsertfootšΠluœ™‘S– footSeparator™R˜ŠIindentš‘,˜,R˜@Uš‘œ!‘˜‘œ ‘œ‘œ™˜οQ˜Ušœ&˜&Ušœ2˜2Ušœ)˜)Ušœ‘œ˜Q˜Ušœ%˜%Ušœ1˜1Ušœ#˜#UšœΟe˜! šœΎ‘œ'‘œ ˜ϊUš₯‘€ ‘€˜— šœ€œL€ œ!˜ƒUš₯‘€ ‘€‘€˜—Ršœ«‘œ‚˜Α— šœ ˜ ˜–RšŸœc˜xRšŸœ/˜FRšŸœe˜{—R˜1— ˜ šœΞ‘œr‘ œ*˜‰Uš‘˜— ˜5Ušœ‘I˜J—Ršœ\‘œ.˜—— šœ˜IbodyšœΣ˜Σ ˜a š‘œ‘˜)UšΟi˜— š‘œ‘˜6Uš©˜—— šœ€‘œ˜5Uš₯‘€˜ —Rš œ?€‘œE€‘œw€‘œ€‘œe˜‹ ˜έS– footSeparator™T–footš£œΫ™άS– footSeparator™— ˜4 š‘)˜)Uš©˜——Rš œ¦€œ‘œl‘œ<‘€œ‘˜ιRšœz˜z š‘1˜1Uš©˜— ˜bUš¦₯‘˜ —R˜«Ršœˆ‘˜šRšœY˜Y— šœ˜ ˜ šœω˜ωUš‘˜— ˜Uš‘-˜-—— ˜ ˜‚Uš₯‘€ ˜!—Ršœ€ œΎ˜Ν— ˜ ˜Υ š₯‘€˜)Uš©"˜"—— ˜SUš₯‘€!˜5— ˜“Uš₯‘€ ˜— ˜S š₯‘€ ‘˜Iitemš₯ €˜Wš₯ € ˜—— šœ»€ œ(˜ξUš₯‘€ ˜—R˜Ό— ˜ šœ}‘œ~˜€Uš‘$˜$—Ršœ‘œ0‘œ?‘œ‘œE‘œA‘œ&‘œ‘œ˜ήR˜f—— šœ"˜" ˜yUš¦₯‘˜ — š œ{‘€‘œ€‘œ€‘œ˜ΰUš₯‘€‘€˜$—Ršœ‹§œŸ‘œ ˜Ή ˜;Uš₯‘˜ — ˜EUš₯‘˜ —R˜kRšœ ‘œ–˜² ˜=Uš‘*˜*—— šœ˜R˜Z ˜™ K™˜‚— ˜ ˜0Uš₯‘˜— ˜.Uš₯‘€ ‘€‘ œ‘ ˜A— šœ€œ&˜@Uš ¦₯‘ œ€‘€‘€‘˜,RšœO˜O—— ˜ šœ€œ&˜@Uš¦₯‘˜ — šœ€œ ‘œ'˜NUš¦₯‘€‘€˜&————…—?τJ™