[_CDCSL_93-16_]<1>Cedar>release>Cinder>CinderDoc.tioga~

CinderDoc.Tioga

Swinehart, May 23, 1984 8:48:09 am PDT

Subhana, May 30, 1984 2:05:42 pm PDT

Andy Litman August 2, 1988 12:01:37 pm PDT

JKF October 12, 1988 8:38:50 am PDT

USING THE CINDER

CEDAR X — FOR INTERNAL XEROX USE ONLY

Using Cinder

XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304

For Internal Xerox Use Only

Introduction

Cinder is a revision of the Mesa Binder for the Portable Cedar project. The idea is that to get the bindings we desire in a C environment we replace the work done by the Binder and the Loader with a set of runtime calls. Cinder takes a C/Mesa file and produces a C module containing the set of runtime calls to InstallationSupport, which is part of the Portable Cedar library. The C module can then be compiled and linked with the component modules of the configuration, which are translated into C by Mimosa. Cinder produces a Mesa object file (with extension .mob) which represents the configuration, and is used as input for further Cindering. Cinder also produces a UNIX script (with extension .ld) which can be run on a UNIX machine to produce an executable file.

Cinder does version checking on the components of the configuration. The Mesa runtime also does version checking at load time, but most users prefer to be told about version mismatches at Cinder time. Version checking can be disabled with a switch (see below).

This document does not describe the C/Mesa language that is used to specify the production of system configurations from independent modules. [See the C/Mesa section (section 7.9) of the Mesa Language Manual for that.] However, additions to the C/Mesa language which facilitate multiple language configurations and loading on demand is described in this document.

Installing Cinder

BringOver the public part of Cinder.DF from the Mimosa directory, into a directory that will be on your search path when you want to use it -- preferably to a Commands subdirectory [See CompilerDoc].

Invoking Cinder

Like the Compiler, there ought to be a simple Cinder command that allows full path names and the "slash"-style format in file names, and a ComplexCinder command, providing a wider range of configuration options but restricting filename specifications (due to conflicts in the syntax).

At present, the one and only Cinder command has the "ComplexCinder" syntax, but it includes a simple option which most people use most of the time.

[see CreateButtonDoc] for ways to produce Command tool buttons for invoking Cinder.

The "Cinder" command -- simple version

Syntax

Most users will only need to issue Cinder commands of the form:

% Cind switches configurationFileName

where configurationFileName is a simple fileName (default extension ".config"), which may not include host or directory specifications, and switches is either omitted or the string "/S", which evokes a useful symbol-copy option.

Semantics

Reminder: [See the C/Mesa section (section 7.9) of the Mesa Language Manual for a description of the syntax and semantics of Cedar configuration files].

This simple form of the Cind command is almost always sufficient to produce even the most complicated systems.

Examples

% Cind DoSomethingPackage

where "DoSomethingPackage.Config" contains:

DoSomethingPackage: CONFIGURATION

IMPORTS Atom, DoSomethingPrivate, Process

EXPORTS DoSomething

CONTROL DoFirst, DoSecond, DoThird = {
DoFirst;
DoSecond;
DoThird;
}.

This produces "DoSomethingPackage.c" and "DoSomethingPackage.mob" from the configuration description and from the previously-compiled modules "DoFirst.mob", "DoSecond.mob" and "DoThird.mob". The output file "DoSomethingPackage.mob" contains a description of the resulting configuration.

% Cind /S DoSomethingPackage

This does the same thing, but includes all the symbols, rather than references to the components that contained them, in the output mob file.

The "Cinder" command -- complete syntax

Syntax

The full Cinder syntax includes the following forms:

% Cind outputFile ←

globalSwitches inputFile[id1: file1, id2: file2, ..., idn: filen] localSwitches

% Cind [mob: mobFile, symbols: symbolFile] ←

globalSwitches inputFile[id1: . . . ] localSwitches

File names may not include host or directory specifications. Switches are letter strings introduced by the "/" character. A "-" or "~" preceding a switch specifies a FALSE setting.

Semantics

