Cedar10.1ReleaseMessage.tioga
Copyright Ó 1992 by Xerox Corporation. All rights reserved.
Michael Plass, January 17, 1992 4:46 pm PST
Willie-s, June 11, 1992 5:25 pm PDT
CEDAR 10.1 RELEASE
CEDAR 10.1 FOR INTERNAL XEROX USE ONLY
Cedar 10.1 Release
Ó Copyright 1992 Xerox Corporation. All rights reserved.
Abstract: Getting started in Cedar10.1
Created by: Michael Plass
Maintained by: Willie-Sue Orr
Keywords: porting, cross debugging
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
Significant changes for Cedar 10.1
Directory structure
The use of the automount map /pseudo has been dropped. There will only be a /project/cedar10.1 map used; all of the pieces of Cedar10 will be subdirectories of /project/cedar10.1. The .mesa, .c2c.c, etc. files are in the subdirectory release; that is, the counterpart of /pseudo/pcedar2.0 is now /project/cedar10.1/release. The files that are in /project/pcedar2.0 (bin/ X/, etc.) have been moved to /project/cedar10.1 (bin/ X/, etc.), making changes as needed.
DF file structure
The structure of the DF files that describe the release have been simplified. There is no longer any source sharing with DCedar; only a single DF file per component is used, rather than the DF suite of PCedar2.0.
The only object files modelled by the DF files are the optimized sun4 versions; these are under the sun4 subdirectory in each component.
(Strategies for modelling debuggable versions are TBD).
Documentation files, as a rule, now live within each component, rather than being under a separate Documentation directory. This file, for example, is stored ion [Cedar10.1]<CedarRelease>Cedar10.1ReleaseMessage.tioga; from within Cedar10.1, it is accessible as /r/Cedar10.1ReleaseMessage.tioga (you need the .tioga becasue there is already a dot in the name).
The web of tangled interdependencies among the PCedar2.0 DF files has been sorted out, so that the DF files are now partially ordered.
The use of DFPorter for moving components to Cedar10.1 is strongly encouraged. See below.
Character code changes
The source files have been changed to use the Xerox Character Codes for left-arrow and up-arrow, instead of the ascii code for underscore and circumflex. To type these, use the arrow keys on the keypad (R10 for left-arrow, R8 for up-arrow). There is a command named "FixupCedarFile" that will fix up an existing source file. FixupCedarFile does not do a good job on documentation files; these should be looked at by the person porting the package.
Interface changes
Many low-level interfaces have been changed in some way; but an effort has been made to limit the required changes in client source code to a reasonable level. Almost all of the required changes should be detectable by the compiler, so a reasonable porting strategy is to rely on the Mimosa compiler for guidance. Here are highlights of the changes; at some point there may be more detailed documentation:
Basics - the move and copy routines have been rationalized, and re-implemented efficiently. Some unused/unimplemented procs have been removed.
Char - This is a new interface describing an extended 32-bit character representation.
Rope - A new variant was added to the record definition that will allow a wide-character supertype of ROPE to be defined. Also, Rope.Cat demands at least 2 arguments, so some uses will need to be changed to Rope.Concat.
SafeStorage - The PFinalize interface is renamed to Finalization. The defunct section of SafeStorage that dealt with old-style finalization has been removed.
IO - There is an explicit buffer added to the STREAM object, so that inline versions of GetChar and PutChar can be provided. There are new provisions for I/O of 64-bit numbers (both fixed and floating point). The PutF* routine now demand an appropriate number of arguments; this may call for a significant amount of (trivial) editing while porting code, but helps control the object code size.
Imager - AIS support is removed from the public interfaces. A new object has been added at the DeviceWorks level. The XChar type is now Char.XCHAR. See /r/ImagerChanges.tioga for details.
Interpress - The "Interpress" interface is now named "InterpressInterpreter".
RopeFile - The RopeFile interface and implementation is very different, no longer assuming a particular file system. Most clients will not use the RopeFile interface directly, but instead will call PFS.RopeOpen.
SunRPC - now supports TCP as well as UDP. A new interface, SunRPCBinding, simplifies setting up a connection. A compatible stub generator is available.
Tioga - Low-level interfaces have been rationalized (and in many cases renamed). [details from Wyatt]
UserCredentials - No longer exists; use SystemNames.UserName[] or see XNSCredentials.
Viewers, TIP - Changes so that some low-level interfaces are no more exposed to vanilla clients of viewers. [details from Jacobi]
X11, X11Viewers - Many changes. The one change you have to know about: New keyboard mapping code shared between X11 and TIP. Copy the file /Cedar10.1/Keyboards/XmodmapForSunType4.text to ~.Xmodmap-type4 to get a keyboard mapping which works for Cedar10.1, PCedar2.0, vanilla X applications, and, Sun's deskset tools simultanously. Eventually this file (maybe with PCedar2.0 removed) should make it into the PARC default X windows setup. [details from Jacobi]
Other changes
Things to be on the lookout for:
Trying to store a nested procedure into a data structure will cause a runtime error in checked code. This is required to ensure safety, and it was a bug that it was not being done.
FS.Error is now a VAR ERROR that gets a value of PFS.Error; it turns out that if such a VAR ERROR is not exported, you won't get any warning messages from the loader, and your program may die with an address fault in a fairly mysterious way.
Getting started in Cedar10.1
Before you start, edit your profile to avoid references to PCedar; this will typically mean commenting out Require commands in your BootCommands. Make sure your search rules don't have any PCedar-dependent directories.
Unless you do something clever with version maps, it is best to remove references to VersionMap.SourceMaps; in PCedar2.0 and Cedar10.1, the defaults (used for openr, findr, getfromrelease, etc) are probably what you want.
The profile entries for Tioga.*TIP now need to be full path names; /r/will do as the prefix for the name. Tioga.StyleSearchRules should use the prefix /release, if you want styles other than the defaults; e.g. /my/styles/ /Release/styles
The version command now returns a number without preceding blanks; one can use this value to execute different boot commands, depending on the version that is running. An example is:
CommandTool.BootCommands: "
CommandsFromProfile CommandTool.BootCommands$(version)
"
CommandTool.BootCommands2.0: "
pcedar2.0 stuff
"
CommandTool.BootCommands10.1: "
cedar10.1 stuff
"
To start a Cedar10.1 world at PARC, type
enable cedar10.1
to a UNIX shell. Then one can type:
CedarCommander X11Viewers
OR
CedarCommander RawViewers
OR
X11ViewersWorld | RawViewersWorld
The first two will get you a dynamically-loaded X11Viewers or RawViewers world. Now you may load up this world with your favorite components, and then (in a commander viewer), say
CD /usr/tmp; PackageIt XV X11Viewers; sh1 ./XV.ld
OR
CD /usr/tmp; PackageIt RV RawViewers; sh1 ./RV.ld
(ignore warnings of : cc: File with unknown suffix)
This will make a packaged world, /usr/tmp/XV (or RV), which you can invoke the next time you want to start up a world. To invoke that package:
/usr/tmp/XV
(You may want to build the package in some place other than /usr/tmp, but it should probably be on your workstation to avoid too much network dependence.)
For further details about this process, see GenerateCedarScriptDoc, CommanderDoc, and PackageIt.cm
Porting code from PCedar2.0 to Cedar10.1
These instructions assume you are running in a Cedar10.1 world; then the compiling conventions are correct (i. e., code will be optimized O2).
Use DFPort to port packages (see DFPorterDoc, but here is a crib sheet).
A handy alias is:
Alias dp10i (foo) dfport Ported.df Cedar10.1 foo /pcedar2.0/top/foo-Suite.df
Then one can type
dp10i mumble
Included in Cedar10.1 is a sample Ported.df (/Cedar10.1/CedarRelease/Ported.df or /r/Ported.df), which includes everything up through Viewers and Tioga. Add to your own copy as needed.
DFPort will complain if something is imported that is not in the Ported.df file; you'll have to hand edit mumble.df, to change xx-PCR.df to xx.df in the imports clauses.
After doing DFPort, you need to bringover the sources from PCedar2.0:
qbo -s /pcedar2.0/top/mumble-Suite.df
Now get the imports from Cedar10.1:
qbo -r mumble.df.
If you find something the program imports does not exist in Cedar10.1, you can do that port or get someone else to do it, or try to fins substitute. If something has changed, look for changed interfaces or new ones in the df files.
Now run the translation program over the sources (does character code changes, makes sure there are copyrights, etc):
tenize mumble
Tenize.command is the following alias:
alias tenize (foo) DFContents -s -p (FixupCedarFile base.ext) foo.df | Commander
DO NOT type tenize foo.df or it will complain about not finding foo.df.df
This will print out information about which files were changed.
Look at all .command and .require files and change any PCedar references to Cedar.
Now make the package:
makedo -df mumble
Once the makedo is successful, be sure to run makeverify over the df. Once you have smodeled the package, you'll have to get the torch for that package to smodel again (taketorch mumble).
Using Cirio in PCedar2.0 to debug Cedar10.1
The last few versions of Cirio have made cross world debugging easier - that is, one can see ropes, if one knows the magic incantation. It is:
cirioremote host portnumber /cedar10.1/ciriothings /cedar10.1/rope /cedar10.1/atom
Of course, you need to have done a
pma /cedar10.1 -vux:/project/cedar10.1/release
for this to work.
That is, you have to tell Cirio where to find the mobs that define ropes, atoms, etc. To give the search paths, you must include the portnumber, even if it is 4815.
One can also see opaque types in the Cedar10.1 world if, before invloking Cirio, one does:
AddToDefaultVersionMaps /cedar10.1/cedarversionmap/
REMEMBER: the default is for code to be optimized, so you'll have to recompile anything you wish to debug in detail. The following is an interim way to get MakeDo to build debuggable code; note that you'll have to make the file(s) look changed to MakeDo, so simply load into a viewer and click save. See also /r/MakeDoCommandsDoc.tioga, under the MakeDo command.
*** Gross Hack ***
There is an interim, unprincipled way to control the optimization level of compilations directed by MakeDo. It is controlled by the switches below, which are further options for an arg. THIS IS UNPRINCIPLED! HOW UNPRINCIPLED IS IT?? IT IS SO UNPRINCIPLED, these switches do not affect the determination of what needs to be recompiled, and affect only those compilations done during the MakeDo invocation in which they are given --- and I won't even THINK about concurrent invocations of MakeDo with different values for these switches.
-OL: Compile at the "lower" level of optimization.
-ON: Compile at the "normal" level of optimization.
For SunOS:
for files in the `sun4' directory, `-O2' is the `normal' level of optimization and `-g' is the `lower' level;
for files in the `sun4-o3' directory, `-O3' is the `normal' level of optimization and `-O2' is the `lower' level.