[Cyan]<Cedar6.0>Documentation>BinderDoc.tioga!1

BinderDoc.Tioga

Last Edited by: Swinehart, May 23, 1984 8:48:09 am PDT

Last Edited by: Subhana, May 30, 1984 2:05:42 pm PDT

USING THE BINDER

CEDAR 5.2 — FOR INTERNAL XEROX USE ONLY

Using the Binder

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

For Internal Xerox Use Only

Introduction

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 (chapter 7.8 ff) of the Mesa 11.0 manual, available in hardcopy, for that.] But it does describe the Binder, a Cedar program that produces such a configuration given its specification. Usually, the binder follows simple rules to derive the input and file names that it needs. But we also describe the complete syntax for specifying all these things explicitly.

This is a companion to the document that describes the use of the Cedar compiler. [See [Indigo]<CedarŽ>Documentation>CompilerDoc.tioga]. Many of the instructions contained here are abbreviated versions of procedures that are spelled out more fully in that memo.

Installing the Binder

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

Invoking the Binder

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

At present, the one and only Binder command has the "ComplexBinder" 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 the Binder.

The "Binder" command -- simple version

Syntax

(adapted from the Trinity Mesa User's Manual)

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

% Bind 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 "/A", which evokes a useful symbol-copy option.

Semantics

Reminder: [See the C/Mesa section (chapter 7.8 ff.) of the Mesa 11.0 manual for a description of the syntax and semantics of Cedar configuration files].

This command produces "Root.BCD" (Root is the configurationFileName excluding extension) from the components (modules and other configurations) described in the configuration file. The configuration file and all of the component (.BCD) files must reside in the current working directory, and that's where the output file will go as well. For each component in the configuration, the Binder assumes that the component's root file name (extension ".BCD") is the same as its component name.

If you do not specify any options, the code for each of the input components will be copied to the output file, but symbols will not be. Instead, the output file will contain references to the input component files that will allow the debugger and other programs that need the symbols to find them when necessary. This means that the component .BCD's will have to be on your directory at run time in order to use the debugger. You may prefer to include the "/A" switch option, which will cause both code and symbols to be copied to the (considerably larger) output file. Do not use "/A" for components that are to be released as part of the Cedar system; there are special facilities for dealing with symbols that are part of a release.

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

Examples

% Bind DoSomethingPackage

where "DoSomethingPackage.Config" contains:

DoSomethingPackage: CONFIGURATION

IMPORTS Atom, DoSomethingPrivate, Process

EXPORTS DoSomething

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

This produces "DoSomethingPackage.BCD" from the configuration description and from the previously-compiled modules "DoFirst.BCD", "DoSecond.BCD" and "DoThird.BCD". The output file contains a description of the resulting configuration, along with copies of the code (but not the symbols) from each of the components.

% Bind /A DoSomethingPackage

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

The "Binder" command -- complete syntax

Syntax

(derived from the Trinity Mesa User's Manual; but note those things below that don't work!)

The full Binder syntax includes the following forms:

% Bind outputFile ← globalSwitches inputFile[id1: file1, id2: file2, ..., idn: filen] localSwitches

% Bind [bcd: bcdFile, code: codeFile, 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 the second form of the command, and anything (except the "/A" switch mentioned above) having to do with switches. 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 code and symbol information could be obtained at load time. In addition, the design allows code and symbol information to be placed in separate files. The second binder 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, along with some binder control options that are not relevant in Cedar. At the present time, the Cedar binder apparently supports the full syntax, but will not produce the separate output files. Cedar configurations are always single .BCD files that contain full copies of the code (and optionally symbols) from all their input files.

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. The Binder 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

% Bind DidSomething ←

DoSomethingPackage[DoFirst: PrimusImpl, DoThird: TertiusImpl]

This produces a configuration named "DidSomething.BCD", using the same configuration mentioned in the previous example. However, the file "PrimusImpl.BCD" 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.BCD"), and similarly for the "DoThird" component. "DoSecond", as before, comes from "DoSecond.BCD". Code, but not symbols, will be copied to the output file.

Switches

Recommendation: Ignore this section; the default settings, augmented perhaps by use of "/A", are the only reasonable ones.

Default settings: ~AC~DG~P~S~W

A: copy all (code and symbols); shorthand for /CS.

C: copy code; otherwise the configuration will refer to code in the input files.

D: call debugger on error; who knows what this means.

G: Produce Binder.log instead of Root.Errlog.

P: Pause after binding a config that includes errors (implemented?)

S: copy symbols: otherwise the configuration will refer to symbols in the input files.

W: Pause after binding a config that includes warnings (implemented?).

Logs

The binder produces a file named Binder.Errlog on the working directory. It opens a viewer on this file if there were any errors during binding.

The Binder and UserProfile

Default settings for binder switches can be specified in the user profile by including a Binder.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:

Binder.Switches: A