Recommendation: Ignore this second form of the command. The full syntax is included for completeness. Mesa was designed to allow configurations either to be self-contained by including copies of everything in their inputs, or to contain only references to earlier configurations from which symbol information could be obtained at load time. The second Cinder form allows one to be explicit about where to put everything, and under what names. The local and global switches provide an abbreviated way to specify what copy options should be invoked. At the present time, Cinder apparently supports the full syntax, but will not produce the separate output files. Cedar configurations are always single .mob files that optionally contain symbols from all their components.

The outputFile may be omitted, resulting in an output file derived from the input name, as in the previous section.

The id list may also be omitted. If present, it allows one to specify the file names from which any or all of the component names mentioned in the configuration file should be obtained. Cinder will assume that the file name matches the component name for any component that is not mentioned in this list. This feature continues the grand Mesa tradition of allowing renaming at all levels as formal parameters are bound to actual values. This binding list form, along with the ability to name the output file explicitly, can occasionally be useful when a named component has multiple implementations from which other configurations must select.

Examples

% Cind DidSomething ←

DoSomethingPackage[DoFirst: PrimusImpl, DoThird: TertiusImpl]

This produces a configuration named "DidSomething.mob", using the same configuration mentioned in the previous example. However, the file "PrimusImpl.mob" will be used to supply the component named "DoFirst" (which must appear as the configuration or program name in the source used to produce "PrimusImpl.mob"), and similarly for the "DoThird" component. "DoSecond", as before, comes from "DoSecond.mob".

C/Mesa Language Changes

Two language constructs, "STATIC REQUESTS" and "DYNAMIC REQUESTS", have been added to C/Mesa to facilitate building multiple language configurations and loading on demand. Both constructs are added to the C/Mesa file after the EXPORTS clause, and each is followed by a list of filenames.

For static requests, Cinder puts the filenames in the "ld" command of the ".ld" file; this allows non-Mesa derived object files to be linked into the configuration. Static Requests should be used to link a module written in C into a configuration, for instance.

For dynamic requests, Cinder puts the filenames in runtime calls to XR←request("file"), which are executed when the configuration is installed. XR←request is a cedarboot routine that loads the file if it has not already been loaded. Dynamic Requests should be used to access common packages. Note that the interface checking is done by the loader, and the file found at loadtime may not export the interface you wanted.

Examples

Foo: CONFIG
IMPORTS ...
EXPORTS ...
STATIC REQUESTS "foo.o", ...
DYNAMIC REQUESTS "/usr/local/lib/cedar/BarPackage", ...
CONTROL ...

When this configuration is sent through Cinder, "foo.o" will appear in the link command in Foo.ld. "XR←request(/usr/local/lib/cedar/BarPackage") will appear in Foo.c.

Switches

StandardDefaults: PACKED ARRAY CHAR ['a..'z] OF BOOL ~ [

FALSE, -- A Copy all (code and symbols)

FALSE, -- B TRUE => make install proc call XR←StartCedarModule

FALSE, -- C Copy code

FALSE, -- D Call debugger error

TRUE, -- E Make installation procs be extern rather than static

FALSE, -- F Unused

TRUE, -- G TRUE => errlog goes to cinder.log, FALSE => use root.errlog

FALSE, -- H TRUE => Link together a packaged world. The "MakeBoot" switch.

FALSE, -- I Unused

FALSE, -- J FALSE => old behaviour, ie -lxrc -lm, TRUE => no library search

FALSE, -- K Unused

FALSE, -- L Unused (used to be the lf/cr swtich - makedo still issues it, but it's obsolete)

FALSE, -- M MakeDo switch - if true => generate .c2c.c extension vs. .c

FALSE, -- N Unused

FALSE, -- O Unused

FALSE, -- P Pause after config with errors

FALSE, -- Q Generate .ld file with cc -pic

FALSE, -- R Generate .ld file with no -r option to ld

FALSE, -- S Copy symbols

FALSE, -- T Generate .ld file with cc -PIC

FALSE, -- U Unused

FALSE, -- V Do version checking on the input files

FALSE, -- W Pause after config with warnings

FALSE, -- X Copy compressed symbols (not implemented)

FALSE, -- Y Unused

FALSE];-- Z Unused

Log

Cinder produces a file named Cinder.log on the working directory. It opens a viewer on this file if there were any errors during binding.

Cinder and UserProfile

Default settings for Cinder switches can be specified in the user profile by including a Cinder.Switches entry. [See the compiler/binder section of UserProfileDoc]. You might want to include the following entry in your profile, in order to copy symbols when binding, but be sure to override it when you produce components for a Cedar Release:

Cinder.Switches: S

Cinder and PCR-Packaged Worlds

The cinder includes mild support for building PCR-Pacakged applications. Starting with PCR version 2� the packaged world semantics have been architected such that most of the work of creating a package can be done by Cinder. To use the Cinder to create a packaged application:

1. Create a config file which describes all of the Cedar code to be contained in your application. For example, the PCedarTools.config looks like:

PCedarTools: CONFIGURATION

EXPORTS ALL

CONTROL CedarCore, BasicCedar, CommanderSysPImpl, CommanderOpsImpl, UnixDirectoryImpl, DatagramSocketImpl, MiscRegistryImpl, SystemNamesImpl, ArpaImpl, PFSPackage, RopeFileOnPFSImpl, FSOnPFSImpl, TFSOnPFSImpl, PFSCommandsImpl, PFSPrefixMapInit, RunCommandsImpl, CommanderBasicCommandsImpl, CommanderFileCommandsImpl, CommandToolCompatibilityImpl, FileNamesOnPFSImpl, IntToIntTabImpl, UserProfileImpl, LoaderImpl, StructuredStreamsPackage, MimosaStubsImpl, DisplayStubs, TRope, TJaMPackage, RosaryImpl, TBasePackage, TiogaExecCommands, TextReplaceImpl, IntCodePackage, MobMapperImpl, Mimosa, C2CPackage, Cinder, MobListerUtilsPackage, XLister, SimpleStreamsImpl, CedarProcessImpl, VersionMapImpl, ArgsPackage, ExtendADotOutPackage, DFPackage, DFCommandsImpl, MoberyImpl, ContainersStubsImpl, ButtonStubsImpl, MakeDoPackage, StandardMMCmds, CcCommandsImpl, MakeDoCommands, PCedarToolsImpl, CommanderOnStandardStreamsImpl ~ {

CedarCore;

BasicCedar;

CommanderSysPImpl;

...

PCedarToolsImpl;

CommanderOnStandardStreamsImpl;

2. Then include a C string (no, a Mesa STRING won't do!) in your configuration which will be used by PCR at startup time to describe the default command line arguments. For example, PCedarToolsImpl.mesa (part of PCedarTools.config) includes the lines:

DefineDefaultArgs: PROC = TRUSTED MACHINE CODE {

"+char *defaultArgs = \"-msgs 0 -slaveiop 1 -mem 550000 -stack 90000 \\\n";

"-tmpdir . -- -h 4000000 -install𡤊nd←run←package --\";\n.";

};

-- mainline code:

DefineDefaultArgs[];

...

3. Then create a .switches file for your config which directs MakeDo to use Cinder's -h flag. For example, PCedarTools.mob.switches:

-hm

4. Then create a sun4>Package.MakeIt and sun4-o3>Package.MakeIt file which directs MakeDo to link the config with a version of the PCR. For example, sun4-o3>PCedarToolsPackage.MakeIt:

-- { sun4-o3/PCedarTools.c2c.o }

ComplexRsh -cmd "cc -Qpath /net/kimball/usr2/pjames/lang/ld/sparc/ -Bstatic -o sun4-o3/PCedarToolsPackage /pseudo/xrhome/3𡤀.X/LIB/OptThreads-sparc/XRRoot.o /pseudo/xrhome/3𡤀.X/LIB/OptThreads-sparc/DebugNub.o sun4-o3/PCedarTools.c2c.o /pseudo/xrhome/3𡤀.X/LIB/OptThreads-sparc/xr.a /pseudo/xrhome/3𡤀.X/LIB/OptThreads-sparc/libxrc.a"

5. Then run MakeDo to build your package